Tile​Updater Tile​Updater Tile​Updater Class

Definition

Changes the content of the specific tile that the updater is bound to.

public : sealed class TileUpdater : ITileUpdater, ITileUpdater2public sealed class TileUpdater : ITileUpdater, ITileUpdater2Public NotInheritable Class TileUpdater Implements ITileUpdater, ITileUpdater2
Attributes
Windows 10 requirements
Device family
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.


Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().enableNotificationQueue(true);

The following example shows the use of the RemoveFromSchedule method.


var notifier = Notifications.TileUpdateManager.createTileUpdaterForApplication();
var scheduled = notifier.getScheduledTileNotifications();

for (var i = 0, len = scheduled.length; i < len; i++) {

    // The itemId value is the unique ScheduledTileNotification.Id assigned to the 
    // notification when it was created.
    if (scheduled[i].id === itemId) {
        notifier.removeFromSchedule(scheduled[i]);
    }
}

Remarks

To get an instance of this object, call the TileUpdateManager.CreateTileUpdaterForApplication or TileUpdateManager.CreateTileUpdaterForSecondaryTile method.

When it is created, TileUpdater is bound to a specific app or secondary tile, so the methods of this class affect only the single tile that the object instance is bound to.

Properties

Setting Setting Setting

Gets a value that specifies whether a tile can be updated through notifications.

public : NotificationSetting Setting { get; }public NotificationSetting Setting { get; }Public ReadOnly Property Setting As NotificationSetting
Value
NotificationSetting NotificationSetting NotificationSetting

A value that indicates either that the tile can be updated through notifications, or who disabled them: developer, user, or administrator.

Attributes

Remarks

See Also

Methods

AddToSchedule(ScheduledTileNotification) AddToSchedule(ScheduledTileNotification) AddToSchedule(ScheduledTileNotification)

Adds a ScheduledTileNotification to the schedule.

public : void AddToSchedule(ScheduledTileNotification scheduledTile)public void AddToSchedule(ScheduledTileNotification scheduledTile)Public Function AddToSchedule(scheduledTile As ScheduledTileNotification) As void
Parameters
scheduledTile
ScheduledTileNotification ScheduledTileNotification ScheduledTileNotification

The scheduled tile update object.

Attributes

Remarks

If your call to this method returns a failure code, examine these possible causes:

  • Possible cause: You've exceeded the maximum allowed number of scheduled notifications.

Fix: TileUpdater.addToSchedule will fail if you attempt to schedule more than 4096 notifications. Reduce your number of scheduled notifications.

  • Possible cause: Your notification is scheduled for a time in the past relative to the current system clock time.

Fix: Make sure that the scheduled notification time is in the future. Examine the system clock time.

See Also

Clear() Clear() Clear()

Removes all updates and causes the tile to display its default content as declared in the app's manifest.

public : void Clear()public void Clear()Public Function Clear() As void
Attributes

Remarks

Note

This method does not stop periodic updates. If your tile is using periodic updates, you must also call StopPeriodicUpdate to prevent further updates.

See Also

EnableNotificationQueue(Boolean) EnableNotificationQueue(Boolean) EnableNotificationQueue(Boolean)

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
Parameters
enable
bool Boolean Boolean

True to enable queuing; otherwise false.

Attributes

Examples

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



Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().enableNotificationQueue(true);

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:

See Also

EnableNotificationQueueForSquare150x150(Boolean) EnableNotificationQueueForSquare150x150(Boolean) EnableNotificationQueueForSquare150x150(Boolean)

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
Parameters
enable
bool Boolean Boolean

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

Attributes
See Also

EnableNotificationQueueForSquare310x310(Boolean) EnableNotificationQueueForSquare310x310(Boolean) EnableNotificationQueueForSquare310x310(Boolean)

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

public : void EnableNotificationQueueForSquare310x310(bool enable)public void EnableNotificationQueueForSquare310x310(Boolean enable)Public Function EnableNotificationQueueForSquare310x310(enable As Boolean) As void
Parameters
enable
bool Boolean Boolean

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

Attributes

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.

See Also

EnableNotificationQueueForWide310x150(Boolean) EnableNotificationQueueForWide310x150(Boolean) EnableNotificationQueueForWide310x150(Boolean)

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

public : void EnableNotificationQueueForWide310x150(bool enable)public void EnableNotificationQueueForWide310x150(Boolean enable)Public Function EnableNotificationQueueForWide310x150(enable As Boolean) As void
Parameters
enable
bool Boolean Boolean

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

Attributes
See Also

GetScheduledTileNotifications() GetScheduledTileNotifications() GetScheduledTileNotifications()

Retrieves a list of scheduled updates to the tile.

public : IVectorView<ScheduledTileNotification> GetScheduledTileNotifications()public IReadOnlyList<ScheduledTileNotification> GetScheduledTileNotifications()Public Function GetScheduledTileNotifications() As IReadOnlyList( Of ScheduledTileNotification )
Returns
IVectorView<ScheduledTileNotification> IReadOnlyList<ScheduledTileNotification> IReadOnlyList<ScheduledTileNotification>

The collection of scheduled updates for this tile.

Attributes
See Also

RemoveFromSchedule(ScheduledTileNotification) RemoveFromSchedule(ScheduledTileNotification) RemoveFromSchedule(ScheduledTileNotification)

Removes an upcoming tile update from the schedule.

public : void RemoveFromSchedule(ScheduledTileNotification scheduledTile)public void RemoveFromSchedule(ScheduledTileNotification scheduledTile)Public Function RemoveFromSchedule(scheduledTile As ScheduledTileNotification) As void
Parameters
scheduledTile
ScheduledTileNotification ScheduledTileNotification ScheduledTileNotification

