Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.

API de transferencia de cuentas

Los usuarios pueden copiar datos y Cuentas de Google desde un dispositivo existente con Android a un nuevo dispositivo con Android mediante Tap & Go. Usa la API de transferencia de cuentas para permitir que los usuarios también copien las credenciales de cuentas personalizadas implementadas mediante AbstractAccountAuthenticator e integradas con AccountManager. El sistema invoca la API de transferencia de cuentas del asistente de configuración de Tap & Go que se ejecuta en el dispositivo nuevo. El sistema también invoca la API de transferencia de cuentas para transferir datos de un teléfono Android a un Pixel con un cable.

Pantalla de bienvenida de Tap & Go Pantalla de Tap & Go para seleccionar una fuente de datos

Figura 1 : La API de transferencia de cuentas se invoca desde el asistente de configuración de Tap & Go que se ejecuta en un dispositivo nuevo.

Para agregar compatibilidad con la transferencia de cuentas personalizadas, integra la API de transferencia de cuentas en tu app. Luego, Servicios de Google Play puede establecer un canal encriptado bidireccional entre el dispositivo existente, también conocido como dispositivo fuente, y el dispositivo nuevo, también conocido como dispositivo objetivo, para transferir datos de la cuenta, como se ilustra en la figura 2. El canal encriptado no depende de una conexión a servidores de terceros para completar la transferencia.

Ten en cuenta los siguientes requisitos cuando integres la API de transferencia de cuentas en tu app:

  • El dispositivo de origen debe ejecutar Android 4.0.1 (API nivel 14) o versiones posteriores.
  • El dispositivo de destino debe ejecutar Android 8.0 (API nivel 26) o versiones posteriores.
  • Tanto los dispositivos de origen como los de destino deben ejecutar la versión 11.2.0 o versiones posteriores de Servicios de Google Play.
  • Debes compilar tu APK con la versión 11.2.0 o versiones posteriores del SDK de Servicios de Google Play.

Ilustración de transferencia de cuenta del dispositivo de origen al de destino

Figura 2: La transferencia se realiza mediante un canal encriptado que los Servicios de Google Play establecen entre los dispositivos de origen y de destino.

Cómo agregar la API de transferencia de cuentas a tu proyecto

Para usar la API de transferencia de cuentas en tu proyecto, primero debes configurarlo con el SDK de Servicios de Google Play. Para obtener instrucciones detalladas sobre cómo configurar el SDK de Servicios de Google Play, consulta Cómo configurar Servicios de Google Play.

Si deseas compilar de forma selectiva la API de transferencia de Cuentas de Google en tu app, agrega la siguiente regla de compilación al archivo build.gradle en el directorio del módulo de tu app, en el bloque dependencies:

apply plugin: 'com.android.application'
        ...

        dependencies {
            // VERSION_NUMBER must be equal to or higher than 11.2.0.
            compile 'com.google.android.gms:play-services-auth:<VERSION_NUMBER>'
        }
    

Si quieres admitir la transferencia de cuentas personalizadas, debes declarar el receptor de emisión START_ACCOUNT_EXPORT para tu servicio de autenticación en el manifiesto de tu app:

<receiver android:name=".MyBroadcastReceiver"  android:exported="true">
        <intent-filter>
            <action android:name="com.google.android.gms.auth.START_ACCOUNT_EXPORT"/>
            ...
        </intent-filter>
    </receiver>
    

Si tu app no está instalada en una imagen del sistema OEM y no tienes pensado incluirla en el futuro, asegúrate de registrarte para escuchar la emisión de ACTION_START_ACCOUNT_EXPORT en el dispositivo de origen a fin de exportar los datos de la cuenta como se describió anteriormente.

Si instalas tu app en una imagen del sistema OEM, también debes registrarte para las siguientes emisiones:

Cómo transferir los datos de la cuenta

Después de que un usuario decide restablecer el contenido de su dispositivo existente, el sistema envía la emisión ACTION_START_ACCOUNT_EXPORT a los paquetes asociados con las cuentas relevantes en el dispositivo de origen.

Cómo enviar los datos de la cuenta

Para enviar datos de la cuenta, inicia un servicio de autenticador en el dispositivo de origen y llama a sendData() después de que el servicio reciba la emisión de ACTION_START_ACCOUNT_EXPORT. Obtienes la referencia a un objeto AccountTransferClient llamando a getAccountTransferClient(Context) o a getAccountTransferClient(Activity). En el siguiente fragmento de código, se ilustra cómo puedes enviar datos desde un dispositivo de origen:

Kotlin

    val client: AccountTransferClient = AccountTransfer.getAccountTransferClient(this)
    val exportTask: Task<Void> = client.sendData(ACCOUNT_TYPE, transferBytes)
    try {
        // Wait for the task to either complete or provide the callback.
        Tasks.await(exportTask, TIMEOUT_API, TIME_UNIT)
    } catch (e: Exception) {
        when(e) {
            is ExecutionException, is InterruptedException, is TimeoutException -> {
                client.notifyCompletion(ACCOUNT_TYPE,
                        AuthenticatorTransferCompletionStatus.COMPLETED_FAILURE)
                return
            }
            else -> throw e
        }
    }
    

Java

    AccountTransferClient client = AccountTransfer.getAccountTransferClient(this);
    Task<Void> exportTask = client.sendData(ACCOUNT_TYPE, transferBytes);
    try {
      // Wait for the task to either complete or provide the callback.
      Tasks.await(exportTask, TIMEOUT_API, TIME_UNIT);
    } catch (ExecutionException | InterruptedException | TimeoutException e) {
      client.notifyCompletion(ACCOUNT_TYPE,AuthenticatorTransferCompletionStatus.COMPLETED_FAILURE);
      return;
    }
    

El asistente de configuración del dispositivo de destino recibe los datos de la cuenta.

Cómo recibir los datos de la cuenta

Si el mismo servicio de autenticador está instalado en este dispositivo y ha registrado su interés escuchando la emisión de ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, el dispositivo de destino envía la emisión de ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE a los paquetes correspondientes.

Cuando recibas la emisión de ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, inicia un servicio y llama a retrieveData() en el dispositivo de destino para recuperar los datos enviados desde el dispositivo de origen. En el siguiente fragmento de código, se ilustra cómo puedes recuperar datos en el dispositivo de destino:

Kotlin

    val client: AccountTransferClient = AccountTransfer.getAccountTransferClient(this)
    val transportTask: Task<Void> = client.retrieveData(ACCOUNT_TYPE)
    try {
        val transferBytes: ByteArray = Tasks.await(transferTask, TIMEOUT_API, TIME_UNIT)
        // Add the transferred account(s) to AccountManager to register it with the framework.
    } catch (e: Exception) {
        when(e) {
            is ExecutionException, is InterruptedException, is TimeoutException -> {
                client.notifyCompletion(ACCOUNT_TYPE,
                        AuthenticatorTransferCompletionStatus.COMPLETED_FAILURE)
                return
            }
            else -> throw e
        }
     }
    client.notifyCompletion(ACCOUNT_TYPE, AuthenticatorTransferCompletionStatus.COMPLETED_SUCCESS)

    

Java

    AccountTransferClient client = AccountTransfer.getAccountTransferClient(this);
    Task<Void> transferTask = client.retrieveData(ACCOUNT_TYPE);
    try {
      byte[] transferBytes = Tasks.await(transferTask, TIMEOUT_API, TIME_UNIT);
      // Add the transferred account(s) to AccountManager to register it with the framework.
    } catch (ExecutionException | InterruptedException | TimeoutException e) {
      client.notifyCompletion(ACCOUNT_TYPE, AuthenticatorTransferCompletionStatus.COMPLETED_FAILURE);
      return;
    }
    client.notifyCompletion(ACCOUNT_TYPE, AuthenticatorTransferCompletionStatus.COMPLETED_SUCCESS);

    

Cómo finalizar la transferencia

Si es necesario, el servicio de autenticador en el dispositivo de destino también puede transferir datos al dispositivo de origen llamando a sendData().

Para recibir datos en el dispositivo de origen, tu servicio de autenticador debe escuchar la emisión de ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE. De manera similar, el servicio de autenticador en el dispositivo de origen puede enviar más mensajes al dispositivo de destino.

Cuando finaliza la transferencia, tu servicio de autenticador debe llamar a notifyCompletion() con el estado de finalización apropiado.

Si necesitas más seguridad, puedes presentar un desafío para el usuario en el dispositivo de origen o de destino. Primero, debes verificar si se pueden mostrar los desafíos llamando a getDeviceMetaData() e inspeccionando el resultado. Si el servicio de autenticador en el dispositivo de destino admite desafíos, puedes llamar a showUserChallenge() para mostrar el desafío.

Si el servicio de autenticador requerido no está instalado en el dispositivo de destino en el momento de la transferencia, el sistema almacena los datos transferidos en el almacenamiento local temporal. Cuando la aplicación se instala y se abre por primera vez, puede llamar a retrieveData() para comprobar si hay datos disponibles en el almacenamiento local temporal. Si hay datos disponibles, la API de transferencia de cuentas muestra los datos; de lo contrario, la llamada falla. Si no hay datos disponibles en el almacenamiento local temporal, es posible que fallen los intentos de recuperación de datos. No llames a notifyCompletion(), ya que puede fallar.

Ilustración del dispositivo de destino que almacena los datos transferidos en el almacenamiento local temporal

Figura 3 : Si el servicio de autenticador requerido no está instalado en el dispositivo de destino, el sistema almacena los datos transferidos en el almacenamiento local temporal.

Cómo probar la transferencia de cuentas

El asistente de configuración se ejecuta cuando configuras un nuevo dispositivo. El restablecimiento de fábrica frecuente de un dispositivo para probar la configuración y la transferencia de una cuenta sería tedioso y requeriría mucho tiempo. En su lugar, puedes ejecutar un subconjunto del flujo del asistente de configuración para probar la transferencia de la cuenta de un usuario de un dispositivo a otro.

Asegúrate de tener al menos una cuenta personalizada en tu dispositivo de origen antes de comenzar la prueba. Además, asegúrate de que el dispositivo de destino no haya accedido a ninguna cuenta personalizada. Si el dispositivo de destino ya accedió a una cuenta personalizada cuando ejecutas el asistente de configuración, el intento de agregar la misma cuenta falla cuando el sistema llama al método AccountManager.addAccountExplicitly().

Para fines de prueba, debes usar un dispositivo con Android 8.0 (API nivel 26) o versiones posteriores como dispositivo de destino.

Puedes usar un dispositivo con Android 4.0.1 (API nivel 14) o versiones posteriores, así como con la versión 11.2.0 o versiones posteriores de Servicios de Google Play como dispositivo de origen. Para compilar el APK que estás probando, debes usar la versión 11.2.0 o versiones posteriores del SDK de Servicios de Google Play.

Para probar el flujo del asistente de configuración, ejecuta el siguiente comando en tu dispositivo de destino:

$ adb shell am start -a android.intent.action.MAIN -n com.google.android.gms/.smartdevice.d2d.ui.TargetActivity
    

El comando inicia una actividad y muestra el asistente de configuración, listo para vincular el dispositivo de prueba con otro. Cuando los dispositivos establecen una conexión, puedes comenzar el proceso de transferencia de cuentas.