Quickstart: Showing tile and badge updates on the lock screen (Windows Store apps) (Windows)

Language: JavaScript and HTML | VB/C#/C++ and XAML

3 out of 8 rated this helpful - Rate this topic

In this article

Prerequisites
Declare the type of lock screen presence for your app
Declare a badge logo image
Declare a background task
Specify a wide logo
Summary and next steps
Related topics

This topic explains how to enable your app to show tile and toast notifications on the lock screen.

To see C#, C++, or Visual Basic versions of the JavaScript examples given in this Quickstart, click the "VB/C#/C++ and XAML" link at the upper right of this page.

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 JavaScript using Windows Runtime APIs. For more information, see Getting started with Windows Store apps.
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. Declare the type of lock screen presence for your app

Lock screen capabilities are declared in your app's package.appxmanifest file. If you use Microsoft Visual Studio Express 2012 for Windows 8, simply choose the appropriate Lock Screen Notifications option in the Application UI tab.

The following example shows the XML that is inserted in the package.appxmanifest file as a result of the option choice. The LockScreen element is added as a child node of the manifest's VisualElements element.

The XML shown here is also what you use if you are creating the package.appxmanifest file directly, outside of Visual Studio Express 2012 for Windows 8. For more information, see How to create a package manifest manually.

XML



<VisualElements 
    ...
    <LockScreen Notification="badge" BadgeLogo="images\logo-lockscreen.png"/>
    ...
</VisualElements>

XML



<VisualElements 
    ...
    <LockScreen Notification="badgeAndTileText" BadgeLogo="images\logo-lockscreen.png"/>
    ...
</VisualElements>

2. Declare a badge logo image

The following example shows the XML declaration of the BadgeLogo attribute of the LockScreen element. Note that, again, you will normally set this value through Visual Studio Express 2012 for Windows 8 rather than directly. For information on image requirements, see Lock screen apps overview.

XML



<VisualElements 
    ...
    <LockScreen Notification="badge" BadgeLogo="images\logo-lockscreen.png"/>
    ...
</VisualElements>

3. Declare a background task

An app with a lock screen presence must declare one of the following types of background tasks:

Control Channel
Timer
Push Notification

In Visual Studio Express 2012 for Windows 8, this value is set in the Declarations page of the manifest editor.

Choose "Background Tasks" from the Available Declarations drop-down list.
Click the Add button.
Select the appropriate items from the Properties list and add any additional information required by your choices.

In the manifest's XML, this value is declared in the BackgroundTasks element.

For more information on background tasks, see the Introduction to Background Tasks whitepaper.

4. Specify a wide logo

If you chose the badgeAndTileText value in Step 1, you must specify a wide logo image as part of the app's default tile. If the user has set your tile on the lock screen and chosen it to display detailed status, a wide tile is used. Square tiles are not used on the lock screen, so tile notifications sent as square tiles are not seen on the lock screen.

You can specify a wide logo image through the Visual Studio Express 2012 for Windows 8 manifest editor, or in the manifest's XML as shown here.

XML



<VisualElements 
    ...
    <DefaultTile ShortName="Tiles JS" ShowName="allLogos" WideLogo="images\tile-sdk.png"/>
    ...
</VisualElements>

Summary and next steps

After you complete the steps above, your tile is a candidate to be shown on the lock screen, should the user choose to show it. After the procedure detailed in this topic, your app is listed as a lock screen app in the Personalize category of PC settings. The user has the final choice of which of those apps to show on the lock screen, and which single one of them will show detailed status through text.

Quickstart: Showing tile and badge updates on the lock screen (Windows Store apps)