Custom Native Push
Integrating a custom Native Push Notification provider as part of your Operator API
Fast Tracks supports Firebase as Native Push Notification provider, if your business need a provider which is not a part of the list of supported providers then you can build this API.
Fast Track Native Push Notification Service
The Fast Track Native Push Notification service can be configured to send Native Push Notification requests to the Operator API endpoints listed below, which allows the Operator to manage the Native Push Notification provider. It supports sending messages and to get fetch delivery status. Sending is available for both single or batched Native Push Notification requests.
The following endpoints can be built as a part for your Operator API:
⬆️ POST /channels/push/single
⬆️ POST /channels/push/batch
The Operator can then forward these requests to the Native Push Notification provider for processing and answer back with the respective responses.
API format and responses need to be formatted as outlined below
It is important that the "meta" data outlined below is sent back to Fast Track in either Webhook or Polling so that conversion data can be stored correctly. Please refer to the shown examples and the tables underneath for further clarification.
Pre-Requisites
- Advice Fast Track if any rate limiting should be taken into consideration. (If you plan to implement rate limiting please contact Fast Track before, so we can guide you on supported implementation)
- Advice Fast Track if any batch maximums should be taken into consideration.
- Provide Fast Track with any credentials specific for the integrated providers (if required)
Send Native Push Notification (Single)
A single Native Push Notification send request will contain the data of each individual Native Push Notification in separate requests to the API.
Endpoint Implementation
Implement the endpoint in the format below to support single-send Native Push Notification through API.
⬆️ POST <operator-api-endpoint-url>/channels/push/single
Request Header
The header of the sent request contains an "X-Api-Key" which is a token required to authenticate the API calls at the endpoint. This token needs to be passed on to Fast Track in order to make these requests.
Request Body Schema
Refer to the following example of a single Native Push Notification request sent by Fast Track. The description of each field is listed in the table below it.
Top-level fields
| Key | Type | Description |
|---|---|---|
activity * | object | Activity context object — see sub-table below |
title * | string | The push notification title |
body * | string | The push notification body text |
image_url | string | URL of an image to display in the notification |
android | object | Android-specific configuration — see Android fields below. Omit if unused |
ios | object | iOS-specific configuration — see iOS fields below. Omit if unused |
web | object | Web push-specific configuration — see Web fields below. Omit if unused |
meta | object | Custom key-value pairs defined in the Fast Track CRM activity |
activity fields
| Key | Type | Description |
|---|---|---|
activity.id * | integer | A unique identifier of the Native Push Notification |
activity.brand_id * | integer | The unique identifier of the brand on Fast Track |
activity.user_id * | string | The unique identifier of the player |
activity.activity_id * | integer | The unique identifier of the activity setup in Fast Track |
activity.action_group_id * | integer | The unique identifier of the action group which the Native Push Notification originates from Fast Track |
activity.trigger_hash * | string | Trigger hash |
activity.action_id * | integer | The unique identifier of the individual action from Fast Track |
activity.origin | string | Optional origin label for the activity |
android fields — all optional
| Key | Type | Description |
|---|---|---|
priority | string | Message delivery priority |
ttl | string | Time-to-live duration for the message |
collapse_key | string | Key used to collapse pending messages |
restricted_package_name | string | Target Android package name |
icon | string | Notification icon resource name |
color_rgb | string | Notification accent colour in hex format |
sound | string | Notification sound |
tag | string | Tag used to replace existing notifications |
click_action | string | Action triggered when the notification is tapped |
body_loc_key | string | Localisation key for the body text |
body_loc_arcs | array of strings | Substitution values for body_loc_key |
title_loc_keys | string | Localisation key for the title |
title_loc_args | array of strings | Substitution values for title_loc_key |
channel_id | string | Android notification channel identifier |
ios fields — all optional
| Key | Type | Description |
|---|---|---|
badge | string | App icon badge count |
category | string | Notification category identifier |
thread_id | string | Thread identifier for the grouping notifications |
sub_title | string | Notification subtitle |
loc_key | string | Localisation key for the body text |
loc_args | array of strings | Substitution values for loc_key |
title_loc_key | string | Localisation key for the title |
title_loc_args | array of strings | Substitution values for title_loc_key |
sub_title_loc_key | string | Localisation key for the subtitle |
sub_title_loc_args | array of strings | Substitution values for sub_title_loc_key |
action_loc_key | string | Localisation key for the action button label |
launch_image | string | Launch image filename shown when the app opens |
web fields — all optional
| Key | Type | Description |
|---|---|---|
icon | string | URL of the notification icon |
badge | string | URL of the badge icon |
dir | string | Text direction. Values: ltr | rtl | auto |
lang | string | Notification language tag (e.g. en) |
renotify | string | Whether to notify the user after replacing an existing notification |
require_interaction | string | Whether the notification should remain until the user interacts with it |
silent | string | Whether the notification should be silent |
tag | string | Tag used to replace existing notifications |
timestamp | integer | Unix timestamp representing the notification time |
vibrate | array of strings | Vibration pattern as an array of durations in milliseconds |
link | string | URL to open when the notification is clicked |
Expected Responses
The Operator API should return the responses for each individual Native Push Notification message respectively to avoid unrelated storage of Native Push Notification data.
Successful HTTP 200-299 JSON Response
The push_id will be a unique identifier generated by the Operator API which allows Fast Track to identify that particular Native Push Notification message in order to update its delivery status after it is sent.
ERROR Non-200 response JSON Response
Erroneous responses are typically associated with HTTP status codes 400s or 500s. The response should contain an "error" field with a description to show what went wrong and assist with troubleshooting.
The responses from the Operator API will be handled differently depending on the class of the HTTP status code. The table below gives a summary of how the HTTP status are handled separately.
| HTTP Status Codes | Description |
|---|---|
200-299 | Successfully Delivered. Fast Track will acknowledge the message and start processing the next message in the queue. |
400-499 | Non Successful. When receiving this error, Fast Track will skip the Native Push Notification message. Additionally, it will send its data to Failed Actions, if the service is enabled. |
500 or any other status code which is not listed above | Non Successful. The service fatals and Fast Track will keep retrying until a 200 response is received. |
Batch Native Push Notifications
Batch Native Push Notification helps to process a collection of Native Push Notification in one request to the API. The number of messages within the batch request is limited by a set integer amount in the configuration and sent within a configured time span, even when the batch is not yet full.
Endpoint Implementation
Implement the endpoint in the format below to support batch-send Native Push Notification through API.
⬆️ POST <operator-api-endpoint-url>/channels/push/batch
Request Header
The header of the sent request contains an "X-Api-Key" which is a token required to authenticate the API calls at the endpoint. This token needs to be passed on to Fast Track in order to make these requests.
Request Body Schema
Here is an example of expected format when batching the requests. It is similar to the Single Native Push Notification request but the requests are stored in an array, one after the other.
See table above (for /push/single) for more information on each property in the payload.
Expected Responses
The below responses should be returned by the Operator API.
Successful HTTP 200 JSON Response
The "activity.id" initially sent in the request will be returned back in the response as "id". This is required to help Fast Track identify the individual Native Push Notification message in the initial batch request.
The push_id will be a unique identifier generated by the Operator API, which Fast Track will use to identify the related Native Push Notification message when updating its status.
If any of the listed categories ("successful", "failed" or "fatal") do not have an associated Native Push Notification, they should be returned as an empty array.
The request need to include one of the properties successful, failed or fatal
The logic flow on how the response will be handled is very similar to how the HTTP status codes are handled in the Single Native Push Notification. The sole difference is that the response with a status code 200 will be handled instead, according to the message's category in the response.
| Response Category | Description |
|---|---|
successful | Successfully Delivered. Fast Track will acknowledge the message and start processing the next batch in the queue. |
failed | Non Successful. When receiving this error, Fast Track will skip the Native Push Notification message. Additionally, it will send its data to Failed Actions, if the service is enabled. |
fatal | Messages will be retried |
Any other messages that are not listed within the response will be retried.
ERROR (non 500 response) JSON Response
Fast Track will only support HTTP Status Code 200 in batching. The whole batch request will be retried if any other status code is received with the following response.