Using the notification queue (Windows Store apps) (Windows)

1 out of 3 rated this helpful - Rate this topic

In this article

Replacing queued notifications
Enabling the notification queue
Using the notification queue with local and scheduled notifications
Using the notification queue with push notifications
Using the notification queue with periodic updates
Related topics

This topic discusses the notification queue—the ability of 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 applications.

Replacing queued notifications

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

Tags are app-specified strings that can be set on both local and push notifications. 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 request your first push notification channel, start periodic updates, or send any local notifications to that tile. Your app should 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 URL is provided for each notification. The URL is polled on a periodic basis by Windows for updated notification content. You can provide an array of up to five URLs, one for each notification. The content payload returned from the URL should contain both wide and square versions of the XML for the notification. Each polled URL also can optionally return its own unique expiration time and tag value. The URLs are provided through the StartPeriodicUpdateBatch method.

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 Uniform Resource Identifier (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 Scenario 4 in the Push and periodic notifications sample.

Using the notification queue (Windows Store apps)