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

   • push_single: Allow sending a push notification to a single device

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

   • push_all: Allow sending push notifications to all registered users of this application

   • pushregistrations_read: Retrieve registered device information

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

Java Integration for SAP Mobile Services

Java integration for SAP Mobile Services consists of an open source library, available in Maven Central. Please see GitHub: Java integration for SAP Mobile Services for detailed information and library contents.

Add the following dependency to the pom.xml:

<dependency>
    <groupId>com.sap.cloud.platform.mobile.services</groupId>
    <artifactId>java-integration</artifactId>
    <version>0.1.0</version>
</dependency>

To connect using a SAP Mobile Services settings file, create the settings file with the following content:

{
  "server": "https://any.mobile.application.url.com",
  "platform": "CF",
  "applicationId": "applicationId",
  "services": [
    {
      "name": "push",
      "serviceKeys": [
        {
          "alias": "myAlias",
          "url": "https://service.key.url.com/2787d5ea-17cb-4c71-85ca-a9600d4b97c9",
          "apiKey": "apiKey"
        }
      ]
    }
  ]
}

Sending Push Notifications and Response Handling

Typical push notification use cases include: notifying all devices, a list of users, or a specific device. See Advanced Push Use Cases for additional push notification use cases.

Some requests make use of URL parameters to define the recipients, such as: user name, device ID, and so on. URL parameters are noted as {placeholder} in the following requests. The actual values must be URL-encoded.

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

Java

MobileServicesSettings mobileServicesSettings = MobileServicesSettings.fromResource("mobileservices.json");
PushClient pushClient = new PushClientBuilder().build(mobileServicesSettings);

PushResponse response = pushClient.pushToUsers(Collections.singleton("user1"),
        PushPayload.builder().alert("Hello World").build());

Push to Device

Sending single notifications 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 Native Provider Notification Handling for additional parameters, like sound, badge, and so forth.

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/{username}/devices/{deviceId}/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/{username}/devices/{deviceId}/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"alert" : "Hello World"}'

Java

MobileServicesSettings mobileServicesSettings = MobileServicesSettings.fromResource("mobileservices.json");
PushClient pushClient = new PushClientBuilder().build(mobileServicesSettings);

PushResponse response = pushClient.pushToDevice("user1", "deviceId",
        PushPayload.builder().alert("Hello World").build());

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. Please review the push results for details for queued or unprocessable messages.

• 202 Accepted: Returned by push to device only. The request was accepted and the notification has been queued by the service. The communication with the native push provider failed. The native push provider will block notifications when sending too many unprocessable messages.

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

• 404 Not Found: User, device, capability was not found or the path is invalid. Please review the returned error message for details.

• 422 Unprocessable Entity: The notification was rejected by the native push provider. Please review the push results. Do not try to resend the notification to this target without fixing the root cause, because this can cause the native push provider to block any notification requests.

• 429 Too Many Requests: You have reached the maximum number of notifications for your trial account.

• 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,
            "message": "The payload was rejected by APNS: DeviceTokenNotForTopic"
        },
        {
            "target": "AC477C60-FDEF-4006-8B0C-201BBE7CD1F9",
            "notificationId": "176a345c-04b1-4ef3-8474-b7d5b4011c1d",
            "code": 0,
            "message": "success"
        }
    ]
}

Possible status codes are:

• -1 - Notification was queued. The communication with the native push provider failed.

• 0 - Notification was sent.

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

• 4 - The notification configuration has expired.

• 5 - The push token in the registration is missing. The device must obtain a new push token.

• 6 - The device token was rejected by the native push provider.

• 7 - The device registration has expired and the device must register again.

• 8 - Too many notifications were sent to the device and the notification was rejected. Notifications will resume once the number is reduced.

• 9 - The native notification is too large. Reduce the notification size.

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

• 11 - Recoverable IO problem while sending the notification to the native push provider. The notification was queued.

• 12and 13 - The communication with the native push provider failed. The notification was not queued. Please retry later and raise a support ticket with the full request and response, including headers and body.

• 14 - The notification quota for the push provider has been exceeded. Reduce the number of notifications sent by the back-end for this native push provider.

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/{notificationId}/status \
-H 'accept: application/json' -u ${PUSH_USER}

POWERSHELL

curl.exe ${PUSH_URL}/mobileservices/push/v1/backend/notifications/{notificationId}/status \
    accept: application/json' -u ${PUSH_USER}

Java

NotificationStatusResponse status = pushClient.getNotificationStatus("notificationId");

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.

Queued Notification

The push notification service queues a notification when communication issues with the native push provider occur and tries to resend it with low priority. New notification requests are handled with priority over queued notifications. The service discards the notification after three retries. The native push provider blocks the push service instance when too many notifications, or notifications with errors, are sent. All notification requests are queued and not delivered to the device. Regenerate the push configuration at the native push provider and register all devices to send device notifications again.

Advanced Push Use Cases

Push to Topic

It is important to strive for the right balance of mobile notifications so that users maintain interest and don't ignore important notifications. One way to maintain interest is to group notifications into topics and allow device users to subscribe and unsubscribe to topics. Use the Push to Topic method to send a notification to either all users or a list of users that are subscribed to the topic.

The topic is defined between the mobile app and the notification producer and no validation is performed by mobile services.

The topics list is mandatory and must contain at least one topic. When a device is subscribed to multiple topics of the topics list, only one notification is send.

The users list is optional. When provided, the notifications are filtered by users and subscriptions.

Push to Topic supports localization on the back end, see Localized Push Notification. Provide the fallback notification definition only on app-based push localization.

HTTP

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

