Edit

Share via

Push notification device registration for application developers

  • Article

To learn more about the overall approach to setting up push notifications in Customer Insights - Journeys, visit the push notification setup overview.

To enable push notifications in Customer Insights - Journeys, you need to complete the following steps:

  1. Push notification application configuration
  2. User mapping for push notifications
  3. Device registration for push notifications
  4. Receiving push notifications on devices
  5. Interaction reporting for push notifications

This diagram describes the two steps necessary to register devices and users within Customer Insights - Journeys.

Push notifications device and user registration diagram.

Device registration

To complete the mobile app configuration, the developer must register devices across servers. You should already have the device token, user ID from Customer Insights - Journeys (contact ID, lead ID, Customer Insights - Data profile ID), and the mobile application ID from Customer Insights - Journeys.

Upon successful call of a device registration request, there's a 202 response. The 202 response only indicates the request was accepted. To confirm a successful request, you need to check the status by using a webhook or calling the status endpoint directly.

API

Device registration (single)

Sample HTTP request (iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "ApiToken": "%API_TOKEN%",
    "ApnsDeviceToken": "%APNS_TOKEN%"
}

Sample HTTP request (Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "ApiToken": "%API_TOKEN%",
    "FcmDeviceToken": "%FCM_TOKEN%"
}

Headers:

  • x-ms-track-registration: when true, the information about registration success/failure is stored and be available through registration status API.
  • x-ms-callback-url: When not empty, a failed or successful device registration triggers POST request webhook.
  • x-ms-callback-url-headers: Contains a serialized JSON of a string-to-string dictionary, representing headers passed for webhook requests. Used only when x-ms-callback-url is defined.

Returns: 202 if provided request is valid, 400 otherwise.

Response body:

When x-ms-track-registration is true:

{
    "RegistrationRequestId": "%GUID%"
}

Otherwise, empty body.

Definitions
Name Description
MobileAppId The identifier of the mobile application configured in Customer Insights - Journeys.
UserId The user identifier of the contact, lead, or Customer Insights - Data profile from Customer Insights - Journeys.
ApiToken Your API token to authorize the request.
ApnsDeviceToken The unique device token identifier generated by the iOS application. This will only be sent for an iOS device
FcmDeviceToken The unique device token identifier generated by the Android application. This will only be sent for an Android device

Device registration (multiple)

The body of the batch registration contains an array of up to 100 objects representing device registration requests.

Sample HTTP request (iOS):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "ApnsDeviceToken": "%APNS_TOKEN%"
    }
]

Sample HTTP request (Android):

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/batch

[
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",      
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    },
    {
        "MobileAppId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "ApiToken": "%API_TOKEN%",
        "FcmDeviceToken": "%FCM_TOKEN%"
    }
]

Headers:

  • x-ms-track-registration: When true, the information about registration success or failure is stored and be available through registration status API.
  • x-ms-callback-url: When not empty, a failed or successful device registration triggers a POST request webhook.
  • x-ms-callback-url-headers: Contains a serialized JSON of a string-to-string dictionary, representing headers passed for webhook requests. Used only when x-ms-callback-url is defined.

Returns: 202 if provided request is valid, 400 otherwise.

Response body:

When x-ms-track-registration is true: an array of items, each item order corresponds to order from the request body array.

[
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    },
    {
        "RegistrationRequestId": "%REG_REQUEST_ID%"
    }
]

Otherwise, empty body.

Device registration status

POST  {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/status/

Request body:

{
    "RegistrationRequestIds": [
        "%REG_REQUEST_ID%"
    ],
    "MobileAppId": "%MOBILE_APP_ID%",
    "ApiToken": "%API_TOKEN%"
}

Returns: 200 if provided request is valid, 400 otherwise.

Response body - an array of items:

[
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    },
    {
        "Status": "Pending|Success|Failed",
        "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid " // dry run sending is a verification of device token by sending an invisible notification to mobile app. Such sending failure might happen due to a wrong device token or incorrect/expired mobile app auth data
    }
]

Each item order corresponds to the order from RegistrationRequestIds array.

Definitions
Name Description
RegistrationRequestIds An array of individual registration requests. The values are taken from the response of the registration calls. This is only provided when the x-ms-track-registration header was used for registration
MobileAppId The identifier of the mobile application configured in Customer Insights - Journeys.
UserId The user identifier of the contact, lead, or Customer Insights - Data profile from Customer Insights - Journeys.

Important

There are three possible reasons why the status can get stuck in a "Pending" state:

  1. The original device registration request had an invalid API token. To prevent malicious actors from performing a DoS attack against an environment by calling "register device" and generating infinite throttling, such attempts don't produce storing of registration history. Therefore, there's no information to check success.
  2. The CRM stays in a throttled state for multiple hours, causing the status update operation to fail executing its job after multiple retries.
  3. The device registration request was made without the x-ms-track-registration header provided.

Device registration status webhook

If an x-ms-status-callback-url is provided the URL when a device registration is successful or failed, Customer Insights - Journeys accesses the value of the header.

POST to the URL provided within x-ms-status-callback-url header of device registration request.

Body:

{ 
    "Status": "Success|Failed", 
    "Signature": "%SIGNATURE%", 
    "FailureReason": " DuplicateExists|DryRunSendingFailed|DeviceTokenTooLong|FailedToStoreDevice|ApiTokenNotValid" 
}

Tip

The signature is the HMACSHA256 hash of the callback URL calculated using the API token as a key. Use the value to verify that Customer Insights - Journeys made the call. Hash the callback URL with the API token on the webhook’s side using the same algorithm and comparing the values.

Note

An attempt to make a request happens once. Any failure to execute a request causes the notification to be lost. Failure types include an incorrect callback URL, REST API call timeout, or unexpected response status code.

Returns: 202 if provided request is valid, 400 otherwise.

Expected body: empty body.

Device cleanup (single)

It's important to remove devices that are no longer valid from the database to ensure performant message sending. Use the following approach to remove old device, user, and application combinations from the devices table.

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Returns: 202 if provided request is valid, 400 otherwise.

Definitions
Name Description
MobileAppId The identifier of the mobile application configured in Customer Insights - Journeys.
ApiToken Your API token to authorize the request.
UserId The user identifier of the contact, lead, or Customer Insights - Data profile from Customer Insights - Journeys.
DeviceToken The unique device token identifier generated by the application.

Device cleanup (multiple)

It's important to remove devices that are no longer valid from the database to ensure performant message sending. Use the following approach to remove old device, user, and application combinations from the devices table.

POST {PublicEndpoint}/api/v1.0/orgs/%ORG_ID%/pushdeviceregistration/devices/cleanup/batch

{
    "MobileAppId": "00000000-0000-0000-0000-000000000000",
    "ApiToken": "%API_TOKEN%",
    "UserId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "DeviceToken": "%OPTIONAL_FCM_OR_APNS_DEVICE_TOKEN%"
}

Returns: 202 if provided request is valid, 400 otherwise.

Definitions
Name Description
MobileAppId The identifier of the mobile application configured in Customer Insights - Journeys.
ApiToken Your API token to authorize the request.
UserId The user identifier of the contact, lead, or Customer Insights - Data profile from Customer Insights - Journeys.
DeviceToken The unique device token identifier generated by the application.