Quickstart: Sending notifications to a secondary tile (Windows Store apps using JavaScript and HTML)

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 C#, C++, or Visual Basic versions of the JavaScript examples given in this Quickstart, click the "VB/C#/C++ and XAML" link at the upper right of this page.

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 through the Start screen app bar, 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.

Prerequisites

To understand this topic, you will need:

• A working knowledge of tile and notification terms and concepts. For more information, see Tiles, Badges, and Notifications.
• A familiarity with the tile XML schema. For more information, see Tile schema.
• The ability to create a basic Windows Store app with JavaScript using Windows Runtime APIs. For more information, see Getting started with Windows Store apps.
• An existing secondary tile for your app. For more information, see Quickstart: Pinning a secondary tile.
• A familiarity with XML and its manipulation through Document Object Model (DOM) APIs.

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 tileWideText04.

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

3. Assign text to the notification

The tileWideText04 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 square version of the notification

It is a best practice to always provide both a square and wide version of any notification sent to a tile, if the tile can be shown in its wide state. (You control whether the wide state is an option by using an overload of the secondary tile constructor that includes a wide logo.) The user can choose to display either version of the tile in the Start screen, so providing both a square and a wide version ensures that your notification can be shown regardless of the tile's size.

var squareTemplate = notifications.TileTemplateType.tileSquareText04;                       
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 square 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);

9. Optional: Updating the secondary tile's logo

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.

Related topics

Quickstart: Pinning a secondary tile

Quickstart: Sending a tile update

Secondary tiles sample

Secondary tiles overview

Guidelines and checklist for secondary tiles

Tile schema

Build date: 11/29/2012