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++
This section describes several ways to ensure that your app gets the location data it needs without spending more resources than necessary.
- 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.
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.
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.
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.
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.
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.
- 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.
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.
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.
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.
This section contains guidelines that ensure that location works as users expect it to in your app.
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.
If location isn't essential to your app, don't access it until the user specifically requests it.
A social networking app has a button for "Check in with my location". This app should not access location until the user clicks the button.
If an app requires location for its main function, then it can access the device when the app starts.
An app for placing the user on a map requires location for its main purpose. It's OK for this app to use location when it starts, to show the user's location right away.
Use the main UI thread for the first use of the Geolocator object:
Provide the user with information about how your app uses location data.
Have your app provide a UI control to enable users to refresh their current location.
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.
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:
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.
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.
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.
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.
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.
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.
A user's geographic location is personally identifiable information (PII). The following website provides guidance for protecting user privacy.
- Geolocation Sample
- Guidelines for using sensitive devices
- Roadmap for creating apps using C#, C++, or VB