Supporting your app with background tasks (HTML)
[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]
The topics in this section show how to run your own lightweight code in the background by responding to triggers with background tasks. Background tasks are separate JavaScript files that the OS runs in the background. You can use background tasks to provide functionality when your app is suspended or not running. In JavaScript, you can also run background tasks on a timer.
Background tasks use the Windows.UI.WebUI.WebUIBackgroundTaskInstance namespace to get information about the current instance of the background task. You register background tasks by using a BackgroundTaskBuilder object. The background task JavaScript file is specified as the entry point while registering the background task.
To get started quickly with a background task, see Quickstart: Create and register a background task.
Background tasks for system events
Your app can respond to system-generated events by registering a background task with the SystemTrigger. An app can use any of the following system event triggers (defined in SystemTriggerType) without being placed on the lock screen.
| Trigger name | Description |
|---|---|
InternetAvailable |
The Internet becomes available. |
NetworkStateChange |
A network change such as a change in cost or connectivity occurs. |
OnlineIdConnectedStateChange |
Online ID associated with the account changes. |
SmsReceived |
A new SMS message is received by an installed mobile broadband device. |
TimeZoneChange |
The time zone changes on the device (for example, when the system adjusts the clock for daylight saving time). |
For more info see How to respond to system events with background tasks.
Conditions for background tasks
You can control when the background task runs, even after it is triggered, by adding a condition. Once triggered, a background task will not run until all of its conditions are met. The following conditions (represented by the SystemConditionType enumeration) can be used.
| Condition name | Description |
|---|---|
| InternetAvailable | The Internet must be available. |
| InternetNotAvailable | The Internet must be unavailable. |
| SessionConnected | The session must be connected. |
| SessionDisconnected | The session must be disconnected. |
For more info see How to set conditions for running a background task.
Application manifest requirements
Before your app can successfully register a background task, it must be declared in the application manifest. For more info see How to declare background tasks in the application manifest.
Background tasks for lock screen-capable apps
Apps can be placed on the lock screen to show real-time information to the user at a glance. The following real-time triggers can be used to run lightweight custom code in the background for apps that are on the lock screen:
Control Channel: Background tasks can keep a connection alive, and receive messages on the control channel, by using the ControlChannelTrigger. For more info see How to use the control channel trigger. (Note that control channel background tasks can only be implemented in C# or C++.) The ControlChannelTrigger is not supported on Windows Phone.
Timer: Background tasks can run as frequently as every 15 minutes, and they can be set to run at a certain time, by using the TimeTrigger. For more info see How to run a background task on a timer.
Push Notification: Background tasks respond to the PushNotificationTrigger to receive raw push notifications. For more info see How to receive raw notifications.
Note Windows Store apps only. The user must place your app on the lock screen before the app can use these background tasks. An app can request lock screen access by calling RequestAccessAsync. This presents a dialog box asking the user to "allow" or "don't allow" your app on the lock screen. An app is only allowed to ask for lock screen access once; any subsequent calls to RequestAccessAsync are ignored.
Note
Windows Phone Store apps can use all of the supported background triggers without being pinned to the lock screen. However, a phone app must call RequestAccessAsync before registering any of the background trigger types.
To ensure that your Windows Phone app continues to run properly after you release an update, you must call RemoveAccess and then call RequestAccessAsync when your app launches after being updated. For more information, see Guidelines for background tasks (Windows Runtime apps).
System event triggers for lock screen-capable apps
Note The SystemTriggerType enumeration includes the following system event triggers that are only usable by lock screen-capable apps. An app must be placed on the lock screen before it can register a background task with any of these system event triggers.
| Trigger name | Description |
|---|---|
UserPresent |
The background task is triggered when the user becomes present. |
UserAway |
The background task is triggered when the user becomes absent. |
ControlChannelReset |
The background task is triggered when a control channel is reset. |
SessionConnected |
The background task is triggered when the session is connected. |
The following system event triggers are also for lock screen-capable apps. These triggers can be registered even when the app is not on the lock screen, making it possible to recognize when the user has moved the app on or off the lock screen.
| Trigger name | Description |
|---|---|
LockScreenApplicationAdded |
An app tile is added to the lock screen. |
LockScreenApplicationRemoved |
An app tile is removed from the lock screen. |
Background task resource constraints
Background tasks are lightweight. Keeping background execution to a minimum ensures the best user experience with foreground apps and battery life. This is enforced by applying resource constraints to background tasks:
CPU usage is limited as follows.
CPU usage quota Refresh time Windows App not on lock screen 1 second
2 hours
WindowsApp on the lock screen 2 seconds
15 minutes
Windows Phone App 2 seconds
15 minutes
When running on battery (DC power), background tasks also have a network data usage limit. This limit is a function of the amount of energy used by the network interface, so it varies depending on the device and network environment - but it can be estimated.
The following table characterizes network data throughput, assuming a resource constrained WiFi network capable of 1Mbps of average data throughput. To estimate the correct limit, multiply by the average megabits per second (Mbps) of the connection. For example, an app can use 25 MB of data every 2 hours on a 10Mbps WiFi connection if it's placed on the lock screen. The example WiFi interface assumes minimal interference.
Refresh period 15 minutes 2 hours Daily Data limit (on lock screen) 0.469 MB n/a 45 MB Data limit (not on lock screen) n/a 0.625 MB 7.5 MB Note The network data usage limit is lifted when the device is plugged in (AC power), but the CPU usage quota still applies. Similarly, the CPU and network resource constraints are suspended for an app's background tasks while the user is interacting with it in the foreground.
Additional background task resource constraints for Windows Phone Store apps
In addition to the resource constraints described in the previous section, background tasks for Windows Phone Store apps also have the following constraints.
Memory constraints
Due to the resource constraints for the phone form factor, especially for low-memory devices, background tasks for Windows Phone apps have a memory limit that determines the maximum amount of memory the background task can use. If your background task exceeds this limit, it will be terminated immediately. The memory allocation depends on the type of background task as well as the total system memory of the device on which it's running. You should consider these limits while developing and testing your app. You can also use the MemoryManager APIs to query your current memory usage and limit in order to adjust your usage at runtime. The following table lists the memory caps, in megabytes, for the specified background task types for different amounts of total system memory on the device.
| Background task type | 512 MB | 1 GB | 2 GB or greater |
|---|---|---|---|
| Location | 16 | 30 | 40 |
| Bluetooth | 16 | 16 | 16 |
| Servicing Complete | 10 | 10 | 10 |
| Other background tasks | 16 | 30 | 40 |
| Limit while debugging | 30 | 40 | 50 |
Per-device limit for apps with background tasks for low-memory devices
On phones with 512 MB of memory, there is a limit to the number of apps that can be installed on a device and use background tasks at any given time. If this number is exceeded, the call to RequestAccessAsync, which is required to register all background tasks on Windows Phone, will fail.
Battery Saver
On Windows Phone, the Battery Saver feature, when enabled, will prevent background tasks from running when the device is not connected to external power and the battery goes below a specified amount of power remaining. This will not prevent you from registering background tasks.
Maintenance trigger
Your app can also run tasks as frequently as every 15 minutes by using the maintenance trigger. Instead of requiring placement on the lock screen, maintenance tasks only run when the device is plugged in to AC power. For more info see How to use maintenance triggers.
Background task for sensors and devices
Your app can access sensors and peripheral devices from a background task with the DeviceUseTrigger class. You can use this trigger for long-running operations such as data synchronization or monitoring. Unlike tasks for system events, a DeviceUseTrigger task can only be triggered while your app is running in the foreground and no conditions can be set on it. Depending where it's running (PC or phone), a DeviceUseTrigger background task supports different APIs, and is subject to different policies. To learn more about these differences, see Accessing sensors and devices from a background task.
Some critical device operations, such as long running firmware updates, cannot be performed with the DeviceUseTrigger. Such operations can be performed only on the PC, and only by a privileged app that uses the DeviceServicingTrigger. A privileged app is an app that the device's manufacturer has authorized to perform those operations. Device metadata is used to specify which app, if any, has been designated as the privileged app for a device. For more info, see Device sync and update for Windows Store device apps.
Managing background tasks
Background tasks can report progress, completion, and cancellation to your app using events and local storage. Your app can also catch exceptions thrown by a background task, and manage background task registration during app updates. For more info see:
How to handle a cancelled background task
How to get a list of pending background tasks
How to monitor background task progress and completion
How to use the ServicingComplete trigger
Related topics
Conceptual guidance for multitasking in Windows 8
Introduction to Background Tasks
Launching, resuming, and multitasking
UI guidance for the lock screen
Displaying tiles on the lock screen
Guidelines and checklist for lock screen tiles
Related background task guidance
Guidelines and checklist for background tasks
How to debug a background task
How to trigger suspend, resume, and background events in Windows Store apps (when debugging)