feat(fcm): Added support for specifying the analytics label for notifications.

src/index.d.ts

@@ -3579,6 +3579,7 @@ type BaseMessage = {
   android?: admin.messaging.AndroidConfig;
   webpush?: admin.messaging.WebpushConfig;
   apns?: admin.messaging.ApnsConfig;
+  fcmOptions?: admin.messaging.FcmOptions;
 };
 
 interface TokenMessage extends BaseMessage {
@@ -3641,6 +3642,11 @@ declare namespace admin.messaging {
      * Android notification to be included in the message.
      */
     notification?: AndroidNotification;
+
+    /**
+     * Options for features provided by the FCM SDK for Android.
+     */
+    fcmOptions?: AndroidFcmOptions;
   }
 
   /**
@@ -3726,6 +3732,17 @@ declare namespace admin.messaging {
     channelId?: string;
   }
 
+  /**
+   * Represents options for features provided by the FCM SDK for Android.
+   */
+  interface AndroidFcmOptions {
+
+    /**
+     * The label associated with the message's analytics data.
+     */
+    analyticsLabel?: string;
+  }
+
   /**
    * Represents the APNs-specific options that can be included in an
    * {@link admin.messaging.Message}. Refer to
@@ -3743,6 +3760,11 @@ declare namespace admin.messaging {
      * An APNs payload to be included in the message.
      */
     payload?: ApnsPayload;
+
+    /**
+     * Options for features provided by the FCM SDK for iOS.
+     */
+    fcmOptions?: ApnsFcmOptions;
   }
   /**
    * Represents the payload of an APNs message. Mainly consists of the `aps`
@@ -3841,6 +3863,28 @@ declare namespace admin.messaging {
     volume?: number;
   }
 
+  /**
+   * Represents options for features provided by the FCM SDK for iOS.
+   */
+  interface ApnsFcmOptions {
+
+    /**
+     * The label associated with the message's analytics data.
+     */
+    analyticsLabel?: string;
+  }
+
+  /**
+   * Represents platform-independent options for features provided by the FCM SDKs.
+   */
+  interface FcmOptions {
+
+    /**
+     * The label associated with the message's analytics data.
+     */
+    analyticsLabel?: string;
+  }
+
 
   /**
    * A notification that can be included in {@link admin.messaging.Message}.

src/messaging/messaging-types.ts

@@ -27,6 +27,7 @@ interface BaseMessage {
   android?: AndroidConfig;
   webpush?: WebpushConfig;
   apns?: ApnsConfig;
+  fcmOptions?: FcmOptions;
 }
 
 interface TokenMessage extends BaseMessage {
@@ -60,6 +61,10 @@ export interface Notification {
   body?: string;
 }
 
+export interface FcmOptions {
+  analyticsLabel?: string;
+}
+
 export interface WebpushConfig {
   headers?: {[key: string]: string};
   data?: {[key: string]: string};
@@ -97,6 +102,7 @@ export interface WebpushNotification {
 export interface ApnsConfig {
   headers?: {[key: string]: string};
   payload?: ApnsPayload;
+  fcmOptions?: ApnsFcmOptions;
 }
 
 export interface ApnsPayload {
@@ -135,13 +141,18 @@ export interface ApsAlert {
   launchImage?: string;
 }
 
+export interface ApnsFcmOptions {
+  analyticsLabel?: string;
+}
+
 export interface AndroidConfig {
   collapseKey?: string;
   priority?: ('high' | 'normal');
   ttl?: number;
   restrictedPackageName?: string;
   data?: {[key: string]: string};
   notification?: AndroidNotification;
+  fcmOptions?: AndroidFcmOptions;
 }
 
 export interface AndroidNotification {
@@ -159,6 +170,10 @@ export interface AndroidNotification {
   channelId?: string;
 }
 
+export interface AndroidFcmOptions {
+  analyticsLabel?: string;
+}
+
 /* Payload for data messages */
 export interface DataMessagePayload {
   [key: string]: string;
@@ -291,6 +306,7 @@ export function validateMessage(message: Message) {
   validateAndroidConfig(message.android);
   validateWebpushConfig(message.webpush);
   validateApnsConfig(message.apns);
+  validateFcmOptions(message.fcmOptions);
 }
 
 /**
@@ -345,8 +361,49 @@ function validateApnsConfig(config: ApnsConfig) {
   }
   validateStringMap(config.headers, 'apns.headers');
   validateApnsPayload(config.payload);
+  validateApnsFcmOptions(config.fcmOptions);
 }
 
+/**
+ * Checks if the given ApnsFcmOptions object is valid.
+ *
+ * @param {ApnsFcmOptions} fcmOptions An object to be validated.
+ */
+function validateApnsFcmOptions(fcmOptions: ApnsFcmOptions) {
+  if (typeof fcmOptions === 'undefined') {
+    return;
+  } else if (!validator.isNonNullObject(fcmOptions)) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD, 'fcmOptions must be a non-null object');
+  }
+
+  if (typeof fcmOptions.analyticsLabel !== 'undefined' && !validator.isString(fcmOptions.analyticsLabel)) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD, 'analyticsLabel must be a string value');
+  }
+}
+
+/**
+ * Checks if the given FcmOptions object is valid.
+ *
+ * @param {FcmOptions} fcmOptions An object to be validated.
+ */
+function validateFcmOptions(fcmOptions: FcmOptions) {
+  if (typeof fcmOptions === 'undefined') {
+    return;
+  } else if (!validator.isNonNullObject(fcmOptions)) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD, 'fcmOptions must be a non-null object');
+  }
+
+  if (typeof fcmOptions.analyticsLabel !== 'undefined' && !validator.isString(fcmOptions.analyticsLabel)) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD, 'analyticsLabel must be a string value');
+  }
+}
+
+
+
 /**
  * Checks if the given ApnsPayload object is valid. The object must have a valid aps value.
  *
@@ -535,6 +592,7 @@ function validateAndroidConfig(config: AndroidConfig) {
   }
   validateStringMap(config.data, 'android.data');
   validateAndroidNotification(config.notification);
+  validateAndroidFcmOptions(config.fcmOptions);
 
   const propertyMappings = {
     collapseKey: 'collapse_key',
@@ -585,3 +643,22 @@ function validateAndroidNotification(notification: AndroidNotification) {
   };
   renameProperties(notification, propertyMappings);
 }
+
+/**
+ * Checks if the given AndroidFcmOptions object is valid.
+ *
+ * @param {AndroidFcmOptions} fcmOptions An object to be validated.
+ */
+function validateAndroidFcmOptions(fcmOptions: AndroidFcmOptions) {
+  if (typeof fcmOptions === 'undefined') {
+    return;
+  } else if (!validator.isNonNullObject(fcmOptions)) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD, 'fcmOptions must be a non-null object');
+  }
+
+  if (typeof fcmOptions.analyticsLabel !== 'undefined' && !validator.isString(fcmOptions.analyticsLabel)) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD, 'analyticsLabel must be a string value');
+  }
+}

