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 {@code +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.
+ +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:
++Note: If you have an existing app that connects to Google Play services with a +subclass of {@code GooglePlayServicesClient}, you should migrate to {@code +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.
+ + + + +Once your project is linked to the Google Play services library, create an instance of {@code +GoogleApiClient} using the {@code +GoogleApiClient.Builder} APIs in your activity's {@link +android.app.Activity#onCreate onCreate()} method. The {@code +GoogleApiClient.Builder} 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 {@code +GoogleApiClient} instance that connects with the Google +Drive service:
++GoogleApiClient mGoogleApiClient = new GoogleApiClient.Builder(this) + .addApi(Drive.API) + .addScope(Drive.SCOPE_FILE) + .build(); ++ +
You can add multiple APIs and multiple scopes to the same {@code +GoogleApiClient} by appending +additional calls to +{@code addApi()} and +{@code addScope()}.
+ +However, before you can begin a connection by calling {@code connect()} on the {@code +GoogleApiClient}, you must specify an implementation for the callback interfaces, {@code ConnectionCallbacks} and {@code onConnectionFailedListener}. These interfaces receive callbacks in +response to the asynchronous {@code connect()} method when the connection to Google Play services +succeeds, fails, or becomes suspended.
+ +For example, here's an activity that implements the callback interfaces and adds them to the Google +API Client:
+ +
+import gms.common.api.*;
+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.
+ ...
+ }
+}
+
+
+With the callback interfaces defined, you're ready to call {@code connect()}. To gracefully manage +the lifecycle of the connection, you should call {@code connect()} during the activity's {@link +android.app.Activity#onStart onStart()} (unless you want to connect later), then call {@code disconnect()} during the {@link android.app.Activity#onStop onStop()} method. For example:
+
+ @Override
+ protected void onStart() {
+ super.onStart();
+ if (!mResolvingError) { // more about this later
+ mGoogleApiClient.connect();
+ }
+ }
+
+ @Override
+ protected void onStop() {
+ mGoogleApiClient.disconnect();
+ super.onStop();
+ }
+
+
+However, if you run this code, there's a good chance it will fail and your app will receive a call +to {@code onConnectionFailed()} with the {@code SIGN_IN_REQUIRED} error because the user account +has not been specified. The next section shows how to handle this error and others.
+ + + + +When you receive a call to the {@code onConnectionFailed()} callback, you should call {@code hasResolution()} on the provided {@code ConnectionResult} object. If it returns true, you can +request the user take immediate action to resolve the error by calling {@code startResolutionForResult()} on the {@code ConnectionResult} object. The {@code startResolutionForResult()} 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).
+ +If {@code hasResolution()} returns false, you should instead call {@code GooglePlayServicesUtil.getErrorDialog()}, 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).
+ +For example, your {@code onConnectionFailed()} callback method should now look like this:
+ +
+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();
+ }
+ }
+}
+
+
+Once the user completes the resolution provided by {@code startResolutionForResult()} or {@code GooglePlayServicesUtil.getErrorDialog()}, 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 {@code connect()} again. For example:
+ +
+@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();
+ }
+ }
+ }
+}
+
+
+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 {@code SIGN_IN_REQUIRED} 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 {@code connect()} again. This results in another call to {@code 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.
+ + + +To avoid executing the code in {@code 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.
+ +As shown in the code above, you should set a boolean to {@code true} each time you call {@code startResolutionForResult()} or display the dialog from {@code GooglePlayServicesUtil.getErrorDialog()}. 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}.
+ +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()}:
+ +
+private static final String STATE_RESOLVING_ERROR = "resolving_error";
+
+@Override
+protected void onSaveInstanceState(Bundle outState) {
+ super.onSaveInstanceState(outState);
+ outState.putBoolean(STATE_RESOLVING_ERROR, mResolvingError);
+}
+
+
+Then recover the saved state during {@link android.app.Activity#onCreate onCreate()}:
+ +
+@Override
+protected void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+
+ ...
+ mResolvingError = savedInstanceState != null
+ && savedInstanceState.getBoolean(STATE_RESOLVING_ERROR, false);
+}
+
+
+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 {@code +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. +
+ + + + +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 {@code +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 {@code +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 +{@code +PendingResult} object:
+ ++Query query = new Query.Builder() + .addFilter(Filters.eq(SearchableField.TITLE, filename)); +PendingResult result = Drive.DriveApi.query(mGoogleApiClient, query); ++ +
Once you have the +{@code +PendingResult}, you can continue by making the request either asynchronous +or synchronous.
+ + +To make the request asynchronous, call {@code setResultCallback()} on the +{@code +PendingResult} and +provide an implementation of the {@code ResultCallback} interface. For example, here's the request +executed asynchronously:
+ +
+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.
+ ...
+ }
+ });
+}
+
+
+When your app receives a {@code Result} +object in the {@code onResult()} callback, it is delivered as an instance of the +appropriate subclass as specified by the API you're using, such as {@code DriveApi.MetadataBufferResult}.
+ + +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 {@code await()} on the +{@code +PendingResult}. This blocks the thread and returns the {@code 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 {@code DriveApi.MetadataBufferResult}.
+ +Because calling {@code 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 {@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:
+ +
+private void loadFile(String filename) {
+ new GetFileTask().execute(filename);
+}
+
+private class GetFileTask extends AsyncTask {
+ 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
+ ...
+ }
+}
+
+
++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.
+ diff --git a/docs/html/google/auth/http-auth.jd b/docs/html/google/auth/http-auth.jd new file mode 100644 index 0000000000000..3b2a83f996280 --- /dev/null +++ b/docs/html/google/auth/http-auth.jd @@ -0,0 +1,534 @@ +page.title=Authorizing with Google for REST APIs +page.tags="oauth 2.0","GoogleAuthUtil" + +trainingnavtop=true +startpage=true + +@jd:body + + +GoogleAuth.zip
+When you want your Android app to access Google APIs using the user's Google account over +HTTP, the {@code GoogleAuthUtil} +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.
+ +You can then use that token in your HTTP-based communications with Google API services +that are not included in the Google Play +services library, such as the Blogger or Translate APIs.
+ +Note: An OAuth 2.0 token using {@code GoogleAuthUtil} +is required only for certain types of Google +APIs that you need to access over HTTP. If you're instead using the Google Play services library to access Google +APIs such as Google+ or Play Games, you don't need an OAuth 2.0 +token and you can instead access these services using the {@code GoogleApiClient}. For more +information, read Accessing Google Play +Services APIs.
+ +To get started with {@code GoogleAuthUtil} +for accessing Google's REST APIs, you must set up your Android app project with the Google Play +services library. Follow the procedures in Setup Google Play Services SDK.
+ + + + +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.
+ +Caution: While you are testing an APK that's signed with a +debug key, 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 +signed +with a release key.
+ +To register your Android app with Google Cloud Console:
+ +Note: The name you provide for the project is the name that +appears to users in the Google Settings app in the list of Connected apps.
+To get the SHA1 fingerprint for your app, run the following command in a terminal: +
+keytool -exportcert -alias <keystore_alias> -keystore <keystore_path> -list -v ++
For example, you're using a debug-key with Eclipse, then the command looks like this:
++keytool -exportcert -alias androiddebugkey-keystore ~/.android/debug.keystore -list -v ++
Then the keystore password is "android".
+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. + + +
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 +{@code +AccountPicker}. 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.
+ +Note: 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 Setup Google Play Services SDK.
+ + + +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 +{@code AccountPicker.newChooseAccountIntent}.
+ + +For example:
+
+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);
+}
+
+
+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.
+ +Most apps should pass the +{@code newChooseAccountIntent()} method the same arguments shown in the above example, +which indicate that:
+ + +For more details about these arguments, see the +{@code newChooseAccountIntent()} method documentation.
+ + + + +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.
+ +Here's an example implementation of the callback {@link android.app.Activity#onActivityResult +onActivityResult()} that receives the selected account:
+ ++String mEmail; // Received from {@code newChooseAccountIntent()}; passed to {@code getToken()} + +@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... +} ++ +
You can now pass the account name held by {@code mEmail} to +{@code GoogleAuthUtil.getToken()} (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.
+ + +Once you have retrieved the account name for the user's Google account, you can call +{@code GoogleAuthUtil.getToken()}, which returns the access token string required by Google API +services.
+ + +Calling this method is generally a straightforward procedure, but you must be +aware that:
+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.
+ +Note: The code shown in this lesson, using {@code GoogleAuthUtil.getToken()}, +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 {@code +getTokenWithNotification()}. This method works the same as {@code GoogleAuthUtil.getToken()}, but if an error occurs, it +also creates an appropriate +notification +that allows the user can recover from the error. +The sample available for download above includes code showing how to use this method instead.
+ + +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 Keeping Your +App Responsive and the {@link android.os.AsyncTask} class reference.
+ + +The {@link android.os.AsyncTask#doInBackground doInBackground()} method in your {@link +android.os.AsyncTask} class is where you should call the +{@code GoogleAuthUtil.getToken()} method. You can also use it to catch some of the generic +exceptions that may occur during your network transactions.
+ +For example, here's part of an {@link android.os.AsyncTask} subclass that calls +{@code GoogleAuthUtil.getToken()}:
+ +