In this document

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 GoogleApiClient ("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.

Connecting to REST APIs

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 Authorizing with Google
for REST APIs.

This guide shows how you can use Google API Client to:

Connect to one or more Google Play services asynchronously and handle failures.

Perform synchronous and asynchronous API calls to any of the Google Play services.

Note: If you have an existing app that connects to Google Play services with a
subclass of GooglePlayServicesClient, you should migrate to GoogleApiClient as soon as possible.

Figure 1. 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.

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 Set Up Google
Play Services SDK.

With the callback interfaces defined, you're ready to call connect(). To gracefully manage
the lifecycle of the connection, you should call connect() during the activity's onStart() (unless you want to connect later), then call disconnect() during the onStop() method. For example:

However, if you run this code, there's a good chance it will fail and your app will receive a call
to onConnectionFailed() with the SIGN_IN_REQUIRED error because the user account
has not been specified. The next section shows how to handle this error and others.

If hasResolution() returns false, you should instead call GooglePlayServicesUtil.getErrorDialog(), passing it the error code. This returns a 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).

In the above code, you probably noticed the boolean, 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 SIGN_IN_REQUIRED error, the user may rotate the screen. This recreates your activity and causes
your onStart() method to be called again, which then calls connect() again. This results in another call to startResolutionForResult(), which
creates another account picker dialog in front of the existing one.

This boolean is effective only
if retained across activity instances, though. The next section explains further.

Maintain state while resolving an error

To avoid executing the code in
onConnectionFailed() 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.

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 GoogleApiClient is discussed in the next section.

For more information about each services's APIs available once you're connected,
consult the corresponding documentation, such as for
Google Play Games or
Google Drive.

Access the Wearable API

On devices that do not have the Android
Wear app installed, connection requests that include the Wearable API fail with the API_UNAVAILABLE error code. If your app uses the Wearable API in addition to other Google APIs, use a separate GoogleApiClient instance to access the Wearable API. This approach enables you to access other Google APIs on devices that are not
paired with a wearable device.

When you use a separate GoogleApiClient instance to access only the Wearable API, you can determine
whether the Android
Wear app is installed on the device:

Communicate with Google Services

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 GoogleApiClient instance.

Note: 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 Google Drive or Google+.

When you perform a read or write request using Google API Client, the immediate result is returned
as a PendingResult object. This is an object representing the request, which hasn't yet
been delivered to the Google service.

For example, here's a request to read a file from Google Drive that provides a
PendingResult object:

Using synchronous calls

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 await() on the
PendingResult. This blocks the thread and returns the Result 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 DriveApi.MetadataBufferResult.

Because calling await() 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 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:

Tip: 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.