test/unit/messaging/messaging.spec.ts

@@ -2469,6 +2469,24 @@ describe('Messaging', () => {
           messaging.send({data: arg, topic: 'test'});
         }).to.throw('data must be a non-null object');
       });
+
+      it(`should throw given invalid fcmOptions: ${JSON.stringify(arg)}`, () => {
+        expect(() => {
+          messaging.send({fcmOptions: arg, topic: 'test'});
+        }).to.throw('fcmOptions must be a non-null object');
+      });
+
+      it(`should throw given invalid AndroidFcmOptions: ${JSON.stringify(arg)}`, () => {
+        expect(() => {
+          messaging.send({android: {fcmOptions: arg}, topic: 'test'});
+        }).to.throw('fcmOptions must be a non-null object');
+      });
+
+      it(`should throw given invalid ApnsFcmOptions: ${JSON.stringify(arg)}`, () => {
+        expect(() => {
+          messaging.send({apns: {fcmOptions: arg}, topic: 'test'});
+        }).to.throw('fcmOptions must be a non-null object');
+      });
     });
 
     const invalidDataMessages: any[] = [
@@ -2750,6 +2768,14 @@ describe('Messaging', () => {
           },
         },
       },
+      {
+        label: 'Generic fcmOptions message',
+        req: {
+          fcmOptions: {
+            analyticsLabel: 'test.analytics',
+          },
+        },
+      },
       {
         label: 'Android data message',
         req: {
@@ -2852,6 +2878,9 @@ describe('Messaging', () => {
               bodyLocArgs: ['arg1', 'arg2'],
               channelId: 'test.channel',
             },
+            fcmOptions: {
+              analyticsLabel: 'test.analytics',
+            },
           },
         },
         expectedReq: {
@@ -2878,6 +2907,9 @@ describe('Messaging', () => {
               body_loc_args: ['arg1', 'arg2'],
               channel_id: 'test.channel',
             },
+            fcmOptions: {
+              analyticsLabel: 'test.analytics',
+            },
           },
         },
       },
@@ -2999,6 +3031,9 @@ describe('Messaging', () => {
               customKey1: 'custom.value',
               customKey2: {nested: 'value'},
             },
+            fcmOptions: {
+              analyticsLabel: 'test.analytics',
+            },
           },
         },
         expectedReq: {
@@ -3032,6 +3067,9 @@ describe('Messaging', () => {
               customKey1: 'custom.value',
               customKey2: {nested: 'value'},
             },
+            fcmOptions: {
+              analyticsLabel: 'test.analytics',
+            },
           },
         },
       },