Google/Firebase Cloud Messaging¶

FCM provides a native mechanism to send notifications to the back end. Back-end systems use the Push REST service to notify the mobile platform about notification messages that it sends to devices.

See About FCM messages for details.

Payload Handling for FCM¶

This provides information and examples of JSON payload handling for FCM custom values. Notification elements send FCM push requests to the mobile platform.

The mobile services push provider for FCM generates two message types based on provided properties.

Notification Messages: FCM automatically displays the message to end-user devices on behalf of the client app when the client app is in background. Notification messages have a predefined set of user-visible keys and an optional data payload of custom key-value pairs. The app is called when the user tabs the notification. Any notification related information, like references to business objects, are passed as custom key-values pairs in the optional data payload.
Data Messages: The app is responsible for processing data messages. Data Messages are used as soon as the notification uses the data property only, but no badge, sound or FCM title or body elements.

The mobile services push provider sends a data message when the payload only contains an alert and data properties. In all other cases, notification messages are sent. Please see FCM: Receive messages in an Android app for details how to process the message data.

JSON Payload Support for FCM Push Notifications¶

When sending push notifications to FCM, JSON payload handling is transparent to the client since it affects only the communication between the mobile platform and the FCM server. Your mobile app is responsible for handling notifications and must implement a callback for Android Notifications. Please see FCM REST Message Reference. Not all parameters are supported by SAP Mobile Services. Use these notification elements to send FCM push requests to the mobile platform:

`alert`(FCM)¶

Mobile services adds the alert property with value to the data payload of the message. The app is responsible to render and display this information. The SAP BTP SDK Wizard for Android adds a default implementation for handling the alert property. The Mobile Development Kit Client implements the foreground handling of the alert property.

`priority` (FCM)¶

The message priority defines the handling on the device, see Setting the priority, In case of FCM, the values normal, which is the default, and high.

`gcm.title`¶

The title of the message. gcm.titleLockKey should be used to retrieve the title from the localized resources of the app based on the user's language configuration. The resource can be parameterized and the parameter values are defined via

gcm.titleLocArgsArray - JSON list of values
gcm.titleLocArgs ‒ must hold a serialized JSON list of values, deprecated

Limit: The maximum title text length is 256 characters.

`gcm.body`¶

If set, this field takes priority over the alert field of the notification element

gcm.BodyLockKey should be used to retrieve the title from the localized resources of the app based on the user's language configuration. The resource can be parameterized and the parameter values are defined via

bodyLocArgsArray - JSON list of values
bodyLocArgs ‒ must hold a serialized JSON list of values, deprecated

Limit: The maximum body text length is 2048 characters.

`gcm.icon`¶

Allows you to implement a custom app icon for the message instead of the default. The icon resource must be present in the app resources.

Example:

{
  "alert": "Hello from your app",
  "gcm": {
    "icon": "app_icon"
  }
}

`gcm.sound`¶

Allows you to play a custom sound when the message is received. If set, this field takes priority over the sound field of the notification element. The custom sound resource must be present in the app resource folder res\raw. default selects the default notification sound.

`gcm.collapseKey`¶

Collapsible messages replace old messages with the same key with new messages with the same key. Android can store up to 100 messages without collapsing. See Non-collapsible and collapsible messages.

`gcm.timeToLive`¶

When an app server posts a message to FCM and receives a message ID back, it does not mean that the message was already delivered to the device. Rather, it means that it was accepted for delivery. What happens to the message after it is accepted depends on many factors. This property can be used to deliver the message only in the next n milliseconds. See Lifetime of a message.

`gcm.restrictedPackageName`¶

Android allows you to use one FCM service instance for multiple apps with different package names. This property will restrict the message to apps with the given package name.

Other Supported Parameters¶

gcm.tag: Identifier used to replace existing notifications in the notification drawer. If not specified, each request creates a new notification. If specified and a notification with the same tag is already being shown, the new notification replaces the existing one in the notification drawer.
gcm.color: Color in RGB format, like #0000ff for blue.
gcm.clickAction: The action associated with a user click on the notification.

