Tiles, Toasts, and Notifications

---

The previous chapters have discussed several different ways that a Windows Store app can be activated. These activations have occurred as responses to user interaction with Windows and as a result of the app participating in different Windows contracts and extensions—remember that launching an application from its Start tile is actually an implementation of the Launch contract. However, Windows Store apps have ways to provide information and seem alive even when the app itself hasn’t been activated: tiles and toasts.

For Windows Store apps, the tiles that appear on the Start screen are more than just oversized desktop icons. These tiles are "live tiles"—their display can be updated with text, images, icons, and animations in response to notifications from both within the system and from external sources. Apps can have both primary and secondary tiles, the latter of which can be used to provide additional information that is passed to the application if they are used to launch the app.

Toasts provide apps a way to communicate information to users while they are using another app. Toasts appear as pop-up notifications in the upper corner of the app, and much like live tiles can include text and images. Toast messages also include information that can be passed to the application if users choose to use the toast to launch the application.

This chapter will show how live tiles can be used to add functionality to otherwise inactive Windows Store apps. Then, toasts will be explored, including configuring how they appear, controlling when they appear, and reacting to what occurs when they are used to launch an app. The chapter will conclude with a discussion of push notifications, which allow updates to be triggered from services external to both the app and the device itself.

Live Tiles

Every Windows Store app that is installed initially has a tile on the Windows Start screen that can be used to launch the application. By default, each app includes a square tile and optionally can include a larger “wide” tile, with the app’s users deciding which size tile they want to include on their Start screen. The initial default content of an app’s tile is set in the app manifest file, and includes the following options:

• The tile’s standard-size logo image.
• The tile’s wide-size logo image.
• Whether title text should be displayed when the standard, wide, both, or neither tile is shown.
• Whether the foreground for text and other content is light or dark if it is being shown.
• The background color of the tile.

Beyond the content initially set for a tile, an app can affect the tile’s appearance in several ways. This includes directly or periodically updating text and image content that is displayed within the tile, updating numeric or glyph “badge” content on the tile, or even creating secondary tiles that provide users the opportunity to directly access specific app functionality from their Windows Start screen.

Updating the Live Tile Content

Through updates to live tile content, an app can be made to seem alive and engaging, even when the app itself isn’t actually running. Tiles can be updated immediately, on a predetermined repeating schedule, or at a set time. They can even be set up to cycle through a rotating queue of up to five tile designs. Both the standard and wide tile contents can be updated in these ways.

A tile’s contents are defined by using XML that specifies a combination of text and images that are to be displayed. This XML is based on a set of predefined templates provided by Windows. There are 46 predefined template types—10 square and 36 wide—which can be chosen for tile layouts. Some of these layouts are considered “peek” layouts; their content includes an image that fills the tile and is scrolled in and out with alternate content that includes some text and perhaps an additional image. There are four square and 14 wide layouts that support peek.

21. An Updated Tile and the Corresponding XML Template

In addition to text and image information, a tile can also include a “branding” setting. A tile’s branding indicates whether the content in the lower corner of the tile (lower left corner in left-to-right languages) will display the app’s small logo, the app’s title, or no content whatsoever. The small logo is the default.

Immediate Tile Updates

The first step in specifying a tile update is to define the XML to be used to define the tile’s contents. The XML for each template can be found in the tile template catalog, which is available at http://msdn.microsoft.com/en-us/library/windows/apps/Hh761491.aspx. This XML can be compiled by hand, or the GetTemplateContent static method of the TileUpdateManager class can be used to provide the basic XML for each template, which can then be filled in with the values to be displayed. Once the XML is defined, call the Update method on an instance of the application’s TileUpdater, which is retrieved from the TileUpdateManager class, with a TileNotification object that includes the XML, and optionally an expiration time for the tile. Note that if the app includes a wide tile, the notification should include populated templates for both the square and wide tiles, making it necessary to merge the XML. The following code shows an immediate tile update performed this way for an app that includes both wide and square tiles, with the tile set to expire two hours from when it is first shown (when it expires, it reverts to the app’s original tile):

Note that this code first performs a check to ensure that updates are enabled. Users can disable tile updates on a tile-by-tile basis by selecting the tile in the Start screen and selecting Turn live tile off from the app bar. If a live tile’s updates are disabled, they can be re-enabled by selecting Turn live tile on.

The previous code shows the same immediate tile update performed using the NotificationExtensions helper class.

