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.

Warning

Notifications are typically processed by the operating system and displayed without app involvement. Don't send sensitive information in the notification message fields, because it might be shown even if the device is locked.

Customer Events¶

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

Limit: The maximum alert text length is 2048 characters.

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

Limit: The maximum length for the reference to the sound resource is 256 characters.

`data`¶

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

Android only:

Supports maps/key text value pairs; other JSON objects are ignored.
The alert is included in the data

Limit: The maximum serialized / escaped JSON key/value map is 2000 characters.

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

Limit: The maximum priority identifier length is 128 characters.

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

The mobile services push provider for APNS supports two notification types:

Visual Notifications are handled without app involvement by the Notification Center when the app is in the background. Notifications are displayed in the lock or home screen based on the system notification configuration for the app. The app can modify the content before it appears in the Notification Center when the flag apns.mutableContent is set.
Silent Notifications are handled by the app. The app's notification callback function is called when a new notification arrives. See apns.contentAvailable notification parameter.

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.

The 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¶

The mobile services on the NEO Cloud environment support 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.

Limit: The maximum alert text length is 2048 characters.

`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" } }

Limit: The maximum sound reference length is 256 characters.

`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 a JSON serialized notation in the customPriorities property.

`apns.expiry` (APNS)¶

The date at which the notification is no longer valid. This value is a timestamp in ISO 8601 combined date and time presentation. If the value is nonzero and the target is offline, APNS stores the notification and tries to deliver it at least once, repeating the attempt as needed until the specified date.

{ "apns": {
  "expiry": "2007-04-05T12:30:01.001−02:00" }
}

`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" } }

Limit: The maximum category identifier length is 128 characters.

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

Limit: The maximum topic identifier length is 256 characters.

`apns.customSound`(APNS)¶

The APNS notification sound can be customized by:

sound: reference to a sound file in /Library/Sounds.
volume: Playback volume. Value range is from 0.0 (silent) to 1.0 (maximum).
critical: The critical alert flag.

{ "apns": {
  "customSound": {
    "sound" : "chime.aiff",
    "volume" : 0.9,
    "critical" : true
  }}
}

`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"] } }

Limits: The maximum key length is 128 characters, the maximum number of arguments is 16 and the maximum argument text length is 256 characters.

`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"] } }

Limits: The maximum key length is 128 characters, the maximum number of arguments is 16 and the maximum argument text length is 256 characters.

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.

Limits: The maximum title and subtitle text length are 256 characters. The maximum body text length is 2048 characters.

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

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.

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

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, see 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
  }
}

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.

`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

`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

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

W3C Push Notification Payload Handling¶

The W3C Push Service enables browser notifications in web pages, see W3C Push Notifications.

mobile services sends the generic properties only, when no w3c.blob specific values are set.

{
   "alert": "Updates Available",
   "badge": 1,
   "data": "{\"URL\":\"https://acme.com/message/1234\"}",
   "priority": "high",
   "sound": "DefaultNotificationSound"
}

is sent as

{
   "alert": "Updates Available",
   "badge": 1,
   "data": {"URL":"https://acme.com/message/1234"},
   "priority": "high",
   "sound": "DefaultNotificationSound"
}

W3C `priority`¶

The message priority. Known values are very-low, low, normal (default) and high.

W3C `w3c.ttl`¶

The time-to-live (TTL) value for this message in seconds. Maximum is 2419200 seconds (default) or 28 days.

Last update: April 25, 2023

Native Provider Notification Handling¶

Customer Events¶

Common Notification Properties¶

alert¶

badge¶

sound¶

data¶

priority¶

Push Provider Specific Notification Properties¶

APNS Push Notification Payload Handling¶

Notification¶

Differences Between API Version 1 and Version 2¶

Common Notification Properties (APNS)¶

alert (APNS)¶

alert Value as a String¶

alert Value as a JSON Object Converted to a String¶

badge (APNS)¶

sound (APNS)¶

data (APNS)¶

priority (APNS)¶

APNS Specific Properties¶

apns.expiry (APNS)¶

apns.category(APNS)¶

apns.contentAvailable(APNS)¶

apns.pushType(APNS)¶

apns.topic (APNS)¶

apns.customSound(APNS)¶

apns.localizedAlertKey and apns.localizedAlertArguments (APNS)¶

apns.localizedAlertTitleKey and apns.localizedAlertTitleArguments (APNS)¶

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

apns.mutableContent (APNS)¶

Other APNS Properties¶

FCM Push Notification Payload Handling¶

Payload Handling for FCM¶

JSON Payload Support for FCM Push Notifications¶

priority (FCM)¶

gcm.title¶

gcm.body¶

gcm.icon¶

gcm.sound¶

gcm.collapseKey¶

gcm.timeToLive¶

gcm.restrictedPackageName¶

Other Supported Parameters¶

Notification Element Validation¶

WNS Push Notification Payload Handling¶

Payload Handling for WNS¶

WNS-Specific Properties¶

wns.badge (WNS)¶

wns.rawData¶

wns.version¶

wns.lang¶

wns.schema¶

wns.tileTemplate¶

wns.toastTemplate¶

wns.message¶

wns.baseUri¶

wns.audio¶

wns.image¶

wns.commands¶

W3C Push Notification Payload Handling¶

W3C priority¶

W3C w3c.ttl¶

`alert`¶

`badge`¶

`sound`¶

`data`¶

`priority`¶

`alert` (APNS)¶

`alert` Value as a String¶

`alert` Value as a JSON Object Converted to a String¶

`badge` (APNS)¶

`sound` (APNS)¶

`data` (APNS)¶

`priority` (APNS)¶

`apns.expiry` (APNS)¶

`apns.category`(APNS)¶

`apns.contentAvailable`(APNS)¶

`apns.pushType`(APNS)¶

`apns.topic` (APNS)¶

`apns.customSound`(APNS)¶

`apns.localizedAlertKey` and `apns.localizedAlertArguments` (APNS)¶

`apns.localizedAlertTitleKey` and `apns.localizedAlertTitleArguments` (APNS)¶

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

`apns.mutableContent` (APNS)¶

`priority` (FCM)¶

`gcm.title`¶

`gcm.body`¶

`gcm.icon`¶

`gcm.sound`¶

`gcm.collapseKey`¶

`gcm.timeToLive`¶

`gcm.restrictedPackageName`¶

`wns.badge` (WNS)¶

`wns.rawData`¶

`wns.version`¶

`wns.lang`¶

`wns.schema`¶

`wns.tileTemplate`¶

`wns.toastTemplate`¶

`wns.message`¶

`wns.baseUri`¶

`wns.audio`¶

`wns.image`¶

`wns.commands`¶

W3C `priority`¶

W3C `w3c.ttl`¶