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

page.title=Remembering Your User
parent.title=Remembering and Authenticating Users
parent.link=index.html

trainingnavtop=true
next.title=Authenticating to OAuth2 Services
next.link=authenticate.html

@jd:body


<div id="tb-wrapper">
  <div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
  <li><a href="#ForYou">Determine if AccountManager is for You</a></li>
  <li><a href="#TaskTwo">Decide What Type of Account to Use</a></li>
  <li><a href="#QueryAccounts">Query the user for an Account</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>


<p>Everyone likes it when you remember their name. One of the simplest, most
effective things you can do to make your app more lovable is to remember who
your user is&mdash;especially when the user upgrades to a new device or starts carrying
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 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>
<li>Auto-fill forms with the user's email address.</li>
<li>Retrieve an ID that is tied to a user, not the device.</li>
</ul>


<h2 id="ForYou">Determine if AccountManager is for You</h2>

<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>Retrieve a unique device ID to remember the device</li>
<li>Retrieve a built-in account from {@link android.accounts.AccountManager}</li>
</ol>

<p>Option (a) is problematic. First, asking the user to type something before
entering your app will automatically make your app less appealing. Second,
there's no guarantee that the username chosen will be unique. </p>

<p>Option (b) is less onerous for the user, but it's
<a href="http://android-developers.blogspot.com/2011/03/identifying-app-installations.html">tricky
to get right</a>. More
importantly, it only allows you to remember the user on one device. Imagine the
frustration of someone who upgrades to a shiny new device, only to find that
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 remember your user, no matter
how many devices the user may own, by adding just a couple of extra taps to your
UI.</p>


<h2 id="TaskTwo">Decide What Type of Account to Use</h2>

<p>Android devices can store multiple accounts from many different providers.
When you query {@link android.accounts.AccountManager} for account names, you
can choose to filter by account type. The account type is a string that
uniquely identifies the entity that issued the account. For instance, Google
accounts have type "com.google," while Twitter uses
"com.twitter.android.auth.login."</p>

<h2 id="QueryAccounts">Query the user for an Account</h2>

<p>Once an account type has been determined, you can prompt the user with an
account chooser as follows:

<pre>
AccountManager am = AccountManager.get(this);  // "this" reference the current Context
Intent chooserIntent = am.newChooseAccountIntent(
        null, // currently select account
        null, // list of accounts that are allowed to be shown
        new String[] { "com.google" }, // Only allow the user to select Google accounts
        false,
        null,  // description text
        null, // add account auth token type
        null, // required features for added accounts
        null);  // options for adding an account
this.startActivityForResult(chooserIntent, MY_REQUEST_CODE);
</pre>

<p>Once the chooser intent is started, the user will be presented with a list of
appropriately typed accounts. From this list they will select one which will be
returned to your app upon onActivityResult as follows:

<pre>
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == MY_REQUEST_CODE && resultCode == RESULT_OK) {
        String name = data.getStringExtra(AccountManage.KEY_ACCOUNT_NAME);
        String type = data.getStringExtra(AccountManage.KEY_ACCOUNT_TYPE);
        Account selectedAccount = new Account(name, type);
        doSomethingWithSelectedAccount(selectedAccount);
    }
}
</pre>

<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
email address. You can use this information in several different ways, such as:
<ul>
    <li> As suggestions in forms, so the user doesn't need to input account information by
hand.</li>
    <li> As a key into your own online database of usage and personalization information.</li>
</ul>
</p>


<h2 id="IdIsEnough">Decide Whether an Account Name is Enough</h2>

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