Scott Main | 98af5edc7 | 2011-12-15 20:13:20 -0800 | [diff] [blame] | 1 | page.title=Remembering Your User |
Dirk Dougherty | 3b33cdc | 2011-12-15 15:34:41 -0800 | [diff] [blame] | 2 | parent.title=Remembering and Authenticating Users |
Scott Main | f9cca66 | 2011-12-15 10:07:03 -0800 | [diff] [blame] | 3 | parent.link=index.html |
| 4 | |
| 5 | trainingnavtop=true |
| 6 | next.title=Authenticating to OAuth2 Services |
| 7 | next.link=authenticate.html |
| 8 | |
| 9 | @jd:body |
| 10 | |
| 11 | |
| 12 | <div id="tb-wrapper"> |
| 13 | <div id="tb"> |
| 14 | <h2>This lesson teaches you to</h2> |
| 15 | <ol> |
| 16 | <li><a href="#ForYou">Determine if AccountManager for You</a></li> |
| 17 | <li><a href="#TaskTwo">Decide What Type of Account to Use</a></li> |
| 18 | <li><a href="#GetPermission">Request GET_ACCOUNT permission</a></li> |
| 19 | <li><a href="#TaskFive">Query AccountManager for a List of Accounts</a></li> |
Dirk Dougherty | 3b33cdc | 2011-12-15 15:34:41 -0800 | [diff] [blame] | 20 | <li><a href="#IdentifyUser">Use the Account Object to Personalize Your App</a></li> |
| 21 | <li><a href="#IdIsEnough">Decide Whether an Account Name is Enough</a></li> |
Scott Main | f9cca66 | 2011-12-15 10:07:03 -0800 | [diff] [blame] | 22 | </ol> |
| 23 | </div> |
| 24 | </div> |
| 25 | |
| 26 | |
| 27 | <p>Everyone likes it when you remember their name. One of the simplest, most |
| 28 | effective things you can do to make your app more lovable is to remember who |
| 29 | your user is—especially when the user upgrades to a new device or starts carrying |
| 30 | a tablet as well as a phone. But how do you know who your user is? And how do |
| 31 | you recognize them on a new device?</p> |
| 32 | |
| 33 | <p>For many applications, the answer is the {@link android.accounts.AccountManager} APIs. With the |
Dirk Dougherty | 3b33cdc | 2011-12-15 15:34:41 -0800 | [diff] [blame] | 34 | user's permission, you can use Account Manager to fetch the account names |
| 35 | that the user has stored on their device.</p> |
Scott Main | f9cca66 | 2011-12-15 10:07:03 -0800 | [diff] [blame] | 36 | |
| 37 | <p>Integration with the user's accounts allows you to do a variety of things such as:</p> |
| 38 | <ul> |
| 39 | <li>Auto-fill forms with the user's email address.</li> |
| 40 | <li>Retrieve an ID that is tied to a user, not the device.</li> |
| 41 | </ul> |
| 42 | |
| 43 | |
| 44 | <h2 id="ForYou">Determine if AccountManager for You</h2> |
| 45 | |
Dirk Dougherty | 3b33cdc | 2011-12-15 15:34:41 -0800 | [diff] [blame] | 46 | <p>Applications typically try to remember the user using one of three techniques:</p> |
Scott Main | f9cca66 | 2011-12-15 10:07:03 -0800 | [diff] [blame] | 47 | <ol type="a"> |
| 48 | <li>Ask the user to type in a username </li> |
Dirk Dougherty | 3b33cdc | 2011-12-15 15:34:41 -0800 | [diff] [blame] | 49 | <li>Retrieve a unique device ID to remember the device</li> |
Scott Main | f9cca66 | 2011-12-15 10:07:03 -0800 | [diff] [blame] | 50 | <li>Retrieve a built-in account from {@link android.accounts.AccountManager}</li> |
| 51 | </ol> |
| 52 | |
| 53 | <p>Option (a) is problematic. First, asking the user to type something before |
| 54 | entering your app will automatically make your app less appealing. Second, |
| 55 | there's no guarantee that the username chosen will be unique. </p> |
| 56 | |
| 57 | <p>Option (b) is less onerous for the user, but it's |
| 58 | <a href="http://android-developers.blogspot.com/2011/03/identifying-app-installations.html">tricky |
| 59 | to get right</a>. More |
| 60 | importantly, it only allows you to remember the user on one device. Imagine the |
| 61 | frustration of someone who upgrades to a shiny new device, only to find that |
| 62 | your app no longer remembers them.</p> |
| 63 | |
| 64 | <p>Option (c) is the preferred technique. Account Manager allows you to get |
| 65 | information about the accounts that are stored on the user's device. As we'll |
Dirk Dougherty | 3b33cdc | 2011-12-15 15:34:41 -0800 | [diff] [blame] | 66 | see in this lesson, using Account Manager lets you remember your user, no matter |
Scott Main | f9cca66 | 2011-12-15 10:07:03 -0800 | [diff] [blame] | 67 | how many devices the user may own, by adding just a couple of extra taps to your |
| 68 | UI.</p> |
| 69 | |
| 70 | |
| 71 | <h2 id="TaskTwo">Decide What Type of Account to Use</h2> |
| 72 | |
| 73 | <p>Android devices can store multiple accounts from many different providers. |
| 74 | When you query {@link android.accounts.AccountManager} for account names, you can choose to filter |
| 75 | by |
| 76 | account type. The account type is a string that uniquely identifies the entity |
| 77 | that issued the account. For instance, Google accounts have type "com.google," |
| 78 | while Twitter uses "com.twitter.android.auth.login."</p> |
| 79 | |
| 80 | |
| 81 | <h2 id="GetPermission">Request GET_ACCOUNT permission</h2> |
| 82 | |
| 83 | <p>In order to get a list of accounts on the device, your app needs the {@link |
| 84 | android.Manifest.permission#GET_ACCOUNTS} |
| 85 | permission. Add a <a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">{@code |
| 86 | <uses-permission>}</a> tag in your manifest file to request |
| 87 | this permission:</p> |
| 88 | |
| 89 | <pre> |
| 90 | <manifest ... > |
| 91 | <uses-permission android:name="android.permission.GET_ACCOUNTS" /> |
| 92 | ... |
| 93 | </manifest> |
| 94 | </pre> |
| 95 | |
| 96 | |
| 97 | <h2 id="TaskFive">Query AccountManager for a List of Accounts</h2> |
| 98 | |
| 99 | <p>Once you decide what account type you're interested in, you need to query for accounts of that |
| 100 | type. Get an instance of {@link android.accounts.AccountManager} by calling {@link |
| 101 | android.accounts.AccountManager#get(android.content.Context) AccountManager.get()}. Then use that |
| 102 | instance to call {@link android.accounts.AccountManager#getAccountsByType(java.lang.String) |
| 103 | getAccountsByType()}.</p> |
| 104 | |
| 105 | <pre> |
| 106 | AccountManager am = AccountManager.get(this); // "this" references the current Context |
| 107 | |
| 108 | Account[] accounts = am.getAccountsByType("com.google"); |
| 109 | </pre> |
| 110 | |
| 111 | <p>This returns an array of {@link android.accounts.Account} objects. If there's more than one |
| 112 | {@link android.accounts.Account} in |
| 113 | the array, you should present a dialog asking the user to select one.</p> |
| 114 | |
| 115 | |
Dirk Dougherty | 3b33cdc | 2011-12-15 15:34:41 -0800 | [diff] [blame] | 116 | <h2 id="IdentifyUser">Use the Account Object to Personalize Your App</h2> |
Scott Main | f9cca66 | 2011-12-15 10:07:03 -0800 | [diff] [blame] | 117 | |
| 118 | <p>The {@link android.accounts.Account} object contains an account name, which for Google accounts |
| 119 | is an |
| 120 | email address. You can use this information in several different ways, such as: |
| 121 | <ul> |
| 122 | <li> As suggestions in forms, so the user doesn't need to input account information by |
| 123 | hand.</li> |
| 124 | <li> As a key into your own online database of usage and personalization information.</li> |
| 125 | </ul> |
| 126 | </p> |
| 127 | |
| 128 | |
Dirk Dougherty | 3b33cdc | 2011-12-15 15:34:41 -0800 | [diff] [blame] | 129 | <h2 id="IdIsEnough">Decide Whether an Account Name is Enough</h2> |
Scott Main | f9cca66 | 2011-12-15 10:07:03 -0800 | [diff] [blame] | 130 | |
Dirk Dougherty | 3b33cdc | 2011-12-15 15:34:41 -0800 | [diff] [blame] | 131 | <p>An account name is a good way to remember the user, but the {@link android.accounts.Account} |
Scott Main | f9cca66 | 2011-12-15 10:07:03 -0800 | [diff] [blame] | 132 | object by |
Dirk Dougherty | 3b33cdc | 2011-12-15 15:34:41 -0800 | [diff] [blame] | 133 | itself doesn't protect your data or give you access to anything besides the user's account name. If your app |
| 134 | needs to allow the user to go online to access private data, you'll need something stronger: authentication. |
Scott Main | f9cca66 | 2011-12-15 10:07:03 -0800 | [diff] [blame] | 135 | The next lesson explains how to authenticate to existing online services. The lesson after that |
| 136 | deals with writing a custom authenticator so that you can install your own |
| 137 | account types.</p> |