Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5d2de143 authored by Robert Ly's avatar Robert Ly Committed by Android Git Automerger
Browse files

am 4664782f: am f93a2941: Merge "docs: update gms auth docs for bug 7737187" into jb-mr1-dev 

* commit '4664782f':
  docs: update gms auth docs for bug 7737187
parents 8a3eb664 4664782f

docs/html/google/google_toc.cs

+1 −1
Original line number Original line Diff line number Diff line
@@ -23,7 +23,7 @@ 
      </li>

      </li>





      <li><a href="<?cs var:toroot?>google/play-services/auth.html">

      <li><a href="<?cs var:toroot?>google/play-services/auth.html">

          <span class="en">Authentication</span></a>

          <span class="en">Authorization</span></a>

      </li>

      </li>





      <li><a href="<?cs var:toroot?>google/play-services/plus.html">

      <li><a href="<?cs var:toroot?>google/play-services/plus.html">

docs/html/google/play-services/auth.jd

+26 −26
Original line number Original line Diff line number Diff line 
page.title=Authentication

page.title=Authorization

@jd:body

@jd:body





<div id="qv-wrapper">

<div id="qv-wrapper">
@@ -6,28 +6,28 @@ page.title=Authentication 
    <h2>In this document</h2>

    <h2>In this document</h2>

    <ol>

    <ol>

    <li><a href="#choose">Choosing an Account</a></li>

    <li><a href="#choose">Choosing an Account</a></li>

    <li><a href="#obtain">Obtaining an Authorization Token</a></li>

    <li><a href="#obtain">Obtaining an Access Token</a></li>

    <li><a href="#handle">Handling Exceptions</a></li>

    <li><a href="#handle">Handling Exceptions</a></li>

    <li><a href="#use">Using the Token</a></li>

    <li><a href="#use">Using the Access Token</a></li>

    </ol>

    </ol>

  </div>

  </div>

</div>

</div>





<p>

<p>

    Google Play services offers a standard authentication flow for all Google APIs and

    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 authentication

    all components of Google Play services. In addition, you can leverage the authorization

    portion of the Google Play services SDK to authenticate to services that are not yet supported 

    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 authentication token to manually make API

    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.

    requests or using a client library provided by the service provider.

</p>

</p>





<p>For implementation details, see the sample in <code>&lt;android-sdk&gt;/extras/google-play-services/samples/auth</code>, which shows you how

<p>For implementation details, see the sample in <code>&lt;android-sdk&gt;/extras/google-play-services/samples/auth</code>,

to carry out these basic steps for obtaining an authentication token.</p>

which shows you how to carry out these basic steps for obtaining an acesss token.</p>





<h2 id="choose">Choosing an Account</h2>

<h2 id="choose">Choosing an Account</h2>

<p>

<p>

    Google Play services leverage existing accounts on an Android-powered device

    Google Play services leverage existing accounts on an Android-powered device

    to authenticate to the services that you want to use. To obtain an authorization token,

    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

    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

    account they want to use by enumerating the Google accounts on the device or using the

    built-in 

    built-in
@@ -39,7 +39,7 @@ AccountPicker}</a> 
</p>

</p>

<p>

<p>

    For example, here's how to gather all of the Google accounts on a device and return them

    For example, here's how to gather all of the Google accounts on a device and return them

    in an array. When obtaining an authorization token, only the email address of the account is 

    in an array. When obtaining an access token, only the email address of the account is 

    needed, so that is what the array stores:

    needed, so that is what the array stores:

</p>

</p>
@@ -55,24 +55,24 @@ private String[] getAccountNames() { 
    return names;

    return names;

}

}

</pre>

</pre>

<h2 id="obtain">Obtaining an Authorization Token</h2>

<h2 id="obtain">Obtaining an Access Token</h2>

<p>

