Quickstart: Creating and registering a raw notification background task (HTML)

  • Article

Note  Not using JavaScript? See Quickstart: Creating and registering a raw notification background task (XAML).

 

You can create and register a background task function for your Windows Store app. This code then runs in response to the receipt of a raw notification, which gives your app functionality when it is not in the foreground.

To complete this procedure, you must edit three separate files: the app's code, the app's manifest, and a new JavaScript file that contains the background task code.

Prerequisites

To understand this topic or to use the code it provides, you will need:

Instructions

1. Create the background task class

Create a new JavaScript (.js) file in your project. In this case, we'll call the file examplebackgroundtask.js. The code in this file will be triggered to run in the background by the receipt of a raw notification. Add the skeleton JavaScript function shown below to that file.

This example's doWork function (of course you can call it anything that you'd like) contains the code that makes up the actual background task. First, it retrieves the content from the notification through the Windows.UI.WebUI.WebUIBackgroundTaskInstance class, which is used to get information about the current instance of the background task. The body of your code, specific to your app-defined raw notification content, will replace the "// ..." comment.

Important  Note that the task code finishes by calling JavaScript's built-in close function. This method must be called whenever a JavaScript background task completes its work or is canceled. If the background task doesn't close itself, the background task's process can continue to exist, consuming memory and battery life even though the background task is complete.

 


(function () {
    "use strict";

    var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current;

    function doWork() {
        var notificationContent = backgroundTaskInstance.triggerDetails.content; 

        // ...

        close();
    }

    doWork();
})();

2. Declare the background task in your app's manifest

Note  As a prerequisite to this step, your app must choose a lock screen option and provide a badge logo before background tasks are supported. For more information, see Quickstart: Showing tile and badge updates on the lock screen.

 

Before your app can register a background task, you must declare the background task and its trigger in the app's manifest. This can be done directly as XML or through the Microsoft Visual Studio Manifest Editor.

  • To use the Manifest Editor, double-click your project's Package.appxmanifest file in Visual Studio. On the Declarations tab, choose Background Tasks from the Available Declarations drop-down list. As a trigger, choose Push notification under Properties. In the Start page box, enter the name of the background task's .js file, in our case examplebackgroundtask.js.

    If your app uses more than one background task, repeat this step for each task, pointing each time to a different file.

  • To add the information directly to the manifest's XML, open the manifest in a text editor. In the Extensions element, add an Extension element for the background task class. The Category attribute should be set to "windows.backgroundTasks" and the StartPage attribute should name the background task's .js file, in our case examplebackgroundtask.js.

    If your app uses more than one background task, add a separate Extension element for each task, each element pointing to a different .js file.

    You must list each type of trigger that a background task uses. Because we're creating a background task that triggers in response to a raw notification, we will declare a push notification trigger. Add a BackgroundTasks element to the Extension element, with its Task element set to "pushNotification".

    The complete Extension element is shown here.


<Extension Category="windows.backgroundTasks" StartPage="js\examplebackgroundtask.js">
  <BackgroundTasks>
    <Task Type="pushNotification"/>
  </BackgroundTasks>
</Extension>

3. Register your background task in your app

The following examples provide code that you will add to your app (for instance, in its Default.js file) to register your background task as a response to a raw notification.

First, determine whether the background task is already registered. This step is important. If your app doesn't check for an existing background task registration, it could register the same task more than once. This could cause performance issues and CPU usage that could prevent the task from completing.

This example iterates through the Windows.ApplicationModel.Background.BackgroundTaskRegistration.AllTasks property and sets a flag to true if the task is already registered.


var taskRegistered = false;
var exampleTaskName = "Example background task class name";

var background = Windows.ApplicationModel.Background;
var iter = background.BackgroundTaskRegistration.AllTasks.first();

while (iter.hasCurrent) {
    var task = iter.current.value;
    
    if (task.name === exampleTaskName) {
        taskRegistered = true;
        break;
    }

    iter.moveNext();
}

If your app finds that the background task is not registered, it can register it by calling the Windows.ApplicationModel.Background.BackgroundTaskBuilder.register method. In the call to this method, you include the name of the background task's .js file, in our case examplebackgroundtask.js, and a PushNotificationTrigger object.


if (taskRegistered != true) {
    var builder = new Windows.ApplicationModel.Background.BackgroundTaskBuilder();
    var trigger = new Windows.ApplicationModel.Background.PushNotificationTrigger();

    builder.name = exampleTaskName;
    builder.taskEntryPoint = "js\\ExampleBackgroundTask.js";
    builder.setTrigger(trigger);

    var task = builder.register();
}

Summary

You should now understand the basics of writing a background task class for use with raw notifications, including how to register the background task from within your app. You should also understand how to update the app manifest so that Windows allows your app to register its background tasks.

Note  You can download the background task sample to see these code examples and more, in the context of a complete and robust JavaScript app that uses several different types of background tasks.

 

Raw notifications sample

Raw notification overview

Guidelines and checklist for raw notifications

Quickstart: Intercepting push notifications for running apps

RawNotification