- 16 Feb 2024
- 6 Minutes to read
Send Targeted App Pushes
- Updated on 16 Feb 2024
- 6 Minutes to read
Overview
You can use the Targeted Push API in various cases such as sending status update of an order from your e-commerce platform, or informing users of a sale on an item that was in their wishlist.
You can reach the analytics of your targeted push notifications sent via this API through Reports > Mobile App Analytics > Push API Campaigns on Inone.
Endpoint and Headers
Headers
Header | Sample Value | Description |
---|---|---|
Content-Type | application/json | This header specifies the media type of the resource. |
Body Parameters
Parameter | Description | Data Type | Required |
---|---|---|---|
headline | Title of the advanced push item | String | Yes |
description | Description of the advanced push item | String | Yes |
api_key | Your API key. Refer to API Authentication Tokens to get your API key. | String | Yes |
notifications | The array of notification object that includes the push data | Array | Yes |
identifiers | The object that contains the unique identifier of the user. The key can be an identifier such as email, phone_number or uuid. E.g. "phone_number": "+651234567890". | Object | Yes |
camp_id | ID of the campaign that can be used to retrieve the statistics of the push notification via Statistics API. You can set any campaign ID. | Integer | Yes |
camp_name | Name of the push notification | String | Yes |
title | Title of the push notification | String | Yes |
message | Content of the push notification | String | Yes |
image_url | URL of the image in rich push notifications | String | Yes |
ttl | Expiration time of the push notification in seconds | Integer | No |
check_optin | true shows the optin delivery count information in the API response. false does not show the count. | Boolean | No |
android | Object for Android details | Object | No |
ios | Object for iOS details | Object | No |
thread_id | ID of the notification thread | Integer | No |
deep_link | Key/value pairs to be passed to the application in the push payload. The most common use of deep links is sending the user to the selected landing page when they open the push notification. | Object | No |
sound | Name of the custom sound file in your app to play a custom sound | String | No |
badge | Badge for iOS | Integer | No |
deliver_silently | (iOS only) true sends the notifications with content--available=1 but notification does not show up. This can be used to execute background tasks remotely. | Boolean | No |
To add key-value pairs to the deep_link object, you can use the following deep link keys depending on its type:
- ins_dl_internal for an internal deep link,
- ins_dl_external for an external deep link,
- ins_dl_url_scheme for a URL scheme deep link,
- ins_dl_json for a JSON deep link.
The URL in the value should always start with https://.
Sample Example
Sample Body
The following is a sample body to send targeted app push notifications.
App push notifications are sent to a user's last active device.
{
"api_key": "Your API Key goes here",
"report_attributes": [
"INSIDER.carrier",
"INSIDER.idfa",
"INSIDER.name",
"INSIDER.surname",
"INSIDER.gender",
"INSIDER.age",
"INSIDER.birthday",
"INSIDER.email",
"INSIDER.phone_number",
"INSIDER.language",
"INSIDER.email_optin",
"INSIDER.sms_optin",
"INSIDER.push_optin",
"INSIDER.location_optin",
"INSIDER.insider_id",
"INSIDER.environment",
"INSIDER.idfa",
"INSIDER.device_token",
"INSIDER.udid",
"INSIDER.model",
"INSIDER.carrier",
"INSIDER.app_version",
"INSIDER.os_version",
"INSIDER.screen_width",
"INSIDER.screen_height",
"INSIDER.platform",
"INSIDER.timezone",
"INSIDER.device_language",
"INSIDER.sdk_version",
"INSIDER.last_ip",
"INSIDER.package_name"
],
"notifications": [
{
"identifiers": {
"INSIDER.email": "sample@mail.com",
"INSIDER.phone_number": "+65123456789",
"INSIDER.uuid": "1234567890"
},
"camp_id": 1,
"camp_name": "Your push notification campaign name goes here",
"title": "Your push notification title goes here",
"message": "Your push content goes here.",
"image_url": "https://your_image_url.jpg",
"ttl": 1,
"check_optin": true,
"android": {
"thread-id": 1,
"sound": "sound_check",
"deep_link": {
"ins_dl_internal": "https://www.deeplink.useinsider"
}
},
"ios": {
"thread-id": 1,
"badge": 1,
"deliver_silently": true,
"mutable-content": true,
"sound": "sound_check",
"content-available": true,
"deep_link": {
"ins_dl_internal": "https://www.deeplink.useinsider"
}
}
}
]
}
Add advanced_push_payload in notifications if you would like to use Advanced Pushes. The advanced_push_type value can be a carousel or slider. The following are the parameters of the advanced_push_payload.
Parameter | Definition | Data Type | Required |
---|---|---|---|
advanced_push_type | Type of the advanced push: carousel or slider | String | Yes |
advanced_push_items | Details of the advanced push | Array | Yes |
image_url | URL of the image in rich push notifications | String | Yes |
deep_links | Key/value pairs to be passed to the application in the push payload. The most common use of deep links is sending the user to the selected landing page when they open the push notification. | Object | No |
description | Description for your push | String | Yes |
headline | Title for your push | String | Yes |
id | ID of your push | Integer | Yes |
For further details on advanced pushes, refer to Send advanced app pushes API.
{
"api_key": "Your API Key goes here",
"report_attributes": [
"INSIDER.carrier",
"INSIDER.idfa",
"INSIDER.name",
"INSIDER.surname",
"INSIDER.gender",
"INSIDER.age",
"INSIDER.birthday",
"INSIDER.email",
"INSIDER.phone_number",
"INSIDER.language",
"INSIDER.email_optin",
"INSIDER.sms_optin",
"INSIDER.push_optin",
"INSIDER.location_optin",
"INSIDER.insider_id",
"INSIDER.environment",
"INSIDER.idfa",
"INSIDER.device_token",
"INSIDER.udid",
"INSIDER.model",
"INSIDER.carrier",
"INSIDER.app_version",
"INSIDER.os_version",
"INSIDER.screen_width",
"INSIDER.screen_height",
"INSIDER.platform",
"INSIDER.timezone",
"INSIDER.device_language",
"INSIDER.sdk_version",
"INSIDER.last_ip",
"INSIDER.package_name"
],
"notifications": [
{
"identifiers": {
"INSIDER.email": "example@gmail.com",
"INSIDER.phone_number": "+9059713551597135123",
"INSIDER.uuid": "5971351231234567"
},
"advanced_push_payload": {
"advanced_push_type": "carousel",
"advanced_push_items": [
{
"image_url": "https://your_image_url.jpg",
"deep_links": {
"your_deeplink_key": "value1"
},
"description": "Description for the item 1",
"headline": "Title for the item 1",
"id": 1
},
{
"image_url": "https://your_image_url.jpg",
"deep_links": {
"your_deeplink_key": "value2"
},
"description": "Description for the item 2",
"headline": "Title for the item 2",
"id": 2
},
{
"image_url": "https://your_image_url.jpg",
"deep_links": {
"your_deeplink_key": "value3"
},
"description": "Description for the item 3",
"headline": "Title for the item 3",
"id": 3
}
]
},
"camp_id": 1,
"camp_name": "Your push notification campaign name goes here",
"title": "Your push notification title goes here",
"message": "Your push content goes here",
"image_url": "https://your_image_url.jpg",
"ttl": 1,
"send_single_user": true,
"check_optin": true,
"android": {
"thread-id": 1,
"sound": "sound_check",
"deep_link": {
"ins_dl_internal": "https://www.deeplink.useinsider"
}
},
"ios": {
"thread-id": 13,
"badge": 1,
"deliver_silently": true,
"mutable-content": true,
"sound": "sound_check",
"content-available": true,
"deep_link": {
"ins_dl_internal": "https://www.deeplink.useinsider"
}
}
}
]
}
Sample Responses
200 OK
You will receive the following response if you send your request with the report_attributes array.
{
"successes": [
{
"INSIDER.age": null,
"INSIDER.app_version": "4.0",
"INSIDER.birthday": null,
"INSIDER.carrier": "mycarrier",
"INSIDER.device_language": "en",
"INSIDER.device_token": "d07951020f3835bbc303084ecda3746170cfb5d696ddcc55b6",
"INSIDER.email": "sample@mail.com",
"INSIDER.email_optin": null,
"INSIDER.environment": "production",
"INSIDER.gender": null,
"INSIDER.idfa": "AF3CCF3F-0V8E-6571-B296-E9BDFF7",
"INSIDER.insider_id": "940E4A98F309288AAC8C4",
"INSIDER.language": null,
"INSIDER.last_ip": null,
"INSIDER.location_optin": false,
"INSIDER.model": "iPhone 11",
"INSIDER.name": "John Smith",
"INSIDER.os_version": "14.7.1",
"INSIDER.package_name": "com.useinsider.iGurmeV3",
"INSIDER.phone_number": "+65123456789",
"INSIDER.platform": "iOS",
"INSIDER.push_optin": true,
"INSIDER.screen_height": null,
"INSIDER.screen_width": null,
"INSIDER.sdk_version": "10.6.0-RN-4.0.0",
"INSIDER.sms_optin": null,
"INSIDER.surname": null,
"INSIDER.timezone": "Europe/Helsinki",
"INSIDER.udid": "98BB170F5078F309288AAC8C4"
}
],
"errors": {}
}
You will receive the following response if you send your request without the report_attributes array.
{
"successes": [
{
"INSIDER.device_token": "d07951020f3084ecd4d3deda3746170cfb5d69672c055b6"
}
],
"errors": {}
}
There might be cases where the request returns a 200 response but the app pushes cannot be sent to users. The following list displays the reasons for these cases.
noUserErr | "NoUserFound" |
optOutErr | "OptOut" |
unregisteredErr | "Unregistered" |
userGloballyCappedErr | "UserGloballyCapped" |
userGloballyCappedForInappErr | "UserGloballyCappedForInapp" |
invalidCertificateErr | "InvalidCertificate" |
400 Bad Request
The following response returns if your request is missing an identifier.
{
"error": "empty_insider_identifiers",
"message": "'insider_identifiers' object need to have at least one identifier"
}
400 Bad Request
The following response returns if the notifications array is empty.
{
"error": "invalid_notifications",
"message": "'notifications' is empty, add some notification objects"
}
400 Bad Request
The following response returns if the array has more than 20 objects.
{
"error": "invalid_notifications",
"message": "'notifications' can't have more than 20 objects"
}
400 Bad Request
The following response returns if the deep link is blacklisted.
{
"error": "blacklisted_deeplink",
"message": "deepLink can't contain 'aps' key"
}
400 Bad Request
The following response returns if the camp ID or channel ID is a negative integer.
{
"error": "negative_integer",
"message": "camp_id' and/or 'channel_id' must be greater than zero"
}
400 Bad Request
The following response returns if the advanced push type is invalid.
{
"error": "invalid_advanced_push_type",
"message": "'advanced_push_type' must be either Carousel or Slider"
}
400 Bad Request
The following response returns if the certificate is invalid.
{
"error": "invalid_certificate",
"message": "You do not have a validated certificate. Please check Certificate section under Insider's Settings."
}
401 Unauthorized
The following response returns if the API key is either empty or wrong.
{
"error": "bad_api_key",
"message": "'api_key' is either empty or wrong. You can get your API key from Insider Dashboard"
}
Fail Records Messages
Message | Definition |
---|---|
InvalidRegistration (Android) | Check the format of the registration passed to the server. Make sure it matches the registration token the client app receives from registering with FCM. Do not truncate or add additional characters. |
NotRegistered (Android) | User uninstalled the app and is no longer reachable. |
MismatchSenderId (Android) | Google Sender ID used in the integration and the FCM Server Key do not belong to the same parent Google Account. |
BadDeviceToken (iOS) | The application and the app environment do not match. One is in development and the other is in production environment. |
DeviceTokenNotForTopic (iOS) | Push notification certificate topic and the application package name do not match. |
Unregistered (iOS) | User uninstalled the app and is no longer reachable. |
Limitations
- All functions must be executed with a simple HTTPS POST request.
- The API key should be provided in the request body. If the key is incorrect, no operation will be executed.
- You must complete the identifier integration with Insider SDK's user object for your platforms. See Android, iOS, React Native, Flutter, and Cordova for further details.
- The camp ID value should be greater than 0.
- The preferred_type value can be slider or carousel.
- The Android channel ID value should be greater than 0.