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.

Navigate to the application and select the Mobile Push Notification feature, and select the Service Keys tab.
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

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

-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.
10 - Notification was not accepted by the native push provider. See the 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.

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

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

Retrieve Registered Devices¶

The notification producer can retrieve device registration information via the registration OData endpoint. This endpoint is limited to reading all registrations. The response can contain personal information. Therefore, only grant the role deviceregistrations_read to trusted services.

HTTP

GET {servicepath}/mobileservices/push/v1/backend/Registrations.svc/Registrations HTTP/1.1
Accept: application/json
Authorization: ***

BASH

curl ${PUSH_URL}/mobileservices/push/v1/backend/Registrations.svc/Registrations \
-H 'accept: application/json' -u ${PUSH_USER}

POWERSHELL

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

Response:

{
  "d": {
    "results": [
      {
        "__metadata": {
          "id": "...",
          "uri": "...",
          "type": "push.Registration"
        },
        "AnonymousUser": false,
        "Created": "/Date(1623901677196)/",
        "Deleted": false,
        "Device": "8c8a49d71f106508",
        "DeviceModel": "Android",
        "FormFactor": "phone",
        "Id": "08CCB838-99AE-404C-BA81-497C26671CAC",
        "InstanceId": "5f5b5a8d-abeb-433e-b6a7-638a0184a990",
        "LastFailedNotification": null,
        "LastKnownLocation": null,
        "LastSuccessfulNotification": "/Date(1626617542289)/",
        "NotificationCount": 1,
        "PushGroup": null,
        "PushProvider": "android",
        "PushToken": "ca..",
        "TimeZone": null,
        "Updated": "/Date(1626617542289)/",
        "UserLocale": "en",
        "UserUUID": null,
        "Username": "john.doe@sap.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: July 21, 2021