AccountTransferClient

  • AccountTransferClient contains APIs used by authenticators for bootstrapping accounts.

  • Authenticators use broadcasts like ACTION_START_ACCOUNT_EXPORT, ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, and ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE to manage data transfer between devices.

  • Data is sent using sendData and received using retrieveData during the account transfer process.

  • Authenticators should call notifyCompletion to indicate the end of the account transfer with an appropriate status.

  • Authenticators can optionally show a user challenge using showUserChallenge, but this is discouraged due to potential friction.
public class AccountTransferClient extends GoogleApi<AccountTransferOptions>

Contains api's used by authenticators for bootstrapping accounts.

Authenticators should register the receivers in their manifest with action AccountTransfer.ACTION_START_ACCOUNT_EXPORT to express their interest for exporting accounts. When a target device is being setup using source device, this broadcast is sent to the packages associated with the accounts on the source device. On receiving this broadcast, authenticators are expected to send their account related data via sendData(String, byte[]), which will be received on the target device side through Setup wizard. On the target device, broadcast with action AccountTransfer.ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE is sent to the corresponding packages if the same authenticator is installed on this device and has registered its interest via listening to action AccountTransfer.ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE. On receiving this broadcast, authenticators need to call retrieveData(String) to retrieve the data sent from the source device side. Moreover, it can transfer data back to the source device by calling sendData(String, byte[]). To receive the data on source device, the authenticator should be listening to broadcast with action AccountTransfer.ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE. Similarly, authenticators on the source side can send additional message to the target device. When the transfer ends, authenticator should call notifyCompletion(String, int) with the appropriate completion status.

In case additional security is needed, a user facing challenge can be thrown. First, an authenticator needs to check if they can show any challenge by calling getDeviceMetaData(String) and inspecting the result. If it's allowed for the authenticator on the device, the challenge can be shown by calling showUserChallenge(String, PendingIntent). Sending user facing challenge is strongly discouraged, as it creates friction for the user to transfer the accounts and leads to sub-optimal user experience.

If the authenticator is not installed on the target device, the transferred data is stored in escrow for some time, the duration of which is subject to change. When the app is first installed and opened, it can call retrieveData(String) to check if there is any data available in escrow. If there is any data that was transferred over, that data is returned, otherwise the call fails. In this case, all other calls may fail. There is no need to call notifyCompletion(String, int) for this case, and if called, it may fail.

If your package is responsible for multiple account types, inspecting AccountTransfer.ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE on the broadcasts received will provide information on the account type for which the broadcast was sent. Account type can be retrieved as shown below.


    String accountType =
        intent.getStringExtra(AccountTransfer.ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE);

Public Method Summary

Task<DeviceMetaData>
getDeviceMetaData(String accountType)
Retrieves DeviceMetaData associated with the device, which authenticators can use to figure out if they can challenge on the device.
Task<Void>
notifyCompletion(String accountType, int completionStatus)
Notifies the completion of the account transfer.
Task<byte[]>
retrieveData(String accountType)
Retrieves data that was transferred over from other side.
Task<Void>
sendData(String accountType, byte[] transferData)
Transfers data that will be transferred over to the other side.
Task<Void>
showUserChallenge(String accountType, PendingIntent pendingIntent)
Sends a user facing challenge, specified by PendingIntent.

Inherited Method Summary

Public Methods

public Task<DeviceMetaData> getDeviceMetaData (String accountType)

Retrieves DeviceMetaData associated with the device, which authenticators can use to figure out if they can challenge on the device.

Parameters
accountType Account type associated with the calling authenticator.
Returns

public Task<Void> notifyCompletion (String accountType, int completionStatus)

Notifies the completion of the account transfer.

Parameters
accountType Account type associated with the calling authenticator.
completionStatus status to notify final status of transfer. Value should be one of the constants listed in AuthenticatorTransferCompletionStatus.

public Task<byte[]> retrieveData (String accountType)

Retrieves data that was transferred over from other side. This should be called under following circumstances.

Parameters
accountType Account type associated with the calling authenticator.
Returns
  • data in bytes that was transferred over from the other side.

public Task<Void> sendData (String accountType, byte[] transferData)

Transfers data that will be transferred over to the other side. This should be called only when the account transfer is in progress. This call should only be made after receiving any of the broadcasts - AccountTransfer.ACTION_START_ACCOUNT_EXPORT, AccountTransfer.ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE or AccountTransfer.ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE. No consecutive calls should be made, unless the above listed broadcast is received.

Parameters
accountType Account type associated with the calling authenticator.
transferData data to be transferred over.

public Task<Void> showUserChallenge (String accountType, PendingIntent pendingIntent)

Sends a user facing challenge, specified by PendingIntent. The pending intent is launched by setup flow.

Parameters
accountType Account type associated with the calling authenticator.
pendingIntent contains the intent which will have a user facing challenge.