Skip to content

Native Provider Notification Handling

In order to deliver push notifications, Mobile Services delegates to native providers, such as Apple Push Notification Service (APNS), Firebase Cloud Messaging (FCM), Windows Notification Service (WNS) or Browser Notifications (W3C). This document describes how the notification payload is handled in the different scenarios. The full notification capability is available via REST API.

Customer Events

SAP Cloud Platform Mobile Services generates event log entries in case of issues handling the push payload. Please review these entries in case of notification issues and perform further action based on the event message.

Common Notification Properties

All native providers share a common set of payload properties. Payload properties are described here.

alert

Alert properties define the notification message. The push provider displays the notification message directly on the device or browser (for W3C Push). See the specific push provider section for additional information. Use plain text for alerts so the notification can be handled by multiple push providers.

badge

The number to display in a badge on your app’s icon. Specify 0 to remove the current badge, if any.

sound

When specified, play a sound when the notification arrives on the device. See the push provider for details.

data

The data property is a serialized / escape JSON object. The object is not shown in the notification, but can be used by the mobile app notification handler.

priority

FCM and APNS message can include an optional message (delivery) priority normalor high. The native push provider translates the priority accordingly. The priority should be used only if needed.

Push Provider Specific Notification Properties

APNS, FCE and WNS defines specific notification properties. The notification payload contains specific properties for each provider that override the common notification properties. Please see the following paragraphs for details.

APNS Push Notification Payload Handling

APNS 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 it sends to devices. The mobile platform maps the incoming JSON payload to APNS custom values. For an in-depth list of APNS-specific parameters, see Apple Developer - Generate a Remote Notification

Note

APNS push provider can be used to send notifications to Apple iPhone, iPod-Touch, Watch or iPad. Some properties are handled by certain device types and OS Versions only.

Mobile Services push provider for APNS only maps widely used APNS message properties. Please use the apns.customParameter property if you need an APNS property that isn't available directly.

Example:

{
  "apns": {
    "sound": "default",
    "alertTitle": "Hello World",
    "alertSubtitle": "It's a sunny day",
    "alertBody": "How do you Do?"
  }
}

Differences Between API Version 1 and Version 2

SAP Mobile Services on the NEO Cloud environment supports API Version 1 with the following APNS specific notification properties:

  • category
  • pushType
  • contentAvailable
  • customValues
  • sound

Please use the customValues parameter to define any other APNS message property.

Common Notification Properties (APNS)

alert (APNS)

The mobile platform maps alert to NS custom value aps.alert. The value of alert can be either a String, or a JSON Object converted to a String.

alert Value as a String

The mobile platform sets alert as value of aps.alert.

alert Value as a JSON Object Converted to a String

The mobile platform parses the String and converts it to a JSON Object. It supports all keys, but we encourage using the relevant apns properties instead.

For example:

{
"alert": "{\"alert_title\": \"This is the title\", \"alert_sub-title\": \"this is the sub-title\", \"alert_body\": \"This is the body\"}}"
}

is forwarded as:

