Share via

Quickstart: Sending a tile update (HTML)

  • Article

Note  Not using JavaScript? See Quickstart: Sending a tile update (XAML).

 

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:

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

TileWide310x150ImageAndText01


var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

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

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.

 


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


var tileTextAttributes = tileXml.getElementsByTagName("text");   
tileTextAttributes[0].appendChild(tileXml.createTextNode("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.

 


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


tileImageAttributes[0].setAttribute("src", "ms-appx:///images/redWide.png");
tileImageAttributes[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.


tileImageAttributes[0].setAttribute("src", "ms-appdata:///local/redWide.png");
tileImageAttributes[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.


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

You can use the optional baseUri attribute to specify a root path, such as "https://www.microsoft.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:


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

could be shortened to this:


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

5. Include notification bindings for multiple tile sizes 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.

       
var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);

var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");   
squareTileTextAttributes[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.


var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(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 visual="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src="ms-appx:///images/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


var tileNotification = new notifications.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.


var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

8. Send the notification to the app tile.


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


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.


var notifications = Windows.UI.Notifications;

var template = notifications.TileTemplateType.tileWide310x150ImageAndText01;                      
var tileXml = notifications.TileUpdateManager.getTemplateContent(template);

var tileTextAttributes = tileXml.getElementsByTagName("text");   
tileTextAttributes[0].appendChild(tileXml.createTextNode("Hello World! My very own tile notification"));

var tileImageAttributes = tileXml.getElementsByTagName("image");
tileImageAttributes[0].setAttribute("src", "ms-appx:///assets/redWide.png");
tileImageAttributes[0].setAttribute("alt", "red graphic");

var squareTemplate = notifications.TileTemplateType.tileSquare150x150Text04;
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(squareTemplate);
var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");   
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Hello World! My very own tile notification"));

var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

var tileNotification = new notifications.TileNotification(tileXml);

var currentTime = new Date();
tileNotification.expirationTime = new Date(currentTime.getTime() + 600 * 1000);

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

Quickstart: Setting up periodic notifications

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

The tile template catalog

Tiles XML schema

Windows.UI.Notifications