Skip to content

Manage Mobile Push Notification Registrations via the REST API

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

Supported Native Push Provider

SAP Cloud Platform 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

Please review Push Service Providers documentation for details and restrictions.

Device ID and Anonymous User

SAP Cloud Platform 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 Cloud Platform 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 Cloud Platform 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 a mobile app is capable to use multiple service configuration with different service keys. The mobile app can retrieve the notification service information and use it to retrieve a push token from the push provider.

    Request:

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

    Response:

    {
      "pushId" : "abcdefg",
      "applicationId": "com.sap.mobile.example",
      "operatingSystem": "android"
    }
    
  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 without device ID:

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

    Request with device ID:

    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 body is incorrect. 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 Cloud Platform Mobile Services 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.

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, used for reporting only. For localized notifications use the Native Push Provider localization capabilities please.

timeZone

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

lastKnownLocation

Optional, used for reporting only. The property format is:

{
  "latitude": "49.2937232",
  "longitude": "8.6430329"
}

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 SAP Mobile Service 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:

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

Last update: September 30, 2020