Windows* Store App Notifications with Live Tiles and Badges

By Miao Wei and Nathan Totura

Downloads

Windows* Store App Notifications with Live Tiles and Badges [PDF 345KB]

Abstract

This article discusses how to add live tiles and badges to your Windows Store apps. Live tiles are used to present rich content from your apps even when they are not the active application. Badges similarly give your app yet another way to convey data to the user by allowing status overlaid on the live tile.

1 Tiles and Notifications

An app tile is a square or rectangle icon representing the app on the Windows 8 Start screen. Besides simply being the icon that allows the user to tap and launch the app, the tile can be used to display a set of content screens associated with the app. For example, the tile of a finance app could show a snapshot of the current major stock market indexes, a photo app could loop through and use thumbnail photos from your picture library. These tiles that show dynamic content are called “live tiles.”

As a UI feature, live tiles serve two main purposes:

They let the apps stand out on the Windows Start screen and serve as “store fronts” for the apps
They provide useful, easily accessible data that the user can quickly consume at a glance instead of needing to launch the app. An example might be a weather app tile that displays the current weather.

The content displayed on tiles can contain text, images, or a combination of the two. Tile content can also include animation to initiate scrolling between multiple pieces of content. The updates a tile receives can be either local or cloud-based.
For a more detailed discussion, see the article “Tile and tile notification overview (Window Store apps)” - http://msdn.microsoft.com/en-us/library/windows/apps/hh779724.aspx

1.1 Tile Template Catalog

