Tips for integrating with Google Accounts on Android

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.