Queued Tile Updates

In addition to setting a single tile update, it is also possible to queue up to five tiles that Windows will automatically cycle through. This is known as queuing, and simply requires that queuing be enabled. Windows will cycle through the five most recent tile updates, with the exception that tiles with the same Tag value will replace each other. The following code shows three tile sets being built up and queuing being enabled through a call to EnableNotificationQueue:

Scheduled Updates

The previous sections have discussed making immediate changes to the application tiles. Another option is for the tile to be updated at a later, predetermined time. In this case, the tile XML and a delivery time are used to create a ScheduledTileNotification, and instead of calling Update on the application’s TileUpdater instance, the ScheduledTileNotification is passed to a call to AddToSchedule, as shown in the following code:

Future updates can be cleared by retrieving the scheduled notification from the TileUpdater instance and calling RemoveFromSchedule. To help with this, it is possible to specify an Id value for the ScheduledTileNotification instance, which can then be examined later in the list of pending updates.

Periodic Updates

A tile can also be set to be updated at a fixed, repeating time period. For this type of update, instead of supplying XML for the tile, a URI to an HTTP or HTTPS endpoint is specified, which Windows will poll at the indicated interval for the XML to use for the tile’s content. Available polling intervals include 30 minutes, one hour, six hours, 12 hours, and daily. The periodic update can be set up with the StartPeriodicUpdate method on the application’s TileUpdater instance. It is also possible to specify a specific time for when the polling should begin, otherwise the first request will occur immediately. A tile can only have one periodic update interval, though multiple URIs—up to five—can be provided which will be called at the polling interval to provide multiple tiles for display via queuing by using the StartPeriodicUpdateBatch method. The server can provide a Tag value for batched tiles by setting the X-WNS-Tag HTTP response header in the value that is returned from the specified endpoints.

The periodic update can be stopped by calling the StopPeriodicUpdate method on the application’s TileUpdater instance.

Clearing Tile Contents

The last tile update to be discussed is the ability to clear any tile updates that have occurred and reset the tile to the default tile layout specified in the application manifest file. That can simply be accomplished by calling the Clear method on the application’s TileUpdater instance.

Badges

On top of containing text and image content, live tiles also host a small piece of status information in the corner opposite the tile’s branding (lower right for left-to-right languages). This information is known as a badge, and can either be a number (1–99) or one of a set of provided glyphs. Information conveyed through badges often includes the number of pending items that require the user’s attention, such as unread email messages, or perhaps some status information like a problem alert or unavailable network destination.

22. Live Tile Showing a Numeric Badge

Like the live tile content, the badge content is defined through specific XML content. As was previously mentioned, a numeric badge can have a number from 1 to 99, and there are 12 available badge values that can be set, including none. The available badge values are defined in the badge image catalog available at http://msdn.microsoft.com/en-us/library/windows/apps/hh761458.aspx. To update a badge value for an application’s tile, a BadgeUpdater instance for the application is obtained from the BadgeUpdateManager class, and the desired badge XML is passed to the Update method provided by the BadgeUpdater instance.

While scheduled updates cannot be set for badges, periodic updates can be configured in a manner that is nearly identical to periodic tile updates, with the exception that there is no provision for batching since there’s also no notion of queued badges. Otherwise, the syntax for the call to the application’s BadgeUpdater instance is identical to that of the TileUpdater.

Likewise, the tile’s badge content is independent from the tile contents, so it is cleared independently of the tile contents, though the same Clear call is used on the BadgeUpdater instance as is used on the TileUpdater.

Secondary Tiles

Apps can optionally create additional live tiles known as secondary tiles that can be used to launch the application with parameters for presenting users with a specific set of information. For example, a weather application could create a specific tile that, when used to launch the application, takes users to a display of the weather for a specific city they are interested in. Likewise, Internet Explorer’s pinning feature creates secondary tiles that instruct the browser to navigate to specific websites.

Working with Secondary Tiles

The process of adding a secondary tile is known as pinning, and must be initiated programmatically. It results in a system-defined dialog being shown to users for them to approve the addition of the tile. Users can remove a secondary tile at any time directly from the Start screen, and an app can also remove a secondary tile programmatically, though users will be presented with a dialog to confirm the removal. A secondary tile can be created with the following parameters:

