Quickstart: Sending notifications to a secondary tile (HTML)

  • Article

Note  Not using JavaScript? See Quickstart: Sending notifications to a secondary tile (XAML).

 

This Quickstart shows how to update an app's secondary tile by sending a local notification. You will see that sending a notification to a secondary tile is identical to sending a notification to the app's main tile, except for the final step. The only difference between the two procedures is that, for secondary tiles, you use a tile updater specific to secondary tiles (CreateTileUpdaterForSecondaryTile).

To see the code supplied in this topic used in a full sample, see the Secondary tiles sample. The sample is provided in JavaScript, C#, C++, and Visual Basic versions.

When an app launches, it should always enumerate its secondary tiles, in case there were any additions or deletions of which it was unaware. When a user deletes a secondary tile, Windows simply removes the tile. The app itself is responsible for releasing any resources that were used by the secondary tile. When Windows copies secondary tiles through the cloud, current tile or badge notifications on the secondary tile, scheduled notifications, push notification channels, and Uniform Resource Identifiers (URIs) used with periodic notifications are not copied with the secondary tile and must be set up again.

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 Secondary tiles sample.

 

Prerequisites

To understand this topic, you will need:

Instructions

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;

2. Retrieve a blank tile template

Any tile template can be used for a secondary tile. Here we use the simple text-only template TileWide310x150Text04.


var wideTemplate = notifications.TileTemplateType.tileWide310x150Text04;                       
var tileXml = notifications.TileUpdateManager.getTemplateContent(wideTemplate);

3. Assign text to the notification

The TileWide310x150Text04 template contains a single text element, to which we assign a string.


var tileTextAttributes = tileXml.getElementsByTagName("text");
tileTextAttributes[0].appendChild(tileXml.createTextNode("This text was delivered through a notification"));

4. Supply the medium version of the notification

It is a best practice to always provide a binding for each tile size that your app supports in any notification payload sent to a tile. As part of the pinning operation, the user can select the secondary tile size from options that you provide. Providing a binding in each notification for each of those size options ensures that your notification is shown regardless of the tile's size. If you also support a large secondary tile, repeat this step and the next for one of the large templates.

Note  All tiles, including secondary tiles, pin as medium tiles on Windows Phone 8.1, after which the user can resize it.


var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;                       
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);

var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("This text was delivered through a notification"));

5. Append the medium notification to the wide notification payload

var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

6. Package the final XML as a tile notification

var tileNotification = new notifications.TileNotification(tileXml);

7. Create a secondary tile updater

Until this step, the process is the same as for a standard tile notification. In this step, however, we use the createTileUpdaterForSecondaryTile method, specific to secondary tiles. This method requires the unique ID of the target secondary tile. In this example, we assume that a secondary tile with an ID stored in the variable appbarTileId is currently pinned to the Start screen.

var updater = notifications.TileUpdateManager.createTileUpdaterForSecondaryTile(appbarTileId);

8. Send the notification to the secondary tile

updater.update(tileNotification);

You must provide a logo image when you create your secondary tile. The logo image, so named because it normally displays an app's logo, is a full-tile image that is shown on the tile before any notifications are received. The tile reverts to the logo image if the notification is removed or expires. In some scenarios, you might want to change the default logo image, perhaps to indicate a change in the pinned content when you would not want to send a full notification update. This step shows you how to change the logo for the secondary tile with an ID that is stored in the variable appbarTileId, by using an image from the app's local storage. Note that this example references the Windows.Foundation.Uri class.


var tileToUpdate = new Windows.UI.StartScreen.SecondaryTile("SecondaryTile.01");
var uriUpdatedLogo = new Windows.Foundation.Uri("ms-appdata:///local/NewSecondaryTileDefault.png");
tileToUpdate.logo = uriUpdatedLogo;
tileToUpdate.updateAsync();

Summary and next steps

In this Quickstart, you sent a notification to a secondary tile associated with your app. You saw that there is only one small difference in sending a notification to the app's main tile and sending a notification to one of its secondary tiles. You also updated your secondary tile's default logo image.

This Quickstart sent the secondary tile update as a local notification. You can also explore the other methods of notification delivery: scheduled, periodic, and push. For more information, see Delivering notifications.

Quickstart: Pinning a secondary tile

Quickstart: Sending a tile update

Secondary tiles sample

Secondary tiles overview

Guidelines and checklist for secondary tiles

Tile schema