{
    "users" : [
        "user1" , "user2", ...
    ],
    "topics" : [
        "topic1", "topic2", ...
    ],
    "notification": {
        "notification": {
            "alert": "Hello!"
        },
        "notifications": {
            "en_US": {
                "alert": "Howdie!"
            },
            "de": {
                "alert": "Guten Tag!"
            }
        }
    }
}

BASH

curl -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/topics/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":["user1"],"topics":["topic1"],"notification":{"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'

POWERSHELL

curl.exe -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/topics/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":["user1"],"topics":["topic1"],"notification":{"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'

Java

MobileServicesSettings mobileServicesSettings = MobileServicesSettings.fromResource("mobileservices.json");
PushClient pushClient = new PushClientBuilder().build(mobileServicesSettings);

PushResponse response = pushClient.pushToTopic(Collections.singleton("user1"), Collections.singleton("topic1"),
        LocalizedPushPayload.builder()
                .notification(PushPayload.builder().alert("Hello World").build()).build());

Push to Application

Sending notifications to all users that are registered for the given application.

HTTP

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

{
    "alert" : "Hello World"
}

BASH

curl -X POST ${PUSH_URL}/mobileservices/push/v1/backend/applications/${PUSH_APP}/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 \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"alert" : "Hello World"}'

Java

MobileServicesSettings mobileServicesSettings = MobileServicesSettings.fromResource("mobileservices.json");
PushClient pushClient = new PushClientBuilder().build(mobileServicesSettings);

PushResponse response = pushClient.pushToApplication(PushPayload.builder().alert("Hello World").build());

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/capabilities/{capability}/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/capabilities/{capability}/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/capabilities/{capability}/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":[{"formFactor":["phone"],"user":"user1"}],"notification":{"alert":"Hello World"}}'

Java

MobileServicesSettings mobileServicesSettings = MobileServicesSettings.fromResource("mobileservices.json");
PushClient pushClient = new PushClientBuilder().build(mobileServicesSettings);

PushResponse response = pushClient.pushToCapability("capability",
        PushToCapabilitiesPayload.builder()
                .capabilityUsers(Collections.singletonList(
                        CapabilityUser.builder().formFactor(Collections.singletonList("phone")).build()))
                .notification(PushPayload.builder().alert("Hello World").build()).build());

Push to Push Group

Send notifications to all users registered for the given application and group.

HTTP

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

{
    "alert" : "Hello World"
}

BASH

curl -X POST ${PUSH_URL}/mobileservices/push/v1/backend/applications/applicationId/groups/{group}/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/applicationId/groups/{group}/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"alert":"Hello World"}'

Java

MobileServicesSettings mobileServicesSettings = MobileServicesSettings.fromResource("mobileservices.json");
PushClient pushClient = new PushClientBuilder().build(mobileServicesSettings);

PushResponse response = pushClient.pushToGroup("group", PushPayload.builder().alert("Hello World").build());

Get Registered Devices

The notification producer can retrieve device registration information via the registration endpoint. The registrations can be filtered on a single registration, all registrations, a username, or push group.

Get Registration by Registration ID

The notification producer receives the registration ID in the push responses. This method allows the producer to retrieve additional information.

HTTP

GET {servicepath}/mobileservices/push/v2/backend/registrations/{registrationId} HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***

BASH

curl ${PUSH_URL}'/mobileservices/push/v2/backend/registrations/{registrationId}' \
    -H 'accept: application/json' -u ${PUSH_USER}

POWERSHELL

curl.exe ${PUSH_URL}'/mobileservices/push/v2/backend/registrations/{registrationId}' \
    -H 'accept: application/json' -u ${PUSH_USER}

Example response:

{
  "id": "F848A83E-FFDD-40F6-A88D-D672794592E9",
  "device": "7027c327e3e51945",
  "deviceModel": "Android",
  "formFactor": "tablet",
  "pushGroup": "all",
  "pushProvider": "android",
  "userLocale": "en",
  "username": "john.doe@acme.com"
}

Get Registrations by Username or Push Group

The get registrations endpoint allows you to retrieve push registrations by user name or push group.

By Username

HTTP

GET {servicepath}/mobileservices/push/v2/backend/registrations?username={username} HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***

BASH

curl ${PUSH_URL}'/mobileservices/push/v2/backend/registrations?username={username}' \
    -H 'accept: application/json' -u ${PUSH_USER}

POWERSHELL

curl.exe ${PUSH_URL}'/mobileservices/push/v2/backend/registrations?username={username}' \
    -H 'accept: application/json' -u ${PUSH_USER}

Example response:

{
  "value": [
    {
      "id": "F848A83E-FFDD-40F5-A88D-D672794592E9",
      "device": "7027c327e3e51945",
      "deviceModel": "Android",
      "formFactor": null,
      "pushGroup": "admin",
      "pushProvider": "android",
      "userLocale": "fr",
      "username": "joana.doe@acme.com"
    }
  ]
}

By Push Group

HTTP

GET {servicepath}/mobileservices/push/v2/backend/registrations?pushGroup={group} HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***

BASH

curl ${PUSH_URL}'/mobileservices/push/v2/backend/registrations?pushGroup={group}' \
    -H 'accept: application/json' -u ${PUSH_USER}

POWERSHELL

curl.exe ${PUSH_URL}'/mobileservices/push/v2/backend/registrations?pushGroup={group}' \
    -H 'accept: application/json' -u ${PUSH_USER}

Example response:

{
  "value": [
    {
      "id": "F848A83E-FFDD-40F5-A88D-D672794592E9",
      "device": "7027c327e3e51945",
      "deviceModel": "Android",
      "formFactor": null,
      "pushGroup": "admin",
      "pushProvider": "android",
      "userLocale": "es",
      "username": "joana.doe@acme.com"
    }
  ]
}

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: August 17, 2022