Sending Push Notifications¶

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

These steps are:

Configuring authentication by using service keys.
Constructing the push notification and configure the messaging options.
Defining the target instances of your app and sending the push notification.
Handling and understanding the response codes.
Retrieving the notification status.

The code snippets are provide in cURL (Windows PowerShell/ Unix BASH Shell) and Java, using the SAP Java Integration Library for SAP Mobile Services.

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 setup process on Cloud Foundry creates a Service Key that is used by the producer to authenticate against the mobile service instance, see Service Keys. 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.

The REST API for push notifications accepts all three authentication methods:

API Key Header X-API-KEY.
Basic Authentication with alias and service key.
X509 Service key. This is the recommended authentication method. Please use the SAP Java Integration Library for SAP Mobile Services for a turn-key implementation of this authentication method.

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_KEY="X-API-Key: 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_KEY "X-API-Key: 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>1.0.0</version>
</dependency>

Please use the correct/latest version value shown in the Getting Started - Java integration for SAP Mobile Services

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

Constructing the Push Notification and Configuring the Messaging Options¶

SAP Mobile Services allows you to send push notifications to any supported push provider. The push notification messages defines a set of common parameters that are available for most targets, but those can be overridden by provider-specifics. The provider-specific parameters are not part of this page, please see:

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.

Notification Payload Properties¶

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

Localization¶

FCM and APNs enables mobile apps to define localization bundles and on device localization via keys and parameters in the notification, however there are situations when this is not feasible, like the number of possible message templates are not known to the mobile app.

Some solutions require on-demand localized messages that cannot be bundled with the mobile app. SAP services provide localized messages based on users setting. This setting can differ from the mobile device language.

The localized push notification API extends the REST API.

Generic Processing of Localized Push Notifications¶

Mobile device push registrations contains the optional property UserLocale. This property is automatically set by the SAP BTP SDK for Android, SAP BTP SDK for iOS and Mobile Development Kit during notification key registration or update. The property reflects the user-selected device language.

The message producer provides a list that includes localized push notification and a mandatory fallback notification definition.

The push service retrieves the targets and selects the localized push notification based on the UserLocale registration value.

Language Fallback¶

The Push Notification service implements a language fallback, based on best match. The device can specify the device language, country and variant. Examples:

de-DE-bay: Bayrisch, a German dialect.
de-CH: Swiss-German
de: German

Assume that the device registers the device language de-DE-bay. The service first tries to find the localized notification using the de-DE-bay key. If not defined, the service tries to fallback to de-DE, and then to de. The default notification is used when no localized notification is defined.

Defining The Target Instances¶

SAP Mobile Services has various ways to define the notification target.

Name	Description
Push to Device	The notification target is selected by username and device ID. The device ID is generated during device push registration.
Push to Users	The notification is delivered to all push registered devices of the users. The users is specified by user name or Global User ID.
Bulk Push	Bulk Push allows to send multiple variations of a notification to multiple users in one request.
Push to Application	The notification is delivered to all push registered devices of the app.
Push to Topic	Mobile apps can subscribe to a list of interests / topics. The provider can publish a notification to all or list of users that are subscribed to this topic.
(Deprecated) Push to Group	The notification is delivered to all push registered devices with the push registration group. Please use Push to Topic instead
(Deprecated) Push to Capability	Push to Capability sends notifications to devices that have been registered with a certain capability. Please use Push to Topic instead

Specifying the Target by Username or Global User ID¶

Push to Users, Push to Topic, and Bulk Push provide a filter on users. The back end has the option to use either the username or the Global User ID, if provided during push registration. See:Configuring Push Notifications.

Info

The Global User ID value for the registration is read from the authentication property user_UUID. SAP BTP SDK for Android, SAP BTP SDK for iOS and Mobile Development Kit performs a device notification registration update as soon as the app is pulled in foreground. In some rare situations, the Global User ID is modified in the Identity Provider. The user must re-login, or the authentication token must be refreshed to update the Global User ID. SAP Mobile Services maintains a history of the Global User ID of each registration and the old Global User ID can be used by the message producer.

Push to Device¶

Sending single notifications to a specific device identified by the device ID and username. 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.

HTTP

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

{
    "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' -H ${PUSH_KEY} \
    -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' -H ${PUSH_KEY} \
    -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());

Push to Users¶

To send notifications to multiple users and their registered devices (for this application):

HTTP

POST {servicepath}/mobileservices/push/v2/backend/applications/{applicationId}/notifications/users HTTP/1.1
Content-Type: application/json
Accept: application/json
X-API-Key: ***

{
    "users" : [
        "user1" , "user2", ...
    ],
    "userUUIDs" : [
        "global-user-ID1", "global-user-ID2", ...
    ],
    "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}/notifications/users \
    -H 'content-type: application/json' -H 'accept: application/json' -H ${PUSH_KEY} \
    -d '{"users":["user1"],"userUUIDs":["userUUIDs1"],"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}/notifications/users \
    -H 'content-type: application/json' -H 'accept: application/json' -H ${PUSH_KEY} \
    -d '{"users":["user1"],"userUUIDs":["userUUIDs1"],"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.pushToUsers(Collections.singleton("user1"),
        Collections.singleton("userUUIDs1"),
        PushPayload.builder().alert("Hello World").build());

Bulk Push¶

Bulk push can be used to send push messages to multiple users. Bulk push defines a global push message and a list of user-specific messages with username or Global User ID to identify the recipient. The specific message properties override the global push message properties.

HTTP

POST {servicepath}/mobileservices/push/v2/backend/applications/{applicationID}/notifications/bulk HTTP/1.1
Content-Type: application/json
Accept: application/json
X-API-Key: ***