<p>

  With an email address, you can now obtain an authorization token. There are two general

  With an email address, you can now obtain an access token. There are two general

  ways to get a token:</p>

  ways to get a token:</p>





    <ul>

    <ul>

      <li>Call one of the two overloaded <a

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

      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

      >{@code GoogleAuthUtil.getToken()}</a> methods in a foreground activity where you can

        display a dialog to the user to interactively handle authentication errors.</li>

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

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

      >{@code getTokenWithNotification()}</a>

        methods if you are authenticating in a background service or sync adapter so that a notification is displayed if an authentication

        methods if you are trying to gain authorization in a background service or sync adapter so that a

        error occurs.</a></li>

        notification is displayed if an error occurs.</a></li>

    </ul>

    </ul>





    <h3>Using getToken()</h3>

    <h3>Using getToken()</h3>

    The following code snippet obtains an authentication token with an email address, the scope that you want to use for the service, and a {@link android.content.Context}:

    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>

<pre>

HelloActivity mActivity;

HelloActivity mActivity;

String mEmail;

String mEmail;
@@ -90,13 +90,13 @@ try { 
<p>Call this method off of the main UI thread since it executes network transactions. An easy way to do this

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

  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.

  The sample in the Google Play services SDK shows you how to wrap this call in an AsyncTask.

  If authentication is successful, the token is returned. If not, the exceptions described in

  If authorization is successful, the token is returned. If not, the exceptions described in

<a href="#handle">Handling Exceptions</a>

<a href="#handle">Handling Exceptions</a>

  are thrown that you can catch and handle appropriately.

  are thrown that you can catch and handle appropriately.

</p>

</p>





  <h3>Using getTokenWithNotification()</h3>

  <h3>Using getTokenWithNotification()</h3>

  <p>If you are obtaining authentication tokens in a background service or sync adapter, there

  <p>If you are obtaining access tokens in a background service or sync adapter, there

  are three overloaded

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

  <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

      >{@code getTokenWithNotification()}</a> methods
@@ -104,11 +104,11 @@ try { 
  <ul>

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

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

    >{@code getTokenWithNotification(Context context, String accountName, String scope, Bundle extras)}</a>:

    For background services. Displays a notification to the user when authentication errors occur.</li>

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

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

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

    This method is for use in background services. It displays a notification to the user

    when authentication errors occur. If a user clicks the notification and then authorizes the

    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:

    app to access the account, the intent is broadcasted. When using this method:

    <ul>

    <ul>

     <li>Create a {@link android.content.BroadcastReceiver} that registers the intent and handles

     <li>Create a {@link android.content.BroadcastReceiver} that registers the intent and handles
@@ -123,7 +123,7 @@ android.content.Intent#toUri toUri(Intent.URI_INTENT_SCHEME)} and 
    <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)"

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

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

This method is for use in sync adapters. It displays a notification to the user when

authentication errors occur. If a user clicks the notification and then authorizes the

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

app to access the account, the sync adapter retries syncing with the information

    contained in the <code>syncBundle</code> parameter.</li>

    contained in the <code>syncBundle</code> parameter.</li>

  </ul>

  </ul>
@@ -135,7 +135,7 @@ app to access the account, the sync adapter retries syncing with the information 




<h2 id="handle">Handling Exceptions</h2>

<h2 id="handle">Handling Exceptions</h2>

<p>

<p>

    When requesting an authentication token with

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

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

    >{@code GoogleAuthUtil.getToken()}</a>,

    the following exceptions can be thrown:

    the following exceptions can be thrown:
@@ -167,7 +167,7 @@ app to access the account, the sync adapter retries syncing with the information 
<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthException.html">{@code

<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthException.html">{@code

GoogleAuthException}</a>:

GoogleAuthException}</a>:

        This exception is thrown when the authorization fails, such as when an invalid scope is 

        This exception is thrown when the authorization fails, such as when an invalid scope is 

        specified or if the email address used to authenticate is actually not on the user's 

        specified or if the email address used for authorization is actually not on the user's 

        device.

        device.

    </li>

    </li>

    <li>

    <li>
@@ -189,7 +189,7 @@ GoogleAuthUtil}</a> class. 












<h2 id="use">Using the Token</h2>

<h2 id="use">Using the Access Token</h2>

<p>

<p>

    Once you have successfully obtained a token, you can use it to access Google services.

    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 

    Many Google services provide client libraries, so it is recommended that you use these when
