AccountTransferClient

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 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 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 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 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 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);
 

Inherited Field Summary

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.

  • When the authenticator package receives ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE or ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE. After these broadcasts, the clients can call to get the newly available data.
  • When the authenticator package is being opened for the first time, it can call this method to check if any data(that was escrowed as part of device setup) is available for this package and account type. If the data is available, that is returned. Otherwise, it is wrapped as an exception.
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 - ACTION_START_ACCOUNT_EXPORT, ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE or 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.