Skip to content

Configuring Push Notifications

Defining Push Notifications

Configure push-related settings for the selected application.

Use native push to send push notifications. The push listener service provided with SAP Mobile Services allows back-end systems to send native notifications to devices. Application developers must enable push notification code in applications. You can also use the native push mechanism to push notifications to a subset of users.

Note

Text message (SMS) support is not available.

For the selected application, select Mobile Push Notification under Assigned Features (or add it first).

  • Select Configuration to configure push notifications at the provider level (PaaS).

    Note

    For Native/MDK apps managed in a one-app cockpit (SaaS), the subscriber administrator can enable or disable push notifications sent to app subscribers. See Enabling / Disabling Push for Subscribers (SaaS).

  • Select Push Registrations to view current registrations and send push notifications. See Sending Push Notifications to send a message.

  • Select Service Keys to view and manage API keys. See Service Keys to manage service keys. See Sending Notifications via the REST API to send push messages from back-end systems.

  • Select Info to view feature details and to download mobile service data in JSON format.

Firebase Cloud Messaging Canonical IDs

For Firebase Cloud Messaging (FCM) clients, canonical IDs prevent problems that could occur if a client application inadvertently triggers multiple registrations for the same device. For example, the device could receive duplicate messages.

If a FCM client application sends a message that contains an old registration ID, FCM processes the request and inserts the canonical ID into the registration_id field of the response.

SAP Mobile Services:

  • Replaces the old registration ID that is stored for the device with the canonical ID.

  • Uses the canonical ID for sending messages to the device.

  • Logs a customer event to inform the client of updated or deleted device registrations that result from managing canonical registration IDs.

Enabling Predefined Push for SAP Mobile Apps

Enable or disable preconfigured push settings.

  1. In SAP mobile service cockpit, select Mobile Applications.

  2. Select an application, then select Mobile Push Notification under Assigned Features (or add it first); for SAP Mobile Cards select Features > Push Notification.

  3. Under Predefined Global Push Configuration > Predefined for select a predefined push configuration when using one of the official SAP mobile apps. Leave it blank when you use your own APNs or Android push configuration.

    Note

    Predefined push configuration is only supported for the app store version for iOS and Android.

    • SAP Fiori Client for B2B ‒ push configuration for SAP Fiori Client for B2B.

    • SAP Mobile Services Client ‒ push configuration for the client of the Mobile Development Kit.

    • SAP Asset Manager ‒ push configuration for SAP Asset Manager.

  4. Click Save.

Configuring Push for Android Apps

To enable client applications to receive Firebase Cloud Messaging (FCM) notifications, configure Android push notifications.

You can use the HTTP version 1 API, which uses a Firebase Service Account Private Key as the credential; or the legacy deprecated HTTP API with Sender ID and Server Key.

Note

SAP mobile service cockpit currently supports both methods. Google has deprecated the legacy HTTP API that uses Server Key authentication and will discontinue the authentication in June 2024. You must update your configuration to Firebase Service Account Private Key beforehand.

  1. In SAP mobile service cockpit, select Mobile Applications.

  2. Select an application, then select Mobile Push Notification under Assigned Features (or add it first); for SAP Mobile Cards select Features > Push Notification.

  3. Under Android, select whether to use Firebase Service Account Private Key or Server Key for push credentials.

    • For Firebase Service Account Private Key:

    • In Service Account Private Key File, browse to select the private key file that you downloaded from the Firebase platform.

    • If the file is valid, the remaining fields are populated automatically using values in the private key file.

      Properties Description
      Project ID The project ID named in the private key file.
      Private Key ID The private key ID named in the private key file.
      Client Email The client email named in the private key file.
    • For Server Key (Deprecated):

      Properties Description
      Access Key The access key you obtained for your Google API project (see Firebase Cloud Messaging).
      Sender ID The project Identifier.
  4. Click Save.

Configuring Push for iOS Apps

Configure APNs push notifications for the selected iOS client application or SAP Mobile Cards.