@@ -224,7 +224,7 @@ if (serverCode == 200) { 




<p>

<p>

    Notice that you must manually invalidate the token if the response from the server

    Notice that you must manually invalidate the token if the response from the server

    signifies an authentication error (401). This could mean the authentication token

    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 

    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

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

href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context, java.lang.String, java.lang.String)"

docs/html/google/play-services/dist.jd

deleted100644 → 0
+0 −56
Original line number Original line Diff line number Diff line 
page.title=Google Play Distribution and Licensing

@jd:body





<h2 id="distribution">

  Manage App Distribution and Licensing

</h2>

<p>

  Google Play allows you to manage your app distribution with features that let you control which users

  can download your app as well as deliver separate versions of your app based on certain

  characteristics like platform version.

</p>

<div class="vspace size-1">

  &nbsp;

</div>

<div class="layout-content-row">

  <div class="layout-content-col span-6">

    <h4>

      Device Filtering

    </h4>

    <p>

      Make sure your app gets to the right users by filtering on a wide range of characteristics

      such as platform versions and hardware features.

    </p><p><a href="{@docRoot}google/play/filters.html">Learn more &raquo;</a></p>

  </div>



  <div class="layout-content-col span-6">

    <h4>

      Multiple APK Support

    </h4>

    <p>

      Distribute different APKs based on a variety of properties such as platform version, screen

      size, and GLES texture compression support.

    </p><p><a href="{@docRoot}google/play/publishing/multiple-apks.html">Learn more &raquo;</a></p>

  </div>



<div class="layout-content-row">

  <div class="layout-content-col span-6">

    <h4>

      APK Expansion files

    </h4>

    <p>

      Tap into Google's content delivery services by serving up to 4GB of assets for free. Provide

      users with high-fidelity graphics, media files, or other large assets that are required by

      your app.

    </p><a href="{@docRoot}google/play/expansion-files.html">Learn more &raquo;</a>

  </div>



   <div class="layout-content-col span-6">

    <h4>

      Application Licensing

    </h4>

    <p>Protect your revenue streams and integrate policies for usage into your app.

    </p><a href="{@docRoot}google/play/licensing/index.html">Learn more &raquo;</a>

  </div>

</div>
 
 No newline at end of file

docs/html/google/play-services/index.jd

+5 −5
Original line number Original line Diff line number Diff line
@@ -37,10 +37,10 @@ each service that let you implement the functionality you want easier and faster 
  </div>

  </div>

  <div class="layout-content-col span-4">

  <div class="layout-content-col span-4">





<h4>Standard Authentication</h4>

<h4>Standard Authorization</h4>

<p>All products in Google Play services share a common authentication API

<p>All products in Google Play services share a common authorization API

  that leverages the existing Google accounts on the device. You and your

  that leverages the existing Google accounts on the device. You and your

  users have a consistent and safe way to grant and receive OAuth2 authentication

  users have a consistent and safe way to grant and receive OAuth2 access tokens

  to Google services.</p>

  to Google services.</p>





  </div>

  </div>
@@ -66,7 +66,7 @@ about your users' Android version.</p> 
<h4 id="client-lib">The Google Play services client library</h4>

<h4 id="client-lib">The Google Play services client library</h4>

<p>

<p>

    The client library contains the interfaces to the individual Google

    The client library contains the interfaces to the individual Google

    services and allows you to obtain authorization from users to authenticate

    services and allows you to obtain authorization from users to gain access

    to these services with their credentials. It also contains APIs that allow

    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

    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

    Google Play services APK. The client library has a light footprint if you use
@@ -90,7 +90,7 @@ about your users' Android version.</p> 
        The Google Play services APK contains the individual Google services and runs

        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

        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.

        through the client library and the service carries out the actions on your behalf.

        An easy-to-use authentication flow is also

        An easy-to-use authorization flow is also

        provided to gain access to the each Google service, which provides consistency for both

        provided to gain access to the each Google service, which provides consistency for both

        you and your users. 

        you and your users. 

    </p>

    </p>