How to set background connectivity options (HTML)

Article
08/31/2015

This topic explains the background network connectivity features available to a Windows Runtime app written in JavaScript and HTML and how to configure background connectivity options.

What you need to know

Technologies

IXMLHTTPRequest2

Enables access to Web resources using an extension to XMLHttpRequest object.
System.Net.Http

Enables connecting to web services with a modern web client.

Prerequisites

The following information applies to any connected or network-aware Windows Runtime app that depends on network connections to always be connected. This topic applies to apps written in JavaScript and HTML for Windows 8.1, Windows Phone 8.1, and Windows Server 2012 R2. For more information on background tasks that apply to JavaScript apps, see Supporting your app with background tasks.

For more information on connected or network-aware Windows Store apps written in C++/XAML and apps using the .NET Framework 4.5 in C#, VB.NET, or managed C++ on Windows 8.1 and Windows Server 2012 R2, see How to stay connected in the background.

Lifecycle model for Windows Store apps

Windows 8 and later introduces a new lifecycle model for Windows Runtime apps that differs from the model used for Windows 8 desktop apps and apps on previous version of Windows. By default, a Windows Runtime app is completely suspended from operation when the app is moved to the background. There are a few exceptions to suspending an app (actively printing, accessing an audio stream, and transferring files in the background using Windows.Networking.BackgroundTransfer, for example). For some of these exceptions (Windows.Networking.BackgroundTransfer, for example), the app may still be suspended but Windows continues the network transfer in a separate process.

This new model for Windows Runtime apps improves responsiveness for the app running in the foreground while reducing overall power used by the system. Lower power use improves the length of time that battery-powered system can operate before being recharged. In addition, this new model provides a mechanism for apps that need to work in the background (such as Voice over Internet Protocol (VoIP), instant messaging (IM), and email) to provide an always-connected experience for the end user. This means that an app that depends on a long-running network connection to a remote server can still work when the app is suspended. These are competing demands between being always connected for a real-time app and also trying to reduce power usage and increase app responsiveness.

In order to enable real-time networking scenarios for a Windows Runtime app written in JavaScript that needs to be always connected, several new features introduced in Windows 8 can be used:

Background tasks
System trigger for SessionConnected
Time triggers
Windows Push Notification Services (WNS)
Raw push notifications

These features provide support for always connected apps that need to receive raw push notifications when a Windows Runtime app is suspended. These apps are also described as being always reachable. The focus of this topic is on how a developer can use WNS and raw push notifications to build a real-time always connected app. These features require that the app also be a lock screen app.

Other background tasks features can also be used by a network app. Some other triggers available for use by a Windows Runtime app include the following:

Maintenance triggers (periodic time events for maintenance)
System triggers for users and sessions (user session connected/disconnected, user present/away, and online ID change)
System triggers for networking status (network state change, internet available/not available)
System triggers for lock screen (app add/remove)

A time trigger could be used when an app does not require real-time connectivity but needs to run for a brief time at some interval. A system trigger could be used when the app needs to be aware of events (for example, the availability of Internet connectivity or user presence). Various triggers can be combined in an app to enable a variety of scenarios. For more information, see Supporting your app with background tasks.

Most Windows Runtime apps will not need to use raw push notifications detailed in this topic. An app can give the user the impression that it is always running in the background by using a live tile, or by using a live tile with push notifications (other than raw push notifications) from WNS. Your app does not need to be a lock screen app (described later in this topic) or run in the background in order to use a live tile. However, your app must be on the lock screen to use a live tile with raw push notifications.

Requirements for always connected

Two elements are normally required for an app to be always connected and reachable:

A long-running process to ensure that any incoming network notifications are received and can be quickly processed by the app.
A long-running network connection to a remote endpoint that can receive and send data as needed.

In previous versions of Windows, apps stay running when they lose focus (in the background). These apps can maintain long-running connections when in the background since they can send and receive data and keep-alive messages. Allowing apps to run in the background consumes resources that can affect the responsiveness of other apps and battery life.

Windows Runtime apps and the lock screen

Windows 8 introduces a new software model that suspends Windows Runtime apps when they are moved to the background. Once an app is suspended, any packets received by the system may not be immediately delivered to the app and incoming network packets may be dropped. No new packets are sent when the app is suspended. As a result of these conditions, existing network connections may be closed.

To be always connected, an app needs to be a lock screen app. A lock screen app is a special type of app that can display notifications on the lock screen and run code in the background when the app is not in the foreground. Only apps that use one or more background tasks may be lock screen apps.

Lock screen apps have some special abilities:

Able to receive a raw push notification from WNS that can run code when the notification is received.
Able to run code when a time trigger occurs.
Able to run code when a user session is started.

Apps pinned to the lock screen can present information to the user when in the background by updating and displaying a badge icon on the lock screen when there is new information. These apps can also display an on-screen notification when a message arrives. If the notification is tapped or clicked, the user is asked to unlock the device. When the device is unlocked, the app corresponding to the notification is launched with context information.

There are some significant limitations placed on lock screen apps. A user can have a maximum of seven lock screen apps at any given time. A user can add or remove an app from the lock screen at any time.

Lock screen apps are great at providing information to users for things they may have missed when they were away from their device. It is also great for providing on screen notifications for events that may require immediate user action, such as an incoming phone call, incoming instant message, or urgent email.