• An Id value to identify the secondary tile.
• A short name to be displayed directly on the tile.
• A display name to be displayed with the tile for tooltips, in the All Programs list, and in Control Panel applications.
• The arguments to be provided to the application when it is activated via this tile.
• An options value to indicate whether the name should be displayed on the square or wide tiles, as well as whether the secondary tile will be shared through the cloud if the app is installed by the user (identified by his or her Microsoft ID) on a different machine.
• URIs to the images that will be placed on the tile (the wide tile logo can be omitted if a wide tile is not desired.)

In addition to the constructor properties, a secondary tile can also be given its own background color.

To pin a new secondary tile, a new SecondaryTile instance should be created, its properties set, and the new tile’s RequestCreateAsync value should be called.

23. User Dialog Presented when Adding a Secondary Tile

Secondary tiles can be updated in all of the same ways as primary tiles. Instead of obtaining a TileUpdater or BadgeUpdater reference by calling the respective TileUpdateManager CreateTileUpdaterForApplication and BadgeUpdateManager CreateBadgeUpdaterForApplication methods, the CreateTileUpdaterForSecondaryTile and CreateBadgeUpdaterForSecondaryTile methods are called with the Id for the secondary tile to be updated.

Removing secondary tiles programmatically involves locating the tile by its Id or creating a new SecondaryTile instance with the same Id, and then calling the tile’s RequestDeleteAsync method.

Responding to Secondary Tile Activation

When a user selects a secondary tile from the Start screen, the application goes through the same launch sequence as was outlined in Chapter 3. The application is activated via the Launch contract, which will result in the OnLaunched method override being called in the application object. An app being launched via one of its secondary tiles can be distinguished from a launch via the primary tile by the value in the launch arguments’ TileId parameter, which will match the value set when the secondary tile was created. Furthermore, the method’s arguments will contain a value for the Arguments property. It is up to the app implementation to decide how the TileId value and the content of the Argument parameter should affect application startup, such as by presenting the application’s initial page with certain data loaded, or perhaps starting the application in a different page.

Toast Notifications

Toast notifications are small message pop-ups that can be triggered to appear in the upper corner (upper right for left-to-right languages) of the Windows Start screen over any running applications. They give the application responsible for the toast notification the opportunity to alert users to some event regardless of what app is currently running, and are the only mechanism available for one Windows Store app to interrupt another. Users can react to a toast notification in one of three ways:

• They can ignore the notification, and after a period of time the notification will disappear.
• They can explicitly close the notification by dragging it off the screen or tapping the X icon it provides.
• They can use the notification to launch the corresponding app by tapping or clicking within the body of the notification window.

To be able to display toast notifications, the app has to indicate it is Toast Capable in the manifest file.

In addition to the app itself enabling toast notifications, users can disable notifications system-wide for a period of time (one hour, three hours, or eight hours) through the Notifications icon in the Settings panel. This is quite useful for situations like presentations where unexpected notifications could be annoying, embarrassing, or otherwise problematic. Users can also elect to disable notifications system-wide or for specific apps from within the Notifications section of the PC settings app.

Raising Toast Notifications

The content that appears in a toast notification is defined in XML in a manner very similar to the way content is defined for a live tile. There are eight available templates—four text-only and four that combine images and text. These templates are defined in the toast template catalog available at http://msdn.microsoft.com/en-us/library/windows/apps/hh761494.aspx. To display a toast notification, a ToastNotifier instance is obtained from the ToastNotificationManager class, and the desired toast XML is wrapped in a ToastNotification instance and passed to the Show method provided by the ToastNotifier instance.

24. A Toast Notification and Its Corresponding XML

Showing Immediate Notifications

The following code shows the process involved in showing a toast notification:

A toast notification can be configured to be shown for either a short duration (seven seconds) or a long duration (25 seconds). Toast notifications displayed for short durations include either the system’s default audible alert, or can be set to use one of several alternate system-provided brief alert sounds. Notifications displayed for long durations can optionally use any of these sounds, as well as may opt to play one of several additional system-provided looping sounds that play for the duration of the toast’s display. In both cases, an option exists to omit playing any sounds at all. The following code shows a toast notification configured for long duration with a looping sound:

Scheduling Toast Notifications

In practice, toast notifications triggered for immediate display like the ones shown so far will not be used directly from application code. For the most part, the application will be interrupting itself, and in these cases, perhaps a message dialog would be a more appropriate way to get users' attention. Instead, these immediate notifications will normally be used from background tasks, which will be discussed in more detail in the next chapter.

