Since we published this post in 2014, we’ve made a lot of updates to the Google Sign-In APIs, deprecating much of this information.

Check out these posts instead:

API Updates for Google Sign-In

Updates on the contents of this post are found here: Using Google Sign-In on your Server

Using Credentials between your Server and Google Services

Happy Tuesday! We've had a few questions come in recently regarding Google Accounts on Android, so we've put this post together to show you some of our best practices. The tips today will focus on Android-based authentication, which is easily achieved through the integration of Google Play services. Let's get started.

Unique Identifiers

A common confusion happens when developers use the account name (a.k.a. email address) as the primary key to a Google Account. For instance, when using GoogleApiClient to sign in a user, a developer might use the following code inside of the onConnected callback for a registered GoogleApiClient.ConnectedCallbacks listener:

[Error prone pseudocode]

String accountName = Plus.AccountApi.getAccountName(mGoogleApiClient); // createLocalAccount() is specific to the app's local storage strategy. createLocalAccount(accountName);

While it is OK to store the email address for display or caching purposes, it is possible for users to change the primary email address on a Google Account. This can happen with various types of accounts, but these changes happen most often with Google Apps For Work accounts.

So what's a developer to do? Use the Google Account ID (as opposed to the Account name) to key any data for your app that is associated to a Google Account. For most apps, this simply means storing the Account ID and comparing the value each time the onConnected callback is invoked to ensure the data locally matches the currently logged in user. The API provides methods that allow you to get the Account ID from the Account Name. Here is an example snippet you might use:

[Google Play Services 6.1+]

String accountName = Plus.AccountApi.getAccountName(mGoogleApiClient); String accountID = GoogleAuthUtil.getAccountId(accountName); createLocalAccount(accountID);

[Earlier Versions of Google Play Services (please upgrade your client)]

Person currentUser = Plus.PeopleApi.getCurrentPerson(mGoogleApiClient); String accountID = currentUser.getID(); createLocalAccount(accountID);

This will key the local data against a Google Account ID, which is unique and stable for the user even after changing an email address.

So, in the above scenario, if your data was keyed on an ID, you wouldn’t have to worry if your users change their email address. When they sign back in, they’ll still get the same ID, and you won’t need to do anything with your data.

Multiple Accounts

If your app supports multiple account connections simultaneously (like the Gmail user interface shown below), you are calling setAccountName on the GoogleApiClient.Builder when constructing GoogleApiClients. This requires you to store the account name as well as the Google Account ID within your app. However, the account name you’ve stored will be different if the user changes their primary email address. The easiest way to deal with this is to prompt the user to re-login. Then, update the account name when onConnected is called after login. Any time a login occurs you, can use code such as this to compare Account IDs and update the email address stored locally for the Account ID.

[Google Play Services 6.1+]

String accountName = Plus.AccountApi.getAccountName(mGoogleApiClient); String accountID = GoogleAuthUtil.getAccountId(accountName); // isExistingLocalAccount(), createLocalAccount(), // getLocalDataAccountName(), and updateLocalAccountName() // are all specific to the app's local storage strategy. boolean existingLocalAccountData = isExistingLocalAccount(accountID); if (!existingLocalAccountData) { // New Login. createLocalAccount(accountID, accountName); } else { // Existing local data for this Google Account. String cachedAccountName = getLocalDataAccountName(accountID); if (!cachedAccountName.equals(accountName)) { updateLocalAccountName(accountID, accountName); } }

This scenario reinforces the importance of using the Account ID to store data all data in your app.

Online data

The same best practices above apply to storing data for Google Accounts in web servers for your app. If you are storing data on your servers in this manner and treating the email address as the primary key:

ID [Primary Key] Field 1 Field 2 Field 3 user1@gmail.com Value 1 Value 2 Value 3

You need to migrate to this model where the primary key is the Google Account ID.:

ID [Primary Key] Email Field 1 Field 2 Field 3 108759069548186989918 user1@gmail.com Value 1 Value 2 Value 3

If you don't make Google API calls from your web server, you might be able to depend on the Android application to notify your web server of changes to the primary email address when implementing the updateLocalAccountName method referenced in the multiple accounts sample code above. If you make Google API calls from your web server, you likely implemented it using the Cross-client authentication and can detect changes via the OAuth2 client libraries or REST endpoints on your server as well.

Conclusion

When using Google Account authentication for your app, it’s definitely a best practice to use the account ID, as opposed to the account name to distinguish data for the user. In this post, we saw three scenarios where you may need to make changes to make your apps more robust. With the growing adoption of Google for Work, users who are changing their email address, but keeping the same account ID, may occur more frequently, so we encourage all developers to make plans to update their code as soon as possible.