How to write a background task for raw push notifications (HTML)

Article
08/31/2015

This topic will show you how to write a background task to receive background network notifications that use raw push notifications in a Windows Runtime app on the lock screen. This topic walks you through writing a background task for the raw push notifications feature in Windows 8.1 for a Windows Runtime app.

What you need to know

Technologies

Windows.Networking.PushNotifications

Enables background network communications using raw push notifications.

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 on Windows 8.1, Windows Phone 8.1, and Windows Server 2012.

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.

Instructions

Writing your background task

An important next step in making the app always reachable is to provide the app code that runs when a raw push notification occurs. For example, in the case of an email app that uses incoming raw push notifications to signal that new mail has arrived on the server, the app needs to run code to process the data in the raw push notification. This data might contain a list of new emails received to raise a notification to the user. An app might also schedule to connect to the email server and download the new emails from the server the next time the app is not longer suspended. This processing is done in the background task.

Every background task is implemented by a function that run when the app registered for a raw push notification. This was specified in the app manifest as the specific JavaScript source file that contains a single function.

The following sample shows the function that runs when the background task is triggered by a raw push notification.

(function () {
    // Get the background task details
    var backgroundTask = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current;
    var settings = Windows.Storage.ApplicationData.current.localSettings;
    var taskName = backgroundTask.task.name;

    console.log("Background task \"" + taskName + "\" starting...");

    // Store the content received from the notification so it can be retrieved
    // from the UI.
    var notificationDetails = backgroundTask.triggerDetails;
    settings.values[taskName] = notificationDetails.content;

    console.log("Background \"" + taskName + "\" completed!");

    // Close the instance running the task
    close();
})();

Note You cannot reference elements of your app user interface (UI) in a background task because the UI elements in your app are not running. When your code is executing in the background task, you can receive the data from the raw push notification, parse and process the data, and raise a notification to the user.

The lifetime of the background task is controlled by the function that implements the background task. When an app exits the function, the app is suspended.

When an app background task is triggered, the operating system ensures that appropriate synchronization delivers the raw push notification data to the app or returns an error (connection aborted, for example). Similarly, at the end of the background task an app must ensure that any notifications are raised before the app is suspended.

Although the background task is primarily targeted towards an app in the suspended state, an app configured with background tasks will also have these background tasks trigger when the app is in the foreground.

Previous steps

For more information on how to create a lock screen app to receive background network notifications that use raw push notifications, see How to create a lock screen app that uses background raw push notifications.

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 guidelines and checklists for using raw push notifications, see

Guidelines and checklist for raw notifications.

Other resources

Adding support for networking

Background Networking

Guidelines and checklist for raw notifications

How to authenticate with the Windows Push Notification Service (WNS)

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

Lock screen overview

Push notification overview

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

Supporting your app with background tasks