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.

  • 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 certificate (or leave blank to use customer configurations such as for Android and Apple).

    Note

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

    • SAP Fiori Client ‒ push certificate for a native/hybrid app or SAP Mobile Cards.

    • SAP CoPilot ‒ push certificate for SAP CoPilot.

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

    • SAP Asset Manager ‒ push certificate 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 legacy HTTP API, which uses the Server Key from the project as the credential; or the HTTP v1 API, which uses a Firebase Service Account Private Key as the credential. If you plan to use the private key file, download it from the Firebase platform in advance.

Note

SAP mobile service cockpit currently supports both methods. Google recommends migrating to Firebase Service Account Private Key, which provides additional security and a turnkey configuration. To learn more see Migrate from legacy HTTP to HTTP v1.

  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:

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

    2. 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:

    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; to configure APNS for a production environment, select Production. Choose either Certificate or Token-Based as the authentication type. (Optional) If you don't want to receive APNS push notifications, under Apple, select None.

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

  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. Push messages are accepted, but always queued with Message was queued. and not received on the device. The server and client are using the same environment (Sandbox or Production) but the configured topic is for another environment. The APNS service rejects messages when the server certificate has been used to sent multiple invalid messages too. Please generate a new certificate and use this.

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

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 disabled Send Push Notification button indicates the role needs to be added to your profile).

  1. In SAP mobile service cockpit, select Mobile Applications > Native/Hybrid 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 an ad hoc 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.


Last update: May 20, 2021