Lock screen overview (Windows Runtime apps)
This topic discusses the concepts and terminology for an app's presence on the lock screen. The lock screen is shown when you lock your device, as well as when you reboot the device or wake it from a sleep state. It is a user-customizable surface that both conveys information and protects the computer against unauthorized use.
The Windows 8 lock screen serves three basic purposes:
- Prevents accidental sign-in attempts on touch devices
- Provides a personalized surface for the user
- Displays lightweight information to the user:
- Date and time
- Network and battery status
- Notifications from a limited set of apps
The following image shows the lock screen on a Windows device.
Lock screen contents
The lock screen contains a mix of system, user, and app content. A background image can be customized by the user through the device's Settings. A light transparent wash is applied to the selected image to increase the visibility of lock screen text and icons. Date and time are always shown and cannot be customized. The network icon is also always shown, while a battery icon is shown for devices running on a battery.
An app can reflect three different types of information to the lock screen:
- The app tile's current badge
- The text from the app tile's most recent tile notification
- Toast notifications
Multiple apps can have a lock screen presence at once. Each of those apps can show badges and toast, but only one of them can show the text of its latest tile notification, though without any accompanying images.
As long as your app has been granted a tile or badge slot on the lock screen and is declared toast capable in the app's Package.appxmanifest file, any toast notifications sent by your app will appear on the lock screen when the device is locked. A toast shown on the lock screen includes both image (if present) and text. The toast is shown for the length of a long-duration toast.
Note For Windows Phone Store apps, the toast is shown for the normal length of time.
Should your app be on the lock screen?
The lock screen is designed to show information that a user can take in with a glance. Users should not have to dwell on this screen to receive information. The best app candidates to be placed on the lock screen can convey understandable, context-free, summary information through only a badge and a logo icon. For example, a mail app that shows a badge with a count of unread messages would work well on the lock screen. An example badge showing the number 3 next to the star logo icon is shown in the image above.
When a user places an app on their lock screen, they indicate that the information which the app provides is important to them, so the app should convey real-time information through the lock screen. For instance, a communication app informs the user when they've received a message or when they're receiving a call. The user should have confidence that they're seeing the latest status when they glance at their screen for updates.
Lock screen content simply mirrors the content of the app's Start screen tile or badge and does not require any additional API calls. However, because on the lock screen the badge sits next to a logo image rather than on a tile and only the text portion of a tile update is shown, some context is lost, and this can be a factor in whether your app is a good candidate to be added to the lock screen.
Careful consideration should be given to the possibility of your app being selected to show detailed status (tile notification content) on the lock screen. Images in the tile update are not displayed on the lock screen. Therefore, a social app that identifies the source of an update only through a contact's picture is not a good candidate to be shown on the lock screen because that context would be lost. However, an app with a text-driven calendar tile would work well.
For more detailed information, see the lock screen section of Guidelines and checklist for tiles and badges.
Note Do not declare lock screen capabilities just to play sound or show information about what is playing—that happens automatically. This applies particularly to music players. Doing so would pointlessly occupy one of the limited lock screen slots, possibly blocking an app which actually needs that slot to function properly.
Declaring your app's lock screen capabilities
For your app to become a lock screen candidate, you must first declare its lock screen capabilities and elements in your app's Package.appxmanifest file. In that file's XML structure, this information is added to the VisualElements element, unless stated otherwise. However, in what follows, we assume that you are using the Microsoft Visual Studio manifest editor.
Note These steps are detailed in Quickstart: Showing tile and badge updates on the lock screen.
Lock screen tile display type
If you use the Visual Studio manifest editor, choose the appropriate Lock screen notifications option in the Application tab. The choices are:
- Badge: Your app can show only a badge on the lock screen.
- Badge and Tile Text: Your app can show both a badge and a detailed status on the lock screen.
Selecting either option provides that toast notifications for your app will appear on the lock screen if toast is enabled for this user.
Note Setting the Lock screen notifications option doesn't place your app on the lock screen—only the user can do that—it just gives the user those possibilities.
When your app's badge is shown on the lock screen, it appears next to an icon for your app. This icon is specific to your badge and is provided through the manifest together with the logo images used by the app on the tile or in search results. An example is shown here: the star is the badge icon, the number 3 is the numeric badge itself.
This icon must meet these requirements:
- Size: 24x24 pixels (for the 100% scale image)
- Type: .png
- Color: monochrome white
- Transparency: any
If a tile is not currently displaying a badge, nothing, including the logo, is shown in the badge's slot on the lock screen.
When the lock screen displays text from a tile update, it does so only in a wide tile. Therefore, if you declared the Badge and Tile Text option, you must provide a wide logo for your app's tile or your manifest will be invalid and your app will not build. The wide logo is declared as a visual asset in your manifest as part of the default tile. For more information, see Quickstart: Creating a default tile using the Microsoft Visual Studio manifest editor.
If the tile notification currently shown on the lock screen is removed, for instance by expiring, nothing is shown in its place until a new tile notification arrives.
An app with a lock screen presence must declare one of the following types of background tasks:
- Control Channel (Windows-only)
- Push Notification
Note that the app can run background tasks only if the user has placed that app on the lock screen.
In Visual Studio, this value is set in the Declarations page of the manifest editor. Add the Background Tasks declaration, then select the specific background tasks from the Properties list that appears. If you are manually creating the manifest file, the background task is declared in the BackgroundTasks element, which is a child of the Extensions element.
In addition to the contents of your app's primary tile, your app's secondary tile content can also be reflected on the lock screen. Here's how:
- Required Provide a badge logo through the LockScreenBadgeLogo property. This badge logo should be a different image than the parent app's badge logo, but it must meet the same requirements.
- Optional Set the LockScreenDisplayBadgeAndTileText property to make the secondary tile eligible for the lock screen's detailed status slot.
Prompting the user to place your app tile on the lock screen
Your app can ask the user to place the app on the lock screen through an API call (requestAccessAsync). This presents a dialog box through which the user can select "allow" or "don't allow". In response to the user's choice, your app receives a value (from the BackgroundAccessStatus enumeration) that is based both on the user's response and on the state of the other apps that the user has selected for their lock screen. This method can only be used for an app's primary tile; the user must manually add eligible secondary tiles to the lock screen.
If all lock screen positions are already full when this request is made, the user is presented with a flyout that asks them to choose which of the currently selected apps the new one should replace. To display detailed status, the user must manually assign your app to that slot—it cannot be prompted for.
Note An app is allowed to ask for lock screen access only once. The user can choose only one of the two options, so their preference will have been stated (although they can also dismiss the dialog without making a choice). Further calls to requestAccessAsync will be ignored. The single exception to this is the case when all lock screen slots are full and the user doesn't choose to replace an existing app with the app that's requesting access. In that case, a subsequent call to requestAccessAsync again displays the confirmation UI. For more information, see Windows.ApplicationModel.Background.BackgroundAccessStatus.
User management of lock screen apps
The user is ultimately in control of what appears on their lock screen. They can manage which apps appear on their lock screen, the order they appear, and the single app that can display text updates. The user does this by through their device's Settings. The image below shows these settings on a Windows device. When the user clicks or touches one of the slots (the gray boxes), a flyout is shown listing all of the eligible apps and secondary tiles from which to choose.
Note For Windows Store apps, the user can toggle an app's lock screen rights (and associated background access) in the Permissions section of the app's Settings pane, shown here. Note that this only applies to the app's primary tile. The user must manually add secondary tiles to the lock screen through the Personalize page in PC Settings. These settings are not available for Windows Phone Store apps.
Sending information to the lock screen
Once your app is on the lock screen, there is no additional work required to route notifications to it. Windows simply routes badge updates, tile updates, and toasts normally and they appear on the lock screen when the lock screen is active. In fact, there is no way for your app to know whether it has a lock screen presence. Because it cannot change its behavior based on that information, careful consideration of that fact should be given when determining whether to ask for a lock screen slot at all.
Note Tile notifications shown on the lock screen do not use the notification queue. Only the most recent tile update appears on the lock screen.