You can use either certificate or token-based authentication for APNs. The advantage of using token-based authentication is that the credentials do not expire automatically, whereas APNs certificates usually expire after one year. You can manually control the lifecycle of the key used for token-based authentication in developer.apple.com. Obtain the credentials used for token-based authentication from your developer account on developer.apple.com.

  1. In SAP mobile service cockpit, select Mobile Applications.

  2. Select an application, then select Mobile Push Notification under Assigned Features (or add it first); for SAP Mobile Cards select Features > Push Notification.

  3. To configure APNs for a development and testing environment, select Sandbox or Production. See Apple Developer - Certificates for certificate types and how to retrieve.

    • Select Sandbox if your mobile app is signed with an iOS Development Certificate.

    • Select Production if your mobile app is signed with an iOS Distribution Certificate.

    • Select None if you don't want to receive APNs push notifications.

  4. Choose either Certificate or Token-Based as the authentication type. (Optional)

    • For Certificate:

      1. Select Browse to navigate to the APNs certificate file, select the file, and click Open.

      2. Enter a valid password.

      3. (Optional) Identify the topic bundle ID that is specific to the iOS application you're setting up to receive notifications. If not configured, the bundle ID is extracted from the certificate.

    • For Token-Based:

      Token Properties

      Property Description
      Topic (Bundle ID) The bundle ID that is specific to the iOS application you're setting up to receive notifications.
      Team ID The 10-character team ID you use for developing your company's apps. Obtain this value from your developer account.
      Key ID The 10-character string that is provided by Apple when you create a key.
      Key (P8) The authentication token signing key (.p8) file that you've downloaded from Apple. Select Browse to navigate to the APNs key file, select the file, and click Open.
  5. Save your changes.

Configuring Windows Push Notification

To enable the back-end servers connected with SAP Mobile Services to send toast, tile, badge, and raw updates to Windows desktop and tablet application users, configure Windows push notifications for the selected application.

  1. In SAP mobile service cockpit, select Mobile Applications.

  2. Select an application, then select Mobile Push Notification under Assigned Features (or add it first); for SAP Mobile Cards select Features > Push Notification.

  3. Under WNS, enter the application credentials, which are provided by the application developer.

    Property Description
    Package SID Package security identifier
    Client Secret Client secret information
  4. Click Save.

Configuring Baidu Push Notification

Baidu provides a push notification routing service for users in some countries/regions. To enable this feature, configure mobile services to connect to the service.

You must subscribe to the Baidu service and obtain Baidu account credentials that include an API key and a secret key.

Because Google services are blocked in some countries/regions, SAP uses Baidu to send push notifications to users. mobile services supports two Baidu push modes:

  • Notification Mode ‒ the message is delivered to the system tray (default).

  • Transparent Mode ‒ the application determines what to do with the message. The application must include the parameter setting "msgType": 0 in the push back-end API, which indicates that transparent mode should be used.

To trigger a transparent message for Baidu push, add the property "msgType": 0 to the message body.

