Skip to content

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.

  1. 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.

  2. 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.

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.

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:

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

  • gcm.color

  • gcm.clickAction

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": "Blue",
     "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: January 8, 2024