An alternative to immediate invocation of a toast notification is to schedule the notification to appear at a pre-scheduled time, perhaps as a reminder for users to return to the app to perform some task. Important notifications can be scheduled to repeat at a predetermined "snooze” interval, so if users dismiss the toast without invoking the application, the toast will reappear some time later. When a snooze interval is set, the maximum number of snoozes must also be set. The following code shows how a scheduled notification can be configured:

Scheduled updates can be cleared by retrieving the scheduled notification from the ToastNotifier instance and calling RemoveFromSchedule. To help with this, it is possible to specify an Id value for the ScheduledToastNotification instance, which can then be examined later in the list of pending updates.

Responding to Toast Notification Activations

When users choose to activate the app by tapping or clicking within the body of the toast notification, the application will go through its launch sequence, including running the application's OnLaunched method. Like launching the app from a secondary tile, this sequence will occur regardless of whether the app is already running. If launch parameters are set on the toast notification, they will be included in the Arguments parameter of the method’s arguments. It is up to the application implementation to decide how these arguments will be used to direct the user interface.

In addition to the activation and launch execution, a running application can subscribe to activation and dismissal events on an immediate notification. Both events return an instance of the notification that is triggering the event, and the dismissed event includes a parameter within its arguments that indicates how the notification was dismissed. Code for subscribing to these events follows:

Push Notifications

Up to this point, this chapter has focused on live tile updates and toast notifications that are initiated by the app itself, either immediately or through the use of some of the available scheduling options. In addition to these approaches, Windows Store apps can also make use of a mechanism known as a push notification to allow events that occur outside of the machine to to display tile updates or toasts through services managed by Windows. These push notifications extend the ability for an app to provide additional interaction with users, regardless of whether the app is running.

Push notifications are powered by a combination of a local service managed by Windows and a Microsoft-provided, cloud-based service known as the Windows Notification Service (WNS). The following diagram illustrates the sequence for working with push notifications:

25. Push Notification Life Cycle

This diagram illustrates the following steps:

16. The Windows Store app requests and is issued a push notification channel.
17. The Windows Store app provides this channel to the Internet service that will be sending the notification, which stores the channel information along with any other relevant information for later use.
18. Some event occurs which causes the Internet service to decide it is appropriate to send a push notification to its subscribers.
19. The Internet service uses some criteria to identify which subscribers should receive a notification, gathers the list of channels for those subscribers, and sends the notification to the Windows Notification Service in the form of an XML payload by calling each of the channel URIs.
20. If the channel is still valid, the Windows Notification Service routes the notification to the appropriate device, where the notification payload and device settings determine how the notification should be displayed.

To provide some context, if a sports app were to provide users with the ability to receive push notifications for news related to their favorite teams, the app would first obtain a channel. The app would then upload that channel URI plus some information to describe the user’s favorite teams to a sports Internet service related to that sports app, which would store that information internally. The sports service would then receive score and news updates in some manner. As each notification-worthy update arrived, the sports service would first build the appropriate notification XML. It would then query the notification information it had stored in order to identify channels where the favorite teams matched the incoming news. The sports service would then issue the notification XML to the WNS by using each one of these channels, and WNS in turn would provide the notification to the corresponding device, potentially displaying a toast message or a tile update indicating a change in the game score.

There are four kinds of push notifications available that can be sent to Windows Store apps. Tile, badge, and toast notifications are the same as the app-initiated notifications that have been discussed so far. In addition to these, push notifications include a raw notification option. A raw notification simply includes custom text content that can be sent to the Windows Store application—it is up to the application to determine how best to process the text. In order to interact with a raw notification, either the app has to be running, or a background task has to be configured to handle the notification on the app’s behalf. Background tasks will be discussed in the next chapter.

Now that the background of push notifications has been presented, the specific details for each of the steps involved will be discussed.

Configuring an App for Push Notifications

In order for a Windows Store app to participate in push notifications, it must first be registered with the Windows Store. Information related to this registration process will be presented here, while a more complete discussion of registering an app with the Windows Store will be included in the subsequent chapter concerning app deployment.

The simplest way to associate an app with the Windows Store is to select the Associate App with the Store menu option from the project’s Store context menu command in Visual Studio:

26. Associating an App with the Windows Store from Visual Studio

This will start the Associate Your App with the Windows Store wizard. The wizard will prompt for Windows Store credentials (discussed later), and then list the apps that have been registered in the Windows Store with those credentials. Once an app has been selected, the final page of the wizard will list changes that will be made to the app as a result of completing the wizard. These changes typically include:

