New Windows Phone 8 Lock Screen Features: How to Upgrade Your App to Show Notifications

One of the nice additions to the Windows Phone 8 is that the 3rd party apps can now update the phone’s lock screen. The apps can be grouped to two categories based on how they manipulate the lock screen:

• Lock screen background image providers
• Lock screen notification providers

In this tutorial we’ll focus on the notification providers. We’ll take an existing Windows Phone 7 app and upgrade it to use the new Windows Phone 8 lock screen features.

The old app

In this tutorial a Windows Phone 7 news reader app is upgraded to show notifications on the lock screen. The app already have live tiles which shows the count of unread news items and the title of the latest article. The app updates the live tile using the following code:

var tile in ShellTile.ActiveTiles.First(); 
var tileData = new StandardTileData() 
{ 
    Count = newNews.Count > 99 ? 99 : newNews.Count, 
    BackTitle = latestNews.Publisher, 
    BackContent = latestNews.Title 
};

tile.Update(tileData);

Upgrading to Windows Phone 8 (and fixing the problems caused by Async CTP 3)

Upgrading our app to Windows Phone 8 happens through the project’s context menu:

It’s quite likely that the upgrade goes smoothly and we have a working WP8 app without having to do any changes. Unless we’ve used the Async CTP3, in which case we’re going to see errors like these:

Cannot find all types required by the 'async' modifier. Are you targeting the wrong framework version, or missing a reference to an assembly?

The solution to these is to remove the reference to AsyncCtpLibrary_Phonefrom your projects and to add the package Microsoft.Bcl.Async through NuGet (make sure to select the “Include prereleases”):

Adding the lock screen notification capabilities to the app

Now that we’ve upgraded the app to Windows Phone 8, we’re ready to add the lock screen notification capabilities to the app. This requires only few actions:

1. The WMAppManifest.xml is modified to include the Lock Screen notification capabilities
2. A new 30x30 icon is added to the project

Modifying the manifest

First step is to modify the app’s manifest file. This happens by manually editing the WMAppManifest.xml. Right click the file (located in project’s Properties-folder) and select Open With – Source Code (Text) Editor:

We need to add a new Extensions element into the file and declare the notification capabilities there:

<Extensions> 
  <Extension ExtensionName="LockScreen_Notification_IconCount" ConsumerID="{111DFF24-AA15-4A96-8006-2BFF8122084F}" TaskID="_default" /> 
  <Extension ExtensionName="LockScreen_Notification_TextField" ConsumerID="{111DFF24-AA15-4A96-8006-2BFF8122084F}" TaskID="_default" /> 
</Extensions>

These should be added just under the Tokens-element:

The new icon

In order to show notifications on the lock screen, the app must include a new 30x30 pixel sized icon. The documentation states that the “image must contain only white pixels plus some level of transparency.” So let’s add a new “lockscreen.png” to the root of the project and set it’s Build Action to “Content”:

We again have to modify the WMAppManifest.xml to include the new icon. When the app was upgraded to Windows Phone 8, the upgrade process added a new DeviceLockImageURI-property inside the Tokens-element. The lock screen icon is declared there:

<DeviceLockImageURI IsRelative="true" IsResource="false">lockscreen.png</DeviceLockImageURI>

The next step

The next step is to just sit back and enjoy. This feature doesn’t require any code changes.When the app updates the live tile, the lock screen is automatically updated too.

But.

This only happens if the user manually adds the app to the Settings – lock screen – “Choose apps to show quick status”:

In order for the application to show text notifications on the lock screen (in our case the title of the latest news item), the app must be set to show “detailed status”:

Testing

Now only thing left is to test the functionality. The app uses a scheduled agent to update the tile. But as we want to be sure that the lock screen is updated, we need to use the Visual Studio’s “Simulation Dashboard”to turn on the lock screen:

From the dashboard we can change the emulator to display the lock screen with a single click:

Now we can be sure that the lock screen is receiving its notifications:

The text content on the lock screen is the value from the “BackContent” propertyof the StandardTileData. The values from Title or BackTitleare not displayed.

Directing the user to make the app a lock screen application

Adding the support for lock screen notifications is rather easy. But because the feature requires a manual interaction from the user, it can be a good idea to push the user a little further. Instead of just asking them to navigate to the settings – lock screen, the following code automatically moves the user to the correct settings page:

await Windows.System.Launcher.LaunchUriAsync(new Uri("ms-settings-lock:"));

Secondary tiles and notifications

The lock screen notifications are updated through the main tile.

Conclusion

The new lock screen functionalities of the Windows Phone 8 are a nice addition to the OS. And it doesn’t require much from the developer to add these new capabilities: A few lines of XML and a new icon are all that is required. There’s no code involved.