{
"users": ["user id"],
"notification": {
"alert": "*** 消息内容 baidu message from MS ***",
"badge": 1,
"sound": "sound",
"priority": "priority",
"data": "

{\"key\":\"value\"}
",
"sendAsSms": false,
"apns": null,
"gcm": null,
"wns": null,
"baidu": {
"android":

{ "title": "*** 消息标题 Title 1 ***", "description": " ", "notification_builder_id": 1, "notification_basic_style": 6, "open_type": 1, "url": "http://developer.baidu.com", "pkg_content": "pkgContent" }
,
"ios":

{ "alert": "ios_alert", "sound": "ios_sound", "badge": 5 }
,
"msgType": 0
}
}
}
  1. In SAP mobile service cockpit, select Mobile Applications.

  2. Select an application, then select Mobile Push Notification under Assigned Features (or add it first); for SAP Mobile Cards select Features > Push Notification.

  3. Under Baidu, select Enable push to Android devices or Enable push to iOS devices. You can push to both Android and iOS devices simultaneously by selecting both the options.

  4. Specify the API Key and Secret Key.

  5. Save your changes.

    Push messages are accepted, but always queued with a Message was queued message, and not received on the device. The server and client use the same environment (Sandbox or Production), but the configured topic is for another environment. The APNs service also rejects messages when the server certificate has been used to send multiple invalid messages. Please generate a new certificate to resolve this issue.

Custom Push

Custom push provides a push notification routing service to a custom push server for users in some countries/regions. To enable this feature, configure a destination URL to the custom push server. Prerequisites include:

  • The custom push server must implement a Custom Push API that is able to receive push notification messages from mobile services, and then coordinate distribution of push notifications to mobile clients.

  • In SAP mobile service cockpit, you must set up a destination URL to point to an API endpoint address, such as https://custom.push.<server>.<host>/push, as described in Creating a Destination.

See the GitHub repository for Custom Push API details.

SAP Mobile Services sends a general notification message to the push destination server. The destination server handles further forwarding of the notifications.

See the GitHub repository for example custom push micro apps and test code. The custom push examples have been tested for Huawei and Xiaomi devices.

  1. In SAP mobile service cockpit, select Mobile Applications.

  2. Select an application, then select Mobile Push Notification under Assigned Features (or add it first); for SAP Mobile Cards select Features > Push Notification.

  3. Under Custom Push, select Enable Custom Push.

  4. In Custom Push Destination, select the destination that you set up for the custom push server.

  5. Click Save.

Once custom push is configured with the destination URL, the device application can register its push ID, specific to local push vendors with mobile services, and mobile services stores the ID transparently.

Later, the back end calls mobile services to send push notifications to those devices. SAP Mobile Services finds the registered push ID based on the username, application ID, and\or other information like APNs and FCM, and then sends push IDs and push messages to the custom push provider.

In this process, mobile services tries not to modify the push messages, and passes the messages to the custom push provider for parsing and processing.

Browser Notification

To enable client applications to receive browser notifications enable W3C notifications. W3C enables push notification service for Google Chrome, Mozilla Firefox and Microsoft Edge browsers.

  1. In SAP mobile service cockpit, select Mobile Applications.

  2. Select an application, then select Mobile Push Notification under Assigned Features (or add it first); for SAP Mobile Cards select Features > Push Notification.

  3. Under W3C, select Enable W3C Push API for Google Chrome, Mozilla Firefox, and Microsoft Edge browsers.

    Note

    When you disable W3C notification it removes all the previous browser subscriptions and this cannot be reverted.

  4. Save your changes.

W3C Push API and Mobile Services

mobile services supports sending push notifications to Google Chrome, Mozilla Firefox, and Microsoft Edge (only for versions based on Chrome, available since January 2020) browsers using the Push API.

First create an application or use an existing application and make sure the Mobile Push Notification feature is enabled. To enable Mobile Push Notifications, see Browser Notification. You should then create a service key and assign the role push_single to it. This key is later used to send a push notification to the user.

The following sections provides information about the concept of Service Workers and the actual subscription call for client code. To learn more, see Push API.

Retrieve applicationServerKey. The applicationServerKey is required for the JavaScript code to successfully subscribe to push messages. mobile services provides a general purpose API to retrieve the pushId, which, in the case of W3C Push API, corresponds to the Base64-encoded public key of the server.

    fetch('/mobileservices/push/v1/runtime/applications/dummy/pushconfigurations/os/w3cpushapi/pushid').then((response) => {
        if (response.status >= 400 && response.status < 500) {
            return response.text()
            .then((responseText) => {
                console.log('Failed web push response: ', response, response.status);
            });
        }
        else {
            response.json().then((pushid) => {
            this._applicationServerKey = pushid.pushId;
            });
        }
        });

Send Subscription to mobile services. Once the subscription is done and the PushSubscription is available, the PushSubscription details need to be sent to mobile services as the pushToken. It is recommended to register the token with a Device ID to allow the same user to register several browsers for push and update and to delete the registration individually. For this reason a random value is generated and persisted into local storage.

In case there is already a registration (from a previous load of the web page), the server returns a 409 (conflict) to the POST request, which causes the request to be repeated as a PUT, to update the existing user information:

     var deviceId = localStorage.getItem("mobile-device-id");
    if (!deviceId) {
      deviceId = Math.floor(Math.random() * 1000000000).toString();
      localStorage.setItem("mobile-device-id", deviceId)
    }
    // try to register the browser - if ther is a conflict we will update the existing record
    fetch('/mobileservices/push/v1/runtime/applications/any/os/w3cpushapi/devices/' + deviceId, {
      method: 'POST',
      cache: 'no-cache',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ pushToken: JSON.stringify(subscription) })
    }).then((response) => {
      if (response.status == 409) {
        fetch('/mobileservices/push/v1/runtime/applications/any/os/w3cpushapi/devices/' + deviceId, {
          method: 'PUT',
          cache: 'no-cache',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({ pushToken: JSON.stringify(subscription) })
        }).then((response) => {
          console.log('Push registration update response: ', response, response.status);
        });
      } else {
        console.log('Push registration response: ', response, response.status);
      }
    });

