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

From class com.google.android.gms.common.api.GoogleApi

String

getApiFallbackAttributionTag(Context arg0)

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

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

Task wrapping DeviceMetaData associated with the device.

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 AccountTransfer.ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE or AccountTransfer.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 - 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.