The content of a tile is defined in XML. Tiles are updated based on a set of Windows-provided, predefined XML templates. For a full list of tile templates along with examples for each template, you can reference the MSDN article “The tile template catalog (Windows Store apps)” (http://msdn.microsoft.com/en-us/library/windows/apps/hh761491.aspx).

In this example of TileSquarePeekImageAndText03, the developer has the opportunity to add four lines of custom text and one image:

<tile>
<visual>
<binding template="TileSquarePeekImageAndText03">
<image id="1" src="image1" alt="alt text"/>
<text id="1">Text Field 1</text>
<text id="2">Text Field 2</text>
<text id="3">Text Field 3</text>
<text id="4">Text Field 4</text>
</binding> 
</visual>
</tile>

XML Template for TileSquarePeekImageAndText03

The following images are examples of sample content using the WidePeekImage02 template:

WidePeekImage02 Live Tile notification template example

1.2 Tile Updates with XML DOM

Because tile content is defined in Windows-provided XML templates, one easy way to control the content of a tile is to manipulate it directly through the XML Document Object Model (DOM).
The following steps are involved in sending tile updates through XML DOM:

Decide which tile template to use and retrieve the empty XML document template using TileUpdateManager
Set values in the text fields
Set image URI values in the image fields
Include a square version tile content along with the wide version tile content
Create a TileNotification object from the XML document and set an expiration time
Send the update to the tile using the TileNotification object

The following source code in Example 1 sends a tile notification to a healthcare app tile that is configured to be removed after 10 minutes.

void UpdateTileWithImageText(int numofpatients)
{
    // 1) Get the tile template
    XmlDocument wideTileTemplateXml = 
        TileUpdateManager.GetTemplateContent( TileTemplateType.TileWidePeekImage02);
    
    // 2) Set text field values
    XmlNodeList tileTextFields = wideTileTemplateXml.GetElementsByTagName("text");
    tileTextFields[0].InnerText = “John Doe”;
    tileTextFields[1].InnerText = "15 appointments today";
    tileTextFields[2].InnerText = numofpatients.ToString() + " patients in records";
    tileTextFields[3].InnerText = "2 new patients added";
    tileTextFields[4].InnerText = "  " + DateTime.Today.ToString();

    // 3) Set image URI field values
    XmlNodeList tileImageFields = wideTileTemplateXml.GetElementsByTagName("image");
    ((XmlElement)tileImageFields[0]).SetAttribute("src", "images/LogoBlueWide.png");
    ((XmlElement)tileImageFields[0]).SetAttribute("alt", "Logo Image");

    // 4) Create square content too, this gives the user more choices
    XmlDocument squareTileTemplateXml = 
        TileUpdateManager.GetTemplateContent(TileTemplateType.TileSquareText04);

    // 2) Set text and image values for square tile content
    XmlNodeList squareTileTextFields = squareTileTemplateXml.GetElementsByTagName("text");
    ((XmlElement)squareTileTextFields[0])
        .AppendChild(squareTileTemplateXml.CreateTextNode("EMR App"));

    IXmlNode node = wideTileTemplateXml
        .ImportNode(squareTileTemplateXml.GetElementsByTagName("binding").Item(0), true);
    wideTileTemplateXml.GetElementsByTagName("visual").Item(0).AppendChild(node);

    // 5) Create the tile notification object using the rectangular template and set
    //    expiration time
    TileNotification tileNotification = new TileNotification(wideTileTemplateXml);
    tileNotification.ExpirationTime = DateTimeOffset.UtcNow.AddMinutes(10);
    
// 6) Send the update
    TileUpdateManager.CreateTileUpdaterForApplication().Update(tileNotification);
}

Code Example 1 Manipulate tile updates through XML DOM **

1.3 Tile Updates through NotificationsExtensions Library

Instead of directly manipulating tile content through XML DOM, Microsoft also provided a “NotificationsExtensions” library to make this process easier for developers. The library includes helper and factory functions for creating blank notifications and populating the text values and images.

1.3.1 Getting the NotificationsExtensions library

The NotificationsExtensions library is included by Microsoft in the “App tiles and badges sample” projects. You can download the sample files at http://code.msdn.microsoft.com/windowsapps/app-tiles-and-badges-sample-5fc49148, unzip the files, and build the “Tiles” project.

Under the project directory, you will see a “NotificationsExtensions” folder. In the “bin” directory look for the “NotificationsExtensions.winmd” file generated during the build. The “.winmd” file extension is for “Windows Meta Data” files. In some ways you can think of them as the DLL files. NotificationsExtensions.winmd is all you need to use the NotificationsExtensions APIs in your project.

1.3.2 Including the NotificationsExtensions library in your project

To include the NotificationsExtensions library, you may copy the NotificationsExtensions.winmd file to a place under your project folder. In our project, we put it under a “Libs” directory.

On Visual Studio* 2012 “Solution Explorer” window, right click on the project name (PRAPP in our example, Figure 1), and select “Add Reference…”. Browse and select the NotificationsExtensions.winmd file (Figure 2). Now you should see the NotificationsExtensions library under your projects “References” folder (Figure 2).

Figure 1. Adding reference (screen shot of Solution Explorer in Visual Studio* 2012)

Figure 2.Browsing for winmd file (screen shot of Solution Explorer in Visual Studio* 2012)

Figure 3.Adding reference to the NotificationsExtensions library (screen shot of Solution Explorer in Visual Studio* 2012)

1.3.3 Using the NotificationsExtensions library to update tile content

The following steps are involved in updating tile content using the NotificationsExtensions library API:

Decide which tile template to use and use TileContentFactory to create a tile content object
Set text and image fields of the tile content
Create a square version tile content and assign it to the tile content
Create a notification and update the tile using TileUpdateManager

In the following Code Example 2, we use the NotificationsExtensions APIs to send a notification to the tile.

 void UpdateTileWithImageText(int numofpatients) { // 1) create the empty tile content ITileWidePeekImage02 tileContent = TileContentFactory.CreateTileWidePeekImage02(); // 2) Set text and image field values tileContent.TextBody1.Text = “John Doe”; tileContent.TextBody2.Text = "11 appointments today"; tileContent.TextBody3.Text = numofpatients.ToString() + " patients in records"; tileContent.TextBody4.Text = "2 new patients"; tileContent.TextBody5.Text = DateTime.Today.ToString(); tileContent.Image.Src = "images/LogoBlueWide.png"; tileContent.Image.Alt = "Logo image"; // 3) Create square content ITileSquareImage squareContent = TileContentFactory.CreateTileSquareImage(); squareContent.Image.Src = "images/graySquare.png"; squareContent.Image.Alt = "Gray image"; tileContent.SquareContent = squareContent; // 4) Send the notification to the app's application tile TileUpdateManager .CreateTileUpdaterForApplication().Update(tileContent.CreateNotification()); }

Code Example 2 Updating tile content using NotificationsExtensions library functions **

1.4 Notification Queue

By default, an app tile displays a notification until it expires or a new notification is received. In this case the new notification overwrites the previous one. Sometimes the previous notification content may still be useful for the user. To make the tiles more dynamic, Windows 8 supports a live tile feature called “notification queue.” The notification queue preserves up to five update notifications for an app tile. The app tile cycles through these update notifications. The notification queue is a FIFO queue. When the notification count exceeds the queue limit, the oldest notification will be replaced by the new notification. A notification also includes a “tag” field to prevent duplicating conflicting content. A new notification will replace the existing notification with the same tag in the queue.

Here are the general steps involved in adding a notification queue for an app tile:

Call TileUpdateManager to Create a TileUpdater for the app and set EnableNotificationQueue to true.
Select a tile template and create a tile content object.
Populate the content object’s text and image fields, along with the square content for the tile content.
Create a notification object for the tile content.
Create a tag for the notification object.
Update the tile with the notification object.
Repeat the above steps for other notifications to be added to the queue.

In the following Code Example 3, we implemented a notification queue for our app tile.

void UpdateTileWithImageText(int numofpatients)
{
    // 1) enable notifications
    TileUpdateManager.CreateTileUpdaterForApplication()
        .EnableNotificationQueue(true);

    // 2) Create template
    ITileWidePeekImageAndText02 tileContent1 = 
        TileContentFactory.CreateTileWidePeekImageAndText02();

    // 2) set wide content
    tileContent1.TextBody1.Text = “John Doe”;
    … // set content values the same way as previous example

    // 2) set square content
    ITileSquareImage squareContent1 = TileContentFactory.CreateTileSquareImage();
    squareContent1.Image.Src = "images/graySquare.png";
    squareContent1.Image.Alt = "Gray image";
    tileContent1.SquareContent = squareContent1;

    // 3) Create notification object using the tile content
    TileNotification tileNotification1 = tileContent1.CreateNotification();

    // 4) tag it
    tileNotification1.Tag = "WhatIsNew";
    
    // 5) Update the tile with the notification
    TileUpdateManager.CreateTileUpdaterForApplication()
        .Update(tileNotification1);

    // 2) Create template
    ITileWideText02 tileContent2 = TileContentFactory.CreateTileWideText02();

    // 2) set wide content
    tileContent2.TextHeading.Text = "Alerts";
    tileContent2.TextColumn1Row1.Text = "Dr Nate";  
    … // set content values the same way as previous example

    // 2) set square content
    ITileSquareText02 squareContent2 = TileContentFactory.CreateTileSquareText02();
    squareContent2.TextHeading.Text = "Alerts";
    squareContent2.TextBodyWrap.Text = "New alerts for Dr Nate and Dr Wong";
    tileContent2.SquareContent = squareContent2;

    // 3) Create second notification object using the second tile content
    TileNotification tileNotification2 = tileContent2.CreateNotification();

    // 4) tag the second notification 
    tileNotification2.Tag = "Alerts";

    // 4) assign an expiration time for the second notification 
    tileNotification2.ExpirationTime = DateTimeOffset.UtcNow.AddMinutes(60);


    // 6) Update the tile with the second notification
    TileUpdateManager
        .CreateTileUpdaterForApplication().Update(tileNotification2);

}

Code Example 3 Enable the notification queue in the app tile **

2 Badges

Badges are lightweight UI elements used to show the status of a Windows Store app on the lower right corner of the app tile. Badges can also appear on a Windows lock screen, which we will discuss briefly in the next section.

A badge can include numbers (1-99) or a set of non-extensible Windows-provided glyphs. Please refer to the link http://msdn.microsoft.com/en-us/library/windows/apps/hh779719.aspx for a list of available glyphs provided by Windows.

Although badges are normally shown on app tiles, they are not part of the tile template XML. They actually overlay on top of the tile’s lower right corner. Like tiles, badges are also defined as XML documents. Also like tiles, badge updates can be implemented either directly through the XML DOM or using the NotificationsExtensions library.

2.1 Badge updates using XML DOM

In Code Example 4, we send a badge number “2” to our app tile, which is shown in the lower right corner of the app tile.

void UpdateTileBadgeNumber()
{
    // create the blank badge template
    XmlDocument badgeTemplateXml =
        BadgeUpdateManager.GetTemplateContent(BadgeTemplateType.BadgeNumber);
    
    // Set the content value to “2”
    XmlElement badgeElement = 
        (XmlElement)badgeTemplateXml.SelectSingleNode("/badge");
    badgeElement.SetAttribute("value", "2");

    // create a notification
    BadgeNotification badgeNotification = new
        BadgeNotification(badgeTemplateXml);

    // Update the live tile with the badge
    BadgeUpdateManager.CreateBadgeUpdaterForApplication()
        .Update(badgeNotification);
}

Code Example 4 Send a badge notification to the app tile **

This use case is very similar to updating tile content using XML DOM. To display a glyph badge, you may call the GetTemplateContent method within BadgeTemplateType.BadgeGlyph.

2.2 Badge updates using the NotificationsExtensions library

The NotificationsExtensions library also includes the helper functions to update badge content and frees app developers from directly manipulating the XML document. In Code Example 5, we update the badge on our app tile using the NotificationsExtensions library.

void UpdateTileBadgeNumberUsingNotificationExtensions()
{
    BadgeNumericNotificationContent badgeContent = new
        BadgeNumericNotificationContent(2);
    BadgeUpdateManager.CreateBadgeUpdaterForApplication()
        .Update(badgeContent.CreateNotification());
}

Code Example 5 Update badge content using the NotificationsExtensions library **

3 Other Notifications

Besides tile and badge notifications, Windows Store apps can use other methods to convey their app statuses. These include:

Toast notifications
Lock screen badges
Lock screen tile

A toast notification is a brief transient message that appears on the upper right corner of the screen. It normally carries information the user is interested in, such as the arrival of a new email message.

Windows 8 allows up to seven apps to be designated as lock screen apps. While the device is in lock screen state, these apps can show only badges. In addition, one of those apps can be configured by the user to show its latest tile notification text on the lock screen. An app must be defined to support lock screen notifications and declared to support background tasks in order to be eligible to be selected as a lock screen app. For more information on how to give your app a prescence on the lock screen, see the following article “Quickstart: Showing tile and badge updates on the lock screen (Windows Store apps)” - http://msdn.microsoft.com/en-us/library/windows/apps/hh700416.aspx. To select lock screen apps, go to PC Settings, “Personalize” menu and select the “Lock screen” tab.

4 Summary

We have discussed the Windows Store app client-side notification mechanisms, focusing on live tiles and badges. In addition, we mentioned toast and lock screen app notifications. These methods are used to communicate the current status of a Windows Store app to the user.

About the Authors

	Miao Wei is a software engineer in the Intel Software and Services Group. He is currently working on the Intel® Atom™ processor scale-enabling projects.
	Nathan Totura is an application engineer in the Intel Software and Services Group. Currently working on the Intel® Atom™ processor-enabling team, he helps connect software developers with Intel technology and resources. Primarily these technologies include tablets and handsets on the Android, Windows 8, and iOS platforms.