TileUpdater
TileUpdater
TileUpdater
TileUpdater
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// You can use this class in JavaScript.
- Attributes
| 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 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// You can use this property in JavaScript.
A value that indicates either that the tile can be updated through notifications, or who disabled them: developer, user, or administrator.
Remarks
- See Also
Methods
AddToSchedule(ScheduledTileNotification) 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// You can use this method in JavaScript.
- scheduledTile
- ScheduledTileNotification ScheduledTileNotification ScheduledTileNotification ScheduledTileNotification
The scheduled tile update object.
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() 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// You can use this method in JavaScript.
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) 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// You can use this method in JavaScript.
- enable
- bool Boolean Boolean Boolean
True to enable queuing; otherwise false.
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:
- EnableNotificationQueueForSquare150x150
- EnableNotificationQueueForSquare310x310
- 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.
- TileSquare310x310SmallImagesAndTextList01
- TileSquare310x310SmallImagesAndTextList02
- TileSquare310x310SmallImagesAndTextList03
- TileSquare310x310SmallImagesAndTextList04
- TileSquare310x310TextList01
- TileSquare310x310TextList02
- TileSquare310x310TextList03
- See Also
-
EnableNotificationQueueForSquare150x150(Boolean) 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// You can use this method in JavaScript.
- enable
- bool Boolean Boolean Boolean
True to enable queuing on this tile size; otherwise false.
EnableNotificationQueueForSquare310x310(Boolean) 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// You can use this method in JavaScript.
- enable
- bool Boolean Boolean Boolean
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.
- TileSquare310x310SmallImagesAndTextList01
- TileSquare310x310SmallImagesAndTextList02
- TileSquare310x310SmallImagesAndTextList03
- TileSquare310x310SmallImagesAndTextList04
- TileSquare310x310TextList01
- TileSquare310x310TextList02
- TileSquare310x310TextList03
EnableNotificationQueueForWide310x150(Boolean) 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// You can use this method in JavaScript.
- enable
- bool Boolean Boolean Boolean
True to enable queuing on this tile size; otherwise false.
GetScheduledTileNotifications() 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 )// You can use this method in JavaScript.
The collection of scheduled updates for this tile.
- See Also
-
RemoveFromSchedule(ScheduledTileNotification) 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// You can use this method in JavaScript.
- scheduledTile
- ScheduledTileNotification ScheduledTileNotification ScheduledTileNotification ScheduledTileNotification
The notification to remove from the schedule.
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) 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// You can use this method in JavaScript.
- tileContent
- Uri Uri Uri Uri
The Uniform Resource Identifier (URI) from which the XML content of the tile update will be retrieved.
- startTime
- DateTime DateTimeOffset DateTimeOffset DateTimeOffset
The time at which the Uniform Resource Identifier (URI) should first be polled for new tile content.
- requestedInterval
- PeriodicUpdateRecurrence PeriodicUpdateRecurrence PeriodicUpdateRecurrence PeriodicUpdateRecurrence
The frequency with which the Uniform Resource Identifier (URI) is polled for new tile content, following the initial update at startTime.
StartPeriodicUpdate(Uri, PeriodicUpdateRecurrence) 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// You can use this method in JavaScript.
- tileContent
- Uri Uri Uri Uri
The Uniform Resource Identifier (URI) from which the XML content of the tile update will be retrieved.
- requestedInterval
- PeriodicUpdateRecurrence PeriodicUpdateRecurrence PeriodicUpdateRecurrence PeriodicUpdateRecurrence
The frequency with which the Uniform Resource Identifier (URI) is polled for new tile content, following the initial update at startTime.
StartPeriodicUpdateBatch(IIterable, DateTime, PeriodicUpdateRecurrence)
StartPeriodicUpdateBatch(IIterable, DateTime, PeriodicUpdateRecurrence)
StartPeriodicUpdateBatch(IIterable, DateTime, PeriodicUpdateRecurrence)
StartPeriodicUpdateBatch(IIterable, 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// You can use this method in JavaScript.
- tileContents
- IIterable<Uri> IEnumerable<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 DateTimeOffset
The time at which the initial Uniform Resource Identifier (URI) should first be polled for new content.
- requestedInterval
- PeriodicUpdateRecurrence PeriodicUpdateRecurrence PeriodicUpdateRecurrence PeriodicUpdateRecurrence
The frequency with which the Uniform Resource Identifier (URI) is polled for new tile content, following the initial update at startTime.
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.
StartPeriodicUpdateBatch(IIterable, PeriodicUpdateRecurrence)
StartPeriodicUpdateBatch(IIterable, PeriodicUpdateRecurrence)
StartPeriodicUpdateBatch(IIterable, PeriodicUpdateRecurrence)
StartPeriodicUpdateBatch(IIterable, 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// You can use this method in JavaScript.
- tileContents
- IIterable<Uri> IEnumerable<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 PeriodicUpdateRecurrence
The frequency with which the Uniform Resource Identifier (URI) is polled for new tile content, following the initial update at startTime.
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
-
StartPeriodicUpdateBatch(IIterable<Uri>, DateTime, PeriodicUpdateRecurrence)StartPeriodicUpdateBatch(IIterable<Uri>, DateTime, PeriodicUpdateRecurrence)StartPeriodicUpdateBatch(IIterable<Uri>, DateTime, PeriodicUpdateRecurrence)StartPeriodicUpdateBatch(IIterable<Uri>, DateTime, PeriodicUpdateRecurrence)
StopPeriodicUpdate() StopPeriodicUpdate() StopPeriodicUpdate() StopPeriodicUpdate()
Cancels the current series of timed updates for the tile that the updater is bound to.
public : void StopPeriodicUpdate()public void StopPeriodicUpdate()Public Function StopPeriodicUpdate() As void// You can use this method in JavaScript.
- See Also
-
Update(TileNotification) 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// You can use this method in JavaScript.
- notification
- TileNotification TileNotification TileNotification TileNotification
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);
}
- See Also
-