{
 "aps": {
    "alert": {
      "title" : "This is the title",
      "sub-title" : "This is the sub-title",
      "body" : "this is the body"
    }
}

badge (APNS)

The number to display in a badge on your app’s icon. Specify 0 to remove the current badge, if any. For example:

{ "badge": 1 }

is forwarded as:

{ "aps": { "badge": 1 } }

sound (APNS)

The name of a sound file in your app’s main bundle or in the Library/Sounds folder of your app’s container directory. Specify the string "default" to play the system sound. No sound is played when the property is missing.

{ "sound": "chime.aiff" }

is forwarded as:

{ "aps": { "sound": "chime.aiff" } }

data (APNS)

The mobile platform maps data to an APNS custom value using key=data. The value must be a String. For example, the client sends:

{ "data" : "{\"acme1\":\"bar\", \"acme2\" : [\"bang\", \"whiz\" ]}" }

The mobile platform forwards this JSON to APNS:

{ "data": "{\"acme1\":\"bar\", \"acme2\" : [\"bang\", \"whiz\" ]}" }

priority (APNS)

The APNS push provider maps the value normalto 5 and high to 10. Silent push notifications sets the priority from high to normal.

APNS Specific Properties

The push provider for APNS also supports a list of specific APNS message properties directly via apns property. Any property that is not available directly, can be added as JSON serialized notation in the customPrioertiesproperty.

apns.category(APNS)

The notification type. This can be used to define actionable notifications in the device notification center. The notification types and list of actions are defined in the app bundle.

{ "apns": {
  "category": "approve-reject" }
}

is forwarded as:

{ "aps": { "category": "approve-reject" } }

apns.contentAvailable(APNS)

The background notification flag. To perform a silent background update, specify the value true and don't include the alert, badge, or sound keys in your payload.

{ "apns": {
  "contentAvailable": true }
}

is forwarded as:

{ "aps": { "contentAvailable": 1 } }

apns.pushType(APNS)

The push type is used to explicitly define the notification type. Allowed values are:

ALERT, BACKGROUND, VOIP, COMPLICATION, FILEPROVIDER and MDM

apns.topic (APNS)

The topic to be sent along with the APNS notification. If not specified the topic is determined from the certificate.

apns.localizedAlertKey and apns.localizedAlertArguments (APNS)

The localized key value is defined in the iOS application and is used to provide localized alert. The localized message can be enriched by arguments, defined in the localizedAlertArguments property.

{ "apns": {
  "localizedAlertKey": "NEW_PLAYER",
  "localizedAlertArguments": ["John Doe"]
  }
}

is forwarded as:

{ "aps": { "loc-key": "NEW_PLAYER", "loc-args": [ "John Doe"] } }

apns.localizedAlertTitleKey and apns.localizedAlertTitleArguments (APNS)

The localized key value is defined in the iOS application and is used to provide localized alert titles. The localized message can be enriched by arguments, defined in the localizedAlertTitleArguments property.

{ "apns": {
  "localizedAlertTitleKey": "NEW_PLAYER",
  "localizedAlertTitleArguments": ["John Doe"]
  }
}

is forwarded as:

{ "aps": { "title-loc-key": "NEW_PLAYER", "title-loc-args": [ "John Doe"] } }

apns.localizedAlertSubtitleKey and apns.localizedAlertSubtitleArguments can be used to add a localized alert subtitle to the notification.

apns.alertTitle, apns.alertBody and apns.alertSubtitle (APNS)

These properties define the alert headers and body.

apns.mutableContent (APNS)

The mutable content property controls the message handling in the iOS notification center. The iOS notification center calls the app to enrich the message when set to true. This can be used to provide sophisticated messaging. See Apple Developer - Customizing the Appearance of Notifications for details.

Other APNS Properties

The following properties are also passed directly to the aps element.

  • launchImageFileName - string value
  • showActionButton - Boolean value
  • actionButtonLabel - string value
  • localizedActionButtonKey - string value
  • urlArguments - list of string values
  • threadId - string value

FCM Push Notification Payload Handling

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.

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. Use these notification elements to send FCM push requests to the mobile platform:

  • priority ‒ allows the definition of a priority that is forwarded to the respective notification type handler. In case of FCM, the values normal, which is the default if the field is left blank, and high are valid values.

  • gcmNotification ‒ holds FCM-specific notification elements. Unless specified, the data type for each element is string. These are optional.

  • collapseKey

  • delayWhileIdle ‒ holds a Boolean value

  • timeToLive ‒ holds a long value (TTL in milliseconds)

  • restrictedPackageName

  • title ‒ if set, this field takes priority over the alert field of the notification element

  • body

  • icon

  • sound ‒ if set, this field takes priority over the sound field of the notification element

  • tag

  • color

  • clickAction

  • bodyLocKey

  • bodyLocArgs ‒ must hold a serialized JSON list of values

  • titleLocKey

  • titleLocArgs ‒ must hold a serialized JSON list of values

For more detailed descriptions of the FCM specific fields, see FCM Connection Server Reference > HTTP Protocol, Downstream HTTP messages (JSON): https://firebase.google.com/cloud-messaging/http-server-refsend-downstream.

If the JSON payload handling for FCM custom values feature is inactive, the old FCM notification handling behavior is applied, meaning that the above-mentioned notification elements are not part of the push message sent to FCM, and the message sent to FCM remains in plain-text format, instead of JSON format. Through the feature flag, the mobile platform FCM notification handler stays backward compatible, offering the possibility of including the (old) notification payload via headers and URL parameters.

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": "TheIcon",
     "body": "The Notification Body",
     "sound": "OverrideSound",
     "color": "Blue",
     "tag": "TheTag",
     "collapseKey": "TheCollapseKey",
     "delayWhileIdle": true,
     "timeToLive": 10,
     "restrictedPackageName": "com.sap.test",
     "clickAction": "TheClickAction",
     "bodyLocKey": "message",
     "bodyLocArgs": "[\"msg1\",\"msg2\"]",
     "titleLocKey": "titleMessage",
     "titleLocArgs": "[\"tmsg1\",\"tmsg2\"]"
    },
   "customParameters": {
     "gcm.badge": 2
   }
 }

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:

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

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

  • 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
  }
}

