Quickstart: Sending notifications to a secondary tile (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).
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.
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.
- 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.
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.
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);
The TileWide310x150Text04 template contains a single text element, to which we assign a string.
var tileTextAttributes = tileXml.getElementsByTagName("text"); tileTextAttributes.appendChild(tileXml.createTextNode("This text was delivered through a 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.
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.appendChild(squareTileXml.createTextNode("This text was delivered through a notification"));
var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true); tileXml.getElementsByTagName("visual").item(0).appendChild(node);
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);
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();
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