Delete Subscription from mobile services. In case the user revokes the privilege for push messages, the registration should be deleted:

     var deviceId = localStorage.getItem("mobile-device-id");
    // Remove the subscription from Mobile Services
    fetch('/mobileservices/push/v1/runtime/applications/any/os/w3cpushapi/devices/' + deviceId, {
      method: 'DELETE',
      cache: 'no-cache'
    }).then((response) => {
      console.log('Push registration delete response: ', response, response.status);
    });

This section describes how to send the push message.

Sending the push message. You will need the API Key and URL from the Service Key that you created earlier. After replacing these two parameters and filling in the username of the registered user you can run this curl command to send out a push message:

curl -H 'x-api-key: API_KEY_FROM_PUSH_SERVICE_KEY' -H 'content-type: application/json' --data '{"users":["YOUR_USERNAME"],"notification": {"alert":"Hello"}}' URL_FROM_PUSH_SERVICE_KEY/mobileservices/push/v1/backend/applications/any/notifications/users

Depending on the operating system, the notification message might not show up if the browser and web page is in the foreground.

The same command also sends the push message to Android and iOS applications registered for the same user (assuming that push is correctly configured in mobile services).

Using SAML Attribute as Alternative User Name

SAP Mobile Services Mobile Push Notification retrieves notification targets using a user name as the default identifier, as described in Sending Notifications via the REST API. Back-end might use a different SAML Attribute to identify users and the user name is not available in the back-end. You can choose a SAML Attribute in Push User Name:

  • Enable Use SAML Attribute as User Name to use a SAML attribute as an alternative user name.

  • Provide the SAML attribute name in SAML Attribute Name

  • The Global User ID is stored in the registration and, if already provided as a SAML Attribute, can be used to specify the recipient.

This value is stored during device push registration or update in the push registration for this device.

Note

The SAML attributes are provided by the Identity Provider after the user has logged in. New values are used after the current authentication has been revoked and the user has logged in again. See Revoking OAuth Tokens.

Retrieving the Available User Attributes

You can retrieve the available user attributes by calling the User Info Service.

  1. Open the SAP Mobile Services cockpit and navigate to the mobile application configuration.

  2. Retrieve the application ID from the Info tab.

  3. Retrieve the server URL from the API tab.

  4. Call the user information service

    GET {server URL}/mobileservices/application/{application ID}/roleservice/application/{application ID}/v2/Me
    Accept: application/json
    Authorization: Bearer {bearer token}
    
    https://{server URL}/mobileservices/application/{application ID}/roleservice/application/{application ID}/v2/Me?auth=uaa
    

    This returns the user info with the available user attributes in the detail property:

    {
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "id": "john.doe@acme.corp",
        "userName": "john.doe@acme.corp",
        "name": {
            "familyName": "Doe",
            "givenName": "John"
        },
        "emails": [
            {
                "value": "john.doe@acme.corp"
            }
        ],
        "roles": [
            "openid",
            "user_attributes",
            "uaa.user"
        ],
        "detail": {
            "email": [
                "john.doe@acme.corp"
            ],
            "Groups": [
                "Admin",
                "Sales"
            ],
            "family_name": [
                "Doe"
            ],
            "given_name": [
                "John"
            ],
            "SAPUID": [
                "S01234567"
            ]
            "acr": [
                "urn:oasis:names:tc:SAML:2.0:ac:classes:X509"
            ],
            "remoteEntityId": [
                "acme.account100.ondemand.com"
            ]
        }
    }
    

