Quickstart: Sending notifications to a secondary tile (Windows Runtime apps using C#/VB/C++ and 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).
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.
- The ability to create a basic Windows Store app with C# or C++ Microsoft Visual Basic using Windows Runtime APIs. For more information, see Create your first Windows Store app using C# or Visual Basic.
- Understanding of how to create a code-behind for a Windows Store app with Extensible Application Markup Language (XAML).
- A familiarity with XML and its manipulation through Document Object Model (DOM) APIs.
- This topic assumes that you have already created a secondary tile and pinned it to the Start screen. To walk through that procedure, see Quickstart: Pinning a secondary tile.
using namespace Windows::UI::Notifications; using namespace Windows::UI::StartScreen; using namespace Windows::Data::Xml::Dom;
Any tile template can be used for a secondary tile. Here we use the simple text-only template TileWide310x150Text04.
XmlDocument^ tileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileWide310x150Text04);
The TileWide310x150Text04 template contains a single text element, to which we assign a string.
XmlNodeList^ tileTextAttributes = tileXml->GetElementsByTagName("text"); tileTextAttributes->Item(0)->InnerText = "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.
XmlDocument^ squareTileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileSquare150x150Text04); XmlNodeList^ squareTileTextAttributes = squareTileXml->GetElementsByTagName("text"); squareTileTextAttributes->Item(0)->AppendChild(squareTileXml->CreateTextNode("This text was delivered through a notification"));
IXmlNode^ node = tileXml->ImportNode(squareTileXml->GetElementsByTagName("binding")->GetAt(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.
TileUpdater^ secondaryTileUpdater = 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.
auto tileToUpdate = ref new SecondaryTile(appbarTileId); tileToUpdate->Logo = ref new Windows::Foundation::Uri::Uri("ms-appx:///Assets/NewSecondaryTileDefaultImage.png"); 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