Sending Notifications via the REST API

This page describes the remaining steps to generate push notifications, after your mobile application is registered and configured for push.

The first part is to allow the back end to access the Notification REST API, followed by common push notification uses cases and response handling. Generic notification, APNS and Fiori Cloud-specific notification properties are covered too, but for details see the Push Service Providers documentation. Finally, this page also reflects how the back end can retrieve the notification status.

Initial Configuration for Push Notification Producer

After enabling mobile applications to register and consume push notifications, you need to allow the producer to generate push notifications.

The following chapters also guides you to get the Push REST API base URL that is used as placeholder in the following examples.

Cloud Foundry

The setup process on Cloud Foundry creates a Service Key that is used by the producer to authenticate against the mobile service instance. The service key is bound to a mobile application. Each role, application, organization or space results in a different service key. The service key changes if you recreate it.

1. Navigate to the application and select the Mobile Push Notification feature, and select the Service Keys tab.

2. Create a new Service Key by pressing Select at least one of the following roles for notification producers

   1. push_single: Allow sending a push notification to a single user or device

   2. push_all: Allow sending push notifications to all registered users of this application or capability

   3. push_multiple: Allow sending of notifications to multiple users with one request

This creates a new service key.

The service key now can be used to send notifications. The URL is the service path, used in the push examples- The alias and API Key provides the required Basic Authentication for this URL.

Environment Variables for cURL Examples

Copy the data from the newly created Service Key into environment variables. The API Key already includes the application name and is ignored when calling the back-end API using an API key, but we encourage to set it correctly:

Example using Unix Shell:

BASH

export PUSH_USER="backend:999999fcef9999984299f1263232502158aaca9a1aa9e81fe0c2dbe78943fe40"
export PUSH_URL=https://service-push-p0123456.cfapps.sap.hana.ondemand.com/5f9b5b8d-ffeb-4330-b607-638a0184a990
export PUSH_APP=any

POWERSHELL

set PUSH_USER "backend:999999fcef9999984299f1263232502158aaca9a1aa9e81fe0c2dbe78943fe40"
set PUSH_URL https://service-push-p0123456.cfapps.sap.hana.ondemand.com/5f9b5b8d-ffeb-4330-b607-638a0184a990
set PUSH_APP any

Sending Push Notifications and Response Handling

This paragraph focuses on typical push notification use cases, notifying all devices of a list of users or a specific device. See Advanced Push Use Cases for additional push notification use cases

Push to Users

Sending notifications to multiple users and their registered devices (for this application). Please Note The user ID is case sensitive and matches how it's returned by the identity provider.

Note

apns and gcm defines target platform specific notification properties. gcm is used for Google Firebase Cloud Messaging which has replaced Google Cloud Messaging.

HTTP

POST {servicepath}/mobileservices/push/v1/backend/applications/{applicationId}/notifications/users HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***

{
    "users" : [
        "user1" , "user2", ...
    ],
    "notification" : {
        "alert" : "Hello World",
        "sound" : "default",
        "apns" : {
            "category" : "immediate-action",
            "customValues" : "{\"order\" : \"4711-2314\"}"
        },
        "gcm" : {
            "delayWhileIdle" : true,
            "timeToLive" : 123456
        }
    }
}

BASH

curl -X POST ${PUSH_URL}/mobileservices/push/v1/backend/applications/${PUSH_APP}/notifications/users \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{ "users" : ["user1"],"notification" : {"alert" : "Hello World"}}'

POWERSHELL

curl.exe -X POST ${PUSH_URL}/mobileservices/push/v1/backend/applications/${PUSH_APP}/notifications/users \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{ "users" : ["user1"],"notification" : {"alert" : "Hello World"}}'

Push to Device

Sending single notification to a specific device, identified by the device ID. The device ID is usually provided by the device during push registration. A unique device ID is provided, when it's not provided during device registration. Please see *** for additional parameters, like sound, badge,...

HTTP

POST {servicepath}/mobileservices/push/v1/backend/applications/{applicationId}/users/{username}/devices/{deviceId}/notifications HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***

{
    "alert" : "Hello World",
    "sound" : "default",
    "apns" : {
        "category" : "immediate-action",
        "customValues" : "{\"order\" : \"4711-2314\"}"
    },
    "gcm" : {
        "delayWhileIdle" : true,
        "timeToLive" : 123456
    }
}

BASH

curl -X POST ${PUSH_URL}/mobileservices/push/v1/backend/applications/${PUSH_APP}/notifications/users/user1/devices/bac3ce2df47/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"alert" : "Hello World"}'

POWERSHELL

curl.exe -X POST ${PUSH_URL}/mobileservices/push/v1/backend/applications/${PUSH_APP}/notifications/users/user1/devices/bac3ce2df47/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"alert" : "Hello World"}'

Common Notification Parameter

The REST API Notification uses a set of common notification parameters that are used for APNS and Google FCM.

• alert The Notification text.

• badge Number, shown at the application icon.

• sound If default, play standard notification sound. FCM and APNS allow custom sounds, but those are defined different. Therefore, custom sounds are usable for single-platform scenarios only.

• priority Specify the notification priority. In APNS and FCM scenarios, high and medium are supported. These values are mapped directly for FCM. APNS uses the priority 10 for high and 5 for medium, see Notification Priority

Response Handling and Notification Status

All push requests response the same way via HTTP status code:

• 200 OK: The push notification has been sent directly to the notification gateway.

• 202 Accepted: The request was accepted and the notification has been queued by the service and is not directly sent to the notification gateway.

• 304 Not Modified: The request was accepted, but no registered device was found for this notification request.

