diff options
author | Quddus Chong <quddusc@google.com> | 2015-05-26 14:21:05 -0700 |
---|---|---|
committer | Quddus Chong <quddusc@google.com> | 2015-05-26 14:52:08 -0700 |
commit | 4b927284a62a89fdd37d1f832b022f2a7feab136 (patch) | |
tree | 4c3dd368e883a5de8dbaeca933c9e60a0785f874 /docs/html/google | |
parent | c03c11e584abf1e61a902ea441818912f912fda7 (diff) | |
download | frameworks_base-4b927284a62a89fdd37d1f832b022f2a7feab136.zip frameworks_base-4b927284a62a89fdd37d1f832b022f2a7feab136.tar.gz frameworks_base-4b927284a62a89fdd37d1f832b022f2a7feab136.tar.bz2 |
docs: Remove Google Play Services pages under Develop > Google Services.
bug: 21407467
Change-Id: I392075b58bebc5556f306c2d20987811efe90b13
Diffstat (limited to 'docs/html/google')
-rw-r--r-- | docs/html/google/auth/api-client.jd | 654 | ||||
-rw-r--r-- | docs/html/google/auth/http-auth.jd | 558 | ||||
-rw-r--r-- | docs/html/google/play-services/auth.jd | 239 | ||||
-rw-r--r-- | docs/html/google/play-services/index.jd | 706 | ||||
-rw-r--r-- | docs/html/google/play-services/setup.jd | 398 |
5 files changed, 0 insertions, 2555 deletions
diff --git a/docs/html/google/auth/api-client.jd b/docs/html/google/auth/api-client.jd deleted file mode 100644 index 8f926f5..0000000 --- a/docs/html/google/auth/api-client.jd +++ /dev/null @@ -1,654 +0,0 @@ -page.title=Accessing Google APIs -page.tags="oauth 2.0","GoogleAuthUtil" - -trainingnavtop=true -startpage=true - -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - -<h2>In this document</h2> -<ol> - <li><a href="#Starting">Start a Connection</a> - <ol> - <li><a href="#HandlingFailures">Handle connection failures</a></li> - <li><a href="#MaintainingState">Maintain state while resolving an error</a></li> - <li><a href="#WearableApi">Access the Wearable API</a></li> - </ol> - </li> - <li><a href="#Communicating">Communicate with Google Services</a> - <ol> - <li><a href="#Async">Using asynchronous calls</a></li> - <li><a href="#Sync">Using synchronous calls</a></li> - </ol> - </li> -</ol> -</div> -</div> - - -<p>When you want to make a connection to one of the Google APIs provided in the Google Play services -library (such as Google+, Games, or Drive), you need to create an instance of <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code -GoogleApiClient}</a> ("Google API Client"). The Google API Client provides a common entry point to all -the Google Play services and manages the network connection between the user's device and each -Google service.</p> - -<div class="sidebox" style="clear:right;width:190px"> -<h2>Connecting to REST APIs</h2> -<p>If the Google API you want to use is not included in the Google Play services library, you can -connect using the appropriate REST API, but you must obtain an OAuth 2.0 token. For more -information, read <a href="{@docRoot}google/auth/http-auth.html">Authorizing with Google -for REST APIs</a>.</p> -</div> - -<p>This guide shows how you can use Google API Client to:</p> -<ul> -<li>Connect to one or more Google Play services asynchronously and handle failures.</li> -<li>Perform synchronous and asynchronous API calls to any of the Google Play services.</li> -</ul> - -<p class="note"> -<strong>Note:</strong> If you have an existing app that connects to Google Play services with a -subclass of {@code GooglePlayServicesClient}, you should migrate to <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code -GoogleApiClient}</a> as soon as possible.</p> - - -<img src="{@docRoot}images/google/GoogleApiClient@2x.png" width="464px" alt="" /> -<p class="img-caption"> -<strong>Figure 1.</strong> An illustration showing how the Google API Client provides an -interface for connecting and making calls to any of the available Google Play services such as -Google Play Games and Google Drive.</p> - - - -<p>To get started, you must first install the Google Play services library (revision 15 or higher) for -your Android SDK. If you haven't done so already, follow the instructions in <a -href="{@docRoot}google/play-services/setup.html">Set Up Google -Play Services SDK</a>.</p> - - - - -<h2 id="Starting">Start a Connection</h2> - -<p>Once your project is linked to the Google Play services library, create an instance of <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code -GoogleApiClient}</a> using the <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.Builder.html">{@code -GoogleApiClient.Builder}</a> APIs in your activity's {@link -android.app.Activity#onCreate onCreate()} method. The <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.Builder.html">{@code -GoogleApiClient.Builder}</a> class -provides methods that allow you to specify the Google APIs you want to use and your desired OAuth -2.0 scopes. For example, here's a <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code -GoogleApiClient}</a> instance that connects with the Google -Drive service:</p> -<pre> -GoogleApiClient mGoogleApiClient = new GoogleApiClient.Builder(this) - .addApi(Drive.API) - .addScope(Drive.SCOPE_FILE) - .build(); -</pre> - -<p>You can add multiple APIs and multiple scopes to the same <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code -GoogleApiClient}</a> by appending -additional calls to -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.Builder.html#addApi(com.google.android.gms.common.api.Api<? extends com.google.android.gms.common.api.Api.ApiOptions.NotRequiredOptions>)" ->{@code addApi()}</a> and -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.Builder.html#addScope(com.google.android.gms.common.api.Scope)" ->{@code addScope()}</a>.</p> - -<p class="caution"> -<strong>Important:</strong> If you are adding multiple APIs to a -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html"><code>GoogleApiClient</code></a>, -you may run into client connection errors on devices that do not have the -<a href="https://play.google.com/store/apps/details?id=com.google.android.wearable.app&hl=en">Android -Wear app</a> installed. To avoid connection errors, call the -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.Builder.html#addApiIfAvailable(com.google.android.gms.common.api.Api<? extends com.google.android.gms.common.api.Api.ApiOptions.NotRequiredOptions>, com.google.android.gms.common.api.Scope...)">{@code addApiIfAvailable()}</a> -method and pass in the <a -href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code -Wearable}</a> API to indicate that your client should gracefully handle the missing API. -For more information, see <a -href="{@docRoot}google/auth/api-client.html#WearableApi">Access the Wearable API</a>.</p> - -<p>Before you can begin a connection by calling <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html#connect()" ->{@code connect()}</a> on the <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code -GoogleApiClient}</a>, you must specify an implementation for the callback interfaces, <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.ConnectionCallbacks.html" ->{@code ConnectionCallbacks}</a> and <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.OnConnectionFailedListener.html" ->{@code OnConnectionFailedListener}</a>. These interfaces receive callbacks in -response to the asynchronous <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html#connect()" ->{@code connect()}</a> method when the connection to Google Play services -succeeds, fails, or becomes suspended.</p> - -<p>For example, here's an activity that implements the callback interfaces and adds them to the Google -API Client:</p> - -<pre> -import com.google.android.gms.common.api.GoogleApiClient; -import com.google.android.gms.common.api.GoogleApiClient.ConnectionCallbacks; -import com.google.android.gms.common.api.GoogleApiClient.OnConnectionFailedListener; -import gms.drive.*; -import android.support.v4.app.FragmentActivity; - -public class MyActivity extends FragmentActivity - implements ConnectionCallbacks, OnConnectionFailedListener { - private GoogleApiClient mGoogleApiClient; - - @Override - protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - - // Create a GoogleApiClient instance - mGoogleApiClient = new GoogleApiClient.Builder(this) - .addApi(Drive.API) - .addScope(Drive.SCOPE_FILE) - .addConnectionCallbacks(this) - .addOnConnectionFailedListener(this) - .build(); - ... - } - - @Override - public void onConnected(Bundle connectionHint) { - // Connected to Google Play services! - // The good stuff goes here. - } - - @Override - public void onConnectionSuspended(int cause) { - // The connection has been interrupted. - // Disable any UI components that depend on Google APIs - // until onConnected() is called. - } - - @Override - public void onConnectionFailed(ConnectionResult result) { - // This callback is important for handling errors that - // may occur while attempting to connect with Google. - // - // More about this in the next section. - ... - } -} -</pre> - -<p>With the callback interfaces defined, you're ready to call <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html#connect()" ->{@code connect()}</a>. To gracefully manage -the lifecycle of the connection, you should call <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html#connect()" ->{@code connect()}</a> during the activity's {@link -android.app.Activity#onStart onStart()} (unless you want to connect later), then call <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html#disconnect()" ->{@code disconnect()}</a> during the {@link android.app.Activity#onStop onStop()} method. For example:</p> -<pre> - @Override - protected void onStart() { - super.onStart(); - if (!mResolvingError) { // more about this later - mGoogleApiClient.connect(); - } - } - - @Override - protected void onStop() { - mGoogleApiClient.disconnect(); - super.onStop(); - } -</pre> - -<p>However, if you run this code, there's a good chance it will fail and your app will receive a call -to <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.OnConnectionFailedListener.html#onConnectionFailed(com.google.android.gms.common.ConnectionResult)" ->{@code onConnectionFailed()}</a> with the <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SIGN_IN_REQUIRED" ->{@code SIGN_IN_REQUIRED}</a> error because the user account -has not been specified. The next section shows how to handle this error and others.</p> - - -<h3 id="HandlingFailures">Handle connection failures</h3> - -<p>When you receive a call to the -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.OnConnectionFailedListener.html#onConnectionFailed(com.google.android.gms.common.ConnectionResult)"> -{@code onConnectionFailed()}</a> callback, you should call <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#hasResolution()" ->{@code hasResolution()}</a> on the provided <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html" ->{@code ConnectionResult}</a> object. If it returns true, you can -request the user take immediate action to resolve the error by calling <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#startResolutionForResult(android.app.Activity, int)">{@code startResolutionForResult()}</a> on the <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html" ->{@code ConnectionResult}</a> object. The <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#startResolutionForResult(android.app.Activity, int)" ->{@code startResolutionForResult()}</a> behaves the same as {@link -android.app.Activity#startActivityForResult startActivityForResult()} and launches the -appropriate activity for the user -to resolve the error (such as an activity to select an account).</p> - -<p>If <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#hasResolution()" ->{@code hasResolution()}</a> returns false, you should instead call <a -href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#getErrorDialog(int, android.app.Activity, int)" ->{@code GooglePlayServicesUtil.getErrorDialog()}</a>, passing it the error code. This returns a {@link -android.app.Dialog} provided by Google Play services that's appropriate for the given error. The -dialog may simply provide a message explaining the error, but it may also provide an action to -launch an activity that can resolve the error (such as when the user needs to install a newer -version of Google Play services).</p> - -<p>For example, your -<a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.OnConnectionFailedListener.html#onConnectionFailed(com.google.android.gms.common.ConnectionResult)" ->{@code onConnectionFailed()}</a> callback method should now look like this:</p> - -<pre> -public class MyActivity extends FragmentActivity - implements ConnectionCallbacks, OnConnectionFailedListener { - - // Request code to use when launching the resolution activity - private static final int REQUEST_RESOLVE_ERROR = 1001; - // Unique tag for the error dialog fragment - private static final String DIALOG_ERROR = "dialog_error"; - // Bool to track whether the app is already resolving an error - private boolean mResolvingError = false; - - ... - - @Override - public void onConnectionFailed(ConnectionResult result) { - if (mResolvingError) { - // Already attempting to resolve an error. - return; - } else if (result.hasResolution()) { - try { - mResolvingError = true; - result.startResolutionForResult(this, REQUEST_RESOLVE_ERROR); - } catch (SendIntentException e) { - // There was an error with the resolution intent. Try again. - mGoogleApiClient.connect(); - } - } else { - // Show dialog using GooglePlayServicesUtil.getErrorDialog() - showErrorDialog(result.getErrorCode()); - mResolvingError = true; - } - } - - // The rest of this code is all about building the error dialog - - /* Creates a dialog for an error message */ - private void showErrorDialog(int errorCode) { - // Create a fragment for the error dialog - ErrorDialogFragment dialogFragment = new ErrorDialogFragment(); - // Pass the error that should be displayed - Bundle args = new Bundle(); - args.putInt(DIALOG_ERROR, errorCode); - dialogFragment.setArguments(args); - dialogFragment.show(getSupportFragmentManager(), "errordialog"); - } - - /* Called from ErrorDialogFragment when the dialog is dismissed. */ - public void onDialogDismissed() { - mResolvingError = false; - } - - /* A fragment to display an error dialog */ - public static class ErrorDialogFragment extends DialogFragment { - public ErrorDialogFragment() { } - - @Override - public Dialog onCreateDialog(Bundle savedInstanceState) { - // Get the error code and retrieve the appropriate dialog - int errorCode = this.getArguments().getInt(DIALOG_ERROR); - return GooglePlayServicesUtil.getErrorDialog(errorCode, - this.getActivity(), REQUEST_RESOLVE_ERROR); - } - - @Override - public void onDismiss(DialogInterface dialog) { - ((MainActivity)getActivity()).onDialogDismissed(); - } - } -} -</pre> - -<p>Once the user completes the resolution provided by <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#startResolutionForResult(android.app.Activity, int)" ->{@code startResolutionForResult()}</a> or <a -href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#getErrorDialog(int, android.app.Activity, int)" ->{@code GooglePlayServicesUtil.getErrorDialog()}</a>, your activity receives the {@link -android.app.Activity#onActivityResult onActivityResult()} callback with the {@link -android.app.Activity#RESULT_OK} -result code. You can then call <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html#connect()" ->{@code connect()}</a> again. For example:</p> - -<pre> -@Override -protected void onActivityResult(int requestCode, int resultCode, Intent data) { - if (requestCode == REQUEST_RESOLVE_ERROR) { - mResolvingError = false; - if (resultCode == RESULT_OK) { - // Make sure the app is not already connected or attempting to connect - if (!mGoogleApiClient.isConnecting() && - !mGoogleApiClient.isConnected()) { - mGoogleApiClient.connect(); - } - } - } -} -</pre> - -<p>In the above code, you probably noticed the boolean, {@code mResolvingError}. This keeps track of -the app state while the user is resolving the error to avoid repetitive attempts to resolve the -same error. For instance, while the account picker dialog is showing to resolve the <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SIGN_IN_REQUIRED" ->{@code SIGN_IN_REQUIRED}</a> error, the user may rotate the screen. This recreates your activity and causes -your {@link android.app.Activity#onStart onStart()} method to be called again, which then calls <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html#connect()" ->{@code connect()}</a> again. This results in another call to <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#startResolutionForResult(android.app.Activity, int)" ->{@code startResolutionForResult()}</a>, which -creates another account picker dialog in front of the existing one.</p> - -<p>This boolean is effective only -if retained across activity instances, though. The next section explains further.</p> - - - -<h3 id="MaintainingState">Maintain state while resolving an error</h3> - -<p>To avoid executing the code in -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.OnConnectionFailedListener.html#onConnectionFailed(com.google.android.gms.common.ConnectionResult)"> -{@code onConnectionFailed()}</a> while a previous attempt to resolve an -error is ongoing, you need to retain a boolean that tracks whether your app is already attempting -to resolve an error.</p> - -<p>As shown in the code above, you should set a boolean to {@code true} each time you call <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#startResolutionForResult(android.app.Activity, int)" ->{@code startResolutionForResult()}</a> or display the dialog from <a -href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#getErrorDialog(int, android.app.Activity, int)" ->{@code GooglePlayServicesUtil.getErrorDialog()}</a>. Then when you -receive {@link android.app.Activity#RESULT_OK} in the {@link android.app.Activity#onActivityResult -onActivityResult()} callback, set the boolean to {@code false}.</p> - -<p>To keep track of the boolean across activity restarts (such as when the user rotates the screen), -save the boolean in the activity's saved instance data using {@link -android.app.Activity#onSaveInstanceState onSaveInstanceState()}:</p> - -<pre> -private static final String STATE_RESOLVING_ERROR = "resolving_error"; - -@Override -protected void onSaveInstanceState(Bundle outState) { - super.onSaveInstanceState(outState); - outState.putBoolean(STATE_RESOLVING_ERROR, mResolvingError); -} -</pre> - -<p>Then recover the saved state during {@link android.app.Activity#onCreate onCreate()}:</p> - -<pre> -@Override -protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - - ... - mResolvingError = savedInstanceState != null - && savedInstanceState.getBoolean(STATE_RESOLVING_ERROR, false); -} -</pre> - -<p>Now you're ready to safely run your app and connect to Google Play services. -How you can perform read and write requests to any of the Google Play services -using <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code -GoogleApiClient}</a> is discussed in the next section.</p> - -<p>For more information about each services's APIs available once you're connected, -consult the corresponding documentation, such as for -<a href="{@docRoot}google/play-services/games.html">Google Play Games</a> or -<a href="{@docRoot}google/play-services/drive.html">Google Drive</a>. -</p> - - -<h3 id="WearableApi">Access the Wearable API</h3> - -<p>The Wearable API provides a communication channel for your handheld and wearable apps. The API -consists of a set of data objects that the system can send and synchronize over the wire and -listeners that notify your apps of important events with the data layer. The -<a href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code Wearable}</a> -API is available on devices running Android 4.3 (API level 18) or higher when a wearable device is -connected. The API is not available under the following conditions: -</p> - -<ul> -<li>Devices running Android 4.2 (API level 17) or earlier.</li> -<li><a href="https://play.google.com/store/apps/details?id=com.google.android.wearable.app&hl=en">Android -Wear companion app</a> is not installed on the device.</li> -<li>Android Wear device is not connected.</li> -</ul> - -<h4 id="OnlyWearableApi">Using only the Wearable API</h4> - -<p>If your app uses the -<a href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code Wearable}</a> -API but not other Google APIs, you can add this API by calling the -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.Builder.html#addApi(com.google.android.gms.common.api.Api<? extends com.google.android.gms.common.api.Api.ApiOptions.NotRequiredOptions>)" ->{@code addApi()}</a> method. The following example shows how to add the -<a href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code Wearable}</a> -API to your <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code -GoogleApiClient}</a> instance:</p> - -<pre> -GoogleApiClient mGoogleApiClient = new GoogleApiClient.Builder(this) - .addApi(Wearable.API) - .build(); -</pre> - -<p>In situations where the -<a href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code Wearable}</a> -API is not available, connection requests that include the <a -href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code -Wearable}</a> API fail with the <a -href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#API_UNAVAILABLE"> -<code>API_UNAVAILABLE</code></a> error code.</p> - -<p> -The following example shows how to determine whether the -<a href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code Wearable}</a> -API is available: -</p> - -<pre> -// Connection failed listener method for a client that only -// requests access to the Wearable API -@Override -public void onConnectionFailed(ConnectionResult result) { - if (result.getErrorCode() == ConnectionResult.API_UNAVAILABLE) { - // The Wearable API is unavailable - } - ... -} -</pre> - - -<h4 id="WearableApiWithOthers">Using the Wearable API with other APIs</h4> - -<p> -If your app uses the -<a href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code Wearable}</a> -API in addition to other Google APIs, call the -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.Builder.html#addApiIfAvailable(com.google.android.gms.common.api.Api<? extends com.google.android.gms.common.api.Api.ApiOptions.NotRequiredOptions>, com.google.android.gms.common.api.Scope...)">addApiIfAvailable()</a> -method and pass in the -<a href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code Wearable}</a> -API to indicate that your client should gracefully handle the missing API.</p> - -<p>The following example shows how to access the -<a href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code Wearable}</a> -API along with the -<a href="{@docRoot}reference/com/google/android/gms/drive/DriveApi.html">{@code Drive}</a> -API:</p> - -<pre> -// Create a GoogleApiClient instance -mGoogleApiClient = new GoogleApiClient.Builder(this) - .addApi(Drive.API) - .addApiIfAvailable(Wearable.API) - .addScope(Drive.SCOPE_FILE) - .addConnectionCallbacks(this) - .addOnConnectionFailedListener(this) - .build(); -</pre> - -<p>In the example above, the -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code GoogleApiClient}</a> -can successfully connect with the Google Drive service without connecting to the -<a href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code Wearable}</a> -API if it is unavailable. After you connect your -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code GoogleApiClient}</a> -instance, ensure that the -<a href="{@docRoot}reference/com/google/android/gms/wearable/Wearable.html">{@code Wearable}</a> -API is available before making the API calls: -</p> - -<pre> -mGoogleApiClient.hasConnectedApi(Wearable.API); -</pre> - - -<h2 id="Communicating">Communicate with Google Services</h2> - -<p>Once connected, your client can make read and write calls using the service-specific APIs for which -your app is authorized, as specified by the APIs and scopes you added to your <a -href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code -GoogleApiClient}</a> instance.</p> - -<p class="note"> -<strong>Note:</strong> Before making calls to specific Google services, you may first need to -register your app in the Google Developer Console. For specific instructions, refer to the -appropriate getting started guide for the API you're using, such as <a href= -"https://developers.google.com/drive/android/get-started">Google Drive</a> or <a href= -"https://developers.google.com/+/mobile/android/getting-started">Google+</a>.</p> - -<p>When you perform a read or write request using Google API Client, the immediate result is returned -as a <a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html">{@code -PendingResult}</a> object. This is an object representing the request, which hasn't yet -been delivered to the Google service.</p> - -<p>For example, here's a request to read a file from Google Drive that provides a -<a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html">{@code -PendingResult}</a> object:</p> - -<pre> -Query query = new Query.Builder() - .addFilter(Filters.eq(SearchableField.TITLE, filename)); -PendingResult result = Drive.DriveApi.query(mGoogleApiClient, query); -</pre> - -<p>Once you have the -<a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html">{@code -PendingResult}</a>, you can continue by making the request either asynchronous -or synchronous.</p> - - -<h3 id="Async">Using asynchronous calls</h3> - -<p>To make the request asynchronous, call <a -href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html#setResultCallback(com.google.android.gms.common.api.ResultCallback<R>)" ->{@code setResultCallback()}</a> on the -<a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html">{@code -PendingResult}</a> and -provide an implementation of the <a -href="{@docRoot}reference/com/google/android/gms/common/api/ResultCallback.html" ->{@code ResultCallback}</a> interface. For example, here's the request -executed asynchronously:</p> - -<pre> -private void loadFile(String filename) { - // Create a query for a specific filename in Drive. - Query query = new Query.Builder() - .addFilter(Filters.eq(SearchableField.TITLE, filename)) - .build(); - // Invoke the query asynchronously with a callback method - Drive.DriveApi.query(mGoogleApiClient, query) - .setResultCallback(new ResultCallback<DriveApi.MetadataBufferResult>() { - @Override - public void onResult(DriveApi.MetadataBufferResult result) { - // Success! Handle the query result. - ... - } - }); -} -</pre> - -<p>When your app receives a <a -href="{@docRoot}reference/com/google/android/gms/common/api/Result.html">{@code Result}</a> -object in the <a -href="{@docRoot}reference/com/google/android/gms/common/api/ResultCallback.html#onResult(R)" ->{@code onResult()}</a> callback, it is delivered as an instance of the -appropriate subclass as specified by the API you're using, such as <a -href="{@docRoot}reference/com/google/android/gms/drive/DriveApi.MetadataBufferResult.html" ->{@code DriveApi.MetadataBufferResult}</a>.</p> - - -<h3 id="Sync">Using synchronous calls</h3> - -<p>If you want your code to execute in a strictly defined order, perhaps because the result of one -call is needed as an argument to another, you can make your request synchronous by calling <a -href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html#await()" ->{@code await()}</a> on the -<a href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html">{@code -PendingResult}</a>. This blocks the thread and returns the <a -href="{@docRoot}reference/com/google/android/gms/common/api/Result.html">{@code Result}</a> object -when the request completes, which is delivered as an instance of the -appropriate subclass as specified by the API you're using, such as <a -href="{@docRoot}reference/com/google/android/gms/drive/DriveApi.MetadataBufferResult.html" ->{@code DriveApi.MetadataBufferResult}</a>.</p> - -<p>Because calling <a -href="{@docRoot}reference/com/google/android/gms/common/api/PendingResult.html#await()" ->{@code await()}</a> blocks the thread until the result arrives, it's important that you -never perform this call on the UI thread. So, if you want to perform synchronous requests to a -Google Play service, you should create a new thread, such as with {@link android.os.AsyncTask} in -which to perform the request. For example, here's how to perform the same file request to Google -Drive as a synchronous call:</p> - -<pre> -private void loadFile(String filename) { - new GetFileTask().execute(filename); -} - -private class GetFileTask extends AsyncTask<String, Void, Void> { - protected void doInBackground(String filename) { - Query query = new Query.Builder() - .addFilter(Filters.eq(SearchableField.TITLE, filename)) - .build(); - // Invoke the query synchronously - DriveApi.MetadataBufferResult result = - Drive.DriveApi.query(mGoogleApiClient, query).await(); - - // Continue doing other stuff synchronously - ... - } -} -</pre> - -<p class="note"> -<strong>Tip:</strong> You can also enqueue read requests while not connected to Google Play -services. For example, execute a method to read a file from Google Drive regardless of whether your -Google API Client is connected yet. Then once a connection is established, the read requests -execute and you'll receive the results. Any write requests, however, will generate an error if you -call them while your Google API Client is not connected.</p> - diff --git a/docs/html/google/auth/http-auth.jd b/docs/html/google/auth/http-auth.jd deleted file mode 100644 index 7d34d89..0000000 --- a/docs/html/google/auth/http-auth.jd +++ /dev/null @@ -1,558 +0,0 @@ -page.title=Authorizing with Google for REST APIs -page.tags="oauth 2.0","GoogleAuthUtil" - -trainingnavtop=true -startpage=true - -@jd:body - - -<div id="qv-wrapper"> - <div id="qv"> - -<h2>In this document</h2> -<ol> - <li><a href="#Register">Register Your App</a></li> - <li><a href="#AccountPicker">Invoke the Account Picker</a></li> - <li><a href="#AccountName">Retrieve the Account Name</a></li> - <li><a href="#ExtendAsyncTask">Extend AsyncTask to Get the Auth Token</a></li> - <li><a href="#HandleExceptions">Handle Exceptions</a></li> -</ol> -<h2>Try it out</h2> - -<div class="download-box"> -<a href="http://developer.android.com/shareables/training/GoogleAuth.zip" - class="button">Download the sample app</a> -<p class="filename">GoogleAuth.zip</p> -</div> - -</div> -</div> - -<p>When you want your Android app to access Google APIs using the user's Google account over -HTTP, the <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html">{@code GoogleAuthUtil}</a> -class and related APIs provide your users a secure and consistent experience for picking an -account and retrieving an OAuth 2.0 token for your app.</p> - -<p>You can then use that token in your HTTP-based communications with Google API services -that are not included in the <a href="{@docRoot}google/play-services/index.html">Google Play -services</a> library, such as the Blogger or Translate APIs.</p> - -<p class="note"><strong>Note:</strong> An OAuth 2.0 token using <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html">{@code GoogleAuthUtil}</a> -is required only for certain types of Google -APIs that you need to access over HTTP. If you're instead using the <a -href="{@docRoot}google/play-services/index.html">Google Play services library</a> to access Google -APIs such as <a href="{@docRoot}google/play-services/plus.html">Google+</a> or <a -href="{@docRoot}google/play-services/games.html">Play Games</a>, you don't need an OAuth 2.0 -token and you can instead access these services using the {@code GoogleApiClient}. For more -information, read <a href="{@docRoot}google/auth/api-client.html">Accessing Google Play -Services APIs</a>.</p> - -<p>To get started with <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html">{@code GoogleAuthUtil}</a> -for accessing Google's REST APIs, you must set up your Android app project with the Google Play -services library. Follow the procedures in <a href= -"{@docRoot}google/play-services/setup.html">Setup Google Play Services SDK</a>.</p> - - - - -<h2 id="Register">Register Your App</h2> - -<p>Before you can publish an app that retrieves an OAuth 2.0 token for Google REST APIs, -you must register your Android app with the Google Cloud Console by providing your app's -package name and the SHA1 fingerprint of the keystore with which you sign your release APK.</p> - -<p class="caution"><strong>Caution:</strong> While you are testing an APK that's <a -href="{@docRoot}tools/publishing/app-signing.html#debugmode">signed with a -debug key</a>, Google does not require that your app be registered in Google Cloud Console. However, -your app must be registered in Google Cloud Console in order to continue working once it is -<a href="{@docRoot}tools/publishing/app-signing.html#releasemode">signed -with a release key</a>.</p> - -<p>To register your Android app with Google Cloud Console:</p> - -<ol> -<li>Visit <a href="https://cloud.google.com/console" class="external-link" target="_blank" ->Google Cloud Console</a>. -<li>If you have an existing project to which you're adding an Android app, select the project. -Otherwise, click <strong>Create project</strong> at the top, enter your project name and ID, -then click <strong>Create</strong>. -<p class="note"><strong>Note:</strong> The name you provide for the project is the name that -appears to users in the Google Settings app in the list of <em>Connected apps</em>.</p> -<li>In the left-side navigation, select <strong>APIs & auth</strong>. -<li>Enable the API you'd like to use by setting the Status to <strong>ON</strong>. - -<li>In the left-side navigation, select <strong>Credentials</strong>. -<li>Click <strong>Create new client ID</strong> or <strong>Create new key</strong> -as appropriate for your app.</li> -<li>Complete the form that appears by filling in your Android app details. -<p>To get the SHA1 fingerprint for your app, run the following command in a terminal: -<pre class="no-pretty-print"> -keytool -exportcert -alias <keystore_alias> -keystore <keystore_path> -list -v -</pre> -<p>For example, you're using a debug-key with Eclipse, then the command looks like this:</p> -<pre class="no-pretty-print"> -keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -list -v -</pre> -<p>Then the keystore password is "android".</p> -</li> -<li>Click <strong>Create</strong>. -</ol> - -<p>The Credentials page then provides the available credentials such as an OAuth 2.0 client ID and -an Android Key, but you don't need these to authorize your Android users. Simply registering your -app with the package name and SHA1 makes the Google services accessible by your app. - - -<p>To acquire the OAuth 2.0 token that will grant you access to Google APIs over HTTP, you need to -first identify the user's Google account with which you'll query the servers. For this task, the -Google Play services library provides a convenient account picker dialog you can invoke using -<a href="{@docRoot}reference/com/google/android/gms/common/AccountPicker.html">{@code -AccountPicker}</a>. The result delivered to your activity from the account picker is the account -name you'll use to request the OAuth 2.0 token in the next lesson.</p> - -<p class="note"><strong>Note:</strong> In order to use the APIs discussed here, you must -include the Google Play services library with your project. If you haven't set up your project -with the library yet, read the guide to <a -href="{@docRoot}google/play-services/setup.html">Setup Google Play Services SDK</a>.</p> - - - -<h2 id="AccountPicker">Invoke the Account Picker</h2> - -<p>To open the account picker dialog that's managed by the Google Play services library, call -{@link android.app.Activity#startActivityForResult startActivityForResult()} using an {@link -android.content.Intent} returned by <a href= -"{@docRoot}reference/com/google/android/gms/common/AccountPicker.html#newChooseAccountIntent(android.accounts.Account,%20java.util.ArrayList%3Candroid.accounts.Account%3E,%20java.lang.String[],%20boolean,%20java.lang.String,%20java.lang.String,%20java.lang.String[],%20android.os.Bundle)"> -{@code AccountPicker.newChooseAccountIntent}</a>.</p> - - -<p>For example:</p> -<pre> -static final int REQUEST_CODE_PICK_ACCOUNT = 1000; - -private void pickUserAccount() { - String[] accountTypes = new String[]{"com.google"}; - Intent intent = AccountPicker.newChooseAccountIntent(null, null, - accountTypes, false, null, null, null, null); - startActivityForResult(intent, REQUEST_CODE_PICK_ACCOUNT); -} -</pre> - -<p>When this code executes, a dialog appears for the user to pick an account. When the user -selects the account, your activity receives the result in the {@link -android.app.Activity#onActivityResult onActivityResult()} callback.</p> - -<p>Most apps should pass the <a href= -"{@docRoot}reference/com/google/android/gms/common/AccountPicker.html#newChooseAccountIntent(android.accounts.Account,%20java.util.ArrayList%3Candroid.accounts.Account%3E,%20java.lang.String[],%20boolean,%20java.lang.String,%20java.lang.String,%20java.lang.String[],%20android.os.Bundle)"> -{@code newChooseAccountIntent()}</a> method the same arguments shown in the above example, -which indicate that:</p> - - -<ul> -<li>There is no currently selected account.</li> -<li>There is no restricted list of accounts.</li> -<li>The dialog should list only accounts from the "com.google" domain.</li> -<li>Don't prompt the user to pick an account if there's only one available account (just use that -one). However, even if only one account currently exists, the dialog may include an option for the -user to add a new account.</li> -<li>There is no custom title for the dialog.</li> -<li>There is no specific auth token type required.</li> -<li>There are no restrictions based on account features.</li> -<li>There are no authenticator-specific options.</li> -</ul> - -<p>For more details about these arguments, see the <a href= -"{@docRoot}reference/com/google/android/gms/common/AccountPicker.html#newChooseAccountIntent(android.accounts.Account,%20java.util.ArrayList%3Candroid.accounts.Account%3E,%20java.lang.String[],%20boolean,%20java.lang.String,%20java.lang.String,%20java.lang.String[],%20android.os.Bundle)"> -{@code newChooseAccountIntent()}</a> method documentation.</p> - - - - -<h2 id="AccountName">Retrieve the Account Name</h2> - -<p>Once the user selects an account, your activity receives a call to its -{@link android.app.Activity#onActivityResult onActivityResult()} method. The received -{@link android.content.Intent} includes an extra for -{@link android.accounts.AccountManager#KEY_ACCOUNT_NAME}, specifying the account name -(an email address) you must use to acquire the OAuth 2.0 token.</p> - -<p>Here's an example implementation of the callback {@link android.app.Activity#onActivityResult -onActivityResult()} that receives the selected account:</p> - -<pre> -String mEmail; // Received from <a href= -"{@docRoot}reference/com/google/android/gms/common/AccountPicker.html#newChooseAccountIntent(android.accounts.Account,%20java.util.ArrayList%3Candroid.accounts.Account%3E,%20java.lang.String[],%20boolean,%20java.lang.String,%20java.lang.String,%20java.lang.String[],%20android.os.Bundle)" ->{@code newChooseAccountIntent()}</a>; passed to <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)">{@code getToken()}</a> - -@Override -protected void onActivityResult(int requestCode, int resultCode, Intent data) { - if (requestCode == REQUEST_CODE_PICK_ACCOUNT) { - // Receiving a result from the AccountPicker - if (resultCode == RESULT_OK) { - mEmail = data.getStringExtra(AccountManager.KEY_ACCOUNT_NAME); - // With the account name acquired, go get the auth token - getUsername(); - } else if (resultCode == RESULT_CANCELED) { - // The account picker dialog closed without selecting an account. - // Notify users that they must pick an account to proceed. - Toast.makeText(this, R.string.pick_account, Toast.LENGTH_SHORT).show(); - } - } - // Later, more code will go here to handle the result from some exceptions... -} -</pre> - -<p>You can now pass the account name held by {@code mEmail} to <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a> (which is what the {@code getUsername()} method -does), but because it performs network transactions, this method should not be called from the -UI thread. The next lesson shows how to create an {@link android.os.AsyncTask} to get the auth token -on a separate thread.</p> - - -<p>Once you have retrieved the account name for the user's Google account, you can call <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a>, which returns the access token string required by Google API -services.</p> - - -<p>Calling this method is generally a straightforward procedure, but you must be -aware that:</p> -<ul> -<li>The <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a> method requires a network connection, so your app must -acquire the {@link android.Manifest.permission#INTERNET} permission. You should also check whether -the device has a network connection at runtime by querying {@link android.net.NetworkInfo}, which -requires that your app also acquire the {@link android.Manifest.permission#ACCESS_NETWORK_STATE} -permissions—for more details, read <a href= -"{@docRoot}training/basics/network-ops/connecting.html">Connecting to the Network</a>.</li> -<li>Because the <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a> method performs a synchronous network transaction, you should -always perform this call from a worker thread to avoid blocking your app's UI thread.</li> -<li>As is true when performing any network transaction, you should be prepared to handle -exceptions that may occur. There are also specific exceptions that -<a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a> may throw, defined as <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthException.html">{@code -GoogleAuthException}</a> objects.</li> -</ul> - -<p>This lesson shows how you can gracefully handle these concerns by performing authentication in -an {@link android.os.AsyncTask} and providing users with the appropriate information and available -actions during known exceptions.</p> - -<p class="note"><strong>Note:</strong> The code shown in this lesson, using <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)">{@code GoogleAuthUtil.getToken()}</a>, -is appropriate when you will be requesting the OAuth token from an {@link android.app.Activity}. -However, if you need to request the OAuth token from a {@link android.app.Service}, then you -should instead use <a -href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)">{@code -getTokenWithNotification()}</a>. This method works the same as <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)">{@code GoogleAuthUtil.getToken()}</a>, but if an error occurs, it -also creates an appropriate -<a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">notification</a> -that allows the user can recover from the error. -The sample available for download above includes code showing how to use this method instead.</p> - - -<h2 id="ExtendAsyncTask">Extend AsyncTask to Get the Auth Token</h2> - -<p>The {@link android.os.AsyncTask} class provides a simple way to create a worker thread for jobs -that should not run on your UI thread. This lesson focuses on how to create such a thread -to get your auth token; for a more complete discussion about {@link android.os.AsyncTask}, -read <a href="{@docRoot}training/articles/perf-anr.html">Keeping Your -App Responsive</a> and the {@link android.os.AsyncTask} class reference.</p> - - -<p>The {@link android.os.AsyncTask#doInBackground doInBackground()} method in your {@link -android.os.AsyncTask} class is where you should call the <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a> method. You can also use it to catch some of the generic -exceptions that may occur during your network transactions.</p> - -<p>For example, here's part of an {@link android.os.AsyncTask} subclass that calls <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a>:</p> - -<pre> -public class GetUsernameTask extends AsyncTask<Void, Void, Void>{ - Activity mActivity; - String mScope; - String mEmail; - - GetUsernameTask(Activity activity, String name, String scope) { - this.mActivity = activity; - this.mScope = scope; - this.mEmail = name; - } - - /** - * Executes the asynchronous job. This runs when you call execute() - * on the AsyncTask instance. - */ - @Override - protected Void doInBackground(Void... params) { - try { - String token = fetchToken(); - if (token != null) { - // <b>Insert the good stuff here.</b> - // Use the token to access the user's Google data. - ... - } - } catch (IOException e) { - // The fetchToken() method handles Google-specific exceptions, - // so this indicates something went wrong at a higher level. - // TIP: Check for network connectivity before starting the AsyncTask. - ... - } - return null; - } - - /** - * Gets an authentication token from Google and handles any - * GoogleAuthException that may occur. - */ - protected String fetchToken() throws IOException { - try { - <b>return GoogleAuthUtil.getToken(mActivity, mEmail, mScope);</b> - } catch (UserRecoverableAuthException userRecoverableException) { - // GooglePlayServices.apk is either old, disabled, or not present - // so we need to show the user some UI in the activity to recover. - mActivity.handleException(userRecoverableException); - } catch (GoogleAuthException fatalException) { - // Some other type of unrecoverable exception has occurred. - // Report and log the error as appropriate for your app. - ... - } - return null; - } - ... -} -</pre> - -<p>In order to call <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a>, you must provide the app {@link android.content.Context}, -the account name retrieved from the account picker, and the scope for your auth -token request. The above sample code (and the attached sample) defines these -arguments with class members that the host activity passes to the {@link android.os.AsyncTask} class constructor. For more information about setting the scope, see -the <a href="#SpecifyingScopes">Specifying Scopes</a> section below. </p> - -<p class="note"><strong>Note:</strong> -As shown by the {@code fetchToken()} method above, you must handle -special exceptions that may occur during the <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a> method. The next section shows how you should -respond to these exceptions.</p> - -<p>Once you have an {@link android.os.AsyncTask} subclass defined, -you can instantiate and execute an instance after you get the user's -account name from the account picker. -For example, back in the {@link android.app.Activity} class you can do something like this:</p> - -<pre> -String mEmail; // Received from <a href= -"{@docRoot}reference/com/google/android/gms/common/AccountPicker.html#newChooseAccountIntent(android.accounts.Account,%20java.util.ArrayList%3Candroid.accounts.Account%3E,%20java.lang.String[],%20boolean,%20java.lang.String,%20java.lang.String,%20java.lang.String[],%20android.os.Bundle)" ->{@code newChooseAccountIntent()}</a>; passed to <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)">{@code getToken()}</a> -private static final String SCOPE = - "oauth2:https://www.googleapis.com/auth/userinfo.profile"; - -/** - * Attempts to retrieve the username. - * If the account is not yet known, invoke the picker. Once the account is known, - * start an instance of the AsyncTask to get the auth token and do work with it. - */ -private void getUsername() { - if (mEmail == null) { - pickUserAccount(); - } else { - if (isDeviceOnline()) { - <b>new GetUsernameTask(HelloActivity.this, mEmail, SCOPE).execute();</b> - } else { - Toast.makeText(this, R.string.not_online, Toast.LENGTH_LONG).show(); - } - } -} -</pre> - -<p>The {@code pickUserAccount()} method is shown in the first lesson, <a -href="{@docRoot}training/auth-google/picking-account.html">Picking the User's Account</a>. - -<p>For information about how to check whether the device is currently online (as performed by -the {@code isDeviceOnline()} method above), see the attached sample app or the -<a href= -"{@docRoot}training/basics/network-ops/connecting.html">Connecting to the Network</a> lesson.</p> - -<p>The only part left is how you should handle the exceptions that may occur when you call -<a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a>.</p> - -<h3 id="SpecifyingScopes">Specifying scopes</h3> -<p>The scope string is used to specify which Google services can be accessed by - an app using the requested auth token. An auth token can be associated with - multiple scopes.</p> -<p>When specifying the scopes in your auth token request, prefix the - scope string with {@code "oauth2:"} followed by a list of one or more OAuth scope - values. Use a space to separate each scope value in the list. To see a list of - valid OAuth scope values for Google services, browse - the <a href="https://developers.google.com/oauthplayground/" - class="external-link">OAuth 2.0 Playground</a>.</p> -<p class="note"><strong>Tip:</strong> Specify {@code "oauth2:<scope>"} - for a single scope. Specify - {@code "oauth2:<scope1> <scope2> <scopeN>"} for multiple - scopes (using a space to separate each scope).</p> -<p>For example, to access the Google Books API, the scope is - {@code "oauth2:https://www.googleapis.com/auth/books"}. To add an additional - scope, say for Google+ login, your code might look like this:</p> -<pre> -private final static String BOOKS_API_SCOPE - = "https://www.googleapis.com/auth/books"; -private fina; static String GPLUS_SCOPE - = "https://www.googleapis.com/auth/plus.login"; -private final static String mScopes - = "oauth2:" + BOOKS_API_SCOPE + " " + GPLUS_SCOPE; -String token = GoogleAuthUtil.getToken(mActivity, mEmail, mScopes); -</pre> - -<h2 id="HandleExceptions">Handle Exceptions</h2> - -<p>As shown in the <code>fetchToken()</code> method above, you must catch all occurrences of <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthException.html">{@code -GoogleAuthException}</a> when you call <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context,%20java.lang.String,%20java.lang.String)"> -{@code GoogleAuthUtil.getToken()}</a>.</p> - -<p>To provide users information and a proper solution to issues that may occur while acquiring the -auth token, it's important that you properly handle the following subclasses of <a href= -"{@docRoot}reference/com/google/android/gms/auth/GoogleAuthException.html">{@code -GoogleAuthException}</a>:</p> - - -<dl> -<dt><a href="{@docRoot}reference/com/google/android/gms/auth/UserRecoverableAuthException.html">{@code UserRecoverableAuthException}</a></dt> - <dd>This is an error that users can resolve through some verification. For example, users may - need to confirm that your app is allowed to access their Google data or they may need to re-enter - their account password. When you receive this exception, call <a href= -"{@docRoot}reference/com/google/android/gms/auth/UserRecoverableAuthException.html#getIntent()">{@code -getIntent()}</a> on the instance and pass the returned {@link android.content.Intent} to {@link -android.app.Activity#startActivityForResult startActivityForResult()} to give users the opportunity -to solve the problem, such as by logging in.</dd> - -<dt><a href="{@docRoot}reference/com/google/android/gms/auth/GooglePlayServicesAvailabilityException.html">{@code GooglePlayServicesAvailabilityException}</a></dt> - <dd>This is a specific type of <a - href="{@docRoot}reference/com/google/android/gms/auth/UserRecoverableAuthException.html">{@code - UserRecoverableAuthException}</a> indicating that the user's current version -of Google Play services is outdated. Although the recommendation above for -<a href="{@docRoot}reference/com/google/android/gms/auth/UserRecoverableAuthException.html">{@code - UserRecoverableAuthException}</a> also works for this exception, calling {@link -android.app.Activity#startActivityForResult startActivityForResult()} will immediately send users - to Google Play Store to install an update, which may be confusing. So you should instead call <a - href="{@docRoot}reference/com/google/android/gms/auth/GooglePlayServicesAvailabilityException.html#getConnectionStatusCode()"> -{@code getConnectionStatusCode()}</a> and pass the result to <a href= -"{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#getErrorDialog(int,%20android.app.Activity,%20int,%20android.content.DialogInterface.OnCancelListener)"> -{@code GooglePlayServicesUtil.getErrorDialog()}</a>. This returns a {@link android.app.Dialog} -that includes an appropriate message and a button to take users to Google Play Store so they -can install an update.</dd> -</dl> - -<p>For example, the <code>fetchToken()</code> method in the above sample code catches any -occurrence of <a -href="{@docRoot}reference/com/google/android/gms/auth/UserRecoverableAuthException.html">{@code -UserRecoverableAuthException}</a> and passes it back to the activity with a method called -{@code handleException()}. Here's what that method in the activity may look like:</p> - - -<pre> -static final int REQUEST_CODE_RECOVER_FROM_PLAY_SERVICES_ERROR = 1001; - -/** - * This method is a hook for background threads and async tasks that need to - * provide the user a response UI when an exception occurs. - */ -public void handleException(final Exception e) { - // Because this call comes from the AsyncTask, we must ensure that the following - // code instead executes on the UI thread. - runOnUiThread(new Runnable() { - @Override - public void run() { - if (e instanceof GooglePlayServicesAvailabilityException) { - // The Google Play services APK is old, disabled, or not present. - // Show a dialog created by Google Play services that allows - // the user to update the APK - int statusCode = ((GooglePlayServicesAvailabilityException)e) - .getConnectionStatusCode(); - Dialog dialog = GooglePlayServicesUtil.getErrorDialog(statusCode, - HelloActivity.this, - REQUEST_CODE_RECOVER_FROM_PLAY_SERVICES_ERROR); - dialog.show(); - } else if (e instanceof UserRecoverableAuthException) { - // Unable to authenticate, such as when the user has not yet granted - // the app access to the account, but the user can fix this. - // Forward the user to an activity in Google Play services. - Intent intent = ((UserRecoverableAuthException)e).getIntent(); - startActivityForResult(intent, - REQUEST_CODE_RECOVER_FROM_PLAY_SERVICES_ERROR); - } - } - }); -} -</pre> - -<p>Notice that in both cases, the {@code REQUEST_CODE_RECOVER_FROM_PLAY_SERVICES_ERROR} -request code is passed with the request to handle the exception with a dialog or activity. -This way, when the user completes the appropriate action to resolve the exception, -your {@link android.app.Activity#onActivityResult onActivityResult()} method receives an -intent that includes this request code and you can try to acquire the auth -token again.</p> - - -<p>For example, the following code is a complete implementation of {@link -android.app.Activity#onActivityResult onActivityResult()} that handles results for -both the {@code REQUEST_CODE_PICK_ACCOUNT} action (shown in the previous lesson, <a -href="{@docRoot}training/auth-google/picking-account.html">Picking the User's Account</a>) -and the {@code REQUEST_CODE_RECOVER_FROM_PLAY_SERVICES_ERROR} action, which occurs after the user -completes one of the actions above to resolve an exception.</p> - - -<pre> -@Override -protected void onActivityResult(int requestCode, int resultCode, Intent data) { - if (requestCode == REQUEST_CODE_PICK_ACCOUNT) { - // Receiving a result from the AccountPicker - if (resultCode == RESULT_OK) { - mEmail = data.getStringExtra(AccountManager.KEY_ACCOUNT_NAME); - // With the account name acquired, go get the auth token - getUsername(); - } else if (resultCode == RESULT_CANCELED) { - // The account picker dialog closed without selecting an account. - // Notify users that they must pick an account to proceed. - Toast.makeText(this, R.string.pick_account, Toast.LENGTH_SHORT).show(); - } - } else if ((requestCode == REQUEST_CODE_RECOVER_FROM_AUTH_ERROR || - requestCode == REQUEST_CODE_RECOVER_FROM_PLAY_SERVICES_ERROR) - && resultCode == RESULT_OK) { - // Receiving a result that follows a GoogleAuthException, try auth again - getUsername(); - } -} -</pre> - -<p>For a complete set of code that acquires the OAuth token and queries a Google service -over HTTP (including how to use <a -href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)">{@code -getTokenWithNotification()}</a> when you need to acquire the token from -a {@link android.app.Service}), see the sample app available for download at the top -of this page.</p> - - - diff --git a/docs/html/google/play-services/auth.jd b/docs/html/google/play-services/auth.jd deleted file mode 100644 index dded599..0000000 --- a/docs/html/google/play-services/auth.jd +++ /dev/null @@ -1,239 +0,0 @@ -page.title=Authorization -page.tags=AccountManager,oauth2 -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#choose">Choosing an Account</a></li> - <li><a href="#obtain">Obtaining an Access Token</a></li> - <li><a href="#handle">Handling Exceptions</a></li> - <li><a href="#use">Using the Access Token</a></li> - </ol> - </div> -</div> - -<p> - Google Play services offers a standard authorization flow for all Google APIs and - all components of Google Play services. In addition, you can leverage the authorization - portion of the Google Play services SDK to gain authorization to services that are not yet supported - in the Google Play services platform by using the access token to manually make API - requests or using a client library provided by the service provider. -</p> - -<p>For implementation details, see the sample in <code><android-sdk>/extras/google-play-services/samples/auth</code>, -which shows you how to carry out these basic steps for obtaining an access token.</p> - -<h2 id="choose">Choosing an Account</h2> -<p> - Google Play services leverage existing accounts on an Android-powered device - to gain authorization to the services that you want to use. To obtain an access token, - a valid Google account is required and it must exist on the device. You can ask your users which - account they want to use by enumerating the Google accounts on the device or using the - built-in -<a href="{@docRoot}reference/com/google/android/gms/common/AccountPicker.html">{@code -AccountPicker}</a> - class to display a standard account picker view. You'll need the - {@link android.Manifest.permission#GET_ACCOUNTS} - permission set in your manifest file for both methods. -</p> -<p> - For example, here's how to gather all of the Google accounts on a device and return them - in an array. When obtaining an access token, only the email address of the account is - needed, so that is what the array stores: -</p> - -<pre> -private String[] getAccountNames() { - mAccountManager = AccountManager.get(this); - Account[] accounts = mAccountManager.getAccountsByType( - GoogleAuthUtil.GOOGLE_ACCOUNT_TYPE); - String[] names = new String[accounts.length]; - for (int i = 0; i < names.length; i++) { - names[i] = accounts[i].name; - } - return names; -} -</pre> -<h2 id="obtain">Obtaining an Access Token</h2> -<p> - With an email address and the service scope you can now obtain an access token. -</p> -<p class="note"><strong>Note:</strong> Specify <code>"oauth2:<em>scope</em>"</code> for a single scope or - <code>"oauth2:<em>scope1</em> <em>scope2</em> <em>scope3</em>"</code> for multiple scopes.</p> - -There are two general - ways to get a token:</p> - - <ul> - <li>Call one of the two overloaded <a - href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context, java.lang.String, java.lang.String)" - >{@code GoogleAuthUtil.getToken()}</a> methods in a foreground activity where you can - display a dialog to the user to interactively handle authorization errors.</li> - <li>Call one of the three <a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)" - >{@code getTokenWithNotification()}</a> - methods if you are trying to gain authorization in a background service or sync adapter so that a - notification is displayed if an error occurs.</a></li> - </ul> - - <h3>Using getToken()</h3> - The following code snippet obtains an access token with an email address, the scope that you want to use for the service, and a {@link android.content.Context}: - -<pre> -HelloActivity mActivity; -String mEmail; -String mScope; -String token; - -... -try { - token = GoogleAuthUtil.getToken(mActivity, mEmail, mScope); -} catch { - ... -} -</pre> - -<p>Call this method off of the main UI thread since it executes network transactions. An easy way to do this - is in an {@link android.os.AsyncTask}. - The sample in the Google Play services SDK shows you how to wrap this call in an AsyncTask. - If authorization is successful, the token is returned. If not, the exceptions described in -<a href="#handle">Handling Exceptions</a> - are thrown that you can catch and handle appropriately. -</p> - - <h3>Using getTokenWithNotification()</h3> - <p>If you are obtaining access tokens in a background service or sync adapter, there - are three overloaded - <a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)" - >{@code getTokenWithNotification()}</a> methods - that you can use:</p> - <ul> - <li><a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)" - >{@code getTokenWithNotification(Context context, String accountName, String scope, Bundle extras)}</a>: - For background services. Displays a notification to the user when authorization errors occur.</li> - <li><a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle, android.content.Intent)" - >{@code getTokenWithNotification(Context context, String accountName, String scope, Bundle extras, Intent callback)}</a>: - This method is for use in background services. It displays a notification to the user - when authorization errors occur. If a user clicks the notification and then authorizes the - app to access the account, the intent is broadcasted. When using this method: - <ul> - <li>Create a {@link android.content.BroadcastReceiver} that registers the intent and handles -it appropriately</li> - <li>In the app's manifest file, set the <a - href="{@docRoot}guide/topics/manifest/receiver-element.html#exported"><code>android:exported</code></a> - attribute to <code>true</code> for the broadcast receiver</li> - <li>Ensure that the intent is serializable using the {@link -android.content.Intent#toUri toUri(Intent.URI_INTENT_SCHEME)} and - {@link android.content.Intent#parseUri parseUri(intentUri, Intent.URI_INTENT_SCHEME)} methods.</li> - </ul> - <li><a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle, java.lang.String, android.os.Bundle)" - >{@code getTokenWithNotification(Context context, String accountName, String scope, Bundle extras, String authority, Bundle syncBundle)}</a>: -This method is for use in sync adapters. It displays a notification to the user when -errors occur. If a user clicks the notification and then authorizes the -app to access the account, the sync adapter retries syncing with the information - contained in the <code>syncBundle</code> parameter.</li> - </ul> - - <p>See the sample in <code><android-sdk>/extras/google-play-services/samples/auth</code> for implementation details.</p> - - - - -<h2 id="handle">Handling Exceptions</h2> -<p> - When requesting an access token with - <a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context, java.lang.String, java.lang.String)" - >{@code GoogleAuthUtil.getToken()}</a>, - the following exceptions can be thrown: -</p> -<ul> - <li> -<a href="{@docRoot}reference/com/google/android/gms/auth/UserRecoverableAuthException.html" ->{@code UserRecoverableAuthException}</a>: - This exception is thrown when an error occurs that users can resolve, such as not yet granting access to their accounts or if they changed their password. - This exception class contains a {@link android.app.Activity#getIntent getIntent()} - method that you can call to obtain an intent that you can use with -{@link android.app.Activity#startActivityForResult startActivityForResult()} - to obtain the user's resolution. You will need to handle the -{@link android.app.Activity#onActivityResult onActivityResult()} - callback when this activity returns to take action based on the user's actions. - </li> - <li> -<a href="{@docRoot}reference/com/google/android/gms/auth/GooglePlayServicesAvailabilityException.html" ->{@code GooglePlayServicesAvailabilityException}</a>: - This exception is a special case of <a href="{@docRoot}reference/com/google/android/gms/auth/UserRecoverableAuthException.html" - >{@code UserRecoverableAuthException}</a> - and occurs when the actual Google Play services APK is not installed or unavailable. - This exception provides additional client support to - handle and fix this issue by providing an error code that describes the exact cause of the problem. - This exception also contains an intent that you can obtain and use to start - an activity to resolve the issue. - </li> - <li> -<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthException.html">{@code -GoogleAuthException}</a>: - This exception is thrown when the authorization fails, such as when an invalid scope is - specified or if the email address used for authorization is actually not on the user's - device. - </li> - <li> -<a href="{@docRoot}reference/com/google/android/gms/auth/UserRecoverableNotifiedException.html" ->{@code UserRecoverableNotifiedException}</a>: - This exception is thrown when the authorization fails using one of the -<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)" - >{@code getTokenWithNotification()}</a> methods and if the error - is recoverable with a user action. - </li> -</ul> -<p> - For more information on how to handle these exceptions and code snippets, see the reference - documentation for the -<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html">{@code -GoogleAuthUtil}</a> class. -</p> - - - - -<h2 id="use">Using the Access Token</h2> -<p> - Once you have successfully obtained a token, you can use it to access Google services. - Many Google services provide client libraries, so it is recommended that you use these when - possible, but you can make raw HTTP requests as well with the token. The following example - shows you how to do this and handle HTTP error and success responses accordingly: -</p> - -<pre> -URL url = new URL("https://www.googleapis.com/oauth2/v1/userinfo?access_token=" - + token); -HttpURLConnection con = (HttpURLConnection) url.openConnection(); -int serverCode = con.getResponseCode(); -//successful query -if (serverCode == 200) { - InputStream is = con.getInputStream(); - String name = getFirstName(readResponse(is)); - mActivity.show("Hello " + name + "!"); - is.close(); - return; -//bad token, invalidate and get a new one -} else if (serverCode == 401) { - GoogleAuthUtil.invalidateToken(mActivity, token); - onError("Server auth error, please try again.", null); - Log.e(TAG, "Server auth error: " + readResponse(con.getErrorStream())); - return; -//unknown error, do something else -} else { - Log.e("Server returned the following error code: " + serverCode, null); - return; -} -</pre> - -<p> - Notice that you must manually invalidate the token if the response from the server - signifies an authorization error (401). This could mean the access token - being used is invalid for the service's scope or the token may have expired. If this is the - case, obtain a new token using <a -href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context, java.lang.String, java.lang.String)" ->{@code GoogleAuthUtil.getToken()}</a>. -</p> diff --git a/docs/html/google/play-services/index.jd b/docs/html/google/play-services/index.jd deleted file mode 100644 index 11060e8..0000000 --- a/docs/html/google/play-services/index.jd +++ /dev/null @@ -1,706 +0,0 @@ -page.title=Google Play Services -header.hide=1 -page.metaDescription=With Google Play services, your app can take advantage of the latest Google-powered features such as Maps, Analytics, and more: platform updates are distributed automatically as an APK through the Google Play Store. - -@jd:body - -<div class="landing-banner"> - -<div class="col-6"> - <img src="/images/google/gps.png" alt=""> -</div> -<div class="col-6"> - - <h1 itemprop="name" style="margin-bottom:0;">Google Play Services</h1> - <p itemprop="description">Give your apps more features to attract users - on a wider range of devices. - With Google Play services, your app can take advantage - of the latest, Google-powered features such as Maps, Google+, and more, - with automatic platform updates distributed as an APK through - the Google Play store. This makes it faster for your users to receive updates - and easier for you to integrate the newest that Google has to offer. - </p> - -</div> -</div> - - <div class="cols"> - <div class="col-4"> - -<h4>Google Technology</h4> -<p>Google Play services provides you with easy access to Google services and is -tightly integrated with the Android OS. Easy-to-use client libraries are -provided for each service that let you implement the functionality you want -easier and faster.</p> - - </div> - <div class="col-4"> - -<h4>Standard Authorization</h4> -<p>All products in Google Play services share a common authorization API - that leverages the existing Google accounts on the device. You and your - users have a consistent and safe way to grant and receive OAuth2 access tokens - to Google services.</p> - - </div> - <div class="col-4"> - -<h4>Automatic Updates</h4> -<p>Devices running Android 2.3 or higher that have the Google Play Store -app will automatically receive updates to Google Play services. Enhance -your app with the most recent version of Google Play services without worrying -about your users' Android version.</p> - - </div> - <p>To start integrating Google Play services into your app, - follow the <a href="/google/play-services/setup.html">Setup</a> guide.</p> -</div> - -<h2 style="margin-top:0" id="newfeatures">New Features</h2> - -<div class="toggle-content opened"> - <p><a href="#" onclick="return toggleContent(this)"> - <img src="{@docRoot}assets/images/triangle-opened.png" - class="toggle-content-img" - alt=""/>Google Play services, Version 7.3</a> <em>(April 2015)</em> - </p> - - <div class="toggle-content-toggleme"> -<dl> -<dt>Highlights in Version 7.3</dt> -<dd> -<p>For a summary of the feature highlights in Google Play services 7.3, see the -announcement -<a href="http://android-developers.blogspot.com/2015/04/theres-lot-to-explore-with-google-play.html" -class="external-link">blog post</a>.</p> -<ul> - <li> - <strong>Wear</strong> - This release provides you with the ability -to advertise and discover the capabilities of devices that are connected in a Wear network, through -the new <a href="{@docRoot}reference/com/google/android/gms/wearable/CapabilityApi.html"> -{@code CapabilityApi}</a> class. The new -<a href="{@docRoot}reference/com/google/android/gms/wearable/ChannelApi.html">{@code ChannelApi}</a> -class lets you send and receive data bi-directionally from your wearable app on a device to another -wearable node. Use the Channel API to send large files for offline access or to stream real-time -binary data. - <ul> - <li><a href="{@docRoot}training/wearables/data-layer/messages.html"> -Sending and Receiving Messages</a></li> - </ul> - </li> - <li> - <strong>Fit</strong> - This release provides a new -<a href="{@docRoot}reference/com/google/android/gms/fitness/HistoryApi.html#readDailyTotal(com.google.android.gms.common.api.GoogleApiClient,%20com.google.android.gms.fitness.data.DataType)"> -{@code HistoryApi.readDailyTotal()}</a> method for you to get aggregated daily data for a given -data type. -This release also introduces data types for recording granular nutrition information including -protein, fat, cholesterol, and more. - <ul> - <li><a href="https://developers.google.com/fit/android/history#read_daily_total_data" - class="external-link">Read daily total API developer guide</a></li> - <li><a href="https://developers.google.com/fit/android/data-types#data_types_for_instantaneous_readings" - class="external-link">Nutrition data type developer guide</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/fitness/data/Field.html"> - Nutrition data types API reference</a></li> - <li><a href="https://developers.google.com/fit/android/releases#april_2015" - class="external-link">Release notes</a></li> - </ul> - </li> - <li> - <strong>Location</strong> - This release adds a maximum wait time for location updates. By -calling the new -<a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setMaxWaitTime(long)"> -{@code setMaxWaitTime()}</a> method and passing in a value at least double the value requested with -the -<a href="{@docRoot}reference/com/google/android/gms/location/LocationRequest.html#setInterval(long)"> -{@code setInterval()}</a> method, the system can batch location updates together, reducing battery -usage and, on some devices, improving location accuracy. In addition, you can use the new -<a href="{@docRoot}reference/com/google/android/gms/location/LocationCallback.html"> -{@code LocationCallback}</a> class to be notified when the device location has changed or can no -longer be determined. - </li> - <li> - <strong>Places</strong> - This release adds a -<a href="{@docRoot}reference/com/google/android/gms/location/places/PlaceBuffer.html#getAttributions()"> -{@code PlaceBuffer.getAttributions()}</a> method for displaying third-party attributions.</a> - <ul> - <li><a href="https://developers.google.com/places/android/attributions" - class="external-link">Displaying attributions developer guide</a></li> - <li><a href="https://developers.google.com/places/android/releases">Release notes</a></li> - </ul> - </li> -</ul> -</dd> -</dl> - </div> -</div> - -<div class="toggle-content closed"> - <p><a href="#" onclick="return toggleContent(this)"> - <img src="{@docRoot}assets/images/triangle-closed.png" - class="toggle-content-img" - alt=""/>Google Play services, Version 7.0</a> <em>(March 2015)</em> - </p> - - <div class="toggle-content-toggleme"> -<dl> -<dt>Highlights in Version 7.0</dt> -<dd> -<p>For a summary of the feature highlights in Google Play services 7.0, see the -announcement -<a href="http://android-developers.blogspot.com/2015/03/google-play-services-70-places-everyone.html" -class="external-link">blog post</a>.</p> -<ul> - <li><strong>Places</strong> - Using the Google Places API for Android, you can build - location-aware apps that respond contextually to the local businesses and other places near - the device. Use the built-in place picker UI widget and API methods to find the device’s - current place, autocomplete users’ queries, and more. - <ul> - <li><a href="https://developers.google.com/places/documentation/android/" - class="external-link">Places API developer guide</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/location/places/package-summary.html"> - Places API reference</a></li> - </ul> - </li> - <li><strong>Location settings</strong> - While the - <a href="{@docRoot}reference/com/google/android/gms/location/FusedLocationProviderApi.html"> - {@code FusedLocationProviderApi}</a> - combines multiple sensors to give you the optimal location, the accuracy of the location your - app receives still depends greatly on the settings enabled on the device (GPS, wifi, airplane - mode, and others). Using the new - <a href="{@docRoot}reference/com/google/android/gms/location/SettingsApi.html"> - {@code SettingsApi}</a> - class, you can bring up a Location Settings dialog which displays a one-touch control for users - to change their settings without leaving your app. - </li> - <li><strong>Fit</strong> - The Google Fit API is now more efficient with modular calls to specific - functionality within the API. You can now also access distance and granular sleep data. - <ul> - <li><a href="https://developers.google.com/fit/android/get-started.html#step_5_connect_to_the_fitness_service" - class="external-link">Fit API developer guide</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/fitness/package-summary.html"> - Fit API reference</a></li> - </ul> - </li> - <li><strong>Google Mobile Ads</strong> - This release introduces the - <a href="{@docRoot}reference/com/google/android/gms/ads/doubleclick/PublisherAdRequest.Builder.html#addCustomTargeting(java.lang.String,%20java.lang.String)"> - {@code addCustomTargeting()}</a> - and <a href="{@docRoot}reference/com/google/android/gms/ads/doubleclick/PublisherAdRequest.Builder.html#addCategoryExclusion(java.lang.String)"> - {@code addCategoryExclusion()}</a> - methods to the <a href="{@docRoot}reference/com/google/android/gms/ads/doubleclick/PublisherAdRequest.Builder.html"> - {@code PublisherAdRequest.Builder} </a> - class, enabling DoubleClick for Publishers (DFP) developers to - <a href="https://support.google.com/dfp_sb/answer/112648" class="external-link">target custom - criteria</a> - and <a href="https://support.google.com/dfp_premium/answer/2627086" class="external-link">use - ad exclusions to block ads</a>. - <ul> - <li><a href="https://developers.google.com/mobile-ads-sdk/docs/dfp/android/banner" - class="external-link">DFP targeting developer guide</a></li> - </ul> - </li> - <li><strong>Play Game services</strong> - The Nearby Connections API allows users to connect to - each other and exchange messages over a local network. This API supports local multiplayer - and second screen gaming. - <ul> - <li><a href="https://developers.google.com/games/services/android/nearby.html" - class="external-link">Nearby Connections developer guide</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/nearby/connection/package-summary.html"> - Nearby Connection API reference</a></li> - </ul> - </li> - <li><strong>Google API client</strong> - This release introduces the - <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.Builder.html#requestServerAuthCode(java.lang.String,%20com.google.android.gms.common.api.GoogleApiClient.ServerAuthCodeCallbacks)">{@code GoogleApiClient.Builder.requestServerAuthCode()}</a> method. This API makes it significantly easier - to enable servers to be able to make Google API calls on behalf of users. This method reduces - the lines of boilerplate code that you previously had to implement. - <ul> - <li><a href="https://developers.google.com/identity/sign-in/android/sign-in.html#enable_server-side_api_access_for_your_app" - class="external-link">Server-side API access developer guide</a></li> - </ul> - </li> - <li> - <strong>Drive</strong> - This release adds - <a href="{@docRoot}reference/com/google/android/gms/drive/DriveResource.html#trash(com.google.android.gms.common.api.GoogleApiClient))"> - {@code trash()}</a> and - <a href="{@docRoot}reference/com/google/android/gms/drive/DriveResource.html#untrash(com.google.android.gms.common.api.GoogleApiClient)"> - {@code untrash()}</a> methods to the - <a href="{@docRoot}reference/com/google/android/gms/drive/DriveResource.html"> - {@code DriveResource}</a> - class. These methods enable you to move user-visible files and folders to the trash or - restore them from the trash. Trashing a folder recursively trashes its children. The - <a href="{@docRoot}reference/com/google/android/gms/drive/Metadata.html#isExplicitlyTrashed()"> - {@code isExplicitlyTrashed()}</a> method indicates whether a resource was trashed directly, - or as the result of a trashed parent. - <ul> - <li><a href="https://developers.google.com/drive/android/trash.html" - class="external-link">Trashing and untrashing developer guide</a></li> - </ul> - </li> - <li><strong>SafetyNet API</strong> - The API lets you check if your app is running on a device - that matches a device model that has passed Android compatibility testing. The API evaluates - both software and hardware characteristics of a device to determine whether it matches a - known-good configuration that has been previously determined to be compatible. You can use the - SafetyNet API in conjunction with other tools to determine whether the device appears capable - of handling specific features in your app. - <ul> - <li><a href="{@docRoot}reference/com/google/android/gms/safetynet/package-summary.html"> - SafetyNet API reference</a></li> - <li><a href="{@docRoot}google/play/safetynet/index.html"> - SafetyNet developer guide</a></li> - </ul> - </li> -</ul> -</dd> -</dl> - </div> -</div> - -<div class="toggle-content closed"> - <p><a href="#" onclick="return toggleContent(this)"> - <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" - alt=""/>Google Play services, Version 6.5</a> <em>(December 2014)</em> - </p> - - <div class="toggle-content-toggleme"> -<dl> -<dt>Highlights in Version 6.5</dt> - -<dd> -<p>For a summary of the feature highlights in Google Play services 6.5, see the -announcement -<a href="http://android-developers.blogspot.com/2014/11/google-play-services-65.html" -class="external-link">blog post</a>.</p> -<ul> - <li><strong>Maps</strong> - The new <em>lite mode</em> lets your app display a -bitmap image of a map, while still being able to control markers and shapes -client-side. This is particularly useful when you're showing a number of small -maps. You can enable or disable a new map toolbar that lets users open -<a href="https://www.google.com/maps" class="external-link">Google Maps</a> and -get directions and turn by turn navigation to the selected marker. The -{@code getMap()} method in -<a href="{@docRoot}reference/com/google/android/gms/maps/MapView.html">{@code MapView}</a> -and -<a href="{@docRoot}reference/com/google/android/gms/maps/MapFragment.html">{@code MapFragment}</a> -is now deprecated in favor of the new {@code getMapAsync()} method. Similarly, -the new {@code getStreetViewPanoramaAsync()} method in -<a href="{@docRoot}reference/com/google/android/gms/maps/StreetViewPanoramaView.html">{@code StreetViewPanoramaView}</a> and -<a href="{@docRoot}reference/com/google/android/gms/maps/StreetViewPanoramaFragment.html">{@code StreetViewPanoramaFragment}</a> -enables you to get a ready-to-use Street View panorama. - <ul> - <li><a href="https://developers.google.com/maps/documentation/android/lite.html" - class="external-link">Lite mode maps developer guide</a></li> - <li><a href="https://developers.google.com/maps/documentation/android/interactivity.html#toolbar" - class="external-link">Map toolbar developer guide</a></li> - </ul> - </li> - <li><strong>Drive</strong> - This release introduces support for inserting or - updating custom properties. You can now create empty files (for example, a user - preference file that is empty until the user defines some application property). - <ul> - <li><a href="{@docRoot}reference/com/google/android/gms/drive/metadata/CustomPropertyKey.html">{@code CustomPropertyKey} API reference</a></li> - <li><a href="https://developers.google.com/drive/android/create-file.html" - class="external-link">Creating empty files developer guide</a></li> - </ul> - </li> - <li><strong>Fit</strong> - The Fit API now supports activity segments - (<a href="{@docRoot}reference/com/google/android/gms/fitness/data/DataType.html#TYPE_ACTIVITY_SEGMENT">{@code DataType.TYPE_ACTIVITY_SEGMENT}</a>), which - enable you to represent pauses within a workout session and to annotate time - intervals inside a session with different fitness activities. - </li> - <li><strong>Wallet</strong> - You can now enable donations from your Android - app in the same way you enable purchases. To do so, create a - <a href="{@docRoot}reference/com/google/android/gms/wallet/fragment/WalletFragment.html">{@code WalletFragment}</a> and specify the - <a href="{@docRoot}reference/com/google/android/gms/wallet/fragment/WalletFragmentMode.html#BUY_BUTTON">{@code BUY_BUTTON}</a> - mode, then set the button text to - <a href="{@docRoot}reference/com/google/android/gms/wallet/fragment/BuyButtonText.html#DONATE_WITH_GOOGLE">{@code DONATE_WITH_GOOGLE}</a>. - <p class="note"><strong>Note:</strong> Use of the <em>Donate with Google</em> - button is limited to 501(c)(3) organizations. For more information, see the - <a href="https://support.google.com/wallet/business/answer/75724?hl=en&rd=1" class="external-link">Content policies</a>.</p> - <ul> - <li><a href="https://developers.google.com/wallet/instant-buy/android/tutorial.html" class="external-link">Setting button text developer guide</a></li> - </ul> - </li> - <li><strong>Granular dependency management</strong> - If the number of - references in your app exceeds the - <a href="{@docRoot}tools/building/multidex.html">65K method reference limit</a>, - your app may fail to compile. To avoid this problem, you can include just - the specific Google Play services APIs your app uses, instead of all of them, - when compiling your app. For more details, see the Android Studio setup - instructions in - <a href="{@docRoot}google/play-services/setup.html">Setting Up Google Play Services</a>. - </li> - <li><strong>Deprecated clients</strong> - The {@code ActivityRecognitionClient}, - {@code LocationClient}, and {@code PlusClient} classes are deprecated. If - you used those APIs in your app and want to call Google Play services 6.5 - or higher APIs, you must switch to the new programming model that utilizes - <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code GoogleApiClient}</a>. For more information about using <a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html">{@code GoogleApiClient}</a>, see <a href="{@docRoot}google/auth/api-client.html">Accessing Google APIs</a>. - <p>Use these APIs instead of the deprecated APIs:</p> - <ul> - <li>If you were previously using {@code ActivityRecognitionClient}, call - <a href="{@docRoot}reference/com/google/android/gms/location/ActivityRecognition.html">{@code ActivityRecognition}</a> instead.</li> - <li>If you were previously using {@code LocationClient}, call the APIs in the - <a href="{@docRoot}reference/com/google/android/gms/location/package-summary.html">{@code com.google.android.gms.location} package</a> instead.</li> - <li>If you were previously using {@code PlusClient}, call the APIs in the - <a href="{@docRoot}reference/com/google/android/gms/plus/package-summary.html">{@code com.google.android.gms.plus} package</a> instead.</li> - </ul> - </li> -</ul> -</dd> -</dl> - </div> -</div> - -<div class="toggle-content closed"> - <p><a href="#" onclick="return toggleContent(this)"> - <img src="{@docRoot}assets/images/triangle-closed.png" - class="toggle-content-img" - alt=""/>Google Play services, Version 6.1</a> <em>(October 2014)</em> - </p> - - <div class="toggle-content-toggleme"> -<dl> -<dt>Highlights in Version 6.1</dt> - -<dd> -<p>For a summary of the feature highlights in Google Play services 6.1, see the -announcement -<a href="http://android-developers.blogspot.com/2014/09/google-play-services-61.html" -class="external-link">blog post</a>.</p> -<ul> - <li><strong>Drive</strong> - This release adds the - <a href="{@docRoot}reference/com/google/android/gms/drive/events/CompletionEvent.html"> - <code>CompletionEvent</code></a> class to notify you when actions are - committed to the server and respond to conflicts. Recent and starred views - are now available in the file picker user interface provided by - <a href="{@docRoot}reference/com/google/android/gms/drive/OpenFileActivityBuilder.html"> - <code>OpenFileActivityBuilder</code><a/>, and the user interface has been - updated to use - <a href="http://www.google.com/design/spec/material-design/introduction.html" - class="external-link">material design</a>. A new - <a href="{@docRoot}reference/com/google/android/gms/drive/DriveResource.html#setParents(com.google.android.gms.common.api.GoogleApiClient, java.util.Set<com.google.android.gms.drive.DriveId>)"> - DriveResource.setParents()</a> method makes it possible to organize files - and folders. In addition, the - <a href="{@docRoot}reference/com/google/android/gms/drive/Contents.html"> - <code>Contents</code></a> - class has been replaced with a - <a href="{@docRoot}reference/com/google/android/gms/drive/DriveContents.html"> - <code>DriveContents</code></a> class that simplifies working with file - contents. - <ul> - <li><a href="https://developers.google.com/drive/release-notes" - class="external-link">Drive SDK release notes</a></li> - <li><a href="https://developers.google.com/drive/android/completion" - class="external-link">Completion events developer guide and Google - Developers video</a></li> - <li><a href="https://developers.google.com/drive/android/intro?hl=pt-PT#activity_builders" - class="external-link">Using the OpenFileActivity Builder</a></li> - </ul> - </li> - - <li><strong>Tag Manager</strong> - Google Tag Manager now supports - <a href="https://developers.google.com/analytics/devguides/collection/android/v4/enhanced-ecommerce" - class="external-link">Enhanced Ecommerce</a> through the - <a href="https://support.google.com/tagmanager/answer/3281379" - class="external-link">Universal Analytics tag</a>. - <ul> - <li><a href="https://developers.google.com/analytics/devguides/collection/upgrade/" - class="external-link">Universal Analytics Upgrade Center</a></li> - <li><a href="https://developers.google.com/tag-manager/android/v4/" - class="external-link">Enhanced Ecommerce developer guide</a></li> - </ul> - </li> - - <li><strong>Fit</strong> - The Google Fit developer preview, initially - <a href="http://googledevelopers.blogspot.com/2014/08/google-fit-preview-sdk-now-available.html" - class=""external-link>announced</a> in August, has been - refreshed to enable you to test your new fitness apps on any Android device. - <ul> - <li><a href="https://developers.google.com/fit/preview" - class="external-link">Google Fit developer guide</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/fitness/package-summary.html"> - Fit API reference</a></li> - </ul> - </li> - -</ul> -</dd> -</dl> - - </div> -</div> - -<div class="toggle-content closed"> - <p><a href="#" onclick="return toggleContent(this)"> - <img src="{@docRoot}assets/images/triangle-closed.png" - class="toggle-content-img" - alt=""/>Google Play services, Version 5.0</a> <em>(July 2014)</em> - </p> - - <div class="toggle-content-toggleme"> -<dl> -<dt>Highlights in Version 5.0</dt> - -<dd> -<p>For a summary of the feature highlights in Google Play services 5.0, see the -announcement -<a href="http://android-developers.blogspot.com/2014/07/google-play-services-5.html" -class="external-link">blog post</a>.</p> -<ul> - <li><strong>Analytics</strong> - The Enhanced Ecommerce API allows your app -to send product related information and actions to Google Analytics. Use this -API to measure impressions of products seen by users, checkout steps, and -products purchased. This information can be analyzed for the effectiveness of -marketing and merchandising efforts, including the impact of internal -promotions, coupons, and affiliate marketing programs. - <ul> - <li><a href="https://developers.google.com/analytics/devguides/collection/android/v4/enhanced-ecommerce.html" class="external-link">Enhanced Ecommerce developer guide</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/analytics/ecommerce/package-summary.html">Enhanced Ecommerce API reference</a></li> - </ul> - </li> - - <li><strong>App Indexing</strong> - The App Indexing API provides a way -for developers to notify Google about deep links in their native apps and -allows the Google Search App, version 3.6 and above, to drive re-engagement -through Google Search -<a href="https://support.google.com/websearch/answer/106230" -class="external-link">query autocompletions</a>, providing fast and easy access to -inner pages in apps. - <ul> - <li><a href="https://developers.google.com/app-indexing/webmasters/appindexingapi.html" -class="external-link">App Indexing developer guide</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/appindexing/package-summary.html">App -Indexing API reference</a></li> - </ul> - </li> - - <li><strong>Drive</strong> - The Query APIs now allow your app to retrieve -Drive files by sorted order, according to a developer-specified sorting criteria. - <ul> - <li><a href="https://developers.google.com/drive/android/queries.html" -class="external-link">Queries developer guide</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/drive/query/package-summary.html">Sortable -queries API reference</a></li> - </ul> - </li> - - <li><strong>Play Games</strong> - This release introduces the Quests and -Saved Games services. The Quests service gives you the ability to issue -time-bound in-game challenges based on Events data sent from your game, without -republishing your game (for example: Your game sends an event each time a -“gem” is found by a player, and you create a quest to “Find 20 gems”). Players -can complete a quest to earn rewards. Saved Games offers improved functionality -for saving game state information and visually displaying player game progression. - <ul> - <li><a href="https://developers.google.com/games/services/android/quests.html" -class="external-link">Events and Quests developer guide</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/games/event/package-summary.html">Events -API reference</a></a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/games/quest/package-summary.html">Quests -API reference</a></a></li> - <li><a href="https://developers.google.com/games/services/android/savedgames.html" -class="external-link">Saved Games developer guide</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/games/snapshot/package-summary.html">Saved -Games API reference</a></a></li> - </ul> - </li> - - <li><strong>Security</strong> - The Security API allows you to easily -install a dynamic security provider. New versions of Google Play Services will -keep the security provider up-to-date with the latest security fixes as those -become available. - <ul> - <li><a href="{@docRoot}reference/com/google/android/gms/security/package-summary.html">Security -API reference</a></li> - </ul> - </li> - - <li><strong>Wallet</strong> - The Save to Google API for Android lets users -save Wallet Objects to their Google Wallet with the click of a button displayed -in your Android app. - <ul> - <li><a href="https://developers.google.com/wallet/objects/savetowalletnative.html" -class="external-link">Save to Google API for Android tutorial</a></li> - </ul> - </li> - - - <li><strong>Wearables</strong> - The Wearable Data Layer API provides a - communication channel between your handheld and wearable apps. The API - consists of a set of data objects that the system can send and synchronize - and listeners that notify your apps of important events from the other - device. - <ul> - <li><a href="{@docRoot}training/wearables/apps/index.html">Building -Wearable Apps training class</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/wearable/package-summary.html">Wearables -API reference</a></li> - </ul> - </li> - -</ul> -</dd> -</dl> - - </div> -</div> - -<div class="toggle-content closed"> - <p><a href="#" onclick="return toggleContent(this)"> - <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" - alt=""/>Google Play services, Version 4.4</a> <em>(May 2014)</em> - </p> - - <div class="toggle-content-toggleme"> -<dl> -<dt>Highlights in Version 4.4</dt> - -<dd> -<p>For a summary of the feature highlights in Google Play services 4.4, see the -announcement <a href="http://android-developers.blogspot.com/2014/05/google-play-services-44.html" class="external-link">blog post</a>.</p> -<ul> - <li><strong>Maps</strong> - New features for Street View and enhanced control of - Indoor Maps. - <ul> - <li><a href="http://developers.google.com/maps/documentation/android/streetview.html" class="external-link">Street View developer guide</a> - Add Street View to your app and programmatically control - the user’s experience. - <li><a href="http://developers.google.com/maps/documentation/android/map.html#indoor_maps" class="external-link">Indoor Maps developer guide</a> - Customize the level picker - and specify the active level of a building.</a> - </ul> - </li> - - <li><strong>Activity recognition</strong> - The Location API has been updated with new activity detectors for running and walking. - <ul> - <li><a href="{@docRoot}reference/com/google/android/gms/location/DetectedActivity.html"><code>DetectedActivity</code> class reference</a> - </ul> - </li> - - <li><strong>Mobile Ads</strong> - The new in-app purchase APIs allow - publishers to display in-app purchase ads, which enables users to purchase - advertised items directly. - <ul> - <li><a href="https://developers.google.com/mobile-ads-sdk/docs/admob/advanced#play-inapppurchaselistener" class="external-link">In-app purchase APIs developer guide</a> - - Enable in-app purchases via ads by using the in-app purchase APIs. - <li><a href="{@docRoot}reference/com/google/android/gms/ads/purchase/package-summary.html">In-app purchase API reference</a> - </ul> - </li> - - <li><strong>Wallet Fragment</strong> - The new Wallet Fragment API allows you - to easily integrate Google Wallet Instant Buy with an existing app. - <ul> - <li><a href="http://developers.google.com/wallet/instant-buy/android/tutorial.html#about_walletfragment" class="external-link">About Wallet Fragment</a> - Tutorial showing how to - use wallet fragment to handle user events and to automate key parts of the purchase lifecycle. - <li><a href="http://developers.google.com/wallet/instant-buy/diagrams.html#detailed_api_process_flow" class="external-link">Detailed API process flow</a></a> - </ul> - </li> -</ul> -</dd> -</dl> - - </div> -</div> - -<div class="toggle-content closed"> - <p><a href="#" onclick="return toggleContent(this)"> - <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" - alt=""/>Google Play services, Version 4.3</a> <em>(March 2014)</em> - </p> - - <div class="toggle-content-toggleme"> -<dl> -<dt>Highlights in Version 4.3</dt> -<dd> -<p>For a summary of the feature highlights in Google Play services 4.3, see the -announcement <a href="http://android-developers.blogspot.com/2014/03/google-play-services-43.html" class="external-link">blog post</a>.</p> -<ul> -<li><strong>Play Games</strong> - The new Game Gifts API enables games to send virtual in-game requests to anyone in a player’s circles or through player search. - <ul> - <li><a href="http://developers.google.com/games/services/android/giftRequests.html" class="external-link">Developing Game Gifts in Android</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/games/request/package-summary.html">Game Gifts API reference</a></li> - </ul> -</li> -<li><strong>Analytics</strong> - Google Analytics and Tag Manager are now part of Google Play services. - <ul> - <li><a href="http://developers.google.com/analytics/devguides/collection/android/v4/" class="external-link">Getting Started with the Analytics API in Android</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/analytics/package-summary.html">Analytics API reference</a></li> - <li><a href="http://developers.google.com/tag-manager/android/" class="external-link">Getting Started with the Tag Manager API in Android</a></li> - <li><a href="{@docRoot}reference/com/google/android/gms/tagmanager/package-summary.html">Tag Manager API reference</a></li> - </ul> -</li> -<li><strong>Drive</strong> - Change notifications, offline content, and more. - <ul> - <li><a href="http://developers.google.com/drive/android/pinning.html" class="external-link">Pinning Files</a> - Make files available offline.</li> - <li><a href="http://developers.google.com/drive/android/events.html" class="external-link">Listening for Change Events</a> - Receive notifications for change events asynchronously.</li> - <li><a href="http://developers.google.com/drive/android/appfolder.html" class="external-link">Storing Application Data</a> - Store application data in a special hidden folder.</li> - </ul> -</li> -<li><strong>Address</strong> - Let your users provide complete addresses in a single click. - <ul> - <li><a href="{@docRoot}reference/com/google/android/gms/identity/intents/package-summary.html">Address API reference</a> </li> - </ul> -</li> -</ul> -</dd> -</dl> - </div> -</div> - -<h2>How It Works</h2> - -<h4 id="client-lib">The Google Play services client library</h4> -<p> - The client library contains the interfaces to the individual Google - services and allows you to obtain authorization from users to gain access - to these services with their credentials. It also contains APIs that allow - you to resolve any issues at runtime, such as a missing, disabled, or out-of-date - Google Play services APK. The client library has a light footprint if you use - <a href="/tools/help/proguard.html">ProGuard</a> as part of your build process, so it won't have - an adverse impact on your app's file size. -</p> -<p> - If you want to access added features or products, you can upgrade to a new version of the - client library as they are released. However, upgrading is not - necessary if you don't care about new features or bug fixes. - We anticipate more Google services to be continuously added, so be on the lookout for - these updates. -</p> - -<div class="vspace size-2"> </div> - -<div class="cols"> - <div class="col-6"> - <h4 id="apk">The Google Play services APK</h4> - <p> - The Google Play services APK contains the individual Google services and runs - as a background service in the Android OS. You interact with the background service - through the client library and the service carries out the actions on your behalf. - An easy-to-use authorization flow is also - provided to gain access to the each Google service, which provides consistency for both - you and your users. - </p> - <p> - The Google Play services APK is delivered through the Google Play Store, so - updates to the services are not dependent on carrier or OEM system image updates. In general, devices - running Android 2.3 (Gingerbread) or later and have the Google Play Store app installed receive updates within a - few days. This allows you to use the newest APIs in Google Play services and reach most of the - devices in the Android ecosystem (devices older than Android 2.3 or devices without the Google - Play Store app are not supported). - </p> - </div> - - <div class="col-6"> - <img src="/images/play-services-diagram.png" /> - <p class="img-caption"><em>The Google Play services APK on user devices receives regular updates - for new APIs, features, and bug fixes.</em></p> - </div> -</div> - -<h4 id="benefits">The benefits for your app</h4> - -<p>Google Play services gives you the freedom to use the newest APIs for popular -Google services without worrying about device support. Updates to Google Play -services are distributed automatically by the Google Play Store and new versions -of the client library are delivered through the Android SDK Manager. This makes it -easy for you to focus on what's important: your users' experience.</p> - -<p>To get started, <a href="{@docRoot}google/play-services/setup.html">set up</a> the SDK and check out -the various products in the Google Play services platform now!</p> diff --git a/docs/html/google/play-services/setup.jd b/docs/html/google/play-services/setup.jd deleted file mode 100644 index 313e591..0000000 --- a/docs/html/google/play-services/setup.jd +++ /dev/null @@ -1,398 +0,0 @@ -page.title=Setting Up Google Play Services -@jd:body - - - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>In this document</h2> -<ol> - <li><a href="#Setup">Add Google Play Services to Your Project</a></li> - <li><a href="#Proguard">Create a ProGuard Exception</a></li> - <li><a href="#ensure">Ensure Devices Have the Google Play services APK</a></li> -</ol> - - -</div> -</div> - -<script> -$(document).ready(function() { - setupIdeDocToggle(); -}); -</script> - - -<p>To develop an app using the <a href="{@docRoot}reference/gms-packages.html">Google -Play services APIs</a>, you need to set up your project with the Google Play services SDK. -<p>If you haven't installed the Google Play services SDK yet, go get it now by following the guide -to <a href="{@docRoot}sdk/installing/adding-packages.html">Adding SDK Packages</a>.</p> - -<p>To test your app when using the Google Play services SDK, you must use either:</p> -<ul> - <li>A compatible Android - device that runs Android 2.3 or higher and includes Google Play Store.</li> - <li>The Android emulator with an <a href="{@docRoot}tools/devices/index.html">AVD</a> - that runs the Google APIs platform based on Android 4.2.2 or higher.</li> -</ul> - - - -<h2 id="Setup">Add Google Play Services to Your Project</h2> - -<p> -<select class="ide"> - <option value="studio">Using Android Studio</option> - <option value="eclipse">Using Eclipse with ADT</option> - <option value="other">Using something else</option> -</select> -</p> - - -<div class="select-ide studio"> -<p>To make the Google Play services APIs available to your app:</p> -<ol> - <li>Open the <code>build.gradle</code> file inside your application module directory. - <p class="note"><strong>Note:</strong> Android Studio projects contain a top-level - <code>build.gradle</code> file and a <code>build.gradle</code> file for each module. - Be sure to edit the file for your application module. See - <a href="{@docRoot}sdk/installing/studio-build.html">Building Your Project with - Gradle</a> for more information about Gradle.</p></li> - <li>Add a new build rule under <code>dependencies</code> for the latest version of -<code>play-services</code>. For example: -<pre class="no-pretty-print"> -apply plugin: 'com.android.application' -... - -dependencies { - compile 'com.android.support:appcompat-v7:21.0.3' - <strong>compile 'com.google.android.gms:play-services:7.3.0'</strong> -} -</pre> -<p>Be sure you update this version number each time Google Play services is updated.</p> -<p class="note"><strong>Note:</strong> If the number of method references in your app exceeds the -<a href="{@docRoot}tools/building/multidex.html">65K limit</a>, your app may fail to compile. You -may be able to mitigate this problem when compiling your app by specifying only the specific Google -Play services APIs your app uses, instead of all of them. For information on how to do this, -see <a href="#split">Selectively compiling APIs into your executable</a>. - - </li> - <li>Save the changes and click <strong>Sync Project with Gradle Files</strong> -<img src="{@docRoot}images/tools/sync-project.png" style="vertical-align:bottom;margin:0;height:19px" /> -in the toolbar. - </li> -</ol> - -<p>You can now begin developing features with the -<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p> - -<h3 id="split">Selectively compiling APIs into your executable</h3> - -<p>In versions of Google Play services prior to 6.5, you had to compile the entire package of APIs -into your app. In some cases, doing so made it more difficult to keep the number of methods -in your app (including framework APIs, library methods, and your own code) under the 65,536 limit.</p> - -<p>From version 6.5, you can instead selectively compile Google Play service APIs into your app. For -example, to include only the Google Fit and Android Wear APIs, replace the following line in your -<code>build.gradle</code> file:</p> - -<pre class="no-pretty-print"> -compile 'com.google.android.gms:play-services:7.3.0' -</pre> - -<p>with these lines:</p> - -<pre class="no-pretty-print"> -compile 'com.google.android.gms:play-services-fitness:7.3.0' -compile 'com.google.android.gms:play-services-wearable:7.3.0' -</pre> - -<p>Table 1 shows a list of the separate APIs that you can include when compiling your app, and -how to describe them in your <code>build.gradle</code> file. Some APIs do not have a separate -library; include them by including the base library. (This lib is automatically included when -you include an API that does have a separate library.)</p> - -<p class="table-caption" id="table1"> -<strong>Table 1.</strong> Individual APIs and corresponding <code>build.gradle</code> descriptions.</p> - -<table> - <tr> - <th scope="col">Google Play services API</th> - <th scope="col">Description in <code>build.gradle</code></th> - </tr> - <tr> - <td>Google+</td> - <td>com.google.android.gms:play-services-plus:7.3.0</td> - </tr> - <tr> - <td>Google Account Login</td> - <td>com.google.android.gms:play-services-identity:7.3.0</td> - </tr> - <tr> - <td>Google Actions, Base Client Library</td> - <td>com.google.android.gms:play-services-base:7.3.0</td> - </tr> - <tr> - <td>Google App Indexing</td> - <td>com.google.android.gms:play-services-appindexing:7.3.0</td> - </tr> - <tr> - <td>Google Analytics</td> - <td>com.google.android.gms:play-services-analytics:7.3.0</td> - </tr> - <tr> - <td>Google Cast</td> - <td>com.google.android.gms:play-services-cast:7.3.0</td> - </tr> - <tr> - <td>Google Cloud Messaging</td> - <td>com.google.android.gms:play-services-gcm:7.3.0</td> - </tr> - <tr> - <td>Google Drive</td> - <td>com.google.android.gms:play-services-drive:7.3.0</td> - </tr> - <tr> - <td>Google Fit</td> - <td>com.google.android.gms:play-services-fitness:7.3.0</td> - </tr> - <tr> - <td>Google Location, Activity Recognition, and Places</td> - <td>com.google.android.gms:play-services-location:7.3.0</td> - </tr> - <tr> - <td>Google Maps</td> - <td>com.google.android.gms:play-services-maps:7.3.0</td> - </tr> - <tr> - <td>Google Mobile Ads</td> - <td>com.google.android.gms:play-services-ads:7.3.0</td> - </tr> - <tr> - <td>Google Nearby</td> - <td>com.google.android.gms:play-services-nearby:7.3.0</td> - </tr> - <tr> - <td>Google Panorama Viewer</td> - <td>com.google.android.gms:play-services-panorama:7.3.0</td> - </tr> - <tr> - <td>Google Play Game services</td> - <td>com.google.android.gms:play-services-games:7.3.0</td> - </tr> - <tr> - <td>SafetyNet</td> - <td>com.google.android.gms:play-services-safetynet:7.3.0</td> - </tr> - <tr> - <td>Google Wallet</td> - <td>com.google.android.gms:play-services-wallet:7.3.0</td> - </tr> - <tr> - <td>Android Wear</td> - <td>com.google.android.gms:play-services-wearable:7.3.0</td> - </tr> -</table> - -<p class="note"><strong>Note:</strong> ProGuard directives are included in the Play services -client libraries to preserve the required classes. The -<a href="{@docRoot}tools/building/plugin-for-gradle.html">Android Plugin for Gradle</a> -automatically appends ProGuard configuration files in an AAR (Android ARchive) package and appends -that package to your ProGuard configuration. During project creation, Android Studio automatically -creates the ProGuard configuration files and <code>build.gradle</code> properties for ProGuard use. -To use ProGuard with Android Studio, you must enable the ProGuard setting in your -<code>build.gradle</code> <code>buildTypes</code>. For more information, see the -<a href="{@docRoot}tools/help/proguard.html">ProGuard</a> topic. </p> - - -</div><!-- end studio --> - -<div class="select-ide eclipse"> - -<p>To make the Google Play services APIs available to your app:</p> -<ol> - <li>Copy the library project at -{@code <android-sdk>/extras/google/google_play_services/libproject/google-play-services_lib/} - to the location where you maintain your Android app projects.</li> - <li>Import the library project into your Eclipse workspace. Click - <b>File > Import</b>, select <b>Android > Existing Android Code into -Workspace</b>, and browse to the copy of the library project to import it.</li> - <li>In your app project, reference Google Play services library project. See - <a href="{@docRoot}tools/projects/projects-eclipse.html#ReferencingLibraryProject"> - Referencing a Library Project for Eclipse</a> for more information on how to - do this. - <p class="note"><strong>Note:</strong> You should be referencing a copy of the - library that you copied to your development workspace—you should not - reference the library directly from the Android SDK directory.</p> - </li> - <li>After you've added the Google Play services library as a dependency for your app project, - open your app's manifest file and add the following tag as a child of the - <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> -element: - <pre> -<meta-data android:name="com.google.android.gms.version" - android:value="@integer/google_play_services_version" /> - </pre> - </li> -</ol> - -<p>Once you've set up your project to reference the library project, -you can begin developing features with the -<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p> - - -<h2 id="Proguard">Create a ProGuard Exception</h2> - -<p>To prevent <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> from stripping away -required classes, add the following lines in the -<code><project_directory>/proguard-project.txt</code> file: -<pre> --keep class * extends java.util.ListResourceBundle { - protected Object[][] getContents(); -} - --keep public class com.google.android.gms.common.internal.safeparcel.SafeParcelable { - public static final *** NULL; -} - --keepnames @com.google.android.gms.common.annotation.KeepName class * --keepclassmembernames class * { - @com.google.android.gms.common.annotation.KeepName *; -} - --keepnames class * implements android.os.Parcelable { - public static final ** CREATOR; -} -</pre> - - - -</div><!-- end eclipse --> - -<div class="select-ide other"> - -<p>To make the Google Play services APIs available to your app:</p> -<ol> - <li>Copy the library project at -{@code <android-sdk>/extras/google/google_play_services/libproject/google-play-services_lib/} -to the location where you maintain your Android app projects.</li> - - <li>In your app project, reference the Google Play services library project. See - <a href="{@docRoot}tools/projects/projects-cmdline.html#ReferencingLibraryProject">Referencing - a Library Project on the Command Line</a> for more information on how to do this. - <p class="note"><strong>Note:</strong> -You should be referencing a copy of the library that you copied to your development -workspace—you should not reference the library directly from the Android SDK directory.</p> - </li> - <li>After you've added the Google Play services library as a dependency for - your app project, open your app's manifest file and add the following tag as - a child of the - <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a> - element: - <pre> -<meta-data android:name="com.google.android.gms.version" - android:value="@integer/google_play_services_version" /> - </pre> - </li> -</ol> - -<p>Once you've set up your project to reference the library project, -you can begin developing features with the -<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p> - - -<h2 id="Proguard">Create a Proguard Exception</h2> - -<p>To prevent <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> from stripping away -required classes, add the following lines in the -<code><project_directory>/proguard-project.txt</code> file: -<pre> --keep class * extends java.util.ListResourceBundle { - protected Object[][] getContents(); -} - --keep public class com.google.android.gms.common.internal.safeparcel.SafeParcelable { - public static final *** NULL; -} - --keepnames @com.google.android.gms.common.annotation.KeepName class * --keepclassmembernames class * { - @com.google.android.gms.common.annotation.KeepName *; -} - --keepnames class * implements android.os.Parcelable { - public static final ** CREATOR; -} -</pre> - - -</div><!-- end other --> - - - -<h2 id="ensure">Ensure Devices Have the Google Play services APK</h2> - -<p>As described in the <a href="{@docRoot}google/play-services/index.html">Google Play services -introduction</a>, Google Play delivers service updates for users on -Android 2.3 and higher through the Google Play Store app. However, updates might not reach -all users immediately, so your app should verify the version available before attempting to -perform API transactions.</p> - -<p class="caution"> -<strong>Important:</strong> - Because it is hard to anticipate the state of each device, you must <em>always</em> check for a - compatible Google Play services APK before you access Google Play services - features. -</p> - -<p>Because each app uses Google Play services differently, it's up to you decide the appropriate -place in your app to verify the Google Play services version. For example, if Google Play -services is required for your app at all times, you might want to do it when your app first -launches. On the other hand, if Google Play services is an optional part of your app, you can check -the version only once the user navigates to that portion of your app.</p> - -<p>You are strongly encouraged to use the -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.html"> -{@code GoogleApiClient}</a> class to access Google Play services features. This approach allows -you to attach an -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.OnConnectionFailedListener.html"> -{@code OnConnectionFailedListener}</a> object to your client. -To detect if the device has the appropriate version of the Google Play services APK, implement the -<a href="{@docRoot}reference/com/google/android/gms/common/api/GoogleApiClient.OnConnectionFailedListener.html#onConnectionFailed(com.google.android.gms.common.ConnectionResult)"> -{@code onConnectionFailed()}</a> -callback method. If the connection fails due to a missing or out-of-date version of -the Google Play APK, the callback receives an error code such as -<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SERVICE_MISSING"> -{@code SERVICE_MISSING}</a>, -<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SERVICE_VERSION_UPDATE_REQUIRED"> -{@code SERVICE_VERSION_UPDATE_REQUIRED}</a>, or -<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SERVICE_DISABLED"> -{@code SERVICE_DISABLED}</a>. To learn more about how to build your client and handle such -connection errors, see <a href="{@docRoot}google/auth/api-client.html">Accessing Google APIs</a>. -</p> - -<p>Another approach is to use the -<a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#isGooglePlayServicesAvailable(android.content.Context)" ->{@code isGooglePlayServicesAvailable()}</a> method. You might call this method in the -{@link android.app.Activity#onResume onResume()} method of the main activity. If the result code is -<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SUCCESS" ->{@code SUCCESS}</a>, - then the Google Play services APK is up-to-date and you can continue to make a connection. -If, however, the result code is -<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SERVICE_MISSING" ->{@code SERVICE_MISSING}</a>, -<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SERVICE_VERSION_UPDATE_REQUIRED" ->{@code SERVICE_VERSION_UPDATE_REQUIRED}</a>, - or -<a href="{@docRoot}reference/com/google/android/gms/common/ConnectionResult.html#SERVICE_DISABLED" ->{@code SERVICE_DISABLED}</a>, then the user needs to install an update. In this case, call the -<a href="{@docRoot}reference/com/google/android/gms/common/GooglePlayServicesUtil.html#getErrorDialog(int, android.app.Activity, int)"> -{@code getErrorDialog()}</a> method and pass it the result error code. The method returns a -{@link android.app.Dialog} you should show, which provides an appropriate message about the error -and provides an action that takes the user to Google Play Store to install the update.</p> - - -<p>To then begin a connection to Google Play services (required by most Google APIs such -as Google Drive, Google+, and Games), read <a -href="{@docRoot}google/auth/api-client.html">Accessing Google APIs</a>.</p> |