This sample shows how an app can have a presence on the lock screen—the screen that is shown when the computer is locked—with a badge to provide basic status information or a tile to provide more detailed status. An app can also send toast notifications to the lock screen. All apps that are granted a lock screen presence also have the ability to perform background tasks.
The sample demonstrates the following scenarios:
- Requesting lock screen access for the app
- Querying for the current lock screen access status of the app
- Removing the app's lock screen access at its request
- Sending a badge update notification to an app's badge on the lock screen
- Sending a text-only tile update notification to an app's tile on the lock screen
- Using secondary tiles with the lock screen
An app that has a lock screen presence must declare one or more of the following types of background tasks:
- Control channel
- Timer
- Push notification
In Microsoft Visual Studio 2013, this value is set in the Declarations page of the manifest editor, which sets the BackgroundTasks element in the package.appxmanifest file. This value has been set for this sample.
For an app to send a toast notification, the developer must have declared that the app is toast-capable in its app manifest file (package.appxmanifest) as has been done in this sample app. Normally, you do this by using the Visual Studio 2013 manifest editor, where you'll find the setting in the Application UI tab, under the Notifications section. For more info, see How to opt in for toast notifications.
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.
Related topics
- Guidelines and checklist for tiles and badges
- Quickstart: Showing tile and badge updates on the lock screen
- Lock screen overview
- Windows 8 Windows Store app samples
Operating system requirements
| Client | |
|---|---|
| Server |
Build the sample
- Download the sample's .zip file using one of the buttons near the top of the page.
- Unzip the downloaded file into a folder on your computer.
- Start Visual Studio 2013 and select File > Open > Project/Solution.
- Go to the folder where you unzipped the sample.
- Find and open the folder named for the sample and one of its programming language subfolders (C#, JS.
- Double-click the Microsoft Visual Studio Solution (.sln) file to open it.
- Select Build > Build Solution to build the sample.
Run the sample
To debug the app and then run it, press F5 or use Debug > Start Debugging. To run the app without debugging, press Ctrl+F5 or use Debug > Start Without Debugging.
How to use the sample
An app is allowed to ask a user to add the app to the lock screen only one time. When you first run this sample, you must select Request lock screen access in the first scenario before attempting to run any other scenario. At that point, you are presented with a dialog box. Regardless of the answer you choose, because of the "ask only one time" rule, you will not see this dialog box again unless you uninstall and reinstall the sample.
When you choose Allow from the dialog box, the sample app is added to the lock screen. You can verify this by going to PC settings and examining the Lock screen apps list to see the sample's logo listed there. To remove the app from the lock screen, click the logo and click Don't display a badge here. Because the sample app itself can't ask you to add it to the lock screen a second time, if you do remove the app here, you'll have to re-add it here as well, by clicking on one of the plus signs and selecting it from the Flyout.
Return to the sample and select scenario 2. Click the Send badge notification button.
Lock your computer either by clicking your user tile in the upper right corner of the Start screen and selecting Lock or by pressing the Windows logo key + L. Notice the app's logo and the badge displaying the number 6.
Log back in and go to PC settings. Click the Send tile notification button. Under Lock screen apps, click the item under Choose an app to display detailed status and select the sample app from the flyout menu. This step must be performed to send a tile notification to the lock screen. This action can only be performed by the user—it cannot be done programmatically.
Return to the sample and again select scenario 2. Click the Send tile notification button.
One more time, lock your computer to see the lock screen. Notice the tile text that appears above the date.
Return to the sample. Scenario 3 deals with secondary tiles, which are tiles that reference a specific location or experience inside of the parent app. Only the user can create and remove secondary tiles. When you select "Create a badge-only secondary tile" or "Create a badge a tile text secondary tile" you are taking the role of the user and granting permission for those secondary tiles to be created on the Start screen.
After you've created one or both of those tiles, you must manually add them to the lock screen. Go to PC settings, click one of the plus signs, and choose the secondary tile (for instance, "LockScreen JS - Badge only"). If you created the badge and text secondary tile, assign it to the "Choose an app to display detailed status" slot. (Note: Despite its name, the badge and text secondary tile does not display a badge.) Lock your computer to see those items on the lock screen.