Merge "Doc merge from master:Training class on Identifying and Authenticating Users." into ics-mr0

docs/html/training/id-auth/authenticate.jd

@@ -1,9 +1,9 @@
-page.title=Authenticating to OAuth2 Services
-parent.title=Identifying and Authenticating Users
+page.title=Authenticating to OAuth2 Services
+parent.title=Remembering and Authenticating Users
 parent.link=index.html
 
 trainingnavtop=true
-previous.title=Identifying Your User
+previous.title=Remembering Your User
 previous.link=identify.html
 next.title=Creating a Custom Account Type
 next.link=custom_auth.html
@@ -72,11 +72,10 @@ API.</li>
 
 <h2 id="RequestToken">Request an Auth Token</h2>
 
-<p>Now you're ready to request an auth token. Auth tokens usually expire after
-some period of time, so you'll have to renew them.</p>
+<p>Now you're ready to request an auth token. This is a multi-step process.</p>
 
- <!-- TODO: I think a flowchart would be useful here, or perhaps a link to an as-yet-to-be-created
-flowchart that lives in the docs. -->
+<img src="{@docRoot}images/training/oauth_dance.png" alt="Procedure for obtaining
+a valid auth token from the Android Account Manager"/>
 
 <p>To get an auth token you first need to request the
 {@link android.Manifest.permission#ACCOUNT_MANAGER}
@@ -84,13 +83,13 @@ to yourmanifest file. To actually do anything useful with the
 token, you'll also need to add the {@link android.Manifest.permission#INTERNET}
 permission.</p>
 
-<code>
+<pre>
 &lt;manifest ... >
     &lt;uses-permission android:name="android.permission.ACCOUNT_MANAGER" /&gt;
     &lt;uses-permission android:name="android.permission.INTERNET" /&gt;
     ...
 &lt;/manifest>
-</code>
+</pre>
 
 
 <p>Once your app has these permissions set, you can call {@link

docs/html/training/id-auth/custom_auth.jd

@@ -1,5 +1,5 @@
-page.title=Creating a Custom Account Type
-parent.title=Identifying and Authenticating Users
+page.title=Creating a Custom Account Type
+parent.title=Remembering and Authenticating Users
 parent.link=index.html
 
 trainingnavtop=true
@@ -28,8 +28,9 @@ SampleSyncAdapter app</a></li>
   </div>
 </div>
 
-<p>In the previous lessons, we've talked about using Google accounts to identify Google users and
-access Google APIs. But what if you've got your own online service? It turns out
+<p>So far we've talked about accessing Google APIs, which use accounts and users
+defined by Google. If you have your own online service, though, it won't have
+Google accounts or users, so what do you do? It turns out
 to be relatively straightforward to install new account types on a user's
 device. This lesson explains how to create a custom account type that works the
 same way as the built-in accounts do. </p>

docs/html/training/id-auth/identify.jd

@@ -1,5 +1,5 @@
-page.title=Identifying Your User
-parent.title=Identifying and Authenticating Users
+page.title=Remembering Your User
+parent.title=Remembering and Authenticating Users
 parent.link=index.html
 
 trainingnavtop=true
@@ -17,8 +17,8 @@ next.link=authenticate.html
   <li><a href="#TaskTwo">Decide What Type of Account to Use</a></li>
   <li><a href="#GetPermission">Request GET_ACCOUNT permission</a></li>
   <li><a href="#TaskFive">Query AccountManager for a List of Accounts</a></li>
-  <li><a href="#IdentifyUser">Use the Account Object to Identify the User</a></li>
-  <li><a href="#IdIsEnough">Decide Whether Identification is Enough</a></li>
+  <li><a href="#IdentifyUser">Use the Account Object to Personalize Your App</a></li>
+  <li><a href="#IdIsEnough">Decide Whether an Account Name is Enough</a></li>
 </ol>
   </div>
 </div>
@@ -31,8 +31,8 @@ a tablet as well as a phone. But how do you know who your user is? And how do
 you recognize them on a new device?</p>
 
 <p>For many applications, the answer is the {@link android.accounts.AccountManager} APIs. With the
-user's permission, you can use Account Manager to uniquely identify a user
-by the online identity that the user has stored on their device.</p>
+user's permission, you can use Account Manager to fetch the account names
+that the user has stored on their device.</p>
 
 <p>Integration with the user's accounts allows you to do a variety of things such as:</p>
 <ul>
@@ -43,10 +43,10 @@ by the online identity that the user has stored on their device.</p>
 
 <h2 id="ForYou">Determine if AccountManager for You</h2>
 
-<p>Applications typically identify the user in three different ways:</p>
+<p>Applications typically try to remember the user using one of three techniques:</p>
 <ol type="a">
 <li>Ask the user to type in a username </li>
-<li>Use a unique device identifier rather than a user identifier</li>
+<li>Retrieve a unique device ID to remember the device</li>
 <li>Retrieve a built-in account from {@link android.accounts.AccountManager}</li>
 </ol>
 
@@ -63,7 +63,7 @@ your app no longer remembers them.</p>
 
 <p>Option (c) is the preferred technique. Account Manager allows you to get
 information about the accounts that are stored on the user's device. As we'll
-see in this lesson, using Account Manager lets you identify your user, no matter
+see in this lesson, using Account Manager lets you remember your user, no matter
 how many devices the user may own, by adding just a couple of extra taps to your
 UI.</p>
 
@@ -113,7 +113,7 @@ Account[] accounts = am.getAccountsByType("com.google");
 the array, you should present a dialog asking the user to select one.</p>
 
 
-<h2 id="IdentifyUser">Use the Account Object to Identify the User</h2>
+<h2 id="IdentifyUser">Use the Account Object to Personalize Your App</h2>
 
 <p>The {@link android.accounts.Account} object contains an account name, which for Google accounts
 is an
@@ -126,12 +126,12 @@ hand.</li>
 </p>
 
 
-<h2 id="IdIsEnough">Decide Whether Identification is Enough</h2>
+<h2 id="IdIsEnough">Decide Whether an Account Name is Enough</h2>
 
-<p>Account names are a good way to identify the user, but the {@link android.accounts.Account}
+<p>An account name is a good way to remember the user, but the {@link android.accounts.Account}
 object by
-itself doesn't protect your data or give you access to anything. If you intend
-to access private data, you'll need something stronger: authentication.
+itself doesn't protect your data or give you access to anything besides the user's account name. If your app
+needs to allow the user to go online to access private data, you'll need something stronger: authentication.
 The next lesson explains how to authenticate to existing online services. The lesson after that
 deals with writing a custom authenticator so that you can install your own
 account types.</p>

docs/html/training/id-auth/index.jd

@@ -1,8 +1,8 @@
-page.title=Identifying Users
+page.title=Remembering Users
 
 trainingnavtop=true
 startpage=true
-next.title=Identifying Your User
+next.title=Remembering Your User
 next.link=identify.html
 
 @jd:body
@@ -39,7 +39,7 @@ make your application a richer, more personal experience.</p>
 user's identity, enabling you to:</p>
 
 <ul>
-<li>Identify the user by detecting and selecting an account
+<li>Personalize your app by remembering users by their account name(s)
 <li>Authenticate the user to make sure they are who they say they are
 <li>Gain permission to access the user's online data via services like
 the Google APIs
@@ -51,7 +51,7 @@ back-end services
 <h2>Lessons</h2>
 
 <dl>
-  <dt><b><a href="identify.html">Identifying Your User</a></b></dt>
+  <dt><b><a href="identify.html">Remembering Your User</a></b></dt>
     <dd>Use {@link android.accounts.AccountManager} to learn the user's account name(s).</dd>
 
   <dt><b><a href="authenticate.html">Authenticating to OAuth2 Services</a></b></dt>