{
    "notification": {
        "notification": {
            "alert": "generic alert"
        }
    },
    "userNotifications": [
        {
            "userUUID": "global-user-id",
            "user": "user1",
            "notification": {
                "notification": {
                    "alert": "user alert"
                }
            }
        }
    ]
}

BASH

curl -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/notifications/bulk \
    -H 'content-type: application/json' -H 'accept: application/json' -H ${PUSH_KEY} \
    -d '{"notification":{"notification":{"alert":"generic alert"}},"userNotifications":[{"userUUID":"global-user-id","user":"user1","notification":{"notification":{"alert":"user alert"}}}]}'

PowerShell

curl.exe -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/notifications/bulk \
    -H 'content-type: application/json' -H 'accept: application/json' -H ${PUSH_KEY} \
    -d '{"notification":{"notification":{"alert":"generic alert"}},"userNotifications":[{"userUUID":"global-user-id","user":"user1","notification":{"notification":{"alert":"user alert"}}}]}'

Java

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

PushPayload notification = PushPayload.builder().alert("Hello").build();
LocalizedPushPayload pushPayload = LocalizedPushPayload.builder().notification(notification).build();
Collection<LocalizedUserNotification> userNotifications = Collections
        .singleton(LocalizedUserNotification.builder().notification(pushPayload)
                .userUUID("75122e95-fb0c-42e7-ab50-b6a02e8a3777").build());

PushResponse response = pushClient.bulkPush(null, userNotifications);

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
X-API-Key: ***

{
    "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' -H ${PUSH_KEY} \
    -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' -H ${PUSH_KEY} \
    -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 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 SAP 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 and userUUIDs lists are optional. When provided, the notifications are filtered by users and subscriptions.

HTTP

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

{
    "users" : [
        "user1" , "user2", ...
    ],
    "userUUIDs" : [
        "global-user-ID1", "global-user-ID2", ...
    ],
    "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' -H ${PUSH_KEY} \
    -d '{"users":["user1"],"userUUIDs":["userUUIDs1"],"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' -H ${PUSH_KEY} \
    -d '{"users":["user1"],"userUUIDs":["userUUIDs1"],,"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("userUUIDs1"),
        Collections.singleton("topic1"),
        LocalizedPushPayload.builder()
                .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
X-API-Key: ***

{
    "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' -H ${PUSH_KEY} \
    -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' -H ${PUSH_KEY} \
    -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());

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
X-API-Key: ***

{
    "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' -H ${PUSH_KEY} \
    -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' -H ${PUSH_KEY} \
    -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());

Handling the Notification Response and Message Status¶

HTTP Status Codes¶

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.
400 Bad Request: The request payload is invalid.
403 Forbidden: Please ensure the user has the required role.
404 Not Found: No device registration for User, device, capability was 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.

Response Message¶

In addition, the response provides notification IDs and initial status for each found registration.

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

Notification Status¶

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/v2/backend/notifications/{notificationId}/status HTTP/1.1
Accept: application/json
X-API-Key: ***

BASH

curl ${PUSH_URL}/mobileservices/push/v2/backend/notifications/{notificationId}/status \
-H 'accept: application/json' -H ${PUSH_KEY}

PowerShell

curl.exe ${PUSH_URL}/mobileservices/push/v2/backend/notifications/{notificationId}/status \
    accept: application/json' -H ${PUSH_KEY}

Java

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

Response:

{
    "status": {
        "code": 0,
        "notification": null,
        "parameters": null
    },
    "statusDetails": {
        "notificationId": "1cd2ae77-3d7d-4638-bea4-74f2a1fe5553",
        "providerReference" : "7f315519-b4a5-4fce-9901-a3c3e09dfc58",
        "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.

Possible status are:

QUEUED: The notification was not send immediately, but queued. Either it was requested during bulk push or the push provider was not available. SAP Mobile Services queued the notification and retry to send it later.
SENT: The notification was accepted by the provider.
ERROR: Sending the notification failed permanently. Please review the statusInfo property.
RECEIVED: This is an optional status and needs to be set by the mobile App. The status indicates that the message was received by the mobile app.
CONSUMED: This is an optional status and needs to be set by the mobile App. The status indicates that the message was read by the app user.
CONFIRMED: This is an optional status and needs to be set by the mobile App. The status indicates that the message was accepted by the app user.

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
X-API-Key: ***

BASH

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

PowerShell

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

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
X-API-Key: ***

BASH

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

PowerShell

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

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
X-API-Key: ***

BASH

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

PowerShell

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

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

Last update: April 9, 2024

Sending Push Notifications¶

Initial Configuration for Push Notification Producer¶

Environment Variables for cURL Examples¶

Java Integration for SAP Mobile Services¶

Constructing the Push Notification and Configuring the Messaging Options¶

Notification Payload Properties¶

alert¶

badge¶

sound¶

data¶

priority¶

Localization¶

Generic Processing of Localized Push Notifications¶

Language Fallback¶

Defining The Target Instances¶

Specifying the Target by Username or Global User ID¶

Push to Device¶

Push to Users¶

Bulk Push¶

Push to Application¶

Push to Topic¶

Push to Push Group¶

Push to Capability¶

Handling the Notification Response and Message Status¶

HTTP Status Codes¶

Response Message¶

Notification Status¶

Get Registered Devices¶

Get Registration by Registration ID¶

Get Registrations by Username or Push Group¶

By Username¶

By Push Group¶

`alert`¶

`badge`¶

`sound`¶

`data`¶

`priority`¶