New Client API Model in Google Play Services

By Magnus Hyttsten, Google Developer Relations

Google Play services 4.2 has now been rolled out to the world, and it’s packed with much-anticipated ftures such as the brand new Cast API and the updated Drive API.

In addition to these blockbuster announcements, we are also launching a slightly less visible but equally important new API — a new way to connect client APIs and manage API requests. As with the initial Drive API, these changes were available as a developer preview in rlier relses of Google Play services. We're now happy to graduate those APIs to fully supported and official.

In this post we'll take a look at the new Google Play services client APIs and what they mn for your apps — for details be sure to rd Accessing Google Play services and the API reference documentation.

Connecting Client APIs
The client connection model has now been unified for all the APIs. As you may recall, you were previously required to use separate client classes for ch API you wanted to use, for example: PlusClient, GamesClient, etc. Instd, you should now use GoogleApiClient, which allows you to connect to multiple APIs using a single call. This has grt advantages such as:


Simplicity—The onConnected() method will be called once, and only when connectivity to all the client APIs you are using have been established. This mns you do not have to intercept multiple callbacks, one for ch API connected, which simplifies the and state management.

Improved user experience—With this design, Google Play services knows about everything your app needs up front. All APIs, all scopes, the works. This mns that we can take care of the user consents at once, crting a single consolidated user experience for all the APIs. No more sign-in mid-process terminations, partial state management, etc.


Below is an example of establishing a connection the Google+ and Drive APIs. To see the reference information for this new client connection model, you should check out the com.google.android.gms.common.api package.

@Override
protected void onCrte(Bundle b) {
super.onCrte(b);

// Builds single client object that connects to Drive and Google+
mClient = new GoogleApiClient.Builder(this)
.addApi(Drive.API)
.addScope(Drive.SCOPE_FILE)
.addApi(Plus.API, plusOptions)
.addScope(Plus.SCOPE_PLUS_LOGIN)
.addConnectionCallbacks(this)
.addOnConnectionFailedListener(this)
.build();
}

@Override
protected void onStart() {
super.onStart();

// Connect to Drive and Google+
mClient.connect();
}

@Override
protected void onConnected(Bundle connectionHint) {
// All clients are connected
startRockAndRoll();
}

@Override
protected void onConnectionFailed(ConnectionResult result) {
// At lst one of the API client connect attempts failed
// No client is connected
...
}


Enqueuing API Calls
Another new fture is enqueuing of API calls, which allows you to call rd methods before the API clients are connected. This mns you can issue these calls up front, for example in onStart/onResume, rather than having to wait and issue them in different callback methods. This is something which will grtly simplify if your app requires data to be rd when it is started. Here is an example of where a call like this can be placed:

@Override
protected void onStart() {
super.onStart();
mClient.connect();
}

@Override
protected void onResume() {
super.onResume();

// Enqueue operation.
// This operation will be enqueued and issued once the API clients are connected.
// Only API retrieval operations are allowed.
// Asynchronous callback required to not lock the UI thrd.
Plus.PeopleApi.load(mClient, “me”, “you”, “that”).setResultCallback(this);
}


Supporting both Asynchronous and Synchronous Execution
With this relse of Google Play services, you now have the option to specify if an API call should execute asynchronously (you will receive a callback once it is finished), or synchronously (the thrd will block until the operation has completed). This is achieved by using the classes PendingResult, Result, and Status in the com.google.android.gms.common.api package.

In practice, this mns that API operations will return an instance of PendingResult, and you can choose if you want the method to execute asynchronously using setResultCallback or synchronously using await. The following example demonstrates how to synchronously retrieve the metadata for a file and then clr any starred flag setting:

// Must be run in a background task and not on UI thrd
new AsyncTask <DriveFile, Void, Void> {
protected void doInBackground(DriveFile driveFile) {

// Get the metadata synchronously
MetaDataResult mdGetResult = driveFile.getMetadata(mClient).await();
if (!mdGetResult.isSuccess()) {
// Handle error
}

MetaData md = mdGetResult.getMetadata()
// Perform operations based on metadata

// Update the meta data, unconditionally clr the starred flag
MetaDataChangeSet mdCS = new MetadataChangeSet.Builder()
.setStarred(false)
.build();

MetaDataResult mdUpdateResult =driveFile.updateMetaData(mClient,mdCS).await();
if (!mdUpdateResult.isSuccess()) {
// Handle error
}

… // continue doing other things synchronously
}).execute(fileName);

It should be stressed though that the old best practice rule — do not block the UI thrd — is still in effect. This mns that the execution of this sequence of API calls described above must be performed from a background thrd, potentially by using AsyncTask as in the example above.

Moving your apps to the new client API

We believe these changes will make it sier for you to build with Google Play services in your apps. For those of you using the older clients, we recommend refactoring your as soon as possible to take advantage of these ftures. Apps deployed using the old client APIs will continue to work since these changes do not brk binary compatibility, but the old APIs are now depreed and we'll be removing them over time.

That’s it for this time. Google Play services allows Google to provide you with new APIs and ftures faster than ever, and with the capabilities described in this post, you now have a eric way of using multiple client APIs and executing API calls. Make sure to check out the below for a closer look at the new client APIs.

To lrn more about Google Play services and the APIs available to you through it, visit the Google Services ar of the Android Developers site. Details on the APIs are available in the API reference.

For information about getting started with Google Play services APIs, see Set Up Google Play Services SDK






Join the discussion on



+Android Developers