Quickstart: Sending a tile update (XAML)

Articolo
08/31/2015

Note Not using C#/VB/C++? See Quickstart: Sending a tile update (HTML).

A tile begins as a default tile, which is defined in your manifest and displayed when your app is first installed. After your app is installed, you can change your tile's content through notifications. This Quickstart walks you through the steps to define new tile content, send it to your tile, and remove that content once it's no longer needed. These actions are demonstrated through a local notification, which is the simplest notification to implement. We discuss the following steps:

Specifying a template for your notification
Retrieving the template's blank XML content
Adding text to the notification
Adding an image to the notification
Packaging different notification versions for different tile sizes in a single payload
Setting an expiration time for your notification
Sending your update to your tile as a local notification

See this feature in action as part of our App features, start to finish series: Windows Store app UI, start to finish

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 NotificationsExtensions, see the App tiles and badges 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#, C++, or 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).
An existing default tile for your app, defined in your app's manifest. For more information, see Quickstart: Creating a default tile using the Microsoft Visual Studio manifest editor.
A familiarity with XML and its manipulation through Document Object Model (DOM) APIs.

Instructions

1. Add namespace declarations

Windows.UI.Notifications includes the tile APIs.

using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;

using namespace Windows::UI::Notifications;
using namespace Windows::Data::Xml::Dom;

2. Pick a template for your tile and retrieve its XML contents

Choose a template from the system-provided template catalog that fits the layout needs of your content. For the complete list of templates, see the TileTemplateType enumeration. Note that each separate notification that you send can use a different template.

This example uses the TileWide310x150ImageAndText01 template, which requires one image and one string of text. An example is shown here:

Note When getTemplateContent is called on a Windows 8 system, it returns a version 1 template. When this method is called on a Windows 8.1 system, it returns a version 2 template or a version 3 template for Windows Phone-only templates. If an app specifies Windows 8 compatibility in its manifest, this method returns a version 1 template regardless of the Windows version. In this topic, we'll use a version 2 template.

XmlDocument tileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileWide310x150ImageAndText01);

XmlDocument^ tileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileWide310x150ImageAndText01);

The GetTemplateContent method retrieves an XmlDocument. The code above retrieves the following XML skeleton, for which you will provide the details in subsequent steps through standard DOM functions:

<tile>
    <visual version="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</tile>

3. Supply text content for your notification

This code first retrieves all elements in the template with a tag name of "text". The TileWide310x150ImageAndText01 template contains only a single text string, which the code then assigns. This string can wrap over a maximum of two lines, so the length of the string should be set accordingly to avoid truncation.

   
XmlNodeList tileTextAttributes = tileXml.GetElementsByTagName("text");
tileTextAttributes[0].InnerText = "Hello World! My very own tile notification";

XmlNodeList^ tileTextAttributes = tileXml->GetElementsByTagName("text");
tileTextAttributes->Item(0)->InnerText = "Hello World! My very own tile notification";

4. Supply an image for your notification

This code first retrieves all elements in the template with a tag name of "image". The TileWide310x150ImageAndText01 template contains a single image. Note that not all tile templates contain images; some are text only.

Important The image "redWide.png" used here is only an example and is not included in a Microsoft Visual Studio project. You will need to replace "redWide.png" with the name of an actual image of your own that you've added to the project before you attempt to send this notification. If you don't, the notification will not be delivered.

XmlNodeList tileImageAttributes = tileXml.GetElementsByTagName("image");

XmlNodeList^ tileImageAttributes = tileXml->GetElementsByTagName("image");

Images can be used from the app's package, the app's local storage, or from the web. Versions of this step are shown for each image source. In a tile notification that contains multiple images, the image elements can use any combination of those image source types. Images used in templates are required to be less than 200 KB in size and smaller than 1024 x 1024 pixels. For more information, see Tile and toast image sizes.

The following code uses a local image from the app's package. This type of image is included in your Visual Studio solution file and is packaged as part of your app. These images are accessed by using the "ms-appx:///" prefix. As a best practice, we also assign optional alt text for accessibility purposes such as screen readers.

((XmlElement)tileImageAttributes[0]).SetAttribute("src", "ms-appx:///assets/redWide.png");
((XmlElement)tileImageAttributes[0]).SetAttribute("alt", "red graphic");

static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("src", "ms-appx:///assets/redWide.png");                        
static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("alt", "red graphic");

