Push API. Windows

devtodev Push API supports two different formats of notification sending to Windows operational systems:

  • Universal format described in this section works on the basis of Legacy tiles and toast schema. It can be used on Windows Phone 8.1, Windows Phone 10, Windows 8.1, Windows 10. It is described by the "win" object.

  • UWP format - can be used only for Windows 10 and Windows Phone 10. It is described by the "uwp" object.

 

User identifiers

In order to find a user to whom you need to send a notification, you can 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

serialId

string

Hardware serial number

userId

string

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

 

Notification settings

Object "windows" can contain two properties :

  1. The property that describes a message can be represented by one of 4 possible objects:

  • toast (object) - the result of sending is the delivery of toast-notification

  • raw (object) - sends a hidden toast-notification

  • tile (object) - changes tile content of an app

  • badge (object) - changes the value of a badge field displayed in a tile of an app

  1. The property that describes additional parameters of a message represented by the object “options”. Optional.

 

Toast-notification content ("toast" object properties):

Property

Type

Description

title

string

Required. A short string describing the purpose of a notification.

text

string

Required. Main text of a notification message .

text2

string

Optional. Additional text of a notification.

data

object

Optional. 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"
}

 

icon

string

Optional. To replace the application icon (that shows up on the top left corner of the toast) use the URL or the resource name.

Any toast shown on Windows Phone 8.1 does not display the images (the app icon only).
In Windows 10 the image is expressed using the URI of the image source, using one of these protocol handlers:

  • A web-based image: http:// or https://
  • An image included in the app package: ms-appx:///
  • An image saved to local storage: ms-appdata:///local/
  • A local image (Only supported for desktop apps.): file:///

sound

string

Optional. A media file to play in place of a default sound. If the option is not used, a notification comes silently. This property can have one of the following string values:

  • Default

  • IM

  • Mail

  • Reminder

  • SMS

  • Looping.Alarm

  • Looping.Alarm2

  • Looping.Alarm3

  • Looping.Alarm4

  • Looping.Alarm5

  • Looping.Alarm6

  • Looping.Alarm7

  • Looping.Alarm8

  • Looping.Alarm9

  • Looping.Alarm10

  • Looping.Call

  • Looping.Call2

  • Looping.Call3

  • Looping.Call4

  • Looping.Call5

  • Looping.Call6

  • Looping.Call7

  • Looping.Call8

  • Looping.Call9

  • Looping.Call10

On mobile platform, this property can also contain the path to a local audio file, with one of the following prefixes:

  • ms-appx:///

  • ms-appdata:///

action

object

Optional.  Available for Windows 10 and WP 10 only. 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 Windows 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 for Windows 10 and WP 10 only. It is possible to specify an array of notification buttons in the “interactive” object. Each button must contain the following properties:

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

  • text (string) - Text on a button

  • handling (string) - The type of processing

    • background - A button closes an app. Notification parameters are transferred to an app, but an app doesn’t open. It is impossible to tie an action to a button in this regime.

    • foreground  - A button opens an app. Notification parameters are transferred to an app, but an app doesn’t 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",
    }]
}

 

 

Example

{
    "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",
        "serialId": "xxxxxxxxx",
        "customUid": "xxxxxxxxxxxx"
    }],
    "win": {
        "toast": {
            "title": "Toast title",
            "text": "Toast message",
            "data": {
                "key1": "value",
                "key2": "15"
            },
            "icon": "https://domain.com/pic.png",
            "sound": "default",
            "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": {
            "expire": 36000
        }
    }
}

 

Hidden notification ("raw" object):

Property

Type

Description

data

object

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

Example:

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

 

badge

string

Optional. A number from 1 to 99. A value of 0 is equivalent to the glyph value "none" and will clear a badge.

Instead of a number, a badge can display one of a non-extensible set of status glyphs:

  • activity

  • none

  • alarm

  • alert

  • attention

  • available

  • away

  • busy

  • error

  • newMessage

  • paused

  • playing

  • unavailable

It is also possible to send values incrementing or decrementing the current value in a “+2”, “-1” format. In case the previous value was the glyph or 0, the value will be increment. Decrement does not influence the zero value and the glyph.

 

Example

{
    "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",
        "serialId": "xxxxxxxxx",
        "customUid": "xxxxxxxxxxxx"
    }],
    "win": {
        "raw": {
            "data": {
                "key1": "value",
                "key2": "15"
            },
            "badge": "+1"
        }
    }
}

 

Tile-notification content ("tile" object):

Property

Type

Description

text1

string

First string on the tile.

with_header

boolean

Set True to mark "text1" field as a heading to show it larger.

text2

string

Second string on the tile.

text3

string

Third string on the tile.

text4

string

Fourth string on the tile.

image

string

Optional.Application-relative or Internet URI of the image.

Example:

  • "red.jpg" (if image is stored in an app’s installation directory or local storage folder)

  • "http://my.domain.com/img/red.jpg" (for Internet URIs).

We recommend using images with size 336 pixels by 336 pixels.

Important Note:

If you need to use remote Internet URIs for Tile images, you must take the following steps:

  • Ensure the remote image file size is less than 150 KB.

  • Ensure the image can be downloaded in 60 seconds or less.

Example

{
    "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",
        "serialId": "xxxxxxxxx",
        "customUid": "xxxxxxxxxxxx"
    }],
    "win": {
        "tile": {
            "text1": "Text 1",
            "text2": "Text 2",
            "text3": "Text 3",
            "text4": "Text 4",
            "with_header": "true",
            "image": "https://domain.com/pic.png"
        },
        "options": {
            "expire": 36000
        }
    }
}

Badge ("badge" object):

Property

Type

Description

badge

string

A number from 1 to 99. A value of 0 is equivalent to the glyph value "none" and will clear a badge.

Instead of a number, a badge can display one of a non-extensible set of status glyphs:

  • activity

  • none

  • alarm

  • alert

  • attention

  • available

  • away

  • busy

  • error

  • newMessage

  • paused

  • playing

  • unavailable

Example

{
	"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",
		"serialId": "xxxxxxxxx",
		"customUid": "xxxxxxxxxxxx"
	}],
	"win": {
		"badge": {
			"badge": "99"
		}
	}
}

Additional settings of notification delivery and display ("options" object)

Property

Type

Description

expire

number

This option identifies the date when the tile or toast is no longer valid and can be discarded. It is possible to use either relative time in seconds passed since sending, or to specify an exact date in UNIX epoch format date expressed in seconds (UTC). Default value is 7 days (604800 seconds) after sending.

 

 

Android
Windows UWP