App tiles and badges sample

This sample shows you how to use an app tile, which is the representation and launch point for your app on the Start screen. The sample also shows you how to use a badge with that tile, which lets app relay status information to the user when the app is not running—the number of unread mails is the generic example.

Note This sample was created using one of the universal app templates available in Visual Studio. It shows how its solution is structured so it can run on both Windows 8.1 and Windows Phone 8.1. For more info about how to build apps that target Windows and Windows Phone with Visual Studio, see Build apps that target Windows and Windows Phone 8.1 by using Visual Studio.

An app tile can be a static image, but it can also be a live tile, which can show the user updated news, photos, events, or other content related to that app. Notification updates, based on a Windows-supplied set of templates, provide that material (which can come from either a local, network, or web source), keeping the tile content fresh.

The sample demonstrates the following scenarios:

Sending new text content to the tile
Using a local image (from the app's package or local storage) in the tile
Using a web image (http or https protocol) in the tile
Updating a badge on the tile
Updating a tile through a push notification, using Azure Mobile Services
Exercising the full catalog of tile templates
Enabling the notification queue, either regardless of tile size or selectively for specific tile sizes, and using tags to selectively replace notifications in the queue.
Setting an expiration time for a notification so that it is removed from the tile
Accessing images through different protocols and by using a pre-defined root path (baseUri)
Globalization, including localization, scaling of images, and accessibility
Optimizing images before you send your notification, including scaling and cropping (JavaScript only)
Avoiding duplication of content in tiles that show multiple stories

Most of the functionality in this sample requires that the tile can receive notifications. Tile notifications can be disabled by a user for a single app or for all apps, or by a system administrator using group policy.

This sample code has declared the "Internet (Client)" capability in its app's manifest. You must do this in your own code whenever you plan to use non-local content. In the Microsoft Visual Studio 2013 manifest editor, you can find this option under the Capabilities tab.

To obtain an evaluation copy of Windows 8.1, go to Windows 8.1.

To obtain an evaluation copy of Visual Studio 2013, go to Visual Studio 2013.

Note For Windows 8 app samples, download the Windows 8 app samples pack. The samples in the Windows 8 app samples pack will build and run only on Microsoft Visual Studio 2012.

Operating system requirements

Client	Windows 8.1
Server	Windows Server 2012 R2
Phone	Windows Phone 8.1

Build the sample

Start Microsoft Visual Studio 2013 Update 2 and select File > Open > Project/Solution.
Go to the directory to which you unzipped the sample. Then go to the subdirectory named for the sample and double-click the Visual Studio 2013 Update 2 Solution (.sln) file.
Follow the steps for the version of the sample you want:
- To build the Windows version of the sample:
  1. Select Tiles.Windows in Solution Explorer.
  2. Press Ctrl+Shift+B, or use Build > Build Solution, or use Build > Build Tiles.Windows.
- To build the Windows Phone version of the sample:
  1. Select Tiles.WindowsPhone in Solution Explorer.
  2. Press Ctrl+Shift+B or use Build > Build Solution or use Build > Build Tiles.WindowsPhone.

Run the sample

The next steps depend on whether you just want to deploy the sample or you want to both deploy and run it.

Deploying the sample

To deploy the built Windows version of the sample:
1. Select Tiles.Windows in Solution Explorer.
2. Use Build > Deploy Solution or Build > Deploy Tiles.Windows.
To deploy the built Windows Phone version of the sample:
1. Select Tiles.WindowsPhone in Solution Explorer.
2. Use Build > Deploy Solution or Build > Deploy Tiles.WindowsPhone.

Deploying and running the sample

To deploy and run the Windows version of the sample:
1. Right-click Tiles.Windows in Solution Explorer and select Set as StartUp Project.
2. To debug the sample and then run it, press F5 or use Debug > Start Debugging. To run the sample without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.
To deploy and run the Windows Phone version of the sample:
1. Right-click Tiles.WindowsPhone in Solution Explorer and select Set as StartUp Project.
2. To debug the sample and then run it, press F5 or use Debug > Start Debugging. To run the sample without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.
3. Give it several seconds to launch in the emulator (it takes over the full screen, so if you're still seeing your Start screen tiles, the sample hasn't launched yet), after which you can find the sample in the Apps list. Add the tile's sample to the Start screen so that you can see the result of the action that you've taken in the sample. A tile must be pinned to the Start screen to receive notifications.

How to use the sample

After you send a tile or badge notification from one of the scenarios, switch to your Start screen to see the notification appear on the sample's app tile. Click the tile again to return to the sample.

A tile can display only those notifications that contain a binding for the size that the tile currently uses. Otherwise, nothing happens. Therefore, you might have to resize a tile to see the notification that you've sent. For instance, in scenario 6, which allows you to exercise all of the tile templates, your tile on the Start screen must be wide if you are sending a wide tile template. The sample app shows you the notification's XML payload, including the tile size or sizes that the payload contains. To resize your tile on the Start screen, right-click (or press and hold) the tile to be presented with the option to resize. Choose medium, wide, or large as needed. Note that the small size is not a live tile and Windows Phone does not support the large tile size.

Note that scenario 5 ("Send push notifications from Mobile Services") is strictly informational and performs no action on the tile. However, in the Windows Phone emulator, you can experiment with push notifications through its Additional Tools flyout.

Related topics

Operating system requirements

Build the sample

Run the sample

How to use the sample