• 400 Bad Request: The request payload is invalid.

• 403 Forbidden: Please ensure the user has the required role.

• 500 Internal Server Error: Please analyze the generated custom event.

In addition, the response provides notification IDs to retrieve the actual status of a single notification:

{
    "status": null,
    "pushResults": [
        {
            "target": "E436658F-A580-4BD5-B9EB-B4BFE8FF2888",
            "notificationId": "79e89d34-045e-4df1-8339-ab30fc5f8fc5",
            "code": 10,
            "notification": "The payload was rejected by APNS: DeviceTokenNotForTopic"
        },
        {
            "target": "AC477C60-FDEF-4006-8B0C-201BBE7CD1F9",
            "notificationId": "176a345c-04b1-4ef3-8474-b7d5b4011c1d",
            "code": 0,
            "notification": "success"
        }
    ]
}

Possible status codes are:

• 0 - Notification was syntactically correct and queued for processing.

• 1 - Notification was rejected because of invalid data.

• 2 - Notification was rejected because the target type was not found / invalid.

• 3 - Notification could not be queued. See error details.

• 10 - Notification was not accepted by the push gateway. See notification for details.

In case of a negative response, please review the custom events. Most likely a custom event with the same log correlation ID is generated.

Even if the push notification was accepted and queued for further processing, the notification might not be delivered. Therefore, the notification producer should get the notification status when relying on the delivery. The notification producer can use the notification ID to retrieve the status of a notification by:

HTTP

GET {servicepath}/mobileservices/push/v1/backend/notifications/{notificationId}/status HTTP/1.1
Accept: application/json
Authorization: ***

BASH

curl ${PUSH_URL}/mobileservices/push/v1/backend/notifications/cd2ae77-3d7d-4638-bea4-74f2a1fe5553/status \
-H 'accept: application/json' -u ${PUSH_USER}

POWERSHELL

curl.exe ${PUSH_URL}/mobileservices/push/v1/backend/notifications/cd2ae77-3d7d-4638-bea4-74f2a1fe5553/status \
    accept: application/json' -u ${PUSH_USER}

Response:

{
    "status": {
        "code": 0,
        "notification": null,
        "parameters": null
    },
    "statusDetails": {
        "notificationId": "1cd2ae77-3d7d-4638-bea4-74f2a1fe5553",
        "applicationId": null,
        "notificationType": "ios",
        "status": "SENT",
        "statusInfo": null,
        "caller": "push"
    }
}

In the example above, the notification was accepted by the Apple Push Gateway. The notification might not be delivered to the device when it's offline, no data connection exists, application notifications are disabled.

Advanced Push Use Cases

Push to Application

Sending notifications to all users, registered for the given application.

POST {servicepath}/mobileservices/push/v1/backend/applications/{applicationId}/notifications HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***

{
    "alert" : "Hello World"
}

Push to Capability

Push to Capability sends notifications to devices that have been registered with a certain capability. The mobile app can provide a list of capabilities in its push configuration.

Example Registration Payload:

{
  "pushToken": "*****",
  "pushGroup": "all",
  "timeZone": "MESZ",
  "formFactor": "phone",
  "capabilities": [
    {
      "name": "capability1",
      "category": "push",
      "value": "true"
    },
    {
      "name": "capability2",
      "category": "push",
      "value": "true"
    }
  ],
  "userLocale": "en",
  "deviceModel": "iPhone"
}

The registration receives a notification with the following call.

HTTP

POST {servicepath}/mobileservices/push/v1/backend/capability/capability1/name/notifications HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***

{
    "users" : [
        {
            "formFactor" : ["phone"],
            "user" : "user1"
        }
    ],
    "notification" : {
        "alert" : "Hello World"
    }
}

BASH

curl -X POST ${PUSH_URL}/mobileservices/push/v1/backend/capability/capability1/name/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":[{"formFactor":["phone"],"user":"user1"}],"notification":{"alert":"Hello World"}}'

POWERSHELL

curl.exe -X POST ${PUSH_URL}/mobileservices/push/v1/backend/capability/capability1/name/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":[{"formFactor":["phone"],"user":"user1"}],"notification":{"alert":"Hello World"}}'

Apple APNS

The push service support Apple Push, but the notification producer needs to take care some characteristics of APNS.

Localization

APNS notification are localizable via keys and parameters. The keys and localized notifications are defined and referenced via loc-key property in the alert. The key can be parameterized via loc-args. Example:

{
    "notification" : {
            "alert": "{\"loc-key\":\"APNS.helloWorld\",\"loc-args\":[\"Sample User\"]}",
    }
}

Alert Title and Body

APNS notification consists of a title and body field. You can define the JSON element directly in the alert, but it must be escaped. Example:

{
    "notification" : {
            "alert": "{\"title\":\"Hello World\",\"body\": \"This is the body of the notification\"]}",
    }
}

Background Notification

The content-available property can be used to configure background notifications. Background notifications triggers the app listener on the device. The priority is set to 5 - CONSERVE_POWER when no alert is defined. Delivery is not guaranteed when more than 3 silent notifications are sent per device and hour. Background notifications must not use ` "priority" : "high"``

Sounds

The referenced sound must be defined in the app if you set the property sound other than default. Example: "sound" : "notificationCupCake.caf"

Notification Priority

The push service is using the default APNS priority 10 for visual and 5for background notifications. You can set it to 5 by setting the notification priority parameter to normal.

Category

APNS categories can be used to define app actions that can be triggered by the user directly from the notification without opening the application. The categories are defined in the app bundle.

---

Last update: September 1, 2020