Skip to content

Manage Mobile Push Notification Registrations via the REST API

SAP Mobile Services provides a REST API for managing push registration. The API is usually called by the SAP BTP SDK for Android, iOS or Mobile Development Kit. In addition, devices or browser code can call it directly.

Supported Native Push Provider

SAP Mobile Services supports the following Native Push Provider:

Native Push Provider Operating System Identifier
Apple APNs ios
Google Firebase Cloud Messaging android
Windows Notifications windows
Baidu Push baidu
W3C Browser Notifications w3cpushapi

Device ID and Anonymous User

SAP Mobile Services Mobile Notifications service can be used for rapid development by an anonymous user. Multiple anonymous users aren't supported.

The mobile app on the device is identified via a unique device ID. The device ID is used to retrieve the push token and operating system, and report optional registration details. Most operating system provides system calls to generate unique device IDs. Please use device generated device IDs when calling the REST API, but it's optional too. SAP Mobile Services generates a unique device ID internally when none is provided in the REST calls. The device ID is unique for the operating system, mobile application and logged in user and is not returned to the device. Other SAP Mobile Services uses the same ID when not provided by the device.

Register a Device for Push Notifications

A device must register for push, before it can receive native push messages. In order to register for push, the mobile apps performs the following steps.

  1. Get push service information (optional) This step is optional, but can be used if an Android mobile app has the capability to use multiple service configurations with different service keys. SAP BTP SDK for Android and Mobile Development Kit based Android apps use information from the google-services.json configuration file.

    W3C Web apps must retrieve the server-generated public key by calling this API.

    Request:

    GET {servicepath}/mobileservices/push/v1/runtime/applications/{applicationId}/pushconfigurations/os/w3cpushapi/pushid HTTP/1.1
    Accept: application/json
    Authorization: ***
    

    Response:

    {
      "pushId" : "abcdefg",
      "operatingSystem": "w3cpushapi"
    }
    
  2. Get push device token from the native push provider The mobile app generates a device token using the native push providers API. For details, consult the API documentation of the push provider

  3. Register for push, using the device token from the push provider Finally, the mobile app registers for push by calling the Push Notification Service. The push notification service will create a device ID that can be used to update the push device token or unregister from the service. The device ID is unique for the user ID and operating system identifier, therefore, the mobile app must provide a unique identifier when a user can register multiple devices.

    Request with device ID in header:

    POST {servicepath}/mobileservices/push/v1/runtime/applications/{applicationId}/os/{operatingSystem}/devices HTTP/1.1
    Accept: application/json
    X-SMP-DEVICEID: {deviceId}
    Authorization: ***
    
    {
      "pushToken" : "aabbccddeeffgghh"
    }
    

    Request with device ID in request path:

    POST {servicepath}/mobileservices/push/v1/runtime/applications/{applicationId}/os/{operatingSystem}/devices/{deviceId} HTTP/1.1
    Accept: application/json
    Authorization: ***
    
    {
      "pushToken" : "aabbccddeeffgghh"
    }
    

    Response from service:

    • 201: The registration request was successful. The response text contains the provided information in the request.
    • 400: The request is incorrect or the device ID is not provided. Please see the following paragraph.
    • 409: The request was issued by an anonymous user and this user is already registered
    • 404: The application ID is not found on the server. Please review the list of configured applications in the SAP mobile service cockpit. The operating system is not supported.
    • 503: The service is currently down. Please retry.

    The registration payload is described in the following paragraph

Registration Payload

deviceModel

Optional, defines the device model for reporting.

pushToken

The push service token is retrieved by the device from the Native Push Provider and used to address the device.

pushGroup

Optional. Allows the notification producer to send a notification to a group of devices registered for an application. The device can specify the push group during registration.

formFactor

Optional, but required when using Push to capability and describes the form factor of the device. Supported values are: phone, tablet, browser

capabilities

A list of device capabilities for push. A capability entity is using the following three mandatory properties:

  • category always push
  • name the capability identifier
  • value any value. Not used, but mandatory

