From 825261e0168413bd94c0308470b1566868f42872 Mon Sep 17 00:00:00 2001 From: William French Date: Fri, 11 Dec 2015 10:18:09 -0800 Subject: [PATCH] docs: Adds new topic: Change Location Settings bug: 19612879 Change-Id: If80277027917fdc6d0f462d2fa4914b6749fc98f --- .../location/change-location-settings.jd | 251 ++++++++++++++++++ docs/html/training/location/index.jd | 4 + .../location/receive-location-updates.jd | 125 +-------- .../training/location/retrieve-current.jd | 7 +- docs/html/training/training_toc.cs | 5 + 5 files changed, 272 insertions(+), 120 deletions(-) create mode 100644 docs/html/training/location/change-location-settings.jd diff --git a/docs/html/training/location/change-location-settings.jd b/docs/html/training/location/change-location-settings.jd new file mode 100644 index 0000000000000..70733eb588fbb --- /dev/null +++ b/docs/html/training/location/change-location-settings.jd @@ -0,0 +1,251 @@ +page.title=Changing Location Settings +trainingnavtop=true +@jd:body + +
+ +
+ +

If your app needs to request location or receive permission updates, the + device needs to enable the appropriate system settings, such as GPS or Wi-Fi + scanning. Rather than directly enabling services such as the device's GPS, + your app specifies the required level of accuracy/power consumption and + desired update interval, and the device automatically makes the appropriate + changes to system settings. These settings are defined by the + {@code LocationRequest} + data object.

+ +

This lesson shows you how to use the + Settings API + to check which settings are enabled, and present the Location Settings + dialog for the user to update their settings with a single tap.

+ +

Connect to Location Services

+ +

In order to use the location services provided by Google Play Services and + the fused location provider, connect your app using the + Google API Client, + then check the current location settings and prompt the user to enable the + required settings if needed. For details on connecting with the + Google API client, see Getting the Last Known Location.

+ +

Apps that use location services must request location permissions. For this + lesson, coarse location detection is sufficient. Request this permission + with the uses-permission element in your app manifest, as shown + in the following example:

+ +
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  package="com.google.android.gms.location.sample.locationupdates" >
+
+  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
+</manifest>
+
+ +

If the device is running Android 6.0 or higher, and your app's target + SDK is 23 or higher, the app has to list the permissions in the manifest + and request those permissions at run time. For more information, see +Requesting Permissions at Run Time.

+ +

Set Up a Location Request

+ +

To store parameters for requests to the fused location provider, create a + {@code LocationRequest}. + The parameters determine the level of accuracy for location requests. For + details of all available location request options, see the + {@code LocationRequest} + class reference. This lesson sets the update interval, fastest update + interval, and priority, as described below:

+ +
+
+ Update interval +
+
+ {@code setInterval()} + - This method sets the rate in milliseconds at which your app prefers to + receive location updates. Note that the location updates may be faster than + this rate if another app is receiving updates at a faster rate, or slower + than this rate, or there may be no updates at all (if the device has no + connectivity, for example). +
+
+ Fastest update interval +
+
+ {@code setFastestInterval()} + - This method sets the fastest rate in milliseconds at which + your app can handle location updates. You need to set this rate because + other apps also affect the rate at which updates are sent. The Google Play + services location APIs send out updates at the fastest rate that any app + has requested with + {@code setInterval()}. + If this rate is faster + than your app can handle, you may encounter problems with UI flicker or data + overflow. To prevent this, call + {@code setFastestInterval()} + to set an upper limit to the update rate. +
+
Priority
+
+

+ {@code setPriority()} + - This method sets the priority of the request, which gives the Google Play + services location services a strong hint about which location sources to use. + The following values are supported:

+
    +
  • + {@code PRIORITY_BALANCED_POWER_ACCURACY} + - Use this setting to request location precision to within a city + block, which is an accuracy of approximately 100 meters. This is + considered a coarse level of accuracy, and is likely to consume less + power. With this setting, the location services are likely to use WiFi + and cell tower positioning. Note, however, that the choice of location + provider depends on many other factors, such as which sources are + available.
    • +
  • + {@code PRIORITY_HIGH_ACCURACY} + - Use this setting to request the most precise location possible. With + this setting, the location services are more likely to use GPS + to determine the location.
    • +
  • {@code PRIORITY_LOW_POWER} + - Use this setting to request city-level precision, which is + an accuracy of approximately 10 kilometers. This is considered a + coarse level of accuracy, and is likely to consume less power.
    • +
  • {@code PRIORITY_NO_POWER} + - Use this setting if you need negligible impact on power consumption, + but want to receive location updates when available. With this + setting, your app does not trigger any location updates, but + receives locations triggered by other apps.
    • +
+
+
+ +

Create the location request and set the parameters as shown in this + code sample:

+ +
+protected void createLocationRequest() {
+    LocationRequest mLocationRequest = new LocationRequest();
+    mLocationRequest.setInterval(10000);
+    mLocationRequest.setFastestInterval(5000);
+    mLocationRequest.setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);
+}
+
+ +

