My AppsLive demoNewsArticles

Windows UWP

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.

User identifiers

In order to find an addressee 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

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.

Notification settings

Object "uwp" can contain 2 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 the tile content of an app - badge (object) - changes the value of a badge field displayed on a tile

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

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

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

  • 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. 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", }] }

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"
    }],
    "uwp": {
        "toast": {
            "scenario": "default",
            "title": "Notification title",
            "text": "First notification string",
            "text2": "Second notification string",
            "data": {
                "key1": "value",
                "key2": "value"
            },
            "icon": "https://domain.com/pic.png",
            "image": ["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": 3600
        }
    }
}

Tile ("tile" object properties)

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:

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%.

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"
    }],
    "uwp": {
        "tile": {
            "medium": {
                "content": [{
                    "text": "First sting",
                    "wrap": "true",
                    "style": "base",
                    "align": "center"
                }, {
                    "image": "https://domain.com/pic.png",
                    "remove_margin": "true",
                    "align": "center",
                    "crop": "circle",
                    "placement": "background"
                }],
                "v_align": "center",
                "overlay": "60",
                "branding": {
                    "type": "none"
                }
            },
            "wide": {
                "content": [{
                    "text": "First string",
                    "wrap": "true",
                    "style": "base",
                    "h_align": "center"
                }, {
                    "image": "Assets\\Apps\\Weather\\MostlyCloudy.png",
                    "remove_margin": "true",
                    "align": "center",
                    "crop": "circle",
                    "placement": "background"
                }],
                "v_align": "center",
                "branding": {
                    "type": "nameAndLogo",
                    "display_name": "brandname"
                }
            }
        },
        "options": {
            "expire": 3600
        }
    }
}

Hidden notification ("raw" object properties):

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"
    }],
    "uwp": {
        "raw": {
            "data": {
                "key1": "value",
                "key2": "value"
            },
            "badge": "+1"
        }
    }
}

Badge ("badge" object properties):

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"
    }],
    "uwp": {
        "badge": {
            "badge": "99"
        }
    }
}
PreviousAndroidNextWindows

Last updated

#989: best practices - improved readability

Change request updated