The following code uses a local image from the app's local storage. This type of image has been saved by your app to its local storage. This is the location returned by Windows.Storage.ApplicationData.Current.LocalFolder. These images are accessed by using the "ms-appdata:///local/" prefix. Again, we also assign optional alt text for accessibility purposes such as screen readers.

((XmlElement)tileImageAttributes[0]).SetAttribute("src", "ms-appdata:///local/redWide.png");
((XmlElement)tileImageAttributes[0]).SetAttribute("alt", "red graphic");

static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("src", "ms-appdata:///local/redWide.png");                        
static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("alt", "red graphic");

The following code uses a web image. These images are accessed by using the "http://" or "https://" protocol to specify the image's path. Note that your app must have the internetClient capability declared in its manifest in order to use web images.

((XmlElement)tileImageAttributes[0]).SetAttribute("src", "https://www.contoso.com/redWide.png");
((XmlElement)tileImageAttributes[0]).SetAttribute("alt", "red graphic");

static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("src", "https://www.contoso.com/redWide.png");                        
static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("alt", "red graphic");

You can use the optional baseUri attribute to specify a root path, such as "https://www.contoso.com/", that is combined with any relative Uniform Resource Identifiers (URIs) specified in any image's src attributes. This attribute can be set on either the visual element (to apply to the entire notification) or the binding element (to apply to that binding). If baseUri is set on both, the value in binding overrides the value in visual.

If the baseUri was set to "https://www.contoso.com/", this line in the example code:

((XmlElement)tileImageAttributes[0]).SetAttribute("src", "https://www.contoso.com/redWide.png");

could be shortened to this:

((XmlElement)tileImageAttributes[0]).SetAttribute("src", "redWide.png");

5. Include both a square and wide notification in the payload

The user can resize your tile on the Start screen at any time, and there is no way for you to know which state (small, medium, wide, or large) the tile is in when you send a notification. If your tile is sized such that there isn't a matching template binding in your notification, the notification won't be shown. Therefore, it is a best practice to always include versions of the notification in your payload for all live tile sizes (medium, wide, large) for which you supplied a logo image in your manifest.

Note As of Windows Phone 8.1, large tiles are not supported on the phone.

This example defines a text-only medium notification using the same text string that we used in the wide notification.

XmlDocument squareTileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileSquare150x150Text04);

XmlNodeList squareTileTextAttributes = squareTileXml.GetElementsByTagName("text");
squareTileTextAttributes[0].AppendChild(squareTileXml.CreateTextNode("Hello World! My very own tile notification"));

XmlDocument^ squareTileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileSquare150x150Text04);

XmlNodeList^ squareTileTextAttributes = squareTileXml->GetElementsByTagName("text");
squareTileTextAttributes->Item(0)->AppendChild(squareTileXml->CreateTextNode("Hello World! My very own tile notification"));

Next, add the medium tile to the wide tile's payload. Retrieve the binding element that defines the medium tile in the squareTileXml payload. Append that binding element as a sibling of the wide tile.

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);

The preceding steps result in two binding elements under a single visual element in the XML payload, as shown here:

<tile>
    <visual version="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageandText01">
            <image id="1" src="ms-appx:///assets/redWide.png"/>
            <text id="1">Hello World! My very own tile notification</text>
        </binding>

        <binding template="TileSquare150x150Text04" fallback="TileSquareText04">
            <text id="1">Hello World! My very own tile notification</text>
        </binding>
    </visual>
</tile>

6. Create the notification based on the XML content you've specified

TileNotification tileNotification = new TileNotification(tileXml);

TileNotification^ tileNotification = ref new TileNotification(tileXml);

7. Set an expiration time for the notification

By default, local tile and badge notifications do not expire and push, periodic, and scheduled notifications expire after three days. It is a best practice to set an expiration time, particularly on local tile and badge notifications, using a time that makes sense for your app. Your tile's content should not persist longer than it is relevant. In this case, the notification will expire and be removed from the tile in ten minutes.

tileNotification.ExpirationTime = DateTimeOffset.UtcNow.AddMinutes(10);

int minutes = 10;
auto cal = ref new Windows::Globalization::Calendar();
cal->AddMinutes(minutes);    
tileNotification->ExpirationTime = cal->GetDateTime();

8. Send the notification to the app tile.

TileUpdateManager.CreateTileUpdaterForApplication().Update(tileNotification);

