Guidelines for connection usage data

  • Article

Consider the following recommendations when using Windows Runtime Network Information APIs in your connected app.

Modifying app behavior according to network cost type

Although Windows 8 automatically provides connectivity options when a device detects new networks, there is no guarantee of a seamless transition from existing connections to new networks for every operation. A Windows Store app that connects to destinations on the Web should use Network Information APIs to obtain cost information and status change events for the network on which they are sending and receiving data.

Use the NetworkCostType value indicated for each connection to modify its behavior appropriately:

Network Cost Type Recommended App Behavior

Unrestricted

  • Use the network connection freely.

Variable/Approaching Data Cap

  • Delay or schedule lower priority operations until an unrestricted network is available.
  • When streaming content to a user, such as a movie or a video, use a lower bit-rate. For example, if your app is streaming HD-Quality video, stream Standard Definition when on a metered network.
  • Use less bandwidth. For example, switching to header-only mode when receiving emails.
  • Use the network less frequently. An example solution is to reduce the frequency of any polling operations for syndicating news feeds, refreshing content for a website, or getting web notifications.
  • Allow users to explicitly choose to stream HD-Quality video, retrieve full emails, download lower priority updates, etc., rather than doing so by default.
  • Explicitly ask for user permission prior to using the network.

Unknown

  • If the network cost type is unknown, then treat it as an unrestricted network.

 

Maintaining a reliable connection to the Web

One of the most fundamental ways your app can demonstrate agility in the network space is by maintaining a consistent level of quality when interfacing with the Web. This can be done by leveraging the information provided by the connection profile and subsequent network status change notifications and by identifying available networks that meet current requirements.

All Windows Store apps should do the following to support Web connectivity:

  1. Call GetInternetConnectionProfile to check the cost of connecting to the Internet.
  2. Register for network status change notifications for the connection.
  3. Initialize the network operation on the connection.
  4. When a network status changed notification is received, the cost/connectivity options available may have changed. The app should:
    • Check the cost of connecting to the Internet. If the cost characteristic has changed from unrestricted to metered or from metered to unrestricted, retry the network operation. Windows will automatically use the lowest cost network available.
    • If the cost characteristic of connecting to the Internet has not changed, but a cost related notification is received (for example, >80% cap consumed, variable cost, roaming, etc.), adapt behavior as suggested in the NetworkCostType table above.
  5. If an error indicates that the connection went away, the app should:
    • Check the cost of connecting to the Internet via another available network. Follow the guidelines provided in the NetworkCostType table above.
    • Retry the operation; if this fails, then wait for a NetworkStatusChange notification.

Debugging and troubleshooting your connected app

Network glitches can cause applications to hang, crash, or show non-actionable dialog boxes and confusing error messages to the users. Debugging these errors can be difficult because errors can occur anywhere within the networking stack.

All Windows Store apps that use the network either directly (using sockets) or indirectly (using an API that eventually uses the network) are impacted. The ideal situation is for the operating system to handle error conditions automatically on behalf of the developer and when that does not work applications should be prepared to deal with errors.

All connected Windows Store apps need to do the following:

  • When a networking error happens, retry the operation if appropriate. For instance, do not retry the operation if authentication fails, but retry the operation if the network you were communicating on went away because another one may be available. Many errors can simply go away when retrying the operation. On retrying, follow the guidelines specified earlier in Reacting to network status changes.
  • Ensure that you use asynchronous APIs so that there is no blocking call on the UI thread. In other words, if a networking operation takes a long time to complete or there is an error, your application should not hang. Do not emulate synchronous behavior on top of the asynchronous nature of the Windows Runtime.
  • Test your application in various networking environments with activities like disconnecting or reconnecting to your network, suspending or resuming, or switching from one network to another.
  • When you are testing your application and find errors that are not immediately obvious, enable ETW tracing.

Security Considerations

The following articles provide guidance for writing secure C++ code.

Developing connected applications (Whitepaper)

Network information sample

For developers (HTML)

Connection state and cost management

For developers (XAML)

Connection state and cost management