Wensus Analytics

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

imageOne 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:

image

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_Phone from your projects and to add the package Microsoft.Bcl.Async through NuGet (make sure to select the “Include prereleases”):

image

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 30×30 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:

image

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:

image

The new icon

In order to show notifications on the lock screen, the app must include a new 30×30 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”:

image

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”:

image

image

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”:

image

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:

image

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

image

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

image

The text content on the lock screen is the value from the “BackContent” property of the StandardTileData. The values from Title or BackTitle are 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.

  • Alexander Tsoi

    Hi Mikael,

    Thanks for the article. I cannot find Microsoft.Blc.Async package even with “Include prerelease” option. Any other specific filters or actions?

    • http://mikaelkoskinen.net/ Mikael Koskinen

      sorry! It should read .bcl.

      • Alexander Tsoi

        Awesome. Thanks!

  • http://twitter.com/qmatteoq Matteo Pagani

    Why do you have to install the Microsoft.Bcl.Async library? Task support is native in Windows Phone 8, due to the alignment with .NET Framework 4.5 and C# 5

    • http://mikaelkoskinen.net/ Mikael Koskinen

      Thanks for the comment. You’re right about the Task-support but without the Bcl-library you’re going to miss some methods which you probably have used with the async ctp. For example out of the box the WebClient class in WP8 doesn’t support async/await, but the library adds handy extension methods like DownloadStringTaskAsync which are awaitable.

  • Aaron

    Have you got a small sample for this please?

    • http://mikaelkoskinen.net/ Mikael Koskinen

      Unfortunately no :(

      • Aaron

        Your code is fine but I am trying to add a background task to this now to update my primary tile which is not working :(