Example:

"capabilities": [
  {
    "category": "push",
    "name": "push.subscriptions",
    "value": "true"
  }
]

userLocale

Optional, but used for [Server Localized Push Notification](./sending-push.md#localization.

timeZone

Optional, used for reporting only. The time zone is provided by the device and can be localized.

lastKnownLocation

The property lastKnownLocation is provided for legacy reasons. The device's last known location is not stored or returned by the push service.

Update Device Registration

The mobile app can update the push token only when it has provided a device ID during push registration. Please delete and create a new device registration when using the mobile services generated device ID.

Request with device ID:

PATCH {servicepath}/mobileservices/push/v1/runtime/applications/{applicationId}/os/{operatingSystem}/devices/{deviceId} HTTP/1.1
Accept: application/json
Authorization: ***

Response from service:

  • 200: Registration was updated.
  • 400: The request did not contain all required information.
  • 404: The device ID, application ID or operating system was not found.
  • 503: The service is currently down. Please retry.

Get Device Registration

The mobile app can get the push token only when it has provided a device ID during push registration.

Request with device ID:

GET {servicepath}/mobileservices/push/v1/runtime/applications/{applicationId}/os/{operatingSystem}/devices/{deviceId} HTTP/1.1
Accept: application/json
Authorization: ***

Response from service:

  • 200: Registration was found and is returned
  • 404: The device ID, application ID or operating system was not found.
  • 503: The service is currently down. Please retry.

Delete Device Registration

As a good citizen, the mobile app should remove the push registration when it is reset or deleted from the device. The mobile app must provide the device ID that was used for push registration.

Request without device ID:

DELETE {servicepath}/mobileservices/push/v1/runtime/applications/{applicationId}/os/{operatingSystem}/devices HTTP/1.1
Accept: application/json
Authorization: ***

Request with device ID:

DELETE {servicepath}/mobileservices/push/v1/runtime/applications/{applicationId}/os/{operatingSystem}/devices/{deviceId} HTTP/1.1
Accept: application/json
Authorization: ***

Response from service:

  • 204: Registration was deleted.
  • 404: The device ID, application ID or operating system was not found.
  • 503: The service is currently down. Please retry.

Topic Subscriptions

If you are producing notifications, define topics that can be used to group notifications by type or interest, such as Patches, New Features, or Security. Device users can subscribe to topics of choice, and only receive notifications for subscribed topics. This helps application users remain interested in device notifications.

Topics aren't managed by the service and no validation is performed. Topics are part of the contract between mobile apps and the notification producer.

The notification services provides the following methods for subscriptions:

Get Active Topic Subscriptions

The mobile app can retrieve all active subscriptions via the following GET request. The query parameter $count=true is optional and, if set, the number of active subscriptions is returned in the response.

GET {servicepath}/mobileservices/push/v2/runtime/applications/{applicationId}/os/{operatingSystem}/devices/{deviceId}/topics?$count=true HTTP/1.1
Accept: application/json
Authorization: ***

Responses from the service:

  • 200: The active subscriptions are returned. Example response from the service:
  {
    "count": 2,
    "value": [
      "sales",
      "marketing"
    ]
  }
  • 404: The device ID and user are not registered for push.

Subscribe to Topic

The mobile app can add a new topic subscription with the following POST request without a body:

POST {servicepath}/mobileservices/push/v2/runtime/applications/{applicationId}/os/{operatingSystem}/devices/{deviceId}/topics/topic HTTP/1.1
Accept: application/json
Authorization: ***

Responses from the service:

  • 201: The subscription was created.
  • 400: The topic is longer than 64 characters or 32 topics are subscribed. See error message for details.
  • 404: The device ID and user are not registered for push.

Unsubscribe to Topic

The mobile app can unsubscribe from a topic using the following DELETE request;

DELETE {servicepath}/mobileservices/push/v2/runtime/applications/{applicationId}/os/{operatingSystem}/devices/{deviceId}/topics/topic HTTP/1.1
Accept: application/json
Authorization: ***

Responses from the service:

  • 204: The subscription was removed or the user was not subscribed to the topic.
  • 404: The device ID and user are not registered for push.

Manage Push Registration On Behalf of Another

The REST-API provides methods to manage push registrations on behalf of a user or entity, without access to the running devices. This can be used in support cases.

Setup

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 Mobile Push Notification > Service Keys.

  2. Create a new Service Key by pressing add Select the role register_onbehalf. This creates a new service key.

The service key can now be used to manage push registrations on behalf of the user. The URL is the service path, used in the push examples; the Alias and API Key provide 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 REST API using an API key, but we encourage setting it correctly. Please retrieve the DEVICE_ID for the targeted device.

Example using Unix Shell:

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
export OS=android
export DEVICE_USER=john.doe@acme.com
export DEVICE_ID=A11C8CDE-504D-4469-8E99-C28EDA210CAB
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
set OS=android
set DEVICE_USER=john.doe@acme.com
set DEVICE_ID=A11C8CDE-504D-4469-8E99-C28EDA210CAB

Register for Push

Obtain the push token upfront and modify the token value in the JSON payload of the example request.

POST {servicepath}/mobileservices/push/v1/runtime/applications/{applicationId}/os/android/usernames/john.doe@acme.com/devices/aabbccdd HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***

{
    "pushToken" : "aabbccddeeffgghh"
}
curl -v -X POST ${PUSH_URL}/mobileservices/push/v1/runtime/applications/${PUSH_APP}/os/${OS}/usernames/${DEVICE_USER}/devices/${DEVICE_ID} \
  -u ${PUSH_USER}  -H 'content-type: application/json' -H 'accept: application/json' -d '{"pushToken" : "aabbccddeeffgghh"}'
curl.exe -v -X POST ${PUSH_URL}/mobileservices/push/v1/runtime/applications/${PUSH_APP}/os/${OS}/usernames/${DEVICE_USER}/devices/${DEVICE_ID} \
  -u ${PUSH_USER}  -H 'content-type: application/json' -H 'accept: application/json' -d '{"pushToken" : "aabbccddeeffgghh"}'

Update Existing Push Registration

PATCH {servicepath}/mobileservices/push/v1/runtime/applications/{applicationId}/os/android/usernames/john.doe@acme.com/devices/aabbccdd HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***

{
    "pushToken" : "aabbccddeeffgghh"
}
curl -v -X PATCH ${PUSH_URL}/mobileservices/push/v1/runtime/applications/${PUSH_APP}/os/${OS}/usernames/${DEVICE_USER}/devices/${DEVICE_ID} \
  -u ${PUSH_USER}  -H 'content-type: application/json' -H 'accept: application/json' -d '{"pushToken" : "aabbccddeeffgghh"}'
curl.exe -v -X PATCH ${PUSH_URL}/mobileservices/push/v1/runtime/applications/${PUSH_APP}/os/${OS}/usernames/${DEVICE_USER}/devices/${DEVICE_ID} \
  -u ${PUSH_USER}  -H 'content-type: application/json' -H 'accept: application/json' -d '{"pushToken" : "aabbccddeeffgghh"}'

Delete Existing Push Registration

DELETE {servicepath}/mobileservices/push/v1/runtime/applications/{applicationId}/os/android/usernames/john.doe@acme.com/devices/aabbccdd HTTP/1.1
Accept: application/json
Authorization: ***
curl -v -X DELETE ${PUSH_URL}/mobileservices/push/v1/runtime/applications/${PUSH_APP}/os/${OS}/usernames/${DEVICE_USER}/devices/${DEVICE_ID} \
  -u ${PUSH_USER} -H 'accept: application/json'
curl.exe -v -X DELETE ${PUSH_URL}/mobileservices/push/v1/runtime/applications/${PUSH_APP}/os/${OS}/usernames/${DEVICE_USER}/devices/${DEVICE_ID} \
  -u ${PUSH_USER} -H 'accept: application/json'

Last update: December 6, 2023