IOS

User identifiers

In order to find a user to whom you need to send a notification, it is possible specify one or several available identifiers:

Property

Type

Description

token

string

Push token. If you use a push token, all fields with other identifiers will be ignored!

idfa

string

Ad identifier IDFA

idfv

string

Device identifier under vendor IDFV

userId

string

User id is applicable if an internal identifier (cross-platform user identifier) is used in your app

devtodevId

number

Numeric user identifier in devtodev database.

Notification settings

The object of a message for the iOS platform contains 2 fields:

payload (object) - describes the main content of a notification
options (object) - describes the optional settings of notification delivery

Notification content settings ("payload" object)

Property

Type

Description

title

string

Optional. A short string describing the purpose of a notification. Apple Watch displays this string as a part of the notification interface. This string is displayed only briefly and should be crafted so that it can be understood quickly. This key was added in iOS 8.2.

text

string

The text of an alert message. Required if a notification is not hidden.

title-loc-key

string

Optional. The key to a title string in the Localizable.strings file for the current localization. The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in the title-loc-args array. See Localized Formatted Strings for more information. This key was added in iOS 8.2.

title-loc-args

string

Optional. Variable string values to appear in place of format specifiers in title-loc-key. See Localized Formatted Strings for more information. This key was added in iOS 8.2.

action-loc-key

string

Optional. If a string is specified, the system displays an alert that includes the “Close” and “View” buttons. The string is used as a key to get a localized string in the current localization to use for the right button’s title instead of “View”. See Localized Formatted Strings for more information.

loc-key

string

Optional. The key to an alert message string in a Localizable.strings file for the current localization (which is set by the user’s language preferences). The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in the loc-args array. See Localized Formatted Strings for more information.

loc-args

array

Optional. Variable string values to appear in place of format specifiers in loc-key. See Localized Formatted Strings for more information.

launch-image

string

Optional. The filename of an image file in the app bundle, with or without the filename extension. The image is used as a launch image when users tap the action button or move the action slider. If this property is not specified, the system either uses the previous snapshot, uses the image identified by the UILaunchImageFile key in the app’s Info.plist file, or falls back to Default.png. This property was added in iOS 4.0.

data

object

Optional if notification is not hidden. You can pass custom parameters with messages and use them within an app. For instance, you can activate advertising campaign or any other functionality for the user who has received this message.

Example:

"data": { "my_key": "value", "my_another_key": 15 }

badge

number

Optional. The number to display as the badge of the app icon. If this property is absent, the badge is not changed. To remove the badge, set the value of this property to 0.

sound

string

Optional. The name of a sound file in the app bundle or in the Library/Sounds folder of the app’s data container. The sound in this file is played as an alert. If the sound file doesn’t exist or "default" is specified as the value, the default alert sound is played. The audio must be in one of the audio data formats that are compatible with system sounds; see Preparing Custom Alert Sounds for details.

attachment

object

Optional. Available from devtodev iOS SDK 1.9, Cordova SDK 1.9, Unity SDK 2.3, UE4 SDK 1.9, Air SDK 1.8 Added in iOS 10. The possibility to attach images, videos, audio, and GIFs is available in iOS 10. Specify the type of an attachment ("image", "audio" or "video") and URL that leads to a media file. Attention, iOS uses only “https” protocol.

Example:

"attachment": { "type": "image", "url": "https://domain.com/pic.gif" }

action

object

Optional. Available from devtodev iOS SDK 1.9, Cordova SDK 1.9, Unity SDK 2.3, UE4 SDK 1.9, Air SDK 1.8 The action after a click on the body of a notification. By default, a click simply opens an app. It is also possible to perform the following actions:

deeplink (string) - Direct the user to a specific resource, either within your app or on the web.
url (string) - Open a web page in a mobile browser, or any valid device-level URL such as App Store or app protocol links.
share (string) - The Share Action drives a user to share your message when they interact with your push notification.

Examples:

"action": { "url": "http://www.domain.com" }

"action": { "deeplink": "your-url-scheme://host/path" }

"action": { "share": "Happy holidays!" }

interactive

object

Optional. Available from devtodev iOS SDK 1.9, Cordova SDK 1.9, Unity SDK 2.3, UE4 SDK 1.9, Air SDK 1.8 It is possible to specify one of the existing button templates in an “interactive” object, as well as assign the necessary actions to template buttons. It is possible to assign additional actions only to the button that opens an app. The same set of actions is available: deeplink, url and share. The list of accessible button templates is below in the text.

Example:

"interactive": { "template": "dtd_accept.open_decline.dismiss", "buttons": [{ "id": "accept", "action": { "url": "http://www.domain.com/accept" } }] }

Notification delivery and display settings (“options” object)

Property

Type

Description

sandbox

boolean

Default value is false ("Production" gateway). Set to true if you need to send notification through the "Sandbox" gateway (for builds signed with a developer certificate).

hidden

boolean

Switching a notification to the hidden mode. If “true” - a notification will not be displayed to a user, but will be transferred to an app. Such a message must not contain any properties except “data” in the “payload” object.

Including this key and value means that when your app is launched in the background or resumed, application:didReceiveRemoteNotification:fetchCompletionHandler: is called

priority

string

Optional. The priority of a notification. Default value is "normal". Specify one of the following values:

"high" – Send a push message immediately. Notifications with this priority must trigger an alert, sound, or badge on a target device. It is an error to use this priority for a push notification that contains only the content-available key.
"normal" — Send a push message at a time that takes into account power considerations for a device. Notifications with this priority might be grouped and delivered in bursts. They are throttled, and in some cases are not delivered.

expire

number

This option identifies the date when the notification is no longer valid and can be discarded. It is possible to use either relative time in seconds passed since the moment of sending, or to specify the exact date in UNIX epoch format date expressed in seconds (UTC).

Default value is 7 days (604800 seconds) after sending.

If this value is nonzero, APNs stores a notification and tries to deliver it at least once repeating the attempt as needed if it is unable to deliver a notification for the first time. If the value is 0, APNs treats the notification as if it expires immediately and does not store the notification or attempt to redeliver it.

collapse_key

string

Multiple notifications with the same collapse identifier are displayed to a user as a single notification. The value should not exceed 64 bytes.

Button templates

Name

Description

Template ID

Button 1

Button 2

Label

Yes or No (Open an app)

Yes option takes user into an app. No dismisses the notification.

dtd_yes.open_no.dismiss

Yes

yes

Yes or No (Dismiss notification)

Yes and No options dismiss the notification when clicked without taking a user into an app.

dtd_yes.dismiss_no.dismiss

Yes

yes

Accept or Decline (Open the app)

Accept option takes a user into an app. No dismisses a notification.

dtd_accept.open_decline.dismiss

Decline

decline

Accept or Decline (Dismiss notification)

Yes and No options dismiss a notification when clicked without taking a user into an app.

dtd_accept.dismiss_decline.dismiss

Decline

decline

Shop Now

Shop Now takes user into an app. Should be a different location from a notification action.

dtd_shop_now.open

Shop Now

shop_now

Buy Now

Buy Now takes user into an app. Should be a different location from a notification action.

dtd_buy_now.open

Buy Now

buy_now

Tell me more

Deep link to more details about a specific offer or program

dtd_more_info.open

Tell me more

more_info

Download

Download deep links users directly to media e.g. wallpaper images, apps, music downloads, file downloads, etc.

dtd_download.open

Download

download

Pass sharing text through to native OS apps like Facebook and Twitter using the Share action.

dtd_share.open

Download or Share

Download deep links users directly to media e.g. wallpaper images, apps, music downloads, file downloads, etc. Share the same media socially.

dtd_download.open_share.open

Download

download

Shop Now or Share

Shop Now takes a user into an app; should be a different location from a notification action.

dtd_shop_now.open_share.open

Shop Now

shop_now

Buy Now or Share

Buy Now takes a user into an app; should be a different location from a notification action.

dtd_buy_now.open_share.open

Buy Now

buy_now

Like or Dislike

Both options take a user into an app.

dtd_like.open_dislike.open

Dislike

dislike

Like or Dislike

Like option takes user into an app. Dislike dismisses a notification.

dtd_like.open_dislike.dismiss

Dislike

dislike

Option takes a user into an app.

dtd_like.open

Like and Share

Capture user sentiment by allowing users to like a message or share it. Both options take user into an app.

dtd_like.open_share.open

Add

Add an item: most often a wallet pass or card to your digital Wallet.

dtd_add.open

Add

add

Save and No

Save something for future reference.

dtd_save.open

Save

save

Rate now

Drive users to rate an app in the app store by deep linking from this button.

dtd_rate.open

Rate now

rate

Deep link to a search functionality within an app

dtd_search.open

Book now

Deep link to booking flow within an app.

dtd_book.open

Book now

book

The text on the buttons, which are on the list of templates, is translated into N languages and displayed to users individually according to the location of a device.

Examples

Push

https://devtodev.com/api/v1/push/send

POST

{
    "user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "campaign_tag": "campaign name",
    "pack_id": "uniqueid1234",
    "audience": [{
        "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "idfa": "XXXXX-XXXXX-XXXXXX-XXXXXX",
        "idfv": "XXXXX-XXXXX-XXXX-XXXXX-XXXX",
        "userId": "xxxxxxxxxxxx"
    }],
    "ios": {
        "payload": {
            "title": "Title of the notification",
            "text": "Notification content.",
            "data": {
                "key1": "value",
                "key2": "15"
            },
            "badge": 11,
            "sound": "bingbong.aiff",
            "attachment": {
                "type": "image",
                "url": "https://domain.com/pic.png"
            },
            "action": {
                "url": "http://www.domain.com"
            },
            "interactive": {
                "template": "dtd_accept.open_decline.dismiss",
                "buttons": [{
                    "id": "accept",
                    "action": {
                        "url": "http://www.domain.com/accept"
                    }
                }]
            }
        },
        "options": {
            "hidden": false,
            "priority": "normal",
            "expire": "36000",
            "collapse_key": "qwerqwer"
        }
    }
}

Hidden push

https://devtodev.com/api/v1/push/send

POST

{
    "user_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "campaign_tag": "campaign name",
    "pack_id": "uniqueid1234",
    "audience": [{
        "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "idfa": "XXXXX-XXXXX-XXXXXX-XXXXXX",
        "idfv": "XXXXX-XXXXX-XXXX-XXXXX-XXXX",
        "userId": "xxxxxxxxxxxx"
    }],
    "ios": {
        "payload": {
            "data": {
                "key1": "value",
                "key2": "15"
            },
            "badge": "11"
        },
        "options": {
            "hidden": true,
            "priority": "normal",
            "expire": "36000"
        }
    }
}

PreviousPush API NextAndroid

Last updated 1 year ago