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

Article
08/31/2015

This topic will show you how to create a lock screen app to receive background network notifications that use raw push notifications in a Windows Runtime app. Raw push notifications allow an app on the lock screen to receive network notifications when the app is in the background.

Objective: Create a lock screen app that receives network notifications that use 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 JavaScript 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 and apps written in C++/XAML and apps using the .NET Framework 4.5 in C#, VB.NET, or managed C++. For more information on background networking tasks that apply to JavaScript apps, see Supporting your app with background tasks.

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, 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.

JJ679949.wedge(en-us,WIN.10).gif 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 JavaScript source 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 JavaScript source file and 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" StartPage="js\backgroundTask.js">
      <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.


    var lockScreenAdded = false;

    function ClientInit() {
        // Lock screen is required for raw push notification
        // background code to run.
        //
        if (lockScreenAdded == false) {
            BackgroundExecutionManager.RequestAccessAsync().done(function (result) {

            switch (result) {
                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)
                    //
                    WinJS.log && WinJS.log("Lock screen access is denied", "sample", "status");
                    break;
            }
        }, function (e) {
            WinJS.log && WinJS.log("An error occurred while requesting lock screen access.", "sample", "error");
        });
    }

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

Guidelines and checklist for raw notifications

How to use WNS to deliver raw push notifications to a lock screen app

How to write a background task for raw push notifications

Lock screen overview

Push notification overview

Supporting your app with background tasks