TileUpdateManager::CreateTileUpdaterForApplication()->Update(tileNotification);

9. Optional: Clear your tile notification

This example shows how to clear a tile notification through a local call. Note that if your content is time-bound, we recommend that you set an expiration time on the notification rather than explicitly clearing it. The following line of code clears the current notification from the app's tile.

Windows.UI.Notifications.TileUpdateManager.CreateTileUpdaterForApplication().Clear();

Windows::UI::Notifications::TileUpdateManager::CreateTileUpdaterForApplication()->Clear();

For a tile with the notification queue enabled and notifications in the queue, calling the Clear method empties the queue.

Note that you cannot clear a notification from the cloud. A local call to the Clear method will clear the tile regardless of the source of its notifications, but periodic or push notifications can only update the tile to new content.

Summary and next steps

In this Quickstart, you defined and sent new content to your app's tile through a notification, which was then removed after 10 minutes. The following code summarizes the steps above, from choosing a template through sending the notification. It uses an image from the app's package.

To test this code in a sample of your own, place it in a function that is triggered by a button in the sample's UI. For instance, you could place the button in the default.html file. Remember to substitute the name of an actual image.

using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;

XmlDocument tileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileWide310x150ImageAndText01);

XmlNodeList tileTextAttributes = tileXml.GetElementsByTagName("text");
tileTextAttributes[0].InnerText = "Hello World! My very own tile notification";

XmlNodeList tileImageAttributes = tileXml.GetElementsByTagName("image");
((XmlElement)tileImageAttributes[0]).SetAttribute("src", "ms-appx:///assets/redWide.png");
((XmlElement)tileImageAttributes[0]).SetAttribute("alt", "red graphic");

XmlDocument squareTileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileSquare150x150Text04);
XmlNodeList squareTileTextAttributes = squareTileXml.GetElementsByTagName("text");
squareTileTextAttributes[0].AppendChild(squareTileXml.CreateTextNode("Hello World! My very own tile notification"));
IXmlNode node = tileXml.ImportNode(squareTileXml.GetElementsByTagName("binding").Item(0), true);
tileXml.GetElementsByTagName("visual").Item(0).AppendChild(node);

TileNotification tileNotification = new TileNotification(tileXml);

tileNotification.ExpirationTime = DateTimeOffset.UtcNow.AddSeconds(10);

TileUpdateManager.CreateTileUpdaterForApplication().Update(tileNotification);

using namespace Windows::UI::Notifications;
using namespace Windows::Data::Xml::Dom;
namespace WFC = Windows::Foundation::Collections;

XmlDocument^ tileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileWide310x150ImageAndText01);

XmlNodeList^ tileTextAttributes = tileXml->GetElementsByTagName("text");
tileTextAttributes->Item(0)->InnerText = "Hello World! My very own tile notification";

XmlNodeList^ tileImageAttributes = tileXml->GetElementsByTagName("image");
static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("src", "ms-appx:///assets/redWide.png");                        
static_cast<XmlElement^>(tileImageAttributes->Item(0))->SetAttribute("alt", "red graphic");

XmlDocument^ squareTileXml = TileUpdateManager::GetTemplateContent(TileTemplateType::TileSquare150x150Text04);
XmlNodeList^ squareTileTextAttributes = squareTileXml->GetElementsByTagName("text");
squareTileTextAttributes->Item(0)->AppendChild(squareTileXml->CreateTextNode("Hello World! My very own tile notification"));
IXmlNode^ node = tileXml->ImportNode(squareTileXml->GetElementsByTagName("binding")->GetAt(0), true);
tileXml->GetElementsByTagName("visual")->Item(0)->AppendChild(node);

TileNotification^ tileNotification = ref new TileNotification(tileXml);

int seconds = 10;
auto cal = ref new Windows::Globalization::Calendar();
cal->AddSeconds(seconds);    
tileNotification->ExpirationTime = cal->GetDateTime();

TileUpdateManager::CreateTileUpdaterForApplication()->Update(tileNotification);

Now that you've performed your first tile update, you can expand your tile's functionality by enabling a notification queue.

This Quickstart sent the 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.

App tiles and badges sample

Tile and toast image sizes

Tile and tile notification overview

Guidelines and checklist for tiles

How to schedule a tile notification

How to set up periodic notifications for tiles

Quickstart: Creating a default tile using the Visual Studio manifest editor

The tile template catalog

Tiles XML schema

Windows.UI.Notifications