Skip to content

Windows Notification Service

WNS provides a native mechanism to send notifications to the back end. Back-end systems use the Push REST service to notify the mobile platform about notification messages it sends to devices.

Payload Handling for WNS

This section provides examples of JSON payload handling for WNS custom values.

WNS-Specific Properties

The wns entity provides payload handling for Windows. wns is validated with a higher priority than globally-configured properties (such as Data, Sound, Alert). The root element of the new entity, and all its direct sub-elements are optional.

wns.badge (WNS)

The badge element represents a certain WNS push schema (wns/badge).

Element handling:

  • Overrides the global badge configuration, whether it is a number or a string.

  • The badge is sent as a separate request to the device.

  • If a number, 0 clears the badge; values from 1-99 are shown as given; and any value greater than 99 are shown as 99+.

  • If a string, the badge is shown as a predefined Windows glyph.

See also: badge.

wns.rawData

The rawData element represents a certain WNS push schema (wns/raw).

Element handling:

  • Overrides the global data configuration.

  • Any string can be configured as rawData, and sent to the device.

wns.version

The version element sets the version property at the notification requests (tile, toast and badge).

Element handling:

  • Any string configured as version is sent to the device.

  • The default is 1.0.

wns.lang

The lang element sets the lang property for the notification requests (tile, and toast).

Element handling: defines the language property of the content.

wns.schema

The schema element defines which notification schemas should be sent.

Element handling:

  • A list containing up to four elements.

  • Restricted to one of BADGE, TILE, TOAST or RAW.

  • The default sends all (in case content exists).

wns.tileTemplate

The tileTemplate element sets the template property for tile schema at the binding attribute. Windows provides a selection of several predefined templates, which affect the final layout of the displayed notification at the device. The elements that can be selected depend on the device operating system version.

Element handling:

  • Any string.

  • Default value depends on the push content:

  • Text only: TileSquareText04

  • One picture and text: TileSquarePeekImageAndText04

  • Few pictures and text: TileWidePeekImageCollection04

  • One picture only: TileWideImage

  • Few pictures only: TileWideImageCollection

See also: TileTemplateType Enum.

wns.toastTemplate

The toastTemplate element sets the template property for toast schema at the binding attribute. Windows provides a selection of several predefined templates, which affect the final layout of the displayed notification at the device. The elements that can be selected depend on the device operating system version.

Element handling:

  • Any string.

  • Default value depends on the push content:

  • Text only: ToastText01

  • One picture and text: ToastImageAndText04

  • Few pictures and text: ToastImageAndText04

  • One picture only: ToastImageAndText04

  • Few pictures only: ToastImageAndText04

See also: ToastTemplateType Enum.

wns.message

The message element defines the text attribute for tile and toast notifications.

Element handling:

  • No, one, or more messages can be added.

  • Any string.

wns.baseUri

The baseUri element defines the baseUri property at the binding attribute for tile and toast. This property defines a central base URL which is used for all images.

Element handling: any string.

wns.audio

The audio element defines the audio attribute for toast notifications.

Element handling: overrides the global sound configuration.

Properties:

  • loop: [Boolean, optional] ‒ defines whether the sound should be played in a loop.

  • silent: [Boolean, optional] ‒ defines whether the sound should be muted. If true, no sound is sent.

  • src: [String, required] ‒ defines the source of the sound file.

wns.image

The image element defines the image attribute for tile and toast notifications.

Element handling: no, one, or more images can be added.

Properties:

  • alt: [String, optional] ‒ defines an alternative text if the image cannot be loaded.

  • addImageQuery: [Boolean, optional] ‒ allows Windows to add a query to the image src, the default is false.

  • src: [String, required] ‒ defines the source of the image.

wns.commands

The commands element defines the commands attribute for toast notifications. Commands correspond to available actions that the user can take.

Element handling: no, one, or more commands can be added.

Properties: scenario [String, optional] ‒ defines the scenario (alarm or incomingCall, the default is alarm).

Aggregations:

  • id [String, optional] ‒ specifies one command from the system-defined command list. (such as snooze, or dismiss).

  • arguments [String, optional] ‒ an argument string that can be passed to the associated app to provide specifics about the action that it should execute in response to the user action.

W3C Push Notification Payload Handling

The W3C Push Service enables browser notifications in web pages, see W3C Push Notifications.

mobile services sends the generic properties only, when no w3c.blob specific values are set.

{
   "alert": "Updates Available",
   "badge": 1,
   "data": "{\"URL\":\"https://acme.com/message/1234\"}",
   "priority": "high",
   "sound": "DefaultNotificationSound"
}

is sent as

{
   "alert": "Updates Available",
   "badge": 1,
   "data": {"URL":"https://acme.com/message/1234"},
   "priority": "high",
   "sound": "DefaultNotificationSound"
}

W3C priority

The message priority. Known values are very-low, low, normal (default) and high.

W3C w3c.ttl

The time-to-live (TTL) value for this message in seconds. Maximum is 2419200 seconds (default) or 28 days.


Last update: December 6, 2023