feat(fcm): Add 12 new Android Notification Parameters Support (#684)

Discussion
- Introduce support for the new Android notification parameters in FCM API to AdminSDK.

Testing
- Added unit tests and integration tests to reflect this change.

API Changes
- In Messaging added new fields to AndroidNotification interface.
- Introduced LightSettings interface

RELEASE NOTE: Added a series of new parameters to the AndroidNotification class that allow further customization of notifications that target Android devices.

Author: lahirumaramba

src/index.d.ts

@@ -4000,6 +4000,120 @@ declare namespace admin.messaging {
      * ID specified in the app manifest.
      */
     channelId?: string;
+
+    /**
+     * Sets the "ticker" text, which is sent to accessibility services. Prior to 
+     * API level 21 (Lollipop), sets the text that is displayed in the status bar 
+     * when the notification first arrives.
+     */
+    ticker?: string;
+
+    /**
+     * When set to `false` or unset, the notification is automatically dismissed when 
+     * the user clicks it in the panel. When set to `true`, the notification persists 
+     * even when the user clicks it.
+     */
+    sticky?: boolean;
+
+    /**
+     * For notifications that inform users about events with an absolute time reference, sets
+     * the time that the event in the notification occurred. Notifications
+     * in the panel are sorted by this time.
+     */
+    eventTimestamp?: Date;
+
+    /**
+     * Sets whether or not this notification is relevant only to the current device. 
+     * Some notifications can be bridged to other devices for remote display, such as 
+     * a Wear OS watch. This hint can be set to recommend this notification not be bridged. 
+     * See [Wear OS guides](https://developer.android.com/training/wearables/notifications/bridger#existing-method-of-preventing-bridging)
+     */
+    localOnly?: boolean;
+
+    /**
+     * Sets the relative priority for this notification. Low-priority notifications 
+     * may be hidden from the user in certain situations. Note this priority differs 
+     * from `AndroidMessagePriority`. This priority is processed by the client after 
+     * the message has been delivered. Whereas `AndroidMessagePriority` is an FCM concept 
+     * that controls when the message is delivered.
+     */
+    priority?: ('min' | 'low' | 'default' | 'high' | 'max');
+
+    /**
+     * Sets the vibration pattern to use. Pass in an array of milliseconds to 
+     * turn the vibrator on or off. The first value indicates the duration to wait before 
+     * turning the vibrator on. The next value indicates the duration to keep the 
+     * vibrator on. Subsequent values alternate between duration to turn the vibrator 
+     * off and to turn the vibrator on. If `vibrate_timings` is set and `default_vibrate_timings` 
+     * is set to `true`, the default value is used instead of the user-specified `vibrate_timings`.
+     */
+    vibrateTimingsMillis?: number[];
+
+    /**
+     * If set to `true`, use the Android framework's default vibrate pattern for the 
+     * notification. Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). 
+     * If `default_vibrate_timings` is set to `true` and `vibrate_timings` is also set, 
+     * the default value is used instead of the user-specified `vibrate_timings`.
+     */
+    defaultVibrateTimings?: boolean;
+
+    /**
+     * If set to `true`, use the Android framework's default sound for the notification. 
+     * Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml).
+     */
+    defaultSound?: boolean;
+
+    /**
+     * Settings to control the notification's LED blinking rate and color if LED is 
+     * available on the device. The total blinking time is controlled by the OS.
+     */
+    lightSettings?: LightSettings;
+
+    /**
+     * If set to `true`, use the Android framework's default LED light settings 
+     * for the notification. Default values are specified in [`config.xml`](https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml). 
+     * If `default_light_settings` is set to `true` and `light_settings` is also set, 
+     * the user-specified `light_settings` is used instead of the default value.
+     */
+    defaultLightSettings?: boolean;
+
+    /**
+     * Sets the visibility of the notification. Must be either `private`, `public`, 
+     * or `secret`. If unspecified, defaults to `private`.
+     */
+    visibility?: ('private' | 'public' | 'secret');
+
+    /**
+     * Sets the number of items this notification represents. May be displayed as a 
+     * badge count for Launchers that support badging. See [`NotificationBadge`(https://developer.android.com/training/notify-user/badges). 
+     * For example, this might be useful if you're using just one notification to
+     * represent multiple new messages but you want the count here to represent
+     * the number of total new messages. If zero or unspecified, systems 
+     * that support badging use the default, which is to increment a number 
+     * displayed on the long-press menu each time a new notification arrives.
+     */
+    notificationCount?: number;
+  }
+
+  /**
+   * Represents settings to control notification LED that can be included in
+   * {@link admin.messaging.AndroidNotification}.
+   */
+  interface LightSettings {
+    /**
+     * Required. Sets color of the LED in `#rrggbb` or `#rrggbbaa` format.
+     */
+    color: string;
+
+    /**
+     * Required. Along with `light_off_duration`, defines the blink rate of LED flashes.
+     */
+    lightOnDurationMillis: number;
+
+    /**
+     * Required. Along with `light_on_duration`, defines the blink rate of LED flashes. 
+     */
+    lightOffDurationMillis: number;
   }
 
   /**

src/messaging/messaging-types.ts

@@ -171,6 +171,24 @@ export interface AndroidNotification {
   titleLocKey?: string;
   titleLocArgs?: string[];
   channelId?: string;
+  ticker?: string;
+  sticky?: boolean;
+  eventTimestamp?: Date;
+  localOnly?: boolean;
+  priority?: ('min' | 'low' | 'default' | 'high' | 'max');
+  vibrateTimingsMillis?: number[];
+  defaultVibrateTimings?: boolean;
+  defaultSound?: boolean;
+  lightSettings?: LightSettings;
+  defaultLightSettings?: boolean;
+  visibility?: ('private' | 'public' | 'secret');
+  notificationCount?: number;
+}
+
+export interface LightSettings {
+  color: string;
+  lightOnDurationMillis: number;
+  lightOffDurationMillis: number;
 }
 
 export interface AndroidFcmOptions {
@@ -628,18 +646,7 @@ function validateAndroidConfig(config: AndroidConfig) {
         MessagingClientErrorCode.INVALID_PAYLOAD,
         'TTL must be a non-negative duration in milliseconds');
     }
-    const seconds = Math.floor(config.ttl / 1000);
-    const nanos = (config.ttl - seconds * 1000) * 1000000;
-    let duration: string;
-    if (nanos > 0) {
-      let nanoString = nanos.toString();
-      while (nanoString.length < 9) {
-        nanoString = '0' + nanoString;
-      }
-      duration = `${seconds}.${nanoString}s`;
-    } else {
-      duration = `${seconds}s`;
-    }
+    const duration: string = transformMillisecondsToSecondsString(config.ttl);
     (config as any).ttl = duration;
   }
   validateStringMap(config.data, 'android.data');
@@ -691,6 +698,47 @@ function validateAndroidNotification(notification: AndroidNotification) {
         'android.notification.imageUrl must be a valid URL string');
   }
 
+  if (typeof notification.eventTimestamp !== 'undefined') {
+    if (!(notification.eventTimestamp instanceof Date)) {
+      throw new FirebaseMessagingError(
+        MessagingClientErrorCode.INVALID_PAYLOAD, 'android.notification.eventTimestamp must be a valid `Date` object');
+    }
+    // Convert timestamp to RFC3339 UTC "Zulu" format, example "2014-10-02T15:01:23.045123456Z"
+    const zuluTimestamp = notification.eventTimestamp.toISOString();
+    (notification as any).eventTimestamp = zuluTimestamp;
+  }
+
+  if (typeof notification.vibrateTimingsMillis !== 'undefined') {
+    if (!validator.isNonEmptyArray(notification.vibrateTimingsMillis)) {
+      throw new FirebaseMessagingError(
+        MessagingClientErrorCode.INVALID_PAYLOAD,
+        'android.notification.vibrateTimingsMillis must be a non-empty array of numbers');
+    }
+    const vibrateTimings: string[] = [];
+    notification.vibrateTimingsMillis.forEach((value) => {
+      if (!validator.isNumber(value) || value < 0) {
+        throw new FirebaseMessagingError(
+          MessagingClientErrorCode.INVALID_PAYLOAD,
+          'android.notification.vibrateTimingsMillis must be non-negative durations in milliseconds');
+      }
+      const duration = transformMillisecondsToSecondsString(value);
+      vibrateTimings.push(duration);
+    });
+    (notification as any).vibrateTimingsMillis = vibrateTimings;
+  }
+
+  if (typeof notification.priority !== 'undefined') {
+    const priority = 'PRIORITY_' + notification.priority.toUpperCase();
+    (notification as any).priority = priority;
+  }
+
+  if (typeof notification.visibility !== 'undefined') {
+    const visibility = notification.visibility.toUpperCase();
+    (notification as any).visibility = visibility;
+  }
+
+  validateLightSettings(notification.lightSettings);
+
   const propertyMappings = {
     clickAction: 'click_action',
     bodyLocKey: 'body_loc_key',
@@ -699,10 +747,73 @@ function validateAndroidNotification(notification: AndroidNotification) {
     titleLocArgs: 'title_loc_args',
     channelId: 'channel_id',
     imageUrl: 'image',
+    eventTimestamp: 'event_time',
+    localOnly: 'local_only',
+    priority: 'notification_priority',
+    vibrateTimingsMillis: 'vibrate_timings',
+    defaultVibrateTimings: 'default_vibrate_timings',
+    defaultSound: 'default_sound',
+    lightSettings: 'light_settings',
+    defaultLightSettings: 'default_light_settings',
+    notificationCount: 'notification_count',
   };
   renameProperties(notification, propertyMappings);
 }
 
+/**
+ * Checks if the given LightSettings object is valid. The object must have valid color and
+ * light on/off duration parameters. If successful, transforms the input object by renaming
+ * keys to valid Android keys.
+ *
+ * @param {LightSettings} lightSettings An object to be validated.
+ */
+function validateLightSettings(lightSettings: LightSettings) {
+  if (typeof lightSettings === 'undefined') {
+    return;
+  } else if (!validator.isNonNullObject(lightSettings)) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD, 'android.notification.lightSettings must be a non-null object');
+  }
+
+  if (!validator.isNumber(lightSettings.lightOnDurationMillis) || lightSettings.lightOnDurationMillis < 0) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD,
+      'android.notification.lightSettings.lightOnDurationMillis must be a non-negative duration in milliseconds');
+  }
+  const durationOn = transformMillisecondsToSecondsString(lightSettings.lightOnDurationMillis);
+  (lightSettings as any).lightOnDurationMillis = durationOn;
+
+  if (!validator.isNumber(lightSettings.lightOffDurationMillis) || lightSettings.lightOffDurationMillis < 0) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD,
+      'android.notification.lightSettings.lightOffDurationMillis must be a non-negative duration in milliseconds');
+  }
+  const durationOff = transformMillisecondsToSecondsString(lightSettings.lightOffDurationMillis);
+  (lightSettings as any).lightOffDurationMillis = durationOff;
+
+  if (!validator.isString(lightSettings.color) ||
+    (!/^#[0-9a-fA-F]{6}$/.test(lightSettings.color) && !/^#[0-9a-fA-F]{8}$/.test(lightSettings.color))) {
+    throw new FirebaseMessagingError(
+      MessagingClientErrorCode.INVALID_PAYLOAD,
+      'android.notification.lightSettings.color must be in the form #RRGGBB or #RRGGBBAA format');
+  }
+  const colorString = lightSettings.color.length === 7 ? lightSettings.color + 'FF' : lightSettings.color;
+  const rgb = /^#?([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/i.exec(colorString);
+  const color = {
+    red: parseInt(rgb[1], 16) / 255.0,
+    green: parseInt(rgb[2], 16) / 255.0,
+    blue: parseInt(rgb[3], 16) / 255.0,
+    alpha: parseInt(rgb[4], 16) / 255.0,
+  };
+  (lightSettings as any).color = color;
+
+  const propertyMappings = {
+    lightOnDurationMillis: 'light_on_duration',
+    lightOffDurationMillis: 'light_off_duration',
+  };
+  renameProperties(lightSettings, propertyMappings);
+}
+
 /**
  * Checks if the given AndroidFcmOptions object is valid.
  *
@@ -721,3 +832,28 @@ function validateAndroidFcmOptions(fcmOptions: AndroidFcmOptions) {
       MessagingClientErrorCode.INVALID_PAYLOAD, 'analyticsLabel must be a string value');
   }
 }
+
+/**
+ * Transforms milliseconds to the format expected by FCM service.
+ * Returns the duration in seconds with up to nine fractional
+ * digits, terminated by 's'. Example: "3.5s".
+ *
+ * @param {number} milliseconds The duration in milliseconds.
+ * @return {string} The resulting formatted string in seconds with up to nine fractional
+ * digits, terminated by 's'.
+ */
+function transformMillisecondsToSecondsString(milliseconds: number): string {
+  let duration: string;
+  const seconds = Math.floor(milliseconds / 1000);
+  const nanos = (milliseconds - seconds * 1000) * 1000000;
+  if (nanos > 0) {
+    let nanoString = nanos.toString();
+    while (nanoString.length < 9) {
+      nanoString = '0' + nanoString;
+    }
+    duration = `${seconds}.${nanoString}s`;
+  } else {
+    duration = `${seconds}s`;
+  }
+  return duration;
+}

test/integration/messaging.spec.ts

@@ -49,6 +49,25 @@ const message: admin.messaging.Message = {
   },
   android: {
     restrictedPackageName: 'com.google.firebase.testing',
+    notification: {
+      title: 'test.title',
+      ticker: 'test.ticker',
+      sticky: true,
+      visibility: 'private',
+      eventTimestamp: new Date(),
+      localOnly: true,
+      priority: 'high',
+      vibrateTimingsMillis: [100, 50, 250],
+      defaultVibrateTimings: false,
+      defaultSound: true,
+      lightSettings: {
+        color: '#AABBCC55',
+        lightOnDurationMillis: 200,
+        lightOffDurationMillis: 300,
+      },
+      defaultLightSettings: false,
+      notificationCount: 1,
+    },
   },
   apns: {
     payload: {