Most apps will not need to be lock screen apps. When an app is suspended in the background it can use push notifications (other than raw push notifications) from WNS to update a live tile and give users the impression that the app is running, alive and fresh with content. Apps can also use WNS to raise a toast notification to the user at any time or to update the badge count on the app’s tile.

Because there are a limited number of lock screen app slots, you should plan to build your app in such a way that it works even without lock screen app permissions. The user must explicitly allow an app to be added to the lock screen. Your app should always work when it is visible in the foreground. Being a lock screen app simply allows your app to enable some of the same scenarios while in the background.

There is one feature that allows an app written in JavaScript and HTML to receive incoming network packets when the app is in the background

Raw push notifications that are received by the system and result in running a background task in the app. Using this feature, the app receives the raw data from Windows Push Notification Service (WNS). The contents of this data must be understood by the app. The app must register with WNS to receive the raw push notification.

Several mechanisms discussed below can be used to enable real-time scenarios for apps that are placed on the lock screen. Each has its benefits and tradeoffs. The mechanisms are not mutually exclusive and can be combined in some apps.

Using WNS in Windows Store apps

WNS is a cloud service hosted by Microsoft for Windows 8 that can be used by Windows Runtime apps to receive notifications that can run code, update a live tile, or raise an on-screen notification. In order to use WNS, the local computer must be connected to the Internet so that the WNS service can communicate with it. For more information, see Push notification overview

A Windows Runtime app in the foreground can use WNS to update live tiles, raise notifications to the user, or update badges. Apps do not need to be on the lock screen to use WNS. You should consider using WNS in your app if it must run code in response to a push notification.

For apps that do not have to be on the lock screen (most apps), WNS can be used to provide a live tile update.

If you pin your Windows Runtime app to the lock screen and use WNS in the background, the app can receive raw push notifications from WNS in real time and show them on the lock screen as either a badge update or a notification. When a raw push notification is delivered to a lock screen app, the app can run code in response to the notification. WNS use can be more power efficient than using network triggers available to Windows Store apps written in C++/XAML and apps using the .NET Framework 4.5 in C#, VB.NET, or managed C++ on Windows 8.1 and Windows Server 2012 R2.

WNS offers a number of benefits:

WNS offers the most power-efficient mechanism for delivering real-time notifications to lock screen apps.
WNS simplifies the developer model for your app. In most scenarios, developers do not have to write any background tasks, because the operating system renders the tiles or toast. In a small subset of scenarios, if your app must run a background task, it needs to register the raw push notification and the background task to run.
No persistent socket connection needs to be maintained between the client app and a remote server because Windows maintains the connection to WNS. As a result, the overhead of sending keep-alive messages is not required.
A single WNS connection between the client and the cloud service can support all apps on the local computer, which translates to potential battery life efficiency for the client.
The operational cost may be reduced for the service on the server side because there is no need to maintain many parked TCP socket connections between the client and the remote service.
Your app does not have to reside in memory at all times, because it can be terminated and still have WNS update the tile, raise a toast, or trigger a background task to run upon receipt of an incoming raw push notification.
Background tasks that use raw push notifications can be written in JavaScript, C++/XAML, and using the .NET Framework 4.5 in C#, VB.NET, or managed C++ on Windows 8.1 and Windows Server 2012 R2.

The network trigger feature using ControlChannelTrigger is not available in JavaScript.

Note ControlChannelTrigger is not supported on Windows Phone

Background networking that uses network triggers can only be written in C++/XAML, and using the .NET Framework 4.5 in C#, VB.NET, or managed C++ on Windows 8 and Windows Server 2012. For more information, see How to stay connected in the background.

WNS also has some limitations that may affect some apps. WNS is not available to a local computer that is connected to a private home or work network that blocks public Internet access. WNS can also be blocked by some network firewalls even when Internet access is available. There are some other drawbacks using WNS that may need to be considered. Specifically, notifications are delivered on a best-effort basis and there is no guarantee of delivery. The maximum size of the payload in a raw push notification is 5 kilobytes.

Given the advantages, we recommend that developers who build VoIP, IM, or email apps consider using WNS notifications for lock screen apps, but consider alternatives if they do not meet your requirements.

There is no need to build a lock screen app if you simply want to have a live tile update or raise a toast using WNS. A lock screen app is required while using WNS only when the app requires a raw push notification to trigger a background task to run.

Using time triggers or system event triggers in Windows Runtime apps

Lock screen apps can be configured to run code periodically using a time trigger with a minimum interval of 15 minutes. One example is needing to poll for new e-mail messages, possibly when an app is connected to a POP3 or IMAP email server.

Lock screen apps can also use a system event trigger to run code when the user logs on to the local computer (system trigger for session start). One example is signing in the user in to an instant message service when they start a user session, so instant messages can be received.

In this topic, we focus on building lock screen apps using raw push notifications with WNS or the network trigger feature. For more information on using a timer, see How to run a background task on a timer. For more information on background tasks, see Supporting your app with background tasks.

Background task and sandboxing

The lifetime of a background task is determined by the function that implements the background task. To ensure that background tasks do not adversely affect battery life, Windows enforces a limit in terms of CPU and network I/O resources an app can use during background tasks. Each app gets a quota of these resources on a periodic basis, and exhausting this quota suspends your app's background task. An app must be resilient to being suspended due to sandboxing.

For more information, see Supporting your app with background tasks.

Further 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 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 authenticate with the Windows Push Notification Service (WNS)

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

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