For more detailed descriptions of the FCM specific fields, see Firebase Notification.

The following example shows a complete push request to the mobile platform, using every element available:

{
   "alert": "Updates Available",
   "badge": 1,
   "data": "{\"version\":\"1.13\",\"size\":\"14MB\"}",
   "priority": "high",
   "sound": "DefaultNotificationSound",
   "gcm": {
     "title": "The Title For The App",
     "icon": "app_icon",
     "body": "The Notification Body",
     "sound": "OverrideSound",
     "color": "#00ff00",
     "tag": "TheTag",
     "collapseKey": "TheCollapseKey",
     "timeToLive": 60000,
     "restrictedPackageName": "com.sap.test",
     "clickAction": "TheClickAction",
     "bodyLocKey": "message",
     "bodyLocArgsArray": ["msg1","msg2"],
     "titleLocKey": "titleMessage",
     "titleLocArgsArray": ["tmsg1","tmsg2"]
    }
 }

Notification Element Validation¶

In earlier versions, only very basic notification element validation was applied, verifying only that at least one of the following elements alert, badge or data contained information.

This behavior has been changed to accommodate the send-to-sync functionality of FCM, and to provide more granular methods of validating notification payload that is tailored to a specific notification type. See Send-to-Sync, below.

The input validation is still performed synchronously, meaning a notification with invalid values is not accepted, and results in an immediate error response being returned. Summary of the latest changes to the mobile platform FCM notification handler:

gcm.timeToLive ‒ validation ensures that the value of the field is in the range of 0 to 2419200.
priority ‒ validation ensures that the field contains either the value normal or high, or no value at all, for which FCM assumes the default value of normal.
gcm.bodyLocArgs ‒ validation ensures that the value of this field is a proper serialized JSON list containing only string values by trying to deserialize the JSON string into a Java list of string objects.
gcm.titleLocArgs ‒ validation ensures that the value of this field is a proper serialized JSON list containing only string values by trying to deserialize the JSON string into a Java list of string objects.
Maximum payload size ‒ according to FCM documentation, the maximum payload size of the data Element cannot exceed 4 KB. This validation step takes all notification elements into account that are rendered later under the FCM data element, and estimates the total payload size. To maintain backward compatibility with older mobile platform message formats, the maximum allowed payload size is actually only about one third of the 4 KB. See Special Notification Elements, below.

If any validation step fails because an invalid value was sent, the returned HTTP status is 400. The push response provides detailed information, such as the push status, which is 3 denoting an input validation error; and the push status message, which indicates the element that has failed, and why.

Example response:

HTTP/1.1 400 Bad Request
X-SMP-LOG-CORRELATION-ID: b1922884-4612-47a5-8654-fc01792d0bf4
Content-Type: application/JSON

{
  "status": {
    "value":"FCM notification validation error: invalid time_to_live value: 2419201",
    "code":3
  }
}

Troubleshooting: Notifications Not Shown¶

There are multiple reasons why notifications are successfully sent by SAP Mobile Services but not shown on the device. Common reasons are:

Do Not Disturb Mode is on. Turn off Do Not Disturb Mode.
System or app notifications are turned off. Allow system and app notifications.
Power or data settings are preventing the app from retrieving notification alerts. Check your battery settings.
Background execution for the app is disabled. Data messages are handled by the app and requires background execution.
Airplane Mode is on. Network connectivity is required. Turn off Airplane Mode.
Mobile data is turned off and no Wireless LAN is connected. Turn on mobile data. Newer versions of Android OS includes the ability to turn of app access to mobile data when a specific data limit is reached. Double-check these settings if accidentally enabled.

Last update: October 31, 2024

Google/Firebase Cloud Messaging¶

Payload Handling for FCM¶

JSON Payload Support for FCM Push Notifications¶

alert(FCM)¶

priority (FCM)¶

gcm.title¶

gcm.body¶

gcm.icon¶

gcm.sound¶

gcm.collapseKey¶

gcm.timeToLive¶

gcm.restrictedPackageName¶