The notification to remove from the schedule.

Attributes

Examples

The following example shows the use of the RemoveFromSchedule method.


var notifier = Notifications.TileUpdateManager.createTileUpdaterForApplication();
var scheduled = notifier.getScheduledTileNotifications();

for (var i = 0, len = scheduled.length; i < len; i++) {

    // The itemId value is the unique ScheduledTileNotification.Id assigned to the 
    // notification when it was created.
    if (scheduled[i].id === itemId) {
        notifier.removeFromSchedule(scheduled[i]);
    }
}
See Also

StartPeriodicUpdate(Uri, DateTime, PeriodicUpdateRecurrence) StartPeriodicUpdate(Uri, DateTime, PeriodicUpdateRecurrence) StartPeriodicUpdate(Uri, DateTime, PeriodicUpdateRecurrence)

Begins a series of timed updates for the tile that the updater is bound to. Update content is retrieved from a specified Uniform Resource Identifier (URI). Updates begin at a specified time.

public : void StartPeriodicUpdate(Uri tileContent, DateTime startTime, PeriodicUpdateRecurrence requestedInterval)public void StartPeriodicUpdate(Uri tileContent, DateTimeOffset startTime, PeriodicUpdateRecurrence requestedInterval)Public Function StartPeriodicUpdate(tileContent As Uri, startTime As DateTimeOffset, requestedInterval As PeriodicUpdateRecurrence) As void
Parameters
tileContent
Uri Uri Uri

The Uniform Resource Identifier (URI) from which the XML content of the tile update will be retrieved.

startTime
DateTime DateTimeOffset DateTimeOffset

The time at which the Uniform Resource Identifier (URI) should first be polled for new tile content.

requestedInterval
PeriodicUpdateRecurrence PeriodicUpdateRecurrence PeriodicUpdateRecurrence

The frequency with which the Uniform Resource Identifier (URI) is polled for new tile content, following the initial update at startTime.

Attributes
See Also

StartPeriodicUpdate(Uri, PeriodicUpdateRecurrence) StartPeriodicUpdate(Uri, PeriodicUpdateRecurrence) StartPeriodicUpdate(Uri, PeriodicUpdateRecurrence)

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
Parameters
tileContent
Uri Uri Uri

The Uniform Resource Identifier (URI) from which the XML content of the tile update will be retrieved.

requestedInterval
PeriodicUpdateRecurrence PeriodicUpdateRecurrence PeriodicUpdateRecurrence

The frequency with which the Uniform Resource Identifier (URI) is polled for new tile content, following the initial update at startTime.

Attributes
See Also

StartPeriodicUpdateBatch(IIterable<Uri>, DateTime, PeriodicUpdateRecurrence) StartPeriodicUpdateBatch(IIterable<Uri>, DateTime, PeriodicUpdateRecurrence) StartPeriodicUpdateBatch(IIterable<Uri>, DateTime, PeriodicUpdateRecurrence)

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.

Note

To use this feature, you must first enable the tile's notification queue by calling EnableNotificationQueue.

public : void StartPeriodicUpdateBatch(IIterable<Uri> tileContents, DateTime startTime, PeriodicUpdateRecurrence requestedInterval)public void StartPeriodicUpdateBatch(IEnumerable<Uri> tileContents, DateTimeOffset startTime, PeriodicUpdateRecurrence requestedInterval)Public Function StartPeriodicUpdateBatch(tileContents As IEnumerable<Uri>, startTime As DateTimeOffset, requestedInterval As PeriodicUpdateRecurrence) As void
Parameters
tileContents
IIterable<Uri> IEnumerable<Uri> IEnumerable<Uri>

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.

startTime
DateTime DateTimeOffset DateTimeOffset

The time at which the initial Uniform Resource Identifier (URI) should first be polled for new content.

requestedInterval
PeriodicUpdateRecurrence PeriodicUpdateRecurrence PeriodicUpdateRecurrence

The frequency with which the Uniform Resource Identifier (URI) is polled for new tile content, following the initial update at startTime.

Attributes

Remarks

Using the notification queue with periodic updates

To use the notification queue, you must first enable it for your tile with this line of code:

Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().enableNotificationQueue(true);

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.

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

See Also

StartPeriodicUpdateBatch(IIterable<Uri>, PeriodicUpdateRecurrence) StartPeriodicUpdateBatch(IIterable<Uri>, PeriodicUpdateRecurrence) StartPeriodicUpdateBatch(IIterable<Uri>, PeriodicUpdateRecurrence)

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

To use this feature, you must first enable the tile's notification queue by calling EnableNotificationQueue.

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
Parameters
tileContents
IIterable<Uri> IEnumerable<Uri> IEnumerable<Uri>

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.

requestedInterval
PeriodicUpdateRecurrence PeriodicUpdateRecurrence PeriodicUpdateRecurrence

The frequency with which the Uniform Resource Identifier (URI) is polled for new tile content, following the initial update at startTime.

Attributes

Remarks

Using the notification queue with periodic updates

To use the notification queue, you must first enable it for your tile with this line of code:

Windows.UI.Notifications.TileUpdateManager.createTileUpdaterForApplication().enableNotificationQueue(true);

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.

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

See Also

StopPeriodicUpdate() StopPeriodicUpdate() StopPeriodicUpdate()

Update(TileNotification) Update(TileNotification) Update(TileNotification)

Applies a change in content or appearance to the tile.

public : void Update(TileNotification notification)public void Update(TileNotification notification)Public Function Update(notification As TileNotification) As void
Parameters
notification
TileNotification TileNotification TileNotification

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

Attributes

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);

}
See Also