• Updating the package name to a store-determined unique name.
• Updating the package’s digital signature file to a new file that includes a store-determined Publisher ID value.

Once the app’s manifest has been configured to be associated with an app registration in the Windows Store, the app can request a notification channel. The notification channel includes a URI uniquely associated with an installation of the app for a user on the machine. This channel is returned by a call to the CreatePushNotificationChannelForApplicationAsync method of the PushNotificationChannelManager class. A notification channel URI has the format https://xxx.notify.windows.com/?token=<token>, where the xxx value is determined by the WNS service, and the token is also provided by the WNS service.

The notification channel includes properties for both the channel URI and its expiration. It is important to note that the channels provided do expire after a period of time—currently 30 days—so an app must periodically update the Internet service issuing push notifications. To do this, it is a good idea to request a new channel each time the app is invoked, as well as to cache the channel URI value to see if the value returned when the app is invoked has already been sent to the Internet service. This latter step helps to reduce the amount of unnecessary calls to the Internet service by only making the update call when a change has been detected. The following code shows an implementation for this process using the ApplicationData LocalSettings storage:

Once a Windows Store app has obtained a notification channel URI and shared it with the Internet service, perhaps along with other relevant data that helps the service decide when it is time to send a notification to a particular channel, the service is ready to start sending push notifications.

Sending Push Notifications

When it is time for the Internet service to send a notification to a user, the service will issue an HTTP POST request to the Windows Notification Service using the notification channel URI supplied by the Windows Store app. The content of the POST request includes some authentication information, as well as the XML payload that describes the toast, tile, badge, or raw notification.

The Windows Notification Service requires that calls to issue push notifications include an access token that must be obtained by authenticating with the WNS. This authentication requires that the caller supply the application’s Package Security Identifier (Package SID) and client secret values available from the Windows Store entry for the app. These values are available by selecting the app in the Dashboard, navigating to the App Name > Advanced Features page, and then the Push Notifications and Live Connect Services Info link. Note that one access token can be used for multiple notification calls; it is not necessary to obtain a new one for every channel URI being called—though the tokens do expire, so it may be necessary to periodically refresh them.

Once the access token is available, the process of sending a notification includes preparing the XML payload, which is identical to the client-side XML for notifications that has been discussed so far, followed by simply issuing the request. Once the notification has been issued, the response codes should be examined so that expired or invalid notification channel URIs can be removed or otherwise marked to ensure they are not called again. A service that repeatedly attempts to issue notifications to bad endpoints may be throttled to prevent it from issuing notifications. Furthermore, a check should be made prior to sending a notification to ensure that the URI is actually a notification URI, and not a malicious attempt to intercept data destined for a user by providing an alternate URI to the Internet service. All valid notification channel URIs will use the domain notify.windows.com.

A typical sequence for sending notifications to endpoints that match some particular criteria from a .NET service (perhaps a WCF service) is shown in the following sample. Note that only one tile, toast, badge, or raw notification can be sent at a time. The creation of multiple notifications in this sample is simply to illustrate the various factory classes that can be used.

If a user is offline when a toast message is sent, the notification is dropped. The most recent tile and badge notifications will be cached by the service, with the number of tile notifications that make it to the client depending on whether queuing is enabled. By default, raw notifications are not cached.

Interacting with Push Notifications from the App

The push notification channel provides an event that can be used to notify the app when a notification occurs on that channel. There are two general scenarios this event can be used for. First, it provides an app a way to be notified that a raw notification has been received in order for the app to process that notification as appropriate. Second, the app has the opportunity to cancel Windows’ default processing of a notification (for example, to suppress displaying a toast notification that is intended to call attention to new data arriving for an app if the new data will automatically be displayed in the running app’s user interface.)

The following code shows this event being used with a channel when the channel is obtained during app startup:

Recap

This chapter examined the use of tiles and toasts to add additional dimensions to the ways in which a Windows Store app can appear to interact with users, even when the app itself isn’t actively running. This included mechanisms for working with both primary and secondary live tiles, showing toast notifications to call a user’s attention to one app while working in another, and using push notifications to allow actions occurring outside of the user’s machine to work with these tiles and toasts.

The next chapter will introduce the facilities exposed to allow Windows Store apps to perform tasks in the background when the main app itself isn’t activated through the Background Transfer and Background Task mechanisms.