Using the notification queue (Windows Runtime apps)

Use of the notification queue allows a tile to display a rotation of up to five notifications. By default, a tile on the Start screen displays the content of a single notification until a new notification replaces the current notification. With notification queuing enabled, up to five notifications are maintained in the queue and the tile cycles through them. The notification queue can be used with all notification delivery types: local, scheduled, periodic, or push.

Note  The amount of time each notification in the queue is displayed and the order in which they appear on the tile is based on several internal factors and cannot be controlled by apps.

Replacing queued notifications

By default, if the queue has reached its capacity of five notifications, the next new notification replaces the oldest notification in the queue. However, by setting tags on your notifications, you can affect this replacement policy.

Tags are app-specified strings. Windows examines the tag on an incoming notification, looks for a notification in the queue with a matching tag, and, if one is found, replaces that notification in the queue. If no notification with a matching tag is found, the default first in, first out (FIFO) rule is applied.

Notification queuing and tagging can be used to implement a variety of rich notification scenarios. For example, a stock app could send five notifications, each concerning a different stock and tagged with the stock name. This prevents the queue from ever containing two notifications for the same stock, the older of which is out of date.

Enabling the notification queue

Enable the notification queue by calling EnableNotificationQueue. This call should be made before you send any notifications to your tile; that is, before you request your first push notification channel, start periodic updates, or send any local notifications to that tile. Do not switch between an enabled and disabled notification queue; choose whether to support the queue as part of your app design to avoid potentially confusing tile behavior.

Using the notification queue with local and scheduled notifications

The procedure to send notifications locally to your tile (including scheduled notifications) does not change when you use the notification queue. By default, the notifications you update through the local notification APIs are placed in the queue in FIFO order if the queue is enabled. To use tags with your local or scheduled tile notification, supply the optional tag property on the notification object before you send it to the tile or add it to the schedule. For more information, see TileNotification or ScheduledTileNotification.

An example of the use of local notifications with the notification queue can be found in How to use the notification queue.

Using the notification queue with push notifications

The procedure to send push notifications to your tile also does not change when the notification queue is enabled. By default, the notifications you update through the push notification APIs are placed in the queue in FIFO order if the queue is enabled.

To set tags on push notifications, your cloud service must use the X-WNS-Tag HTTP header when sending the notification. For more information, see Push notification service request and response headers.

If you have enabled the notification queue, but the user is offline, up to five notifications will be stored by Windows Push Notification Services (WNS) and delivered when the user comes online. These undelivered notifications conform to the standard FIFO queue and replacement tagging logic.

Using the notification queue with periodic updates

In the case of periodic notifications, a unique Uniform Resource Identifier (URI) is provided for each notification. The URI is polled on a periodic basis by Windows for updated notification content. You can provide an array of up to five URIs, one for each notification, through the StartPeriodicUpdateBatch method. Each polled URI also can optionally return its own unique expiration time and tag value.

Tagging notifications for periodic updates

With periodic notifications, tags are provided in the X-WNS-Tag header of the notification's HTTP response message, which also includes the notification's content. This message is sent in response to the system's periodic call to the notification's URI. The header name and the tag value are case-insensitive.

For an example of a full implementation of periodic notifications used in conjunction with the notification queue, see the Push and periodic notifications sample.

Related topics

How to use the notification queue with local notifications

Windows.UI.Notifications.TileUpdater.EnableNotificationQueue

Windows.UI.Notifications.TileUpdater.StartPeriodicUpdateBatch