Windows 8 WNS Payload Reference

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 data attributes, 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 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:

  • none

  • activity

  • alert

  • available

  • away

  • busy

  • new-message

  • paused

  • playing

  • unavailable

  • error

  • attention

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"
                }
            ]
        }
    }
}