Guidelines for location-aware apps (Windows Runtime apps using C#/VB/C++ and XAML)

This topic describes best practices for building a location-aware app. It also lists requirements for your app to ensure a good user experience.

Roadmap: How does this topic relate to others? See:

• Roadmap for Windows Runtime apps using C# or Visual Basic
• Roadmap for Windows Runtime apps using C++

Performance guidelines

This section describes several ways to ensure that your app gets the location data it needs without spending more resources than necessary.

There are two types of location sessions

Single location requests - This type of session is used when the app needs, at a certain point in time, a one-time location update.

Continuous location requests - This type of session is used when the app needs location updates at regular intervals or to ensure a location update if the user moves by a given distance.

Use one-time location requests when updates aren't needed

Some apps need to acquire location data only once, and don't need to receive location updates. For example, an app that adds a location tag to a photo or email does not need to receive location update events. This type of app should request location by using the GetGeopositionAsync method, as described in Detecting a user's location.

When you make a one-time location request, you should set the following values.

• Specify the accuracy requested by your app by setting the DesiredAccuracy or the DesiredAccuracyInMeters. See below for recommendations on using these parameters
• Set the max age parameter of GetGeopositionAsync to specify how long ago a location can have been obtained to be useful for your app. If your app can use a position that is a few seconds or minutes old, your app can receive a position almost immediately and contribute to saving device power.
• Set the timeout parameter of GetGeopositionAsync. This is how long your app can wait for a position or an error to be returned. You will need to figure out the trade-offs between responsiveness to the user and accuracy your app needs.

Use continuous location session when frequent position updates are required

Subscribe to location events when appropriate. Use PositionChanged and StatusChanged events for detecting movement past a specific threshold or for continuous location updates as they occur.

When requesting location updates, you may want to specify the accuracy requested by your app by setting the DesiredAccuracy or the DesiredAccuracyInMeters. You should also set the frequency at which the location updates are needed, by using the MovementThreshold or the ReportInterval. See below for recommendations on using these parameters.

Adjust the movement threshold

Some apps need location updates only when the user has moved a large distance. For example, an app that provides local news or weather updates may not need location updates unless the user's location has changed to a different city. In this case, you adjust the minimum required movement for a location update event by setting the MovementThreshold property. This has the effect of filtering out PositionChanged events. These events are raised only when the change in position exceeds the movement threshold.

On Windows, when you set the MovementThreshold property, it doesn't change the frequency at which the source of the location data (such as the Windows Location Provider or an attached GPS device) calculates location. On Windows Phone the MovementThreshold property, together with other factors such as estimated speed of movement, is used to tune the frequency at which the location is calculated in the system in order to conserve device power.

Set the report interval

Use a report interval property that aligns with your app experience and that minimizes the use of system resources. For example, a weather app may require a data update only every 15 minutes.

Most apps, other than real-time navigation apps, don't require a highly accurate, constant stream of location updates. If your app doesn't require the most accurate stream of data possible, or requires updates infrequently, set the ReportInterval property to indicate the minimum frequency of location updates that your app needs. The location source can then conserve power by calculating location only when needed.

Apps that do require real-time data should set ReportInterval to 0, to indicate that no minimum interval is specified. On Windows, when the report intercal is 0, the app receives events at the frequency that the most accurate location source sends them. On Windows Phone, the app will receive updates at a rate dependent on the accuracy requested by the app.

Devices that provide location data may track the report interval requested by different apps, and provide data reports at the smallest requested interval. The app with the greatest need for accuracy thus receives the data it needs. Therefore, it's possible that the location provider will generate updates at a higher frequency than your app requested, if another app has requested more frequent updates.

Note  It isn't guaranteed that the location source will honor the request for the given report interval. Not all location provider devices track the report interval, but you should still provide it for those that do.

Set the DesiredAccuracy property

To help conserve power, set the DesiredAccuracy property to indicate to the location platform whether your app needs high-accuracy data. If no apps require high-accuracy data, the system can save power by not turning on GPS providers.

Set DesiredAccuracy to HIGH to enable the GPS to acquire data.

Apps that use location information solely for ad targeting should set DesiredAccuracy to Default and use only a single-shot call pattern to minimize power consumption.

If your app has specific needs around accuracy, you may want to use the DesiredAccuracyInMeters property instead of using DesiredAccuracy. This is particularly useful on Windows Phone, where position can usually be obtained based on cellular beacons, Wi-Fi beacons and satellites. Picking a more specific accuracy value will help the system identify the right technologies to use with the lowest power cost when providing a position.

For example:

• If your app is obtaining location for ads tuning, weather, news, etc, an accuracy of 5000 meter is generally enough.
• If you app is displaying nearby deals in the neighborhood, an accuracy of 300 meter is generally good to provide results.
• If the user is looking for recommendations to nearby restaurants, we likely want to get a position within a block, so an accuracy of 100 meters is sufficient.
• If the user is trying to share his position, the app should request an accuracy of about 10 meters.

Use the Geocoordinate.Accuracy property

Apps that have specific accuracy requirements, such as navigation apps, should use the Geocoordinate.Accuracy property to determine whether the available location data meets the app's requirements.

Consider start-up delay

The first time an app requests location data, there might be a short delay of one to two seconds while the location provider starts up. You should consider this in the design of your app's user interface. For instance, you may want to avoid blocking other tasks pending the completion of the call to GetGeopositionAsync.

Consider background behavior

If a Windows Runtime app doesn't have focus, it won't receive location update events while it's suspended in the background. If your application tracks location updates by logging them, be aware of this. When the app regains focus, it receives only new events. It does not get any updates that occurred when it was inactive.

Connected standby: Windows only. When the PC is in connected standby state, Geolocator objects can always be instantiated. However, the Geolocator object will not find any sensors to aggregate and therefore calls to GetGeopositionAsync will time out after 7 seconds, PositionChanged event listeners will never be called, and StatusChanged event listeners will be called once with the NoData status.

User experience guidelines

This section contains guidelines that ensure that location works as users expect it to in your app.

Start using the location object only when the app requires location data

The app's first access to the location object triggers the consent prompt. This occurs the first time an app calls GetGeopositionAsync or registers an event handler for the PositionChanged event. If an app's primary purpose does not require access to location data, the user can find it confusing to see a prompt for permission to use the device as soon as the app starts. Follow these guidelines for a good user experience.

Use the main UI thread for the first use of the Geolocator object:

Windows only. The first use of the Geolocator object to get location data must be made on the main UI thread, to show a consent prompt to the user. The first use of the Geolocator can be either the first call to GetGeopositionAsync or the first registration of a handler for the PositionChanged event. The consent prompt is described further in Guidelines for using sensitive devices. This means that in an app using JavaScript, the first use of the Geolocator object should not occur in an activation handler.

Tell the user how location data will be used

Provide the user with information about how your app uses location data.

Provide UI for manually refreshing location

Have your app provide a UI control to enable users to refresh their current location.

Display progress while waiting to get location data

While it is waiting to receive location data, your app should display a progress bar. For more info about using a progress control, see Quickstart: Adding progress controls.

Detecting changes in location settings

On Windows, the user can turn off location functionality by using the Settings charm or Control Panel. See Location settings for more info about the UI for changing location settings. On Windows Phone, the user can disable location in the Settings app. See Guidelines for using sensitive devices for design guidance about handling user changes in settings.

• To detect when the user disables or reenables location services:

  • Handle the StatusChanged event. The Status property of the argument to the StatusChanged event has the value Disabled if the user turns off location services.

  • Check the error codes returned from GetGeopositionAsync. If the user has disabled location services, calls to GetGeopositionAsync fail with an ACCESS_DENIED error and the LocationStatus property has the value Disabled.
• If you have an app for which location data is essential—for example, a mapping app—, be sure to do the following:
  • Handle the PositionChanged event to get updates if the user’s location changes.
  • Handle the StatusChanged event as described previously, to detect changes in location settings. For more information, see How to respond to location updates.

Note that the location API will return data as it becomes available. It may first return a location with a larger error radius and then update the location with more accurate information as it becomes available. Apps displaying the user's location would normally want to update the location as more accurate information becomes available.

Show appropriate error messages or dialogs when location services are disabled or not available

When access to location data is revoked by the user, or when data is not available to the app for other reasons, present the user with appropriate error messages. If you must notify the user that location services are turned off, follow the error guidelines described in Guidelines for using sensitive devices, and also these:

• We suggest that you use this message on Windows: "Your location services are currently turned off. Use the Settings charm to turn them back on." On Windows Phone, you can use the following message: "Location is disabled on your device. To enable location, go to Settings and select location."
• Don't let error messages interrupt the app's flow. If location data is not essential to your app, display the message as inline text. Social networking or gaming apps fall into this category.
• If location data is essential to your app's functionality, display the message as a Flyout or a dialog. Mapping and navigation apps fall into this category.
• Don't try to display the Settings charm programmatically.

See the Guidelines for using sensitive devices and the Errors section in Laying out your UI for examples of inline, dialog, and Flyout error messages.

Clear cached location data and release the Geolocator object when the user disables access to location info

Release the Geolocator object if the user turns off access to location info through the Settings charm or PC settings. The app will then receive ACCESS_DENIED results for any location API calls.

If your app saves or caches location data, clear any cached data when the user revokes access to location info.

Provide an alternate way to manually enter location info when location data is not available via location services.

Provide UI for reenabling location services

Have your app provide UI for reenabling location services—for example, a refresh button that reinstantiates the Geolocator object and tries to get location info again.

• If the user reenables location access after disabling it, there is no notification to the app. The Status property does not change and there is no StatusChanged event. Your app should create a new Geolocator object and call GetGeopositionAsync to try to get updated location data, or subscribe again to PositionChanged events. If the status then indicates that location has been reenabled, clear any UI by which your app previously notified the user that location services were disabled, and respond appropriately to the new status.
• Your app should also try again to get location data upon activation, or when the user explicitly tries to use functionality that requires location info, or at any other scenario-appropriate time.

Guidelines for graphical representation of location

Have your app use the accuracy parameter that you receive through the location API to denote the user’s current location on the map clearly. There are three main bands for accuracy—an error radius of approximately 10 meters, an error radius of approximately 100 meters, and an error radius of greater than 1 kilometer. By using the accuracy information, you can ensure that your app displays location accurately in the context of the data available.

• For accuracy approximately equal to 10 meters (GPS resolution), location can be denoted by a dot or pin on the map. With this accuracy, latitude-longitude coordinates and street address can be shown as well.

  

• For accuracy between 10 and 500 meters (approximately 100 meters), location is generally received through Wi-Fi resolution. Location obtained from cellular has an accuracy of around 300 meters. In such a case, we recommend that your app show an error radius. For apps that show directions where a centering dot is required, such a dot can be shown with an error radius surrounding it.

  

• If the accuracy returned is greater than 1 kilometer, you are probably receiving location info at IP-level resolution. This level of accuracy is often too low to pinpoint a particular spot on a map. Your app should refrain from showing any geographic representation of a pin or circle and instead just zoom in to the city level on the map, or to the appropriate area based on the error radius (for example, region level).

  

When location accuracy switches from one band of accuracy to another, provide a graceful transition between the different graphical representations. This can be done by:

• Making the transition animation smooth and keeping the transition fast and fluid.
• Waiting for a few consecutive reports to confirm the change in accuracy, to help prevent unwanted and too-frequent zooms.

Guidelines for textual representation of location

Some types of apps—for example, a weather app or a local information app—need ways to represent location textually at the different bands of accuracy. Be sure to display the location clearly and only down to the level of accuracy provided in the data.

• For accuracy approximately equal to 10 meters (GPS resolution), the location data received is fairly accurate and so can be communicated to the level of the neighborhood name. City name, state or province name, and country/region name can also be used.
• For accuracy approximately equal to 100 meters (Wi-Fi resolution), the location data received is moderately accurate and so we recommend that you display information down to the city name. Avoid using the neighborhood name.
• For accuracy greater than 1 kilometer (IP resolution), display only the state or province, or country/region name.

Privacy considerations

A user's geographic location is personally identifiable information (PII). The following website provides guidance for protecting user privacy.

• Microsoft Privacy

Related topics

Geolocation Sample

Windows.Devices.Geolocation

Guidelines for using sensitive devices

Roadmap for creating apps using C#, C++, or VB