Quickstart: Showing tile and badge updates on the lock screen (Windows Runtime apps)
This topic explains how to enable your app to show badge and tile notifications on the lock screen. Note that there is no special procedure for sending a notification to the lock screen. Notifications shown on the lock screen are the same notifications shown on the Start screen. Toast notifications appear on the lock screen with no special settings.
Prerequisites
To understand this topic, you 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 Create your first Windows Store app using JavaScript.
- 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 the Visual Studio manifest editor, simply choose the appropriate Lock screen notifications option in the Application 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. For more information, see How to create a package manifest manually.
<VisualElements
...
<LockScreen Notification="badge" BadgeLogo="images\logo-lockscreen.png"/>
...
</VisualElements>
<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 normally set this value through Visual Studio rather than manually. For information on image requirements, see Lock screen apps overview.
<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 (Windows only)
- Timer
- Push Notification
In Visual Studio, this value is set in the Declarations page of the manifest editor.
- Choose "Background Tasks" from the 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. Large and medium tiles are not used on the lock screen, so tile notifications sent without a wide binding are not seen on the lock screen.
You can specify a wide logo image through the Visual Studio manifest editor, or in the manifest's XML as shown here.
<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 device's 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.