Share via

How to use the notification queue (HTML)

  • Article

Note  Not using JavaScript? See How to use the notification queue (XAML).

 

This topic shows how to enable the notification queue on your tile, in this case using local notifications. It also shows how to tag your notification before sending it, to avoid duplicate or out-of-date content in the queue. With the notification queue enabled, Windows will cycle through up to five notifications.

To see C#, C++, or Visual Basic versions of the JavaScript examples given in this Quickstart, see How to use the notification queue (C#, C++ or Visual Basic).

Note  In this Quickstart you'll manipulate the notification content directly through the XML Document Object Model (DOM). An optional approach is available through the NotificationsExtensions library, which presents the XML content as object properties, including Intellisense. For more information, see Quickstart: Using the NotificationsExtensions library in your code. To see the code in this Quickstart expressed using NotificationsExtenstions, see the App tiles and badges sample.

 

What you need to know

Technologies

  • Windows Runtime

Prerequisites

To understand this topic, you will need:

Instructions

Step 1: Optional: Declare a namespace variable

This step provides you with a short name to use in place of the full namespace name. It is the equivalent of a "using" statement in C# or the "Imports" statement in Visual Basic. It allows you to simplify your code.

Note  The rest of the code in this Quickstart assumes that this variable has been declared.

 


var notifications = Windows.UI.Notifications;

Step 2: Set the option to enable notification cycling

This code enables the notification queue for your app. This call only needs to be made once while the app is running, though there is no harm in calling it again. We recommend that you place this call in your app's initialization code. This ensures that the call is made before you update the tile locally, request a push notification channel, or start periodic updates for the tile.


notifications.TileUpdateManager.createTileUpdaterForApplication().enableNotificationQueue(true);

Step 3: Create a tile notification

This is the first step in all tile notifications and is no different here than in any other situation; it is included here only for completeness. For more information, see Quickstart: Sending a tile update.

Note  When getTemplateContent is called on a Windows 8 system, it returns a version 1 template. When this method is called on a Windows 8.1 system, it returns a version 2 template or a version 3 template in case of phone-only templates. However, if an app specifies Windows 8 compatibility in its manifest, this method returns a version 1 template regardless of the Windows version. In this topic, we'll use a version 2 template.

 


var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

// TO DO: Fill in the template with your tile content. Define a tile and add it to tileXML.

var tileNotification = new notifications.TileNotification(tileXml);

Step 4: Optional: Give your notification a tag

A tag is a string of no more than 16 alphanumeric characters, plus a terminating null character, that uniquely identifies its notification within your app.

When queuing is enabled, a maximum of five tile notifications can automatically cycle on the tile. By default, the replacement policy for notifications in the queue is first in, first out (FIFO); when the queue is full and a new notification arrives, the oldest notification is removed. Note that the notification display order does not follow a strict linear pattern. Users can see the notifications in a different order than they arrived in.

To override the FIFO queue behavior, a notification can be given a tag. If a new notification arrives with the same tag as an existing notification, the new notification replaces the old, regardless of the older notification's place in the queue. For instance, if your tile shows stock prices, you want to show the most up-to-date info. The use of tags to replace notifications in the queue is optional.

For more information on using tags with the notification queue, see Using the notification queue. The example below shows how to set the tag for local notifications. For information on setting tags for periodic updates, see Tileupdater.startPeriodicUpdateBatch. For information on setting tags for push notifications, see Push notification service request and response headers.

tileNotification.tag = "stockMSFT";

Step 5: Send the notification to the tile


notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);

Quickstart: Sending a tile update

App tiles and badges sample

Tile and toast image sizes

Tile and tile notification overview

Guidelines and checklist for tiles