You can use any user attribute with a single list item, for example: email, family_name, given_name or SAPUID

Disable SAML Attribute as Alternative User Name

Disable Use SAML Attribute as User Name in Push User Name. The SAML attribute value is not removed from existing device registrations but is not used to retrieve device registrations.

Sending Push Notifications

Manage push notifications for the selected application.

This feature uses the existing push notification mechanism to send messages to recipients. You can send a native push notification. You must be assigned the Developer or Manager role for the space to send push notifications (a grayed-out Send Push Notification button indicates the role needs to be added to your profile).

Note that for some push providers, if you delete user registrations for auto registration in Mobile Settings Exchange, you must also manually delete the device registration from Mobile Push Notifications > Push Notifications. This is because the provider does not provide the information needed for automatic deletion in push. For these providers, you must perform the manual delete: Baidu, Custom, and W3C.

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK or SAP Mobile Cards.

  2. Select an application, then select Mobile Push Notification under Assigned Features (or add it first); for SAP Mobile Cards select Features > Push Notification.

  3. Select Push Registrations to see a list of registered users who are eligible for push notifications.

    You can click the Customize Table Columns icon action-settings to change the columns that appear.

    Registered Users Default Columns

    Category Description
    User Name User name of the registered user.
    Device ID The device type for the registered user, such as Android or IOS.
    Push Provider The push provider associated with the device.
    Push Group The push group associated with the device.
    Created At (UTC-700) The time the device registered in UTC format.
    Actions Indicates any actions you can take for the registered user, such as sending a notification, or deleting the registration.
  4. You can use the filters to help find a subset of registered users.

    Filter Criteria

    Filter Description
    User Name Enter a specific user name, or the start of a user name.
    User Locale Enter the language. This field is not validated, so you can enter any string value. Use the field if you know one or more values that users entered during registration, such as EN or German.
    Time Zone Enter one or more time zones, separated by commas. This field is not validated, so you can enter any string value. Use the field if you know one or more values that users entered during registration, such as UTC-1 or PST.
    Device Model Select one or more device model, such as iOS and Android.
    Push Group Enter a push group name. This field is not validated, so you can enter any string value. Use the field to create a temporary group for filtering. Push groups do not persist.
    Registration Timeframe Select a time frame from the list: Last 24 Hours, Last 7 Days, Last 4 Weeks, Last 3 Months, Last 6 Months, Last 12 Months, or Custom Defined (use the date-time picker to define a range).
  5. Select Send Notification to send a push notification to a registered user.

  6. In the Send Push Notification dialog, create your push notification. You can:

    • Select General and type a push notification message.

    • Select Advanced and modify the JSON format payload version of the default push notification message. You should only do this if you are an expert user. Select Revert to Default to revert to the default JSON code.

  7. Select Send. The message The native push notification was sent successfully appears.

  8. Select delete to remove a registered user from the push notification list.

  9. As described above, you may need to delete a registered user if you deleted a user registrations for auto registration in Mobile Settings Exchange for certain vendors, including Baidu, Custom, and W3C.

Enabling Push for Subscribers (SaaS)

For Native/MDK apps managed in a one-app cockpit (SaaS), the subscriber administrator can enable or disable push notifications sent to app subscribers. When turned off, other push configurations, such as global push or push provider, are not available.

  1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK or SAP Mobile Cards.

  2. Select an application, then select Mobile Push Notification under Assigned Features (or add it first); for SAP Mobile Cards select Features > Push Notification.

  3. Make sure the Configuration tab is selected.

  4. Select Enable Mobile Push to enable the subscribers to receive push notifications created in Push Registrations (see Sending Push Notifications). Mobile push notifications are sent to subscribers.

  5. Select Disable push notifications to turn off sending push notifications. Mobile push notifications created in Push Registrations are not sent to subscribers.


Last update: February 27, 2024