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 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 key/value map. The object is not shown in the notification, but can be used by the mobile app notification handler. Android only support maps/key value pairs and other JSON objects are ignored.

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.

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.

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

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

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

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

gcm.icon

Allows you to decorate the message with an app icon, other than the default one. The icon resource must be present in the app resources.

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

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": "TheIcon",
     "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.

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: September 27, 2021