These new validation steps also apply if the feature mentioned in JSON Payload Support for FCM Push Notifications is inactive.

Special Notification Elements

This describes payload handling for several special notification elements, and provides examples.

alert (FCM)

Since a FCM message does not contain an element that corresponds to the mobile platform alert element, the value supplied with this field is rendered under the FCM element data. If the FCM JSON payload feature is inactive, the value is still rendered as the URL parameter data.alert, but is transparent to the client. Keep in mind that alert does not equal the FCM message title element, which enables backward compatibility for clients who expect the alert to be part of the data payload.

badge (FCM)

The mobile platform notification element badge also has no corresponding FCM message element, and is rendered under the data Element.

data (FCM)

The mobile platform notification element data supports these content types:

  • String - a normal string of characters

  • Serialized JSON - a serialized JSON object

Previous versions of the mobile platform notification handler always sent the value as a string in the URL parameter data.data. Now the notification handler tries to deserialize a JSON object structure from the parameter's content, and, if it succeeds, the JSON object structure renders under the FCM message element data. To remain backward compatible, the value from data is also rendered under the FCM message element data using the key data. This way the receiving client then can process the message as needed by accessing the deserialized JSON object, or accessing the serialized JSON string or plain text string. See the example below, which shows how the message is sent to FCM, and how the payload might be passed forward to the client.

customParameters

The mobile platform notification element customParameters also allows you to specify values for "alert", "badge" and "data", which, if set, take priority over their corresponding notification element fields. Aside from this, the values are handled accordingly, and as described above, except the data element, which is additionally rendered under the FCM message element "data" and the key cdata as well. This approach provides backward compatibility, but reduces the maximum supported payload size, since information is duplicated.

Example Requests

The following examples show requests using the data and customParameters Elements.

data Element

Example request using the data element:

{
   "alert": "Update Available",
   "badge": 1,
   "data": "{\"version\":\"1.13\",\"size\":\"14MB\",\"details\":{}}"
}

The resulting FCM message payload:

{
  "to": "FCMTOKEN-1234567",
  "data": {
   "version": "1.13",
   "details": {
    "size": "14MB"
   },
   "data": "{\"version\":\"1.13\",\"details\":{\"size\":\"14MB\"}}",
   "badge": "1",
   "alert": "Update Available"
  }
}
customParameters Element

Example request using the customParameters element:

{
   "customParameters": {
     "gcm.alert": "Update Available",
     "gcm.badge": 1,
     "gcm.data": "{\"version\":\"1.13\",\"size\":\"14MB\",\"details\":{}}"
   }
}

The resulting FCM message payload:

{
  "to": "FCMTOKEN-1234567",
  "data": {
   "version": "1.13",
   "details": {
    "size": "14MB"
   },
   "data": "{\"version\":\"1.13\",\"details\":{\"size\":\"14MB\"}}",
   "cdata": "{\"version\":\"1.13\",\"details\":{\"size\":\"14MB\"}}",
   "badge": "1",
   "alert": "Update Available"
  }
}

The above examples show how data information is duplicated to remain backward compatible with older client applications, which expect data to be sent as string values under certain key names (such as data, or cdata). The examples also show the proper FCM approach for sending a JSON payload, which is to deserialize the given data value into a JSON object structure.

Resend Messages

If processing on the FCM side fails, you can automatically resend messages. Resend is scheduled when the FCM response contains an error code (currently only HTTP 400 error response codes), and includes the Retry-After HTTP header.

If these conditions occur, the original message persists in the database, and is picked up by the push dispatcher, which runs periodically. The previously extracted value from the Retry-After header is honored accordingly. Configure the maximum number of retries using the parameter push.config.async_queue_max_retries. The default value is 3.

The current implementation sends only HTTP 400 error response codes. This does not comply with the Google developer's documentation, which proposes using the Retry-After mechanism for 5xx or 200+ error response codes. To comply, you must provision the 400 error code to handle the Resend mechanism for FCM Push API feature.

WNS Push Notification Payload Handling

WNS 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 it sends to devices.

Payload Handling for WNS

This section provides examples of JSON payload handling for WNS custom values.

WNS-Specific Properties

The wns entity provides payload handling for Windows. wns is validated with a higher priority than globally-configured properties (such as Data, Sound, Alert). The root element of the new entity, and all its direct sub-elements are optional.

wns.badge (WNS)

The badge element represents a certain WNS push schema (wns/badge).

Element handling:

  • Overrides the global badge configuration, whether it is a number or a string.

  • The badge is sent as a separate request to the device.

  • If a number, 0 clears the badge; values from 1-99 are shown as given; and any value greater than 99 are shown as 99+.

  • If a string, the badge is shown as a predefined Windows glyph.

See also: badge.

wns.rawData

The rawData element represents a certain WNS push schema (wns/raw).

Element handling:

  • Overrides the global data configuration.

  • Any string can be configured as rawData, and sent to the device.

wns.version

The version element sets the version property at the notification requests (tile, toast and badge).

Element handling:

  • Any string configured as version is sent to the device.

  • The default is 1.0.

wns.lang

The lang element sets the lang property for the notification requests (tile, and toast).

Element handling: defines the language property of the content.

wns.schema

The schema element defines which notification schemas should be sent.

Element handling:

  • A list containing up to four elements.

  • Restricted to one of BADGE, TILE, TOAST or RAW.

  • The default sends all (in case content exists).

wns.tileTemplate

The tileTemplate element sets the template property for tile schema at the binding attribute. Windows provides a selection of several predefined templates, which affect the final layout of the displayed notification at the device. The elements that can be selected depend on the device operating system version.

Element handling:

  • Any string.

  • Default value depends on the push content:

  • Text only: TileSquareText04

  • One picture and text: TileSquarePeekImageAndText04

  • Few pictures and text: TileWidePeekImageCollection04

  • One picture only: TileWideImage

  • Few pictures only: TileWideImageCollection

See also: TileTemplateType Enum.

wns.toastTemplate

The toastTemplate element sets the template property for toast schema at the binding attribute. Windows provides a selection of several predefined templates, which affect the final layout of the displayed notification at the device. The elements that can be selected depend on the device operating system version.

Element handling:

  • Any string.

  • Default value depends on the push content:

  • Text only: ToastText01

  • One picture and text: ToastImageAndText04

  • Few pictures and text: ToastImageAndText04

  • One picture only: ToastImageAndText04

  • Few pictures only: ToastImageAndText04

See also: ToastTemplateType Enum.

wns.message

The message element defines the text attribute for tile and toast notifications.

Element handling:

  • No, one, or more messages can be added.

  • Any string.

wns.baseUri

The baseUri element defines the baseUri property at the binding attribute for tile and toast. This property defines a central base URL which is used for all images.

Element handling: any string.

wns.audio

The audio element defines the audio attribute for toast notifications.

Element handling: overrides the global sound configuration.

Properties:

  • loop: [Boolean, optional] ‒ defines whether the sound should be played in a loop.

  • silent: [Boolean, optional] ‒ defines whether the sound should be muted. If true, no sound is sent.

  • src: [String, required] ‒ defines the source of the sound file.

wns.image

The image element defines the image attribute for tile and toast notifications.

Element handling: no, one, or more images can be added.

Properties:

  • alt: [String, optional] ‒ defines an alternative text if the image cannot be loaded.

  • addImageQuery: [Boolean, optional] ‒ allows Windows to add a query to the image src, the default is false.

  • src: [String, required] ‒ defines the source of the image.

wns.commands

The commands element defines the commands attribute for toast notifications. Commands correspond to available actions that the user can take.

Element handling: no, one, or more commands can be added.

Properties: scenario [String, optional] ‒ defines the scenario (alarm or incomingCall, the default is alarm).

Aggregations:

  • id [String, optional] ‒ specifies one command from the system-defined command list. (such as snooze, or dismiss).

  • arguments [String, optional] ‒ an argument string that can be passed to the associated app to provide specifics about the action that it should execute in response to the user action.


Last update: August 12, 2020