Account Transfer API

Users can copy Google accounts and data from an existing Android-powered
device to a new Android-powered device using
Tap & Go. Use the
Account Transfer API to let users also copy credentials for custom accounts
implemented using
AbstractAccountAuthenticator
and integrated with
AccountManager. The system
invokes the Account Transfer API from the Tap & Go setup wizard running on the
new device. The system also invokes the Account Transfer API to
transfer data from an Android phone to a Pixel
using a cable.

Figure 1. The Account Transfer API is invoked from the Tap & Go
setup wizard running on a new device.

To add support for transferring custom accounts, integrate the Account Transfer
API in your app. Google Play services can then establish a bidirectional
encrypted channel between the existing device, also known as the
source device, and the new device, also known as the target device, to
transfer account data as illustrated in figure 2. The encrypted channel doesn't
rely on being connected to third-party servers to complete the transfer.

Note: While the Account Transfer API doesn't require a connection to
the internet, you may need to connect to your backend servers to refresh
authentication tokens. If you need to connect to your backend servers during
the account transfer process, make sure to check that at least one of the
devices is connected to the internet.

Consider the following requirements when integrating the Account Transfer API
into your app:

The source device must be running Android 4.0.1 (API level 14) or higher.

The target device must be running Android 8.0 (API level 26) or higher.

Both source and target devices must be running Google Play
services version 11.2.0 or higher.

You must build your APK using Google Play services SDK version 11.2.0 or
higher.

Figure 2. The transfer takes place over an encrypted channel that
Google Play services establishes between source and target devices.

Add the Account Transfer API to your project

To use the Account Transfer API in your project, you first need to set up your
project with the Google Play services SDK. For detailed instructions on setting
up the Google Play services SDK, see
Set Up Google Play Services.

If you want to selectively compile the Google Account Transfer API into your app,
add the following build rule to the build.gradle file inside your application
module directory in the dependencies block:

If your app is not installed in an OEM system image and you don't plan to put
your app in an OEM system image in the future, make sure you register to listen
for the
ACTION_START_ACCOUNT_EXPORT
broadcast on the source device to export account data as described above.

If you install your app on an OEM system image, you must also register for the
following broadcasts:

Transfer the account data

After a user chooses to restore content from their existing device,
the system sends the
ACTION_START_ACCOUNT_EXPORT
broadcast to the packages associated with the relevant accounts on the source
device.

On receiving the
ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE
broadcast, start a service and call
retrieveData()
on the target device to retrieve the data sent from the source device. The
following code snippet illustrates how you can retrieve data on the target
device:

Finish the transfer

If necessary, the authenticator service on the target device can also transfer
data back to the source device by calling
sendData().

To receive data on the source device, your authenticator service must listen for
the ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE
broadcast. Similarly, your authenticator service on the source device can send
further messages to the target device.

When the transfer finishes, your authenticator service must call
notifyCompletion()
with the appropriate completion status.

If you require further security, you can introduce a user-facing challenge on
either the source or target device. First, you must check whether challenges can
be shown by calling
getDeviceMetaData()
and inspecting the result. If the authenticator service on the target device
supports challenges, you can call
showUserChallenge()
to display the challenge.

Caution: Displaying a user-facing challenge is strongly discouraged, as it
creates friction for the user when transferring accounts and results in a poor
user experience.

If the required authenticator service is not installed on the target device at
the time of transfer, the system stores the transferred data in temporary local
storage. When the app is first installed and opened, it can call
retrieveData()
to check whether there is any data available in temporary local storage. If
there is any available data, the Account Transfer API returns the data;
otherwise the call fails. If no data is available in temporary local storage,
any further attempts to retrieve data may fail. Don't call
notifyCompletion()
as it may fail.

Figure 3. If the required authenticator service is not installed on
the target device, the system stores the transferred data in temporary local
storage.

Test the account transfer

The setup wizard runs when you set up a new device. Regularly factory resetting
a device to test the setup and transfer of an account would be tiresome and
time-consuming. Instead, you can run a subset of the setup wizard flow to test
transferring a user's account from one device to another.

Make sure to have at least one custom account on your source device before you
begin the test. Also ensure that the target device isn't signed into any custom
accounts. If the target device is already signed into a custom account when you
run the setup wizard, trying to add the same account fails when the system calls
the
AccountManager.addAccountExplicitly()
method.

For testing purposes, you must use a device running Android 8.0 (API level 26)
or higher as the target device.

You can use a device running Android 4.0.1 (API level 14) or higher, as well as
Google Play services version 11.2.0 or higher, as the source device. To build
the APK that you are testing, you must use Google Play services SDK version
11.2.0 or higher.

To test the setup wizard flow, run the following command on your target device: