Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Examples

The following example shows Update used to send a notification to the app's tile.

function sendTileTextNotification() {
var Notifications = Windows.UI.Notifications;
// Get an XML DOM version of a specific template by using getTemplateContent.
var tileXml = Notifications.TileUpdateManager.getTemplateContent(Notifications.TileTemplateType.tileWide310x150Text03);
// You will need to look at the template documentation to know how many text fields a particular template has.
// Get the text attribute for this template and fill it in.
var tileAttributes = tileXml.getElementsByTagName("text");
tileAttributes[0].appendChild(tileXml.createTextNode("Hello World!"));
// Create the notification from the XML.
var tileNotification = new Notifications.TileNotification(tileXml);
// Send the notification to the calling app's tile.
Notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);
}

The following line of code uses EnableNotificationQueue to enable the notification queue for the calling app's tile.

public : void AddToSchedule(ScheduledTileNotification scheduledTile)public void AddToSchedule(ScheduledTileNotification scheduledTile)Public Function AddToSchedule(scheduledTile As ScheduledTileNotification) As void// You can use this method in JavaScript.

Enables the tile to queue up to five notifications. This enables the notification queue on all tile sizes.

public : void EnableNotificationQueue(bool enable)public void EnableNotificationQueue(Boolean enable)Public Function EnableNotificationQueue(enable As Boolean) As void// You can use this method in JavaScript.

Parameters

enable

boolBooleanBooleanBoolean

True to enable queuing; otherwise false.

Examples

The following line of code enables the notification queue for the calling app's tile.

Remarks

When queuing is enabled, a maximum of five tile notifications can automatically cycle on the tile. Be careful about enabling cycling unless your app explicitly wants to use it, otherwise you can potentially have outdated notifications cycling through. Generally, the queue is FIFO (first in, first out), so that when it is full and a new notification arrives, the oldest notification is removed. However, notifications can be given a Tag, which allows a new notification with that same Tag to replace its older notification in the queue, regardless of its position.

When your tile is based on a peek template, notification cycling is timed so that the full content is always shown before the tile cycles to the next notification.

As of Windows 8.1, you can also enable the notification queue for only specific tile sizes. See the following topics:

EnableNotificationQueueForWide310x150
We recommend that you disable the notification queu when using a large tile with one of the following templates, which already show three notifications simultaneously. This avoids a tile that's distractingly busy to the user. In that case, you may want to use the size-specific enable methods instead of EnableNotificationQueue.

Enables the tile to queue up to five notifications on the medium tile.

public : void EnableNotificationQueueForSquare150x150(bool enable)public void EnableNotificationQueueForSquare150x150(Boolean enable)Public Function EnableNotificationQueueForSquare150x150(enable As Boolean) As void// You can use this method in JavaScript.

public : void EnableNotificationQueueForSquare310x310(bool enable)public void EnableNotificationQueueForSquare310x310(Boolean enable)Public Function EnableNotificationQueueForSquare310x310(enable As Boolean) As void// You can use this method in JavaScript.

Parameters

enable

boolBooleanBooleanBoolean

True to enable queuing on this tile size; otherwise false.

Remarks

We recommend that you disable the notification queu when using a large tile with one of the following templates, which already show three notifications simultaneously. This avoids a tile that's distractingly busy to the user.

public : void EnableNotificationQueueForWide310x150(bool enable)public void EnableNotificationQueueForWide310x150(Boolean enable)Public Function EnableNotificationQueueForWide310x150(enable As Boolean) As void// You can use this method in JavaScript.

public : IVectorView<ScheduledTileNotification> GetScheduledTileNotifications()public IReadOnlyList<ScheduledTileNotification> GetScheduledTileNotifications()Public Function GetScheduledTileNotifications() As IReadOnlyList( Of ScheduledTileNotification )// You can use this method in JavaScript.

public : void RemoveFromSchedule(ScheduledTileNotification scheduledTile)public void RemoveFromSchedule(ScheduledTileNotification scheduledTile)Public Function RemoveFromSchedule(scheduledTile As ScheduledTileNotification) As void// You can use this method in JavaScript.

Begins a series of timed content changes for the tile that the updater is bound to, beginning immediately.

public : void StartPeriodicUpdate(Uri tileContent, PeriodicUpdateRecurrence requestedInterval)public void StartPeriodicUpdate(Uri tileContent, PeriodicUpdateRecurrence requestedInterval)Public Function StartPeriodicUpdate(tileContent As Uri, requestedInterval As PeriodicUpdateRecurrence) As void// You can use this method in JavaScript.

Begins a series of timed updates that cycle on the tile that the updater is bound to. Update content is retrieved from an array of specified Uniform Resource Identifier (URI) with updates beginning at a specified time and subsequent updates occurring at the periodic interval thereafter.

An array of up to five Uniform Resource Identifier (URI) from which the XML content of the cycling tile updates will be retrieved. If the array contains more than five Uniform Resource Identifier (URI), the method will fail.

Using the notification queue with periodic updates

This API only needs to be called once in your app's lifetime, but there is no harm in calling it each time the app launches.

In the case of periodic notifications, a unique URL is provided for each notification. Each URL is polled on a periodic basis by Windows for updated notification content. The content payload returned from each URL should contain versions of the notification XML for all supported tile sizes. Each polled URL also can optionally return its own unique expiration time and tag value.

Tagging notifications for periodic updates

With the notification queue enabled, your tile can cycle through a maximum of five queued notifications. Generally, the oldest notification is replaced in the queue when a new notification arrives. However, notifications can be given a tag so that a new notification with a specific tag will replace an older notification with the same tag, regardless of its place in the queue.

Tags are optional strings of up to 16 characters that can be set on a notification as an identifier. If a new notification arrives with the same tag as a notification already in the queue, the new notification replaces the old one rather than falling under the default first-in, first-out queue behavior. This prevents the case where two versions of the same notification— one of them out-of-date— are present in the queue at the same time.

In the case of 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.

An example is shown here:

X-WNS-Tag: stockMSFT

Setting an expiration time for periodic updates

Tiles expire by default after three days. If your notification content has a significantly different useful lifespan— shorter or longer— you should explicitly set an expiration time for each notification. This prevents stale or irrelevant content from remaining in the queue. This is especially important if the user's machine loses Internet connectivity for a long period of time.

For example, during active trading, it would be advisable for a stock app to set the expiration on a stock price notification to twice that of your polling interval, such as a notification that expires one hour after it is sent if you poll for an update every half-hour. In the case of a news app, an expiration of one day for a tile that shows the top daily news would be appropriate.

For periodic notifications, the expiration time is set in the X-WNS-Expires header of the notification's HTTP response message. The expiration time is expressed as an HTTP-date, which uses one of the formats shown in these examples:

Sun, 06 Nov 1994 08:49:37 GMT

Sunday, 06-Nov-94 08:49:37 GMT

Sun Nov 6 08:49:37 1994

For more information on the HTTP-date format, see the World Wide Web Consortium (W3C) 3 Protocol Parameters document.

Begins a series of timed updates that cycle on the tile that the updater is bound to. Update content is retrieved from an array of specified Uniform Resource Identifier (URI), the first update happening immediately and subsequent updates occurring at the periodic interval thereafter.

Note

public : void StartPeriodicUpdateBatch(IIterable<Uri> tileContents, PeriodicUpdateRecurrence requestedInterval)public void StartPeriodicUpdateBatch(IEnumerable<Uri> tileContents, PeriodicUpdateRecurrence requestedInterval)Public Function StartPeriodicUpdateBatch(tileContents As IEnumerable<Uri>, requestedInterval As PeriodicUpdateRecurrence) As void// You can use this method in JavaScript.

An array of up to five Uniform Resource Identifier (URI) from which the XML content of the cycling tile updates will be retrieved. If the array contains more than five Uniform Resource Identifier (URI), the method will fail.

Using the notification queue with periodic updates

This API only needs to be called once in your app's lifetime, but there is no harm in calling it each time the app launches.

In the case of periodic notifications, a unique URL is provided for each notification. Each URL is polled on a periodic basis by Windows for updated notification content. The content payload returned from each URL should contain versions of the notification XML for all supported tile sizes. Each polled URL also can optionally return its own unique expiration time and tag value.

Tagging notifications for periodic updates

With the notification queue enabled, your tile can cycle through a maximum of five queued notifications. Generally, the oldest notification is replaced in the queue when a new notification arrives. However, notifications can be given a tag so that a new notification with a specific tag will replace an older notification with the same tag, regardless of its place in the queue.

Tags are optional strings of up to 16 characters that can be set on a notification as an identifier. If a new notification arrives with the same tag as a notification already in the queue, the new notification replaces the old one rather than falling under the default first-in, first-out queue behavior. This prevents the case where two versions of the same notification— one of them out-of-date— are present in the queue at the same time.

In the case of 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.

An example is shown here:

X-WNS-Tag: stockMSFT

Setting an expiration time for periodic updates

Periodic notifications expire by default after three days. If your notification content has a significantly different useful lifespan— shorter or longer— you should explicitly set an expiration time for each notification. This prevents stale or irrelevant content from remaining in the queue. This is especially important if the user's machine loses Internet connectivity for a long period of time.

For example, during active trading, it would be advisable for a stock app to set the expiration on a stock price notification to twice that of your polling interval, such as a notification that expires one hour after it is sent if you poll for an update every half-hour. In the case of a news app, an expiration of one day for a tile that shows the top daily news would be appropriate.

For periodic notifications, the expiration time is set in the X-WNS-Expires header of the notification's HTTP response message. The expiration time is expressed as an HTTP-date, which uses one of the formats shown in these examples:

Sun, 06 Nov 1994 08:49:37 GMT

Sunday, 06-Nov-94 08:49:37 GMT

Sun Nov 6 08:49:37 1994

For more information on the HTTP-date format, see the World Wide Web Consortium (W3C) 3 Protocol Parameters document.

public : void Update(TileNotification notification)public void Update(TileNotification notification)Public Function Update(notification As TileNotification) As void// You can use this method in JavaScript.

The object that supplies the new XML definition for the tile's content.

Examples

The following example shows Update used to send a notification to the app's tile.

function sendTileTextNotification() {
var Notifications = Windows.UI.Notifications;
// Get an XML DOM version of a specific template by using getTemplateContent.
var tileXml = Notifications.TileUpdateManager.getTemplateContent(Notifications.TileTemplateType.tileWide310x150Text03);
// You will need to look at the template documentation to know how many text fields a particular template has.
// Get the text attribute for this template and fill it in.
var tileAttributes = tileXml.getElementsByTagName("text");
tileAttributes[0].appendChild(tileXml.createTextNode("Hello World!"));
// Create the notification from the XML.
var tileNotification = new Notifications.TileNotification(tileXml);
// Send the notification to the calling app's tile.
Notifications.TileUpdateManager.createTileUpdaterForApplication().update(tileNotification);
}