How to create a lock screen app that uses background raw push notifications (XAML)

Article
10/13/2015

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

This topic shows how to create a lock screen app to receive background network notifications in a Windows Store app that use raw push notifications.

Objective: Create a lock screen app that receives network notifications using raw push notifications when the app is in the background.

Prerequisites

The following information applies to any connected or network-aware Windows Runtime app that depends on network connections using raw push notifications to always be connected. This topic applies to apps written in C++/XAML and apps using the .NET Framework 4.5 in C#, VB.NET, or managed C++ for Windows 8.1, Windows Phone 8.1, and Windows Server 2012 R2.

Background network connectivity using raw push notifications is supported by a JavaScript app. For more information on background tasks that apply to JavaScript apps, see Supporting your app with background tasks. For information on background network connectivity supported by a JavaScript app, see Staying connected in the background (HTML).

Creating a lock screen app that uses background raw push notifications

Before you can use raw push notification through WNS to activate a background task or use the network trigger feature, you must make your app a lock screen app.

You must set the appropriate capabilities in the app manifest so that your app requests to be placed on the lock screen. Your app must also include code to request to be added to the lock screen and handle cases where it is added to or removed from the lock screen by the user.

To get onto the lock screen, an app must get consent from the user. The consent prompt appears when the lock screen request API is called. If the user does not give your app permission to run on the lock screen, then you will not be able to prompt for permission again. However, if the user accidently dismisses the dialog you will be able to prompt again.

If the user denies your app permission to be a lock screen app, they can add the app to the lock screen at a later time via the system permissions fly-out for your app. Users can also manually add your app to the lock screen from the Personalize section of PC settings.

To request that your app be placed on the lock screen you must complete the following steps. You can make changes to the app manifest using Microsoft Visual Studio 2013 to open the package.appxmanifest file or by manually modifying the app manifest.

Register to become a lock screen app

Ensure that your app’s tile has a wide logo associated with it in the app manifest. Ensure that the app manifest has set the WideLogo attribute on the DefaultTile element.

The following sample adds a DefaultTile element under the <VisualElements> element in an app manifest.
```
    <DefaultTile ShowName="allLogos" WideLogo="images\tile.png" />
```
Indicate your app's intention to use a background task. The app manifest must also specify the executable file that contains the background task and the class name where the entry point of the background task is implemented.

When building a lock screen app that uses raw push notifications with WNS, specify the pushNotification background task type. This will enable your app to receive raw WNS push notifications.

The following sample adds a raw push notification under the <Application> element in an app manifest.
```
<Extensions>
   <Extension Category="windows.backgroundTasks" EntryPoint="BackgroundTasks.SampleBackgroundTask">
     <BackgroundTasks>
       <Task Type="pushNotification" />
     </BackgroundTasks>
   </Extension>
</Extensions>
```
Since your app will be on the lock screen, it must also have a lock screen icon that can be used to display missed notifications. To enable this, update your app manifest to include the LockScreen element.

The following sample shows a LockScreen element added under the <VisualElements> element in an app manifest.
```
    <LockScreen Notification="badge" BadgeLogo="Images\badgelogo.png" />
```

After you have completed the previous steps, your app can request permission from the user to be placed on the lock screen. The Background.BackgroundExecutionManager.RequestAccessAsync methods present the user with a dialog box that requests that an app be added to the lock screen. If the user approves the request, your app can run in the background and place notifications on the lock screen.

The following sample requests permission to be placed on the lock screen.

    bool lockScreenAdded = false;

    async void ClientInit() {
        // Lock screen is required to let in-process RealTimeCommunication related
        // background code to run.
        //
        if (lockScreenAdded == false) {
            BackgroundAccessStatus status = await BackgroundExecutionManager.RequestAccessAsync();
            Diag.DebugPrint("Lock screen status" + status);

            switch (status) {
                case BackgroundAccessStatus.AllowedWithAlwaysOnRealTimeConnectivity:
                    //
                    // App is allowed to use RealTimeConnection broker 
                    // functionality even in low power mode.
                    //
                    lockScreenAdded = true;
                    break;
                case BackgroundAccessStatus.AllowedMayUseActiveRealTimeConnectivity:
                    //
                    // App is allowed to use RealTimeConnection broker 
                    // functionality but not in low power mode.
                    //
                    lockScreenAdded = true;
                    break;
                case BackgroundAccessStatus.Denied:
                    //
                    // App should switch to polling mode (example: poll for email based on time triggers)
                    //
                    Diag.DebugPrint("As Lockscreen status was Denied, App should switch to polling mode such as email based on time triggers.");
                    break;
            }
        }
        return;
    }

When building a WNS-based lock screen app using raw push notifications, the BackgroundAccessStatus for your app will be set to AllowedMayUseActiveRealTimeConnectivity after permission has been granted. The AllowedWithAlwaysOnRealTimeConnectivity real-time connectivity option is used for network trigger feature and does not affect WNS-based lock screen apps using raw push notifications.

After your app is added to the lock screen it should be visible in the Personalize section of the PC settings. Note that users may opt to remove your app from the list of lock screen apps at any time. So you must ensure that your app is always functional even when it has been removed from lock screen.

For more information on lock screen requests, see the Lock screen overview and the Lock screen apps sample.

Summary and next steps

For more information on the process of registering a push notification channel and send it to your server, register a background task to activate from a raw push notification, and send a raw push notification to the channel and activate the background task, see How to use WNS to deliver raw push notifications to a lock screen app.

For more information on how to write a background task to receive background network notifications that use raw push notifications, see How to write a background task for raw push notifications.

For more information on guidelines and checklists for using raw push notifications, see Guidelines and checklist for raw notifications.

Other resources

Adding support for networking

Background Networking

Badge overview

Lock screen overview

Push notification overview

Staying connected in the background

Supporting your app with background tasks

Tile and tile notification overview

Toast notification overview

Transferring data in the background