Push notification device registration for application developers
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:
- Push notification application configuration
- User mapping for push notifications
- Device registration for push notifications
- Receiving push notifications on devices
- Interaction reporting for push notifications
This diagram describes the two steps necessary to register devices and users within Customer Insights - Journeys.
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:
- 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.
- The CRM stays in a throttled state for multiple hours, causing the status update operation to fail executing its job after multiple retries.
- 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. |