Mobile Push Notifications

7min

Overview
Developers can use the Mobile Push Notifications APIs to register their Android or iOS applications and receive push notifications. These APIs allow for customization of message formats with text, images, and action buttons. Additionally, developers can specify delivery options such as priority, expiration time, and device targeting. The APIs are compatible with both Android and iOS platforms, which enables developers to send notifications to users across different devices from a unified interface.
Integration flow
Register a mobile application in Firebase Cloud Messaging (FCM).
Register the notification configuration in the notification service
Send mobile push notifications
Step 1: Register a Mobile App in FCM
Before configuring a mobile app for the notification service, call RegisterMobileAppNotification to add FCM App credentials, including the project ID, client email, and private key to the Secure Data Storage (SDS) service vault. Mobile app registration uses the following parameters:
Parameter
Description
name*﻿
The application name.
appPlatform*﻿
The application platform.
Enum: [android, ios]
appId*﻿
Application ID generated on firebase/apn project.
enableNotification
A boolean indicating whether notifications are enabled for the app.
default: true
accountConfig.projectId*﻿
SDS key for the globally unique, user-assigned ID of the parent project for the app.
accountConfig.clientEmail*﻿
SDS key for firebase service account.
accountConfig.privateKey*﻿
SDS key for private key for firebase service account.
﻿*This is required.
Below is a sample request for registering a mobile app on the Android platform. 
Register Mobile APP
{
  "name": "My App",
  "appPlatform": "android",
  "appId": "com.example.myapp",
  "enableNotification": true,
  "accountConfig": {
    "android": {
      "projectId": "my-project-id",
      "clientEmail": "[email protected]",
      "privateKey": "private-key-123"
    }
  }
}
{
  "name": "My App",
  "appPlatform": "android",
  "appId": "com.example.myapp",
  "enableNotification": true,
  "accountConfig": {
    "android": {
      "projectId": "my-project-id",
      "clientEmail": "client-email@example.com",
      "privateKey": "private-key-123"
    }
  }
}
﻿
Upon success, the response will include a unique id for the registered app. 
Step 2: Register the Notification Configuration
Call RegisterAppNotificationConfig to set the default configuration for your notifications on the Android or iOS. platform. Each platform has it's own configuration options:
Android Notification Config
iOS Notification Config
Parameter
Description
collapseKey
The collapse key for the message. The collapse key serves as an identifier for a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.
priority
FCM concept that controls when the message is delivered.
ttl
Time-to-live duration of the message in milliseconds.
restrictedPackageName
Package name of the application where the registration tokens must match in order to receive the message.
icon
Icon resource for the Android notification.
color
Notification icon color in #rrggbb format.
sound
File name of the sound to be played when the device receives the notification.
tag
Notification tag. This is an identifier used to replace existing notifications in the notification drawer. If not specified, each request creates a new notification.
clickAction
Action associated with a user click on the notification. If specified, an activity with a matching Intent Filter is launched when a user clicks on the notification.
bodyLocKey
Key of the body string in the app's string resource to use to localize the body text.
bodyLocArgs
An array of resource keys that will be used in place of the format specifiers in  the bodyLocKey.
titleLocKey
Key of the title string in the app's string resource to use to localize the title text.
titleLocArgs
An array of resource keys that will be used in place of the format specifiers in titleLocKey.
channelId
The Android notification channel ID (new in Android O). The app must create a channel with this channel ID before any notification with this channel ID can be received. If you don't send this channel ID in the request, or if the channel ID provided has not yet been created by the app, FCM uses the channel ID specified in the app manifest.
ticker
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.
sticky
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.
eventTimestamp
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.
localOnly
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.
notificationPriority
Sets the relative priority for this notification. This priority is processed by the client after the message has been delivered.
defaultSound
If set to true, use the Android framework's default sound for the notification.
defaultVibrateTimings
If set to true, use the Android framework's default vibrate pattern for the notification.
defaultLightSettings
If set to true, use the Android framework's default LED light settings for the notification.
vibrateTimingsMillis
Set 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.
visibility
Sets the visibility of the notification.
notificationCount
Sets the number of items this notification represents. May be displayed as a badge count for Launchers that support badging.
imageUrl
URL of an image to be displayed in the notification.
Parameter
Description
priority
FCM concept that controls when the message is delivered.
imageUrl
URL of an image to be displayed in the notification.
sound
Notification tag. This is an identifier used to replace existing notifications in the notification drawer. If not specified, each request creates a new notification.
criticalSound
﻿
volume
﻿
The sample requests below registers app notification configurations for Android and iOS
Android Config
iOS Config
{
  "name": "My iOS App",
  "appPlatform": "ios",
  "appId": "com.example.myiosapp",
  "enableNotification": true,
  "accountConfig": {
    "ios": {
      "projectId": "ios-project-id",
      "clientEmail": "[email protected]",
      "privateKey": "ios-private-key-123"
    }
  },
  "iosConfig": {
    "priority": 10,
    "sound": "default",
    "volume": 1.0,
    "criticalSound": true,
    "imageUrl": "https://example.com/image.jpg"
  }
}
{
  "name": "My iOS App",
  "appPlatform": "ios",
  "appId": "com.example.myiosapp",
  "enableNotification": true,
  "accountConfig": {
    "ios": {
      "projectId": "ios-project-id",
      "clientEmail": "ios-client-email@example.com",
      "privateKey": "ios-private-key-123"
    }
  },
  "iosConfig": {
    "priority": 10,
    "sound": "default",
    "volume": 1.0,
    "criticalSound": true,
    "imageUrl": "https://example.com/image.jpg"
  }
}
﻿
Upon success, the response will include a unique id for the registered notification configuration. 
Step 3: Send Mobile Push Notifications
Call SendMobilePushNotifications to send mobile push notifications for the Android or iOS platform. This call supports multiple notifications in a single API call, and notifications to multiple devices. The following examples show the following: 
Sending multiple notifications to a single device
Sending notifications to multiple devices
Multiple notifications to a single device
Notification to multiple devices
{
  "notifications": [
    {
      "appPlatform": "android",
      "deviceTokens": [
        "android_device_token_1",
        "android_device_token_2"
      ],
      "body": {
        "title": "New Android Notification",
        "body": "This is a sample notification message for Android devices.",
        "data": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      "androidConfig": {
        "collapseKey": "android_collapse_key",
        "priority": "high",
        "ttl": 3600000,
        "notificationPriority": "default",
        "defaultSound": true,
        "defaultVibrateTimings": true
      }
    },
    {
      "appPlatform": "ios",
      "deviceTokens": [
        "ios_device_token_1",
        "ios_device_token_2"
      ],
      "body": {
        "title": "New iOS Notification",
        "body": "This is a sample notification message for iOS devices.",
        "data": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      "iosConfig": {
        "priority": 10,
        "sound": "default",
        "volume": 1.0,
        "criticalSound": true
      }
    }
  ]
}
{
  "notifications": [
    {
      "appPlatform": "android",
      "deviceTokens": [
        "android_device_token_1",
        "android_device_token_2"
      ],
      "body": {
        "title": "New Android Notification",
        "body": "This is a sample notification message for Android devices.",
        "data": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      "androidConfig": {
        "collapseKey": "android_collapse_key",
        "priority": "high",
        "ttl": 3600000,
        "notificationPriority": "default",
        "defaultSound": true,
        "defaultVibrateTimings": true
      }
    },
    {
      "appPlatform": "ios",
      "deviceTokens": [
        "ios_device_token_1",
        "ios_device_token_2"
      ],
      "body": {
        "title": "New iOS Notification",
        "body": "This is a sample notification message for iOS devices.",
        "data": {
          "key1": "value1",
          "key2": "value2"
        }
      },
      "iosConfig": {
        "priority": 10,
        "sound": "default",
        "volume": 1.0,
        "criticalSound": true
      }
    }
  ]
}
﻿
Multiple notifications to a single device
Notifications to multiple devices
In this example, the request body includes the following properties:
notifications: An array of notification objects for the same device.
Android Notification 1:
appPlatform: The platform of the app (in this case, "android").
deviceTokens: An array containing a single device token for the Android device.
body: An object containing the notification content for the first notification.
androidConfig: An object containing Android-specific notification configuration for the first notification.
Android Notification 2:
appPlatform: The platform of the app (in this case, "android").
deviceTokens: An array containing the same device token for the Android device.
body: An object containing the notification content for the second notification.
androidConfig: An object containing Android-specific notification configuration for the second notification.
This request sends multiple notifications to a single Android device using different notification content and Android-specific configuration options for each notification.
Note: Make sure to replace the android_device_token with the actual device token of the Android device you want to send the notifications to.
In this example, the request body includes the following properties:
notifications: An array of notification objects for different platforms.
Android Notification:
appPlatform: The platform of the app (in this case, "android").
deviceTokens: An array of device tokens for Android devices.
body: An object containing the notification content for Android devices.
androidConfig: An object containing Android-specific notification configuration.
iOS Notification:
appPlatform: The platform of the app (in this case, "ios").
deviceTokens: An array of device tokens for iOS devices.
body: An object containing the notification content for iOS devices.
iosConfig: An object containing iOS-specific notification configuration.
This request sends notifications to multiple devices across different platforms (Android and iOS) using the provided notification content and platform-specific configuration options.
Note: Make sure to replace the tokens arrays with the actual device tokens you want to send the notifications to for each platform.
Upon success, the response includes an ACCEPTED message parameter. 

Parameter	Description
name*	The application name.
appPlatform*	The application platform. Enum: [android, ios]
appId*	Application ID generated on firebase/apn project.
enableNotification	A boolean indicating whether notifications are enabled for the app. default: true
accountConfig.projectId*	SDS key for the globally unique, user-assigned ID of the parent project for the app.
accountConfig.clientEmail*	SDS key for firebase service account.
accountConfig.privateKey*	SDS key for private key for firebase service account.

Parameter	Description
collapseKey	The collapse key for the message. The collapse key serves as an identifier for a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.
priority	FCM concept that controls when the message is delivered.
ttl	Time-to-live duration of the message in milliseconds.
restrictedPackageName	Package name of the application where the registration tokens must match in order to receive the message.
icon	Icon resource for the Android notification.
color	Notification icon color in #rrggbb format.
sound	File name of the sound to be played when the device receives the notification.
tag	Notification tag. This is an identifier used to replace existing notifications in the notification drawer. If not specified, each request creates a new notification.
clickAction	Action associated with a user click on the notification. If specified, an activity with a matching Intent Filter is launched when a user clicks on the notification.
bodyLocKey	Key of the body string in the app's string resource to use to localize the body text.
bodyLocArgs	An array of resource keys that will be used in place of the format specifiers in the bodyLocKey.
titleLocKey	Key of the title string in the app's string resource to use to localize the title text.
titleLocArgs	An array of resource keys that will be used in place of the format specifiers in titleLocKey.
channelId	The Android notification channel ID (new in Android O). The app must create a channel with this channel ID before any notification with this channel ID can be received. If you don't send this channel ID in the request, or if the channel ID provided has not yet been created by the app, FCM uses the channel ID specified in the app manifest.
ticker	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.
sticky	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.
eventTimestamp	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.
localOnly	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.
notificationPriority	Sets the relative priority for this notification. This priority is processed by the client after the message has been delivered.
defaultSound	If set to true, use the Android framework's default sound for the notification.
defaultVibrateTimings	If set to true, use the Android framework's default vibrate pattern for the notification.
defaultLightSettings	If set to true, use the Android framework's default LED light settings for the notification.
vibrateTimingsMillis	Set 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.
visibility	Sets the visibility of the notification.
notificationCount	Sets the number of items this notification represents. May be displayed as a badge count for Launchers that support badging.
imageUrl	URL of an image to be displayed in the notification.

Parameter	Description
priority	FCM concept that controls when the message is delivered.
imageUrl	URL of an image to be displayed in the notification.
sound	Notification tag. This is an identifier used to replace existing notifications in the notification drawer. If not specified, each request creates a new notification.
criticalSound
volume

Updated 23 Apr 2024

Did this page help you?

Secure Data Storage