Quickstart: Sending notifications to a secondary tile (XAML)
Note Not using C#/VB/C++? See 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).
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:
- 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.
Instructions
1. Add namespace declarations
Windows.UI.StartScreen includes the secondary tile APIs. Windows.UI.Notifications includes the notification APIs.
using Windows.UI.Notifications;
using Windows.UI.StartScreen;
using Windows.Data.Xml.Dom;
using namespace Windows::UI::Notifications;
using namespace Windows::UI::StartScreen;
using namespace Windows::Data::Xml::Dom;
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.
XmlDocument tileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileWide310x150Text04);
XmlDocument^ tileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileWide310x150Text04);
3. Assign text to the notification
The TileWide310x150Text04 template contains a single text element, to which we assign a string.
XmlNodeList tileTextAttributes = tileXml.GetElementsByTagName("text");
tileTextAttributes[0].InnerText = "This text was delivered through a notification";
XmlNodeList^ tileTextAttributes = tileXml->GetElementsByTagName("text");
tileTextAttributes->Item(0)->InnerText = "This text was delivered through a notification";
4. Supply the square 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.
XmlDocument squareTileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileSquare150x150Text04);
XmlNodeList squareTileTextAttributes = squareTileXml.GetElementsByTagName("text");
squareTileTextAttributes[0].AppendChild(squareTileXml.CreateTextNode("This text was delivered through a notification"));
XmlDocument^ squareTileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileSquare150x150Text04);
XmlNodeList^ squareTileTextAttributes = squareTileXml->GetElementsByTagName("text");
squareTileTextAttributes->Item(0)->AppendChild(squareTileXml->CreateTextNode("This text was delivered through a notification"));
5. Append the square notification to the wide notification payload
IXmlNode node = tileXml.ImportNode(squareTileXml.GetElementsByTagName("binding").Item(0), true);
tileXml.GetElementsByTagName("visual").Item(0).AppendChild(node);
IXmlNode^ node = tileXml->ImportNode(squareTileXml->GetElementsByTagName("binding")->GetAt(0), true);
tileXml->GetElementsByTagName("visual")->Item(0)->AppendChild(node);
6. Package the final XML as a tile notification
TileNotification tileNotification = new TileNotification(tileXml);
TileNotification^ tileNotification = ref new 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.
TileUpdater secondaryTileUpdater = TileUpdateManager.CreateTileUpdaterForSecondaryTile(appbarTileId);
TileUpdater^ secondaryTileUpdater = TileUpdateManager::CreateTileUpdaterForSecondaryTile(appbarTileId);
8. Send the notification to the secondary tile
secondaryTileUpdater.Update(tile);
secondaryTileUpdater->Update(tile);
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.
SecondaryTile tileToUpdate = new SecondaryTile(appbarTileId);
tileToUpdate.Logo = new Uri("ms-appx:///Assets/NewSecondaryTileDefaultImage.png");
tileToUpdate.UpdateAsync();
auto tileToUpdate = ref new SecondaryTile(appbarTileId);
tileToUpdate->Logo = ref new Windows::Foundation::Uri::Uri("ms-appx:///Assets/NewSecondaryTileDefaultImage.png");
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