Windows 8 WNS Payload Examples
This is a collection of example Push API V3 payloads for WNS.
Platform Specific Section
In order to send to Windows devices, you must choose wns as the device_type. See Audience Selection for mor detail.
The platform-specific key for WNS is wns. The data format is a JSON mirror of the XML schema for
WNS .
Common Data - WNS Header Fields
There are 3 values in the wns section which are common to all push types, and are sent as HTTP headers in the native WNS payload.
| Field | Type | Required | Notes |
|---|---|---|---|
cache_policy | string | no | one of “cache” or “not-cache” |
tag | string | no | |
ttl | number | no |
Common Data - Binding
Toasts and Tiles share a lot of properties, which are grouped into
a binding. A toast can have a single binding, while a tile can have
two (one for square tiles, one for wide tiles). This is parallel to
the <binding> XML element in the native WNS payload. Microsoft’s
documentation can be found in the Toast XML Schema document.
The explanations below are derived from that document. A binding can
have the following fields:
| Field | Type | Required | Notes |
|---|---|---|---|
template | string | yes | The name of the template to render the notification with. The valid range of values are enumerated in this MSDN document: ToastTemplateType enumeration . |
version | number | no | |
fallback | string | no | Fallback can optionally contain the name of another template. This can be used to provide some OS-version independencies for pushes. e.g., if Microsoft adds new template types in an update to Windows 8, we can send one push which will use the new temnplate, and fall back to a templatev that’s guaranteed to be in the base OS release if sent to a device that doesn’t have the new template. |
lang | string | no | |
base_uri | string | no | |
add_image_query | boolean | no | |
image | array of strings | no | |
text | array of strings | no |
Toast
To send a toast notification, set the toast field.
Duration
Toasts can be displayed for either a short duration (7 seconds), which
is the default, or a long duration (30 seconds). This is set by the
optional duration field in the toast object.
Example, with other data fields omitted:
{
"notification": {
"wns": {
"toast": {
"duration": "short"
}
}
}
}Or:
{
"notification": {
"wns": {
"toast": {
"duration": "long"
}
}
}
}Audio
Unless the user has chosen the “No Sounds” system sound theme, toasts
will play a sound when they are delivered to the device. This behavior
can be overriden by the audio key in the WNS payload. The
audio object can have the following fields:
| Field | Type | Required | Notes | | — | — | — | | sound | string | yes | | loop | boolean | no |
Examples
"notification": {
"wns": {
"toast": {
"audio": {
"sound": "reminder"
}
}
}
}To send a silent notification, add "audio": { "sound" : "mute" } to your
notification.
"notification": {
"wns": {
"toast": {
"audio": {
"sound": "mute"
}
}
}
}Templates - ToastText01
The simplest toast notification takes a single string, and looks like this on the device:
Here’s a basic push API payload with no platform-specific section, which generates a simple toast using the ToastText01 template.
{
"notification" : {
"alert" : "ToastText01 - a single line of small text, wrapped as necessary across up to three lines on screen."
}
}If you were to re-write this using the WNS specific schema instead, here’s what it would look like:
"notification": {
"wns": {
"toast": {
"binding": {
"text": [
"ToastText01 - a single line of small text, wrapped as necessary across up to three lines on screen."
],
"template": "ToastText01"
}
}
}
}Obviously that’s a lot more verbose, but there’s a lot to the template capabilities of WNS, and the data format is very regular. It gets more interesting with more complicated templates.
And this is the XML that it turns into for pushing to WNS:
<toast >
<visual>
<binding template="ToastText01">
<text id="1">ToastText01 - a single line of small text, wrapped as necessary across up to three lines on screen.</text>
</binding>
</visual>
</toast>Other Templates
WNS toasts are rendered with a template, of which there 8 - 4 with text only, and 4 with text and an image. Microsoft’s ToastTemplateType enumeration documentation lists them all with screenshots (embedded here).
ToastText02
The ToastText02 template takes two strings - the first is a single-line header, rendered in bold. The second is a two-line body that wraps.
"notification": {
"wns": {
"toast": {
"binding": {
"text": [
"ToastText02 - has a header",
"and a line of small text, wrapped as necessary across up to two lines on screen."
],
"template": "ToastText02"
}
}
}
}ToastText03
ToastText03 inverts ToastText02 - the first text value is a two-line header, rendered in bold. The second is a plain line of text rendered on the third line of the notification.
"notification": {
"wns": {
"toast": {
"binding": {
"text": [
"ToastText03 - has a header, formatted in bold, which can wrap across two lines",
"and a single line of plain text"
],
"template": "ToastText03"
}
}
}
}ToastText04
ToastText04 takes 3 strings, rendering each on a separate, non-wrapping line. The first one is rendered in bold.
"notification": {
"wns": {
"toast": {
"binding": {
"text": [
"ToastText04 - has a single line header in bold",
"And two additional lines",
"which do not wrap"
],
"template": "ToastText04"
}
}
}
}ToastImageAndText01
The image and text templates all match the text formatting of their text-only counterparts, but with a square image on the left side of the notification (and correspondingly narrower lines of text).
"notification": {
"wns": {
"toast": {
"binding": {
"text": [
"ToastImageAndText01 - a toast with an image and a single line of text which wraps"
],
"image": [
"/Assets/1.jpg"
],
"template": "ToastImageAndText01"
}
}
}
}ToastImageAndText02
"notification": {
"wns": {
"toast": {
"binding": {
"text": [
"ToastImageAndText02: header",
"Text2 is a small line that wraps as necessary"
],
"image": [
"/Assets/1.jpg"
],
"template": "ToastImageAndText02"
}
}
}
}ToastImageAndText03
"notification": {
"wns": {
"toast": {
"binding": {
"text": [
"ToastImageAndText03 - has a two-line header that wraps",
"Text2 is a single line"
],
"image": [
"/Assets/1.jpg"
],
"template": "ToastImageAndText03"
}
}
}
}ToastImageAndText04
"notification": {
"wns": {
"toast": {
"binding": {
"text": [
"ToastImageAndText04 - header",
"Text2 - single line",
"Text3 - single line"
],
"image": [
"/Assets/1.jpg"
],
"template": "ToastImageAndText04"
}
}
}
}Badges
| Field | Type | Required | Notes |
|---|---|---|---|
value | number | no* | One of value or glyph must be supplied. |
glyph | string | no |
Value Update
{
"notification": {
"wns": {
"badge": {
"value": "1"
}
}
}
}Glyph Update
In addition to numbers, there is a fixed set of image glyphs that can be set on the badge.
{
"notification": {
"wns": {
"badge": {
"glyph": "busy"
}
}
}
}Acceptables values for the glyph are:
noneactivityalertavailableawaybusynew-messagepausedplayingunavailableerrorattention
Tile Examples
To send a tile notification, set the tile field.
The structure of tile notifications is very much like toasts - for each
binding there is a template, one or more strings, and possibly some
images. But for tiles the binding field is an array of one or more
bindings. there should be two instances of the “binding” object, to
support the two tile sizes that the Windows 8 start screen can display.
Each app can be displayed as either a square tile or a wide tile, so
each tile notification should have a binding for each. The order of
bindings is not important - they will be applied to the tile sizes
according to their template.
There are also many more templates for tiles , with more possible content.
Wide Tiles
TileWideImage
"notification": {
"wns": {
"tile": {
"binding": [
{
"image": [
"/Assets/1.jpg"
],
"template": "TileWideImage"
}
]
}
}
}TileWideImageCollection
"notification": {
"wns": {
"tile": {
"binding": [
{
"image": [
"/Assets/1.jpg",
"/Assets/2.jpg",
"/Assets/3.jpg",
"/Assets/4.jpg",
"/Assets/5.jpg"
],
"template": "TileWideImageCollection"
}
]
}
}
}TileWideImageAndText01
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideImageAndText01"
],
"image": [
"/Assets/1.jpg"
],
"template": "TileWideImageAndText01"
}
]
}
}
}TileWideImageAndText02
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideImageAndText02",
"Text2"
],
"image": [
"/Assets/1.jpg"
],
"template": "TileWideImageAndText02"
}
]
}
}
}TileWideBlockAndText01
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideBlockAndText01",
"Text2",
"Text4",
"Text4",
"34",
"Text6"
],
"template": "TileWideBlockAndText01"
}
]
}
}
}TileWideBlockAndText02
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideBlockAndText02 has a single small line of text that wraps on the left side of the tile",
"99",
"Text3"
],
"template": "TileWideBlockAndText02"
}
]
}
}
}TileWidePeekImageCollection01
TileWidePeekImageCollection02
TileWidePeekImageCollection03
TileWidePeekImageCollection04
TileWidePeekImageCollection05
TileWidePeekImageCollection06
TileWidePeekImageAndText01
TileWidePeekImageAndText02
TileWidePeekImage01
TileWidePeekImage02
TileWidePeekImage03
TileWidePeekImage04
TileWidePeekImage05
TileWidePeekImage06
TileWideSmallImageAndText01
TileWideSmallImageAndText02
TileWideSmallImageAndText03
TileWideSmallImageAndText04
TileWideSmallImageAndText05
TileWideText01
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideText01",
"A bold header.",
"Three additional lines",
"etc..."
],
"template": "TileWideText01"
}
]
}
}
}TileWideText02
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideText02",
"Text2",
"Text3",
"Text4",
"Text5",
"Text6",
"Text7"
],
"template": "TileWideText02"
}
]
}
}
}TileWideText03
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideText03 - a single line of large text that wraps across two lines."
],
"template": "TileWideText03"
}
]
}
}
}TileWideText04
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideText04 - a single line of small text that wraps across up to four lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
],
"template": "TileWideText04"
}
]
}
}
}TileWideText05
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideText05 - four lines of text",
"In one column.",
"That do not wrap.",
"Good for haiku apps."
],
"template": "TileWideText05"
}
]
}
}
}TileWideText06
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideText06",
"Eight strings",
"In two columns",
"Alternating",
"between",
"left",
"and",
"right"
],
"template": "TileWideText06"
}
]
}
}
}TileWideText07
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideText07",
"Header",
"And three lines",
"Split",
"into two columns",
"Narrow",
"and wide"
],
"template": "TileWideText07"
}
]
}
}
}TileWideText08
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TWT08",
"8 lines of text",
"Split",
"into two columns",
"Narrow",
"and wide",
"with",
"no header"
],
"template": "TileWideText08"
}
]
}
}
}TileWideText09
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideText09",
"One large header, plus a single text value set in a small font, wrapped across up to three lines."
],
"template": "TileWideText09"
}
]
}
}
}TileWideText10
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileWideText10",
"Tx2",
"Text3",
"Tx4",
"Text5",
"Tx6",
"Text7"
],
"template": "TileWideText10"
}
]
}
}
}TileWideText11
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"Tx1",
"Text2 - TileWideText11",
"Tx3",
"Text4",
"Tx5",
"Text6",
"Tx7",
"Text8"
],
"template": "TileWideText11"
}
]
}
}
}Square Tiles
TileSquareImage
"notification": {
"wns": {
"tile": {
"binding": [
{
"image": [
"/Assets/1.jpg"
],
"template": "TileSquareImage"
}
]
}
}
}TileSquareBlock
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"99",
"TileSquareBlock"
],
"template": "TileSquareBlock"
}
]
}
}
}TileSquareText01
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"UADemo",
"TileSquareText01",
"Header and",
"three lines"
],
"template": "TileSquareText01"
}
]
}
}
}TileSquareText02
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"UADemo",
"TileSquareText02 - header and one string that wraps across three lines"
],
"template": "TileSquareText02"
}
]
}
}
}TileSquareText03
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileSquareText03",
"Four strings",
"No wrapping",
"That is all."
],
"template": "TileSquareText03"
}
]
}
}
}TileSquareText04
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileSquareText04 - a single string that wraps across up to four lines."
],
"template": "TileSquareText04"
}
]
}
}
}TileSquarePeekImageAndText01
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileSquarePeekImageAndText01",
"Text2",
"Text3",
"Text4"
],
"image": [
"/Assets/1.jpg"
],
"template": "TileSquarePeekImageAndText01"
}
]
}
}
}TileSquarePeekImageAndText02
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileSquarePeekImageAndText02",
"Text2"
],
"image": [
"/Assets/1.jpg"
],
"template": "TileSquarePeekImageAndText02"
}
]
}
}
}TileSquarePeekImageAndText03
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileSquarePeekImageAndText03",
"Text2",
"Text3",
"Text4"
],
"image": [
"/Assets/1.jpg"
],
"template": "TileSquarePeekImageAndText03"
}
]
}
}
}TileSquarePeekImageAndText04
"notification": {
"wns": {
"tile": {
"binding": [
{
"text": [
"TileSquarePeekImageAndText04 has a single line that wraps"
],
"image": [
"/Assets/1.jpg"
],
"template": "TileSquarePeekImageAndText04"
}
]
}
}
}Categories