Push API. Android

User identifiers

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

Property

Type

Description

token

string

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

advertisingId

string

Advertising ID

androidId

string

Android ID

serialId string Serial ID

userId

string

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

 

Notification settings

The object of a message for the Android 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

A short string describing the purpose of a notification.

text

string

The text of an alert message.

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 a user who has received this message.

Example:

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

 

small_icon

string

Optional. You may use an icon from resources of your app. You should use resource name of the icon in this field.

color

string

Optional. The parameter recolors the small icon of an app displayed in a notification in the specified color ("#RRGGBB"). This N parameter on Android also recolors the name of an app and texts on notification buttons.

Example:

"color": "#ff0000"

 

icon

string

Optional. Use the URL to a notification icon or a resource name.

image

string

Optional. The value is image URL. Images should be ≤ 450dp wide, ~2:1 aspect. The image will be center cropped.

sound

string

Optional. A media file to play in place of a default sound. If a sound file doesn’t exist or default is specified as the value, the default notification sound is played. The audio must be in one of the audio data formats that are compatible with system sounds. Supports “default” or the filename of a sound resource bundled in an app. Android sound files must reside in /res/raw/ If the option is not used, a notification comes silently.

badge int Optional. This property was added in Android O. The value of the badge on the home screen app icon.
If not specified, the badge is not changed. If set to 0, the badge is removed.

vibration

boolean

Optional. In case of "true" during notification delivery a device will vibrate (if permission VIBRATION is received)

led_color

string

Optional. LED hex color  ("#RRGGBB"), a device will do its best approximation.

Example:

"led_color": "#ff0000"

 

action

object

Optional. The action after a click on the body of a notification. By default, a click opens an app. It is also possible to perform the following actions:

  • deeplink (string)  - Direct a 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 Google Play 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. It is possible to specify an array of notification buttons in an “interactive” object. Each button should contain the following properties:

  • id (string) - The button identifier. It is transferred to an app.

  • text (string) - A text on a button

  • handling (string) - The type of processing

    • background - The button closes a notification. The parameters of a notification are transferred to an app, but an app does not open. It is impossible to tie an action to a button in this regime.

    • foreground  - The button opens an app. The parameters of a notification are transferred to an app, but an app does not open. It is possible to tie an action to a button in this regime. The list of actions and the principle is analogical to actions with the body of a message.

Example:
"interactive": {
    "buttons": [{
        "id": "accept",
        "text": "Accept",
        "handling":"foreground",
        "action": {
            "url": "http://www.domain.com/accept"
        },
        {
        "id": "decline",
        "text": "Decline",
        "handling":"background"
    }]
}

 

 

 

Notification delivery and display settings ("options" object)

Property

Type

Description

hidden

boolean

Switching the 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.

priority

string

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

  • high" – GCM attempts to deliver high priority messages immediately allowing the GCM service to wake a sleeping device when possible and open a network connection to your app server. Apps with instant messaging, chat, or voice call alerts, for example, generally need to open a network connection and make sure GCM delivers the message to the device without delay. Set high priority only if the message is time-critical and requires the user’s immediate interaction, and beware that setting your messages to high priority contributes to a battery drain more compared to normal priority messages.

  • "normal" — This is the default priority for message delivery. Normal priority messages won't open network connections on a sleeping device, and their delivery may be delayed to preserve a battery. For less time-sensitive messages (such as notifications of new email or other data to sync) choose normal delivery priority.

expire

number

This option identifies the date when a 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 specify an exact date in UNIX epoch format expressed in seconds (UTC).

Default value is 7 days (604800 seconds) after sending. Max. relative value for Android platform is 2 419 200 seconds (4 weeks).

Keep in mind that an "expire" value of 0 means messages that can't be delivered immediately will be discarded. However, as long as such messages are never stored, this provides the best latency for sending notifications.

collapse_key

string

Optional. Notifications are not collapsible by default.

If multiple messages are sent with this key, the most recent message will suppress all previous unread messages with the same key.

Collapsible messages are a better choice from a performance standpoint provided your application doesn't need to use non-collapsible messages. However, if you use collapsible messages, remember that GCM only allows a maximum of 4 different collapse keys to be used by the GCM connection server per registration token at any given time. You must not exceed this number, or it could cause unpredictable consequences.

channel_id string Optional. The notification's channel id (this property was added in Android O). The app must create a channel with this ID before any notification with this key is received. If you don't send this key in the request, or if the channel id provided has not yet been created by your app, devtodev SDK uses the channel id specified by default ("channel_id": "devtodev_general" - name: General notifications).
badge_icon_type int

Optional. This property was added in Android O (API level 26).
0 - Default. If this notification is being shown as a badge, always show as a number.
1 - If this notification is being shown as a badge, use the getSmallIcon() to represent this notification.
2 - If this notification is being shown as a badge, use the getLargeIcon() to represent this notification.

 

 

Examples

Visible push notification

​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",
        "advertisingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "androidId": "xxxxxxxxxxxxxxxxxxxxxxxxx",
        "userId": "xxxxxxxxxxxx"
    }],
    "android": {
        "payload": {
            "title": "Title of the notification",
            "text": "Notification content.",
            "data": {
                "key1": "value",
                "key2": "15"
            },
            "small_icon": "smallicon",
            "icon": "midicon",
            "image": "https://domain.com/pic.png",
            "sound": "bingbong",
            "vibration": true,
            "led_color": "#ff0000",
            "color": "#ff0000",
            "action": {
                "url": "http://www.domain.com"
            },
            "interactive": {
                "buttons": [{
                    "id": "accept",
                    "text": "Accept",
                    "handling": "foreground",
                    "action": {
                        "url": "http://www.domain.com/accept"
                    }
                }, {
                    "id": "decline",
                    "text": "Decline",
                    "handling": "background"
                }]
            }
        },
        "options": {
            "hidden": false,
            "priority": "normal",
            "expire": 36000,
            "collapse_key": "collapse1"
        }
    }
}

Hidden push notification

​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",
        "advertisingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "androidId": "xxxxxxxxxxxxxxxxxxxxxxxxx",
        "userId": "xxxxxxxxxxxx"
    }],
    "android": {
        "payload": {
            "data": {
                "key1": "value",
                "key2": "15"
            }
        },
        "options": {
            "hidden": true,
            "priority": "normal",
            "expire": 36000
        }
    }
}
 
iOS
Windows