Skip to content

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 add 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:

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

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.

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.

Localized Push Notification

The adoption of mobile apps can be increased by localizing them, including push notifications, as described in Translation Hub. The mobile services push feature offers two approaches to localizing mobile push notifications:

  • App-based push localization
  • Push service-based localization

App-Based Push Localization

APNS, Firebase Cloud Messaging, and Windows Messaging Service provide localized notifications using parameterized messages that are defined in the mobile app. The notification sender selects the message via key and provides the parameter values in the push message. See Native Provider Notification Handling. This is the preferred solution when:

  • The notification messages are known
  • The set of languages are known

The localized message template resources are part of the mobile app. A new mobile app is required when message templates are added or modified.

Push Service Based Localization

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. For general information on setup, sending notification and response handling, see Sending Notifications via 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.

Push to Users

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

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

{
    "users" : [
        "user1" , "user2", ...
    ],
    "userUUIDs" : [
        "global-user-ID1", "global-user-ID2", ...
    ],
    "notification": {
        "notification": {
            "alert": "Hello!"
        },
        "notifications": {
            "en_US": {
                "alert": "Howdie!"
            },
            "de": {
                "alert": "Guten Tag!"
            }
        }
    }
}
curl -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/notifications/users \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":["user1"],"userUUIDs":["userUUIDs1"],"notification" : {"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'
curl.exe -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/notifications/users \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":["user1"],"userUUIDs":["userUUIDs1"],"notification" : {"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'
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());

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.

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

GET {servicepath}/mobileservices/push/v2/backend/notifications/{notificationId}/status HTTP/1.1
Accept: application/json
Authorization: ***
curl ${PUSH_URL}/mobileservices/push/v2/backend/notifications/{notificationId}/status \
-H 'accept: application/json' -u ${PUSH_USER}
curl.exe ${PUSH_URL}/mobileservices/push/v2/backend/notifications/{notificationId}/status \
    accept: application/json' -u ${PUSH_USER}
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 and userUUIDs lists are optional. When provided, the notifications are filtered by users and subscriptions.

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

{
    "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!"
            }
        }
    }
}
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"],"userUUIDs":["userUUIDs1"],"topics":["topic1"],"notification":{"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'
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"],"userUUIDs":["userUUIDs1"],,"topics":["topic1"],"notification":{"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'
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 Application

Sending notifications to all users that are 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"
}
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"}'
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"}'
MobileServicesSettings mobileServicesSettings = MobileServicesSettings.fromResource("mobileservices.json");
PushClient pushClient = new PushClientBuilder().build(mobileServicesSettings);

PushResponse response = pushClient.pushToApplication(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.

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

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

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

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

GET {servicepath}/mobileservices/push/v2/backend/registrations/{registrationId} HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***
curl ${PUSH_URL}'/mobileservices/push/v2/backend/registrations/{registrationId}' \
    -H 'accept: application/json' -u ${PUSH_USER}
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

GET {servicepath}/mobileservices/push/v2/backend/registrations?username={username} HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***
curl ${PUSH_URL}'/mobileservices/push/v2/backend/registrations?username={username}' \
    -H 'accept: application/json' -u ${PUSH_USER}
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

GET {servicepath}/mobileservices/push/v2/backend/registrations?pushGroup={group} HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***
curl ${PUSH_URL}'/mobileservices/push/v2/backend/registrations?pushGroup={group}' \
    -H 'accept: application/json' -u ${PUSH_USER}
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 1, 2023