From 28f2ba8e30d774859b38e91a3f1ab91e31a69caf Mon Sep 17 00:00:00 2001 From: Quddus Chong Date: Tue, 26 May 2015 14:21:05 -0700 Subject: docs: Remove Google Play Services pages under Develop > Google Services. Cherry-pick from Change-Id: I392075b58bebc5556f306c2d20987811efe90b13 Change-Id: I17ad018a0875b653c0706fd9bbe5f637760cdfbc --- docs/html/google/auth/api-client.jd | 654 ------------------------------------ docs/html/google/auth/http-auth.jd | 558 ------------------------------ 2 files changed, 1212 deletions(-) delete mode 100644 docs/html/google/auth/api-client.jd delete mode 100644 docs/html/google/auth/http-auth.jd (limited to 'docs/html/google/auth') 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 - -
- -
- - -

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.

- -
-

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:

- - -

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

- - - - -

Start a Connection

- -

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()}.

- -

-Important: If you are adding multiple APIs to a -GoogleApiClient, -you may run into client connection errors on devices that do not have the -Android -Wear app installed. To avoid connection errors, call the -{@code addApiIfAvailable()} -method and pass in the {@code -Wearable} API to indicate that your client should gracefully handle the missing API. -For more information, see Access the Wearable API.

- -

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 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.
-        ...
-    }
-}
-
- -

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.

- - -

Handle connection failures

- -

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.

- - - -

Maintain state while resolving an error

- -

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

- - -

Access the Wearable API

- -

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 -{@code Wearable} -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: -

- - - -

Using only the Wearable API

- -

If your app uses the -{@code Wearable} -API but not other Google APIs, you can add this API by calling the -{@code addApi()} method. The following example shows how to add the -{@code Wearable} -API to your {@code -GoogleApiClient} instance:

- -
-GoogleApiClient mGoogleApiClient = new GoogleApiClient.Builder(this)
-    .addApi(Wearable.API)
-    .build();
-
- -

In situations where the -{@code Wearable} -API is not available, connection requests that include the {@code -Wearable} API fail with the -API_UNAVAILABLE error code.

- -

-The following example shows how to determine whether the -{@code Wearable} -API is available: -

- -
-// 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
-    }
-    ...
-}
-
- - -

Using the Wearable API with other APIs

- -

-If your app uses the -{@code Wearable} -API in addition to other Google APIs, call the -addApiIfAvailable() -method and pass in the -{@code Wearable} -API to indicate that your client should gracefully handle the missing API.

- -

The following example shows how to access the -{@code Wearable} -API along with the -{@code Drive} -API:

- -
-// Create a GoogleApiClient instance
-mGoogleApiClient = new GoogleApiClient.Builder(this)
-        .addApi(Drive.API)
-        .addApiIfAvailable(Wearable.API)
-        .addScope(Drive.SCOPE_FILE)
-        .addConnectionCallbacks(this)
-        .addOnConnectionFailedListener(this)
-        .build();
-
- -

In the example above, the -{@code GoogleApiClient} -can successfully connect with the Google Drive service without connecting to the -{@code Wearable} -API if it is unavailable. After you connect your -{@code GoogleApiClient} -instance, ensure that the -{@code Wearable} -API is available before making the API calls: -

- -
-mGoogleApiClient.hasConnectedApi(Wearable.API);
-
- - -

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 {@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.

- - -

Using asynchronous calls

- -

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}.

- - -

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 {@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<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
-        ...
-    }
-}
-
- -

-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 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 - - -
- -
- -

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.

- - - - -

Register Your App

- -

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:

- -
    -
  1. Visit Google Cloud Console. -
  2. If you have an existing project to which you're adding an Android app, select the project. -Otherwise, click Create project at the top, enter your project name and ID, -then click Create. -

    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.

    -
  3. In the left-side navigation, select APIs & auth. -
  4. Enable the API you'd like to use by setting the Status to ON. - -
  5. In the left-side navigation, select Credentials. -
  6. Click Create new client ID or Create new key -as appropriate for your app.
    7. -
  7. Complete the form that appears by filling in your Android app details. -

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

    -
    8. -
  8. Click Create. -
- -

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.

- - - -

Invoke the Account Picker

- -

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.

- - - - -

Retrieve the Account Name

- -

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.

- - -

Extend AsyncTask to Get the Auth Token

- -

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()}:

- -
-public class GetUsernameTask extends AsyncTask{
-    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) {
-                // Insert the good stuff here.
-                // 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 {
-            return GoogleAuthUtil.getToken(mActivity, mEmail, mScope);
-        } 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;
-    }
-    ...
-}
-
- -

In order to call -{@code GoogleAuthUtil.getToken()}, 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 Specifying Scopes section below.

- -

Note: -As shown by the {@code fetchToken()} method above, you must handle -special exceptions that may occur during the -{@code GoogleAuthUtil.getToken()} method. The next section shows how you should -respond to these exceptions.

- -

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:

- -
-String mEmail; // Received from {@code newChooseAccountIntent()}; passed to {@code getToken()}
-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()) {
-            new GetUsernameTask(HelloActivity.this, mEmail, SCOPE).execute();
-        } else {
-            Toast.makeText(this, R.string.not_online, Toast.LENGTH_LONG).show();
-        }
-    }
-}
-
- -

The {@code pickUserAccount()} method is shown in the first lesson, Picking the User's Account. - -

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 -Connecting to the Network lesson.

- -

The only part left is how you should handle the exceptions that may occur when you call - -{@code GoogleAuthUtil.getToken()}.

- -

Specifying scopes

-

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.

-

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 OAuth 2.0 Playground.

-

Tip: Specify {@code "oauth2:<scope>"} - for a single scope. Specify - {@code "oauth2:<scope1> <scope2> <scopeN>"} for multiple - scopes (using a space to separate each scope).

-

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:

-
-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);
-
- -

Handle Exceptions

- -

As shown in the fetchToken() method above, you must catch all occurrences of {@code -GoogleAuthException} when you call -{@code GoogleAuthUtil.getToken()}.

- -

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 {@code -GoogleAuthException}:

- - -
-
{@code UserRecoverableAuthException}
-
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 {@code -getIntent()} 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.
- -
{@code GooglePlayServicesAvailabilityException}
-
This is a specific type of {@code - UserRecoverableAuthException} indicating that the user's current version -of Google Play services is outdated. Although the recommendation above for -{@code - UserRecoverableAuthException} 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 -{@code getConnectionStatusCode()} and pass the result to -{@code GooglePlayServicesUtil.getErrorDialog()}. 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.
-
- -

For example, the fetchToken() method in the above sample code catches any -occurrence of {@code -UserRecoverableAuthException} and passes it back to the activity with a method called -{@code handleException()}. Here's what that method in the activity may look like:

- - -
-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);
-            }
-        }
-    });
-}
-
- -

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.

- - -

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, Picking the User's Account) -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.

- - -
-@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();
-    }
-}
-
- -

For a complete set of code that acquires the OAuth token and queries a Google service -over HTTP (including how to use {@code -getTokenWithNotification()} 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.

- - - -- cgit v1.1