devtodev Push API supports two different formats of notification sending to Windows operational systems:
UWP format described in this section can be used only for Windows 10 and Windows Phone 10. It is described by the "uwp" object.
The universal format works on a basis of Legacy tiles and toast schema. It can be used for Windows Phone 8.1, Windows Phone 10, Windows 8.1, Windows 10. It is described by the "windows" object.
Use this object (“uwp”) if your clients are users of OS Windows 10 and Windows Phone 10 only. With the help of this method it is possible to realize more opportunities offered by Windows 10.
In order to find an addressee to whom you need to send a notification, it is possible to specify one or several available identifiers:
Object "uwp" can contain 2 properties:
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 the tile content of an app - badge (object) - changes the value of a badge field displayed on a tile
The property that describes additional parameters of a message is represented by the object “options”. Optional.
Example
In UWP format every of tile’s size must be described separately, therefore, the object “tile” can contain up to 4 properties:
small
medium
wide
large (only for desktop)
Each of these sizes is described by an object with the following properties:
Example
Example
Example
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.
devtodevId
number
Numeric user identifier in devtodev database.
Property
Type
Description
scenario
string
Optional. Available values: "default", "alarm", "reminder", "incomingCall". Default value is "default". You do not need this unless your scenario is to pop an alarm, reminder, or incoming call. Do not use this just for keeping your notification persistent on screen.
title
string
Required. A short string describing the purpose of a notification.
text
string
Required. Main text of a notification.
text2
string
Optional. Additional text of a notification.
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 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.
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://
image
string
Optional. Image inside the toast body, below the text. Use the URL or the resource name.
sound
string
Optional. The media file to play in place of the default sound. If the option is not used, the notification comes silently. This property can have one of the following string values:
Default IM
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. 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 - Direct the user to a specific resource, either within your app or on the web.
url - Open a web page in a mobile browser, or any valid device-level URL such as Windows Store or app protocol links.
share - 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 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",
}]
}
Property
Type
Description
content
array
As long as tile’s content is dynamic, it is described by an array, the elements of which can be objects describing either text strings or illustrations.
Text element object properties:
text (string) - Required. The displayed string.
wrap (boolean) - Optional. By default, text doesn't wrap and will continue off the edge of the tile. Set true to set text wrapping on a text element.
style (string ) - Optional. Styles control the font size, color, and weight of text elements. There is a number of available styles including a "subtle" variation of each style that sets the opacity to 60%, which usually makes the text color a shade of light gray. Basic text styles:
caption (12 effective pixels height, regular weight)
body (15 epx, regular)
base (15 epx, semibold)
subtitle (20 epx, regular)
title (24 epx, semilight)
subheader (34 epx, light)
header (46 epx, light)
Numeral text style variations: (These variations reduce the line height so that content above and below come much closer to the text.)
titleNumeral
subheaderNumeral
headerNumeral
Subtle text style variations: (Each style has a subtle variation that gives the text a 60% opacity, which usually makes the text color a shade of light gray.)
captionSubtle
bodySubtle
baseSubtle
subtitleSubtle
titleSubtle
titleNumeralSubtle
subheaderSubtle
subheaderNumeralSubtle
headerSubtle
headerNumeralSubtle
Image element object properties
image (string) - Required. Image URI
remove_margin (boolean ) - Optional. By default, inline images have an 8-pixel margin between any content above or below the image. Set true to remove margin.
align (string) - Optional. Images can be set to align "left", "center", or "right". This will also cause images to display at their native resolution instead of stretching to fill width.
crop (string ) - Optional. Default value is "none". Images can be cropped into a circle in case of "circle" value.
placement (string) - Optional. You can specify an image that "peeks” in from the top of a tile or set a "background" image.
Group element object properties
group (array) - Required. Array of subgroup elements.
Subgroup element object (used inside groups only)
subgroup (array) - Required. Array of text or/and image elements.
branding
object
You can control the branding on the bottom of a live tile (the display name and corner logo) by using this property. Branding object properties:
type (string) - You can choose to display "none", only the "name", only the "logo", or both with "nameAndLogo". Windows Mobile doesn't support a corner logo, so "logo" and "nameAndLogo" default to"name" on mobile.
display_name (string) - Optional. You can override the display name of a notification by entering the text string of your choice.
v_align
string
You can control the vertical alignment of content on your tile by using this property. By default, everything is vertically aligned to the "top", but you can also align content to the "bottom" or "center".
overlay
number
Optional. You can set a black overlay on your background image using this property, which accepts integers from 0-100 with 0 being no overlay and 100 being full black overlay.
If you don't specify an overlay, the background image opacity defaults to 20% and the peek image opacity defaults to 0%.
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.
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