The priority of + {@code PRIORITY_HIGH_ACCURACY}, + combined with the + {@link android.Manifest.permission#ACCESS_FINE_LOCATION ACCESS_FINE_LOCATION} + permission setting that you've defined in the app manifest, and a fast update + interval of 5000 milliseconds (5 seconds), causes the fused location + provider to return location updates that are accurate to within a few feet. + This approach is appropriate for mapping apps that display the location in + real time.

+ +

Performance hint: If your app accesses the + network or does other long-running work after receiving a location update, + adjust the fastest interval to a slower value. This adjustment prevents your + app from receiving updates it can't use. Once the long-running work is done, + set the fastest interval back to a fast value.

+ +

Get Current Location Settings

+ +

Once you have connected to Google Play services and the location services + API, you can get the current location settings of a user's device. To do + this, create a + LocationSettingsRequest.Builder, + and add one or more location requests. The following code snippet shows how + to add the location request that was created in the previous step:

+ +
LocationSettingsRequest.Builder builder = new LocationSettingsRequest.Builder()
+     .addLocationRequest(mLocationRequest);
+
+ +

Next check whether the current location settings are satisfied:

+ +
PendingResult<LocationSettingsResult> result =
+         LocationServices.SettingsApi.checkLocationSettings(mGoogleClient,
+                 builder.build());
+ +

When the PendingResult + returns, your app can check the location settings by looking at the status + code from the LocationSettingsResult + object. To get even more details about the the current state of the relevant + location settings, your app can call the + {@code LocationSettingsResult} + object's + getLocationSettingsStates() + method.

+ +

Prompt the User to Change Location Settings

+ +

To determine whether the location settings are appropriate for the location + request, check the status code from the + {@code LocationSettingsResult} + object. A status code of RESOLUTION_REQUIRED indicates that the + settings must be changed. To prompt the user for permission to modify the + location settings, call + + {@code startResolutionForResult(Activity, int)}. + This method brings up a dialog asking for the user's permission to modify + location settings. The following code snippet shows how to check the location + settings, and how to call {@code startResolutionForResult(Activity, int)}. +

+ +
result.setResultCallback(new ResultCallback<LocationSettingsResult>()) {
+     @Override
+     public void onResult(LocationSettingsResult result) {
+         final Status status = result.getStatus();
+         final LocationSettingsStates = result.getLocationSettingsStates();
+         switch (status.getStatusCode()) {
+             case LocationSettingsStatusCodes.SUCCESS:
+                 // All location settings are satisfied. The client can
+                 // initialize location requests here.
+                 ...
+                 break;
+             case LocationSettingsStatusCodes.RESOLUTION_REQUIRED:
+                 // Location settings are not satisfied, but this can be fixed
+                 // by showing the user a dialog.
+                 try {
+                     // Show the dialog by calling startResolutionForResult(),
+                     // and check the result in onActivityResult().
+                     status.startResolutionForResult(
+                         OuterClass.this,
+                         REQUEST_CHECK_SETTINGS);
+                 } catch (SendIntentException e) {
+                     // Ignore the error.
+                 }
+                 break;
+             case LocationSettingsStatusCodes.SETTINGS_CHANGE_UNAVAILABLE:
+                 // Location settings are not satisfied. However, we have no way
+                 // to fix the settings so we won't show the dialog.
+                 ...
+                 break;
+         }
+     }
+ });
+ +

The next lesson, + Receiving Location Updates, shows + you how to receive periodic location updates.

diff --git a/docs/html/training/location/index.jd b/docs/html/training/location/index.jd index 8ed207112c9cd..dd6825cf14351 100644 --- a/docs/html/training/location/index.jd +++ b/docs/html/training/location/index.jd @@ -78,6 +78,10 @@ href="https://www.youtube.com/watch?v=S8sugXgUVEI">
Learn how to retrieve the last known location of an Android device, which is usually equivalent to the user's current location. +
+ Changing Location Settings +
+ Learn how to detect and apply system settings for location features.
Receiving Location Updates diff --git a/docs/html/training/location/receive-location-updates.jd b/docs/html/training/location/receive-location-updates.jd index 208dc1799faf3..d82905f909d56 100644 --- a/docs/html/training/location/receive-location-updates.jd +++ b/docs/html/training/location/receive-location-updates.jd @@ -7,8 +7,7 @@ trainingnavtop=true

This lesson teaches you how to

    -
  1. Connect to Location Services
    2. -
  2. Set Up a Location Request
    3. +
  3. Get the Last Known Location
  4. Request Location Updates
  5. Define the Location Update Callback
  6. Stop Location Updates
    7. @@ -19,7 +18,7 @@ trainingnavtop=true
    • Setting up Google Play - Services + Services
    • Getting the Last Known Location @@ -64,16 +63,7 @@ trainingnavtop=true {@code requestLocationUpdates()} method in the fused location provider. -

      Connect to Location Services

      - -

      Location services for apps are provided through Google Play services and the - fused location provider. In order to use these services, you connect your app - using the Google API Client and then request location updates. For details on - connecting with the - {@code GoogleApiClient}, - follow the instructions in - Getting the Last Known Location, including - requesting the current location.

      +

      Get the Last Known Location

      The last known location of the device provides a handy base from which to start, ensuring that the app has a known location before starting the @@ -101,112 +91,13 @@ trainingnavtop=true </manifest> -

      Set Up a Location Request

      - -

      To store parameters for requests to the fused location provider, create a - {@code LocationRequest}. - The parameters determine the levels of accuracy requested. For details of all - the options available in the location request, see the - {@code LocationRequest} - class reference. This lesson sets the update interval, fastest update - interval, and priority, as described below:

      - -
      -
      - Update interval -
      -
      - {@code setInterval()} - - This method sets the rate in milliseconds at which your app prefers to - receive location updates. Note that the location updates may be faster than - this rate if another app is receiving updates at a faster rate, or slower - than this rate, or there may be no updates at all (if the device has no - connectivity, for example). -
      -
      - Fastest update interval -
      -
      - {@code setFastestInterval()} - - This method sets the fastest rate in milliseconds at which - your app can handle location updates. You need to set this rate because - other apps also affect the rate at which updates are sent. The Google Play - services location APIs send out updates at the fastest rate that any app - has requested with - {@code setInterval()}. - If this rate is faster - than your app can handle, you may encounter problems with UI flicker or data - overflow. To prevent this, call - {@code setFastestInterval()} - to set an upper limit to the update rate. -
      -
      Priority
      -
      -

      - {@code setPriority()} - - This method sets the priority of the request, which gives the Google Play - services location services a strong hint about which location sources to use. - The following values are supported:

      -
        -
      • - {@code PRIORITY_BALANCED_POWER_ACCURACY} - - Use this setting to request location precision to within a city - block, which is an accuracy of approximately 100 meters. This is - considered a coarse level of accuracy, and is likely to consume less - power. With this setting, the location services are likely to use WiFi - and cell tower positioning. Note, however, that the choice of location - provider depends on many other factors, such as which sources are - available.
        • -
      • - {@code PRIORITY_HIGH_ACCURACY} - - Use this setting to request the most precise location possible. With - this setting, the location services are more likely to use GPS - (Global Positioning System) to determine the location.
        • -
      • {@code PRIORITY_LOW_POWER} - - Use this setting to request city-level precision, which is - an accuracy of approximately 10 kilometers. This is considered a - coarse level of accuracy, and is likely to consume less power.
        • -
      • {@code PRIORITY_NO_POWER} - - Use this setting if you need negligible impact on power consumption, - but want to receive location updates when available. With this - setting, your app does not trigger any location updates, but - receives locations triggered by other apps.
        • -
      -
      -
      - -

      Create the location request and set the parameters as shown in this - code sample:

      - -
      -protected void createLocationRequest() {
-    LocationRequest mLocationRequest = new LocationRequest();
-    mLocationRequest.setInterval(10000);
-    mLocationRequest.setFastestInterval(5000);
-    mLocationRequest.setPriority(LocationRequest.PRIORITY_HIGH_ACCURACY);
-}
-
      - -

      The priority of - {@code PRIORITY_HIGH_ACCURACY}, - combined with the - {@link android.Manifest.permission#ACCESS_FINE_LOCATION ACCESS_FINE_LOCATION} - permission setting that you've defined in the app manifest, and a fast update - interval of 5000 milliseconds (5 seconds), causes the fused location - provider to return location updates that are accurate to within a few feet. - This approach is appropriate for mapping apps that display the location in - real time.

      - -

      Performance hint: If your app accesses the - network or does other long-running work after receiving a location update, - adjust the fastest interval to a slower value. This adjustment prevents your - app from receiving updates it can't use. Once the long-running work is done, - set the fastest interval back to a fast value.

      -

      Request Location Updates

      -

      Now that you've set up a location request containing your app's requirements - for the location updates, you can start the regular updates by calling +

      Before requesting location updates, your app must connect to location + services and make a location request. The lesson on + Changing Location Settings + shows you how to do this. Once a location request is in place you can start + the regular updates by calling {@code requestLocationUpdates()}. Do this in the {@code onConnected()} diff --git a/docs/html/training/location/retrieve-current.jd b/docs/html/training/location/retrieve-current.jd index 5bac3fa49bb2a..42a3da0adf67d 100644 --- a/docs/html/training/location/retrieve-current.jd +++ b/docs/html/training/location/retrieve-current.jd @@ -77,7 +77,7 @@ trainingnavtop=true 

       <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="com.google.android.gms.location.sample.basiclocationsample" >
-  
+
   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
 </manifest>
      @@ -158,5 +158,6 @@ public class MainActivity extends ActionBarActivity implements when the location is not available.

      The next lesson, - Receiving Location Updates, shows - you how to receive periodic location updates.

      + Changing Location Settings, shows + you how to detect the current location settings, and prompt the user to + change settings as appropriate for your app's requirements.

      diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index b16b569fbf23f..1b8990a1f1d34 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -779,6 +779,11 @@ Getting the Last Known Location
      • +
    • + + Changing Location Settings + +
    • Receiving Location Updates