Localized Push Notification¶

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

App Based Push Localization¶

APNS, Firebase Cloud Messaging and Windows Messaging Service provides localized notifications via parameterized messages 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 solution 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 users selected device language.

The message producer provides a list than 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 value of the registration.

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: Swizz-German
de: German

Assuming the device registers the device language de-DE-bay. The service will try to find the localized notification with key de-DE-bayfirst. If not defined, the service tries to fallback to de-DE, then de. The default notification is used when no localized notification is defined.

Sending Push Notifications¶

Localized Push Notifications are sent as described in Sending Notifications via the REST API. The only differences are:

The localized Push Notification API is using the version 2 API.
The Notification payload contains the fallback notification notificationand the localized notification map notifications with language as key.

The following paragraph documents the available Localized Push Notifications methods with localized alert messages. Please see Sending Notifications via the REST API for detailed information. Please see Native Provider Notification Handling for advanced notification properties.

Push To Device¶

Sending a notification to a specific users device.

HTTP

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

{
    "notification": {
        "alert": "Hello!"
    },
    "notifications": {
        "en_US": {
            "alert": "Howdie!"
        },
        "de": {
            "alert": "Guten Tag!"
        }
    }
}

BASH

curl -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/notifications/users/user1/devices/bac3ce2df47/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"notification" : {"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'

POWERSHELL

curl.exe -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/notifications/users/user1/devices/bac3ce2df47/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"notification" : {"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'

Push To Users¶

Sending notifications to multiple users and their registered devices (for this application).

HTTP

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

{
    "users" : [
        "user1" , "user2", ...
    ],
    "notification": {
        "notification": {
            "alert": "Hello!"
        },
        "notifications": {
            "en_US": {
                "alert": "Howdie!"
            },
            "de": {
                "alert": "Guten Tag!"
            }
        }
    }
}

BASH

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

POWERSHELL

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

Push to Topic¶

See Sending Notifications via the REST API - Push to Topic

Push To Group¶

Sending notifications to multiple users and their registered devices (for this application), filtered by group. The group is defined in the device registration.

HTTP

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

{
    "notification": {
        "alert": "Hello!"
    },
    "notifications": {
        "en_US": {
            "alert": "Howdie!"
        },
        "de": {
            "alert": "Guten Tag!"
        }
    }
}

BASH

curl -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/groups/group/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":["user1"],"notification" : {"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'

POWERSHELL

curl.exe -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/groups/group/notifications  \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":["user1"],"notification" : {"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'

Push To Application¶

Sending notifications to all users, registered for the given application.

HTTP

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

    {
        "notification": {
            "alert": "Hello!"
        },
        "notifications": {
            "en_US": {
                "alert": "Howdie!"
            },
            "de": {
                "alert": "Guten Tag!"
            }
        }
    }

BASH

curl -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/notifications \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":["user1"],"notification" : {"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'

POWERSHELL

curl.exe -X POST ${PUSH_URL}/mobileservices/push/v2/backend/applications/${PUSH_APP}/notifications  \
    -H 'content-type: application/json' -H 'accept: application/json' -u ${PUSH_USER} \
    -d '{"users":["user1"],"notification" : {"notification":{"alert":"Hello!"},"notifications":{"en_US":{"alert":"Howdie!"},"de":{"alert":"Guten Tag!"}}}}'

Push To Capability¶

Push to Capability sends notifications to devices that have been registered with a certain capability.

HTTP

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

{
    "users" : [
        {
            "formFactor" : ["phone"],
            "user" : "user1"
        }
    ],
    ,
    "notification": {
        "notification": {
            "alert": "Hello!"
        },
        "notifications": {
            "en_US": {
                "alert": "Howdie!"
            },
            "de": {
                "alert": "Guten Tag!"
            }
        }
    }
}

Get Device Locales¶

The notification producer can retrieve the set of user locales for usernames to send the minimum number of required locales in the push request.

HTTP

GET {servicepath}/mobileservices/push/v2/backend/localizations?usernames={username1},{username2} HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ***

Last update: June 23, 2022