Lock screen background for Windows Phone 8

Article
05/20/2016

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

In Windows Phone 8, a user can choose to use an app as its lock screen background image provider.

For your app to provide the lock screen background image in the phone, you need to declare the app's intent in the app manifest file, and add code to handle changing the background image.

This topic contains the following sections.

Updating the app manifest file

To provide the lock screen background image for the phone, first you need to update the app manifest file to declare your app as a lock screen background provider.

In Solution Explorer, expand Properties, right-click WMAppManifest.xml, click Open With, and then click Source Code (Text Editor) With Encoding.
Add the lock screen background <Extension> element in the <Extensions> element. If the <Extensions> element doesn’t appear in the file, place the entire code example below into the file. The <Extensions> element must be placed below the <Tokens> element.
```
<Extensions>
      <Extension ExtensionName="LockScreen_Background" ConsumerID="{111DFF24-AA15-4A96-8006-2BFF8122084F}" TaskID="_default" />
</Extensions>
```

Adding code to change the lock screen background

The following code example shows you how you can change the lock screen background image when the user taps a designated button.

private async void LockHelper(string filePathOfTheImage, bool isAppResource)
{
    try
    {
        var isProvider = Windows.Phone.System.UserProfile.LockScreenManager.IsProvidedByCurrentApplication;
        if (!isProvider)
        {
            // If you're not the provider, this call will prompt the user for permission.
            // Calling RequestAccessAsync from a background agent is not allowed.
            var op = await Windows.Phone.System.UserProfile.LockScreenManager.RequestAccessAsync();

            // Only do further work if the access was granted.
            isProvider = op == Windows.Phone.System.UserProfile.LockScreenRequestResult.Granted;
        }

        if (isProvider)
        {
            // At this stage, the app is the active lock screen background provider.

            // The following code example shows the new URI schema.
            // ms-appdata points to the root of the local app data folder.
            // ms-appx points to the Local app install folder, to reference resources bundled in the XAP package.
            var schema = isAppResource ? "ms-appx:///" : "ms-appdata:///Local/";
            var uri = new Uri(schema + filePathOfTheImage, UriKind.Absolute);

            // Set the lock screen background image.
            Windows.Phone.System.UserProfile.LockScreen.SetImageUri(uri);

            // Get the URI of the lock screen background image.
            var currentImage = Windows.Phone.System.UserProfile.LockScreen.GetImageUri();
            System.Diagnostics.Debug.WriteLine("The new lock screen background image is set to {0}", currentImage.ToString());
        }
        else
        {
            MessageBox.Show("You said no, so I can't update your background.");
        }
    }
    catch (System.Exception ex)
    {
        System.Diagnostics.Debug.WriteLine(ex.ToString());
    }
}

Unique image names

If you update the lock screen background image from isolated storage, you'll need to provide a unique file name on each update. An easy way to accomplish this is to implement A/B switching logic for the file names.

The following code shows an example of A/B switching logic.

string fileName;
var currentImage = LockScreen.GetImageUri();

if (currentImage.ToString().EndsWith("_A.jpg"))
{
    fileName = "LiveLockBackground_B.jpg";
}
else
{
    fileName = "LiveLockBackground_A.jpg";
}

var lockImage = string.Format("{0}", fileName);

// At this point in the code, write the image to isolated storage.

Setting up a default lock screen background image

A user can set your app as the default lock screen background image provider in the phone lock screen settings screen before your app has had a chance to set up the image. For this reason, you should include a default lock screen background image at the root of your main project's XAP package. Name the image DefaultLockScreen.jpg.

Handling parameters from the lock screen settings screen

If a user sets your app as the default lock screen background image provider in the phone lock screen settings screen, they might tap the open app button, as shown in the following image.

Tapping the open app button launches your app with info in the QueryString. You should design your app to handle this info for the best user experience; for example, you could direct the user to a custom lock screen settings screen within the app, or display a message that the lock screen background image is updating, as the app updates the image.

The following code example demonstrates how you can check for the QueryString info in the OnNavigatedTo(NavigationEventArgs) method.

protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
{
    base.OnNavigatedTo(e);

    string lockscreenKey = "WallpaperSettings";
    string lockscreenValue = "0";

    bool lockscreenValueExists = NavigationContext.QueryString.TryGetValue(lockscreenKey, out lockscreenValue);

    if (lockscreenValueExists)
    {
        // Navigate the user to your app's lock screen settings screen here, 
        // or indicate that the lock screen background image is updating.
    }
}

Linking to the lock screen settings screen from within your app

Consider adding a link to the phone's lock screen settings screen from within your app for your app user’s benefit. This is useful for the user because you can’t programmatically turn off your app as a lock screen background image provider from within the app. The user will need to visit the phone's settings screen and make the change themselves. Providing a link to the settings screen makes this straightforward and easy.

The following code example shows you how you can route a button click to the phone's lock screen settings screen.

private async void btnGoToLockSettings_Click(object sender, RoutedEventArgs e)
{
    // Launch URI for the lock screen settings screen.
    var op = await Windows.System.Launcher.LaunchUriAsync(new Uri("ms-settings-lock:"));
}