API Account Transfer

Gli utenti possono copiare gli Account Google e i dati da un dispositivo Android esistente a un nuovo dispositivo Android utilizzando Tocca e Go. Utilizza l'API Account Transfer per consentire agli utenti anche di copiare le credenziali per gli account personalizzati implementati utilizzando AbstractAccountAuthenticator e integrati con AccountManager. Il sistema richiama l'API Account Transfer dalla configurazione guidata Tap & Go in esecuzione sul nuovo dispositivo. Il sistema richiama anche l'API Account Transfer per trasferire dati da uno smartphone Android a un Pixel utilizzando un cavo.

La schermata di benvenuto di Tap and Go. La schermata Tocca e vai per selezionare un'origine dati.

Figura 1. L'API Account Transfer viene richiamata dalla configurazione guidata Tap & Go in esecuzione su un nuovo dispositivo.

Per aggiungere il supporto per il trasferimento di account personalizzati, integra l'API Account Transfer nella tua app. Google Play Services può quindi stabilire un canale criptato bidirezionale tra il dispositivo esistente, noto anche come dispositivo di origine, e il nuovo dispositivo, chiamato anche dispositivo di destinazione, per trasferire i dati dell'account, come illustrato nella Figura 2. Il canale criptato non si basa sulla connessione a server di terze parti per completare il trasferimento.

Tieni presente i seguenti requisiti quando integri l'API Account Transfer nella tua app:

  • Sul dispositivo di origine deve essere installato Android 4.0.1 (livello API 14) o versioni successive.
  • Sul dispositivo di destinazione deve essere installato Android 8.0 (livello API 26) o versioni successive.
  • I dispositivi di origine e di destinazione devono eseguire Google Play Services 11.2.0 o versioni successive.
  • Devi creare la tua app utilizzando l'SDK Google Play Services 11.2.0 o versioni successive.

Illustrazione del trasferimento dell'account dal dispositivo di origine a quello di destinazione.

Figura 2. Il trasferimento avviene su un canale criptato che Google Play Services stabilisce tra i dispositivi di origine e quelli di destinazione.

Aggiungere l'API Account Transfer al progetto

Per utilizzare l'API Account Transfer nel tuo progetto, devi prima configurare il progetto con l'SDK Google Play Services. Per istruzioni dettagliate sulla configurazione dell'SDK di Google Play Services, consulta l'articolo Configurare Google Play Services.

Se vuoi compilare selettivamente l'API Google Account Transfer nella tua app, aggiungi la seguente regola di build al blocco dependencies nel file build.gradle all'interno della directory del modulo dell'applicazione:

trendy

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

Kotlin

plugins {
    id("com.android.application")
}
...
dependencies {
    // VERSION_NUMBER must be equal to or higher than 11.2.0.
    implementation("com.google.android.gms:play-services-auth:<VERSION_NUMBER>")
}

Per aggiungere il supporto per il trasferimento di account personalizzati, devi dichiarare il ricevitore di trasmissione START_ACCOUNT_EXPORT per il servizio di autenticazione nel file manifest dell'app:

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

Se la tua app non è installata in un'immagine di sistema OEM e non prevedi di inserirla in un'immagine di sistema OEM, assicurati di registrarti per ascoltare la trasmissione di ACTION_START_ACCOUNT_EXPORT sul dispositivo di origine al fine di esportare i dati dell'account come descritto sopra.

Se installi l'app su un'immagine di sistema OEM, devi registrarti anche per le seguenti trasmissioni:

Trasferire i dati dell'account

Dopo che un utente sceglie di ripristinare i contenuti dal dispositivo esistente, il sistema invia la trasmissione ACTION_START_ACCOUNT_EXPORT ai pacchetti associati agli account pertinenti sul dispositivo di origine.

Invia i dati dell'account

Per inviare i dati dell'account, avvia un servizio di autenticazione sul dispositivo di origine e chiama sendData() dopo che il servizio riceve la trasmissione di ACTION_START_ACCOUNT_EXPORT. Puoi ottenere un riferimento a un oggetto AccountTransferClient chiamando getAccountTransferClient(Context) o getAccountTransferClient(Activity). Il seguente snippet di codice illustra come inviare i dati dal dispositivo di origine:

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

La configurazione guidata sul dispositivo di destinazione riceve i dati dell'account.

Ricevere i dati dell'account

Se su questo dispositivo è installato lo stesso servizio di autenticazione e ha registrato il suo interesse ascoltando la trasmissione ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, il dispositivo di destinazione invia la trasmissione ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE ai pacchetti corrispondenti.

Quando ricevi la trasmissione ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, avvia un servizio e chiama retrieveData() sul dispositivo di destinazione per recuperare i dati inviati dal dispositivo di origine. Il seguente snippet di codice illustra come recuperare i dati sul dispositivo di destinazione:

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 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 with the framework.
} catch (ExecutionException | InterruptedException | TimeoutException e) {
  client.notifyCompletion(ACCOUNT_TYPE, AuthenticatorTransferCompletionStatus.COMPLETED_FAILURE);
  return;
}
client.notifyCompletion(ACCOUNT_TYPE, AuthenticatorTransferCompletionStatus.COMPLETED_SUCCESS);

Completa il trasferimento

Se necessario, il servizio di autenticazione sul dispositivo di destinazione può anche trasferire nuovamente i dati al dispositivo di origine chiamando sendData().

Per ricevere dati sul dispositivo di origine, il servizio di autenticazione deve rimanere in ascolto della trasmissione di ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE. Analogamente, il servizio di autenticazione sul dispositivo di origine può inviare ulteriori messaggi al dispositivo di destinazione.

Al termine del trasferimento, il servizio di autenticazione deve chiamare notifyCompletion() con lo stato di completamento appropriato.

Se hai bisogno di ulteriore sicurezza, puoi introdurre una verifica rivolta all'utente sul dispositivo di origine o di destinazione. Innanzitutto, verifica se è possibile mostrare le sfide chiamando getDeviceMetaData() e ispezionando il risultato. Se il servizio di autenticazione sul dispositivo di destinazione supporta le verifiche, chiama showUserChallenge() per visualizzarle.

Se il servizio di autenticazione richiesto non è installato sul dispositivo di destinazione al momento del trasferimento, il sistema archivia i dati trasferiti in uno spazio di archiviazione locale temporaneo. Quando l'app viene installata e aperta per la prima volta, può chiamare retrieveData() per verificare se sono disponibili dati nello spazio di archiviazione locale temporaneo. Se sono disponibili dati, l'API Account Transfer li restituisce; in caso contrario, la chiamata non va a buon fine. Se non sono disponibili dati nello spazio di archiviazione locale temporaneo, eventuali ulteriori tentativi di recupero dei dati potrebbero non riuscire. Non chiamare notifyCompletion(), poiché potrebbe non funzionare.

Illustrazione del dispositivo di destinazione che memorizza i dati trasferiti nello spazio di archiviazione locale temporaneo.

Figura 3. Se il servizio di autenticazione richiesto non è installato sul dispositivo di destinazione, il sistema archivia i dati trasferiti in uno spazio di archiviazione locale temporaneo.

Testare il trasferimento dell'account

La configurazione guidata viene eseguita quando configuri un nuovo dispositivo. Eseguire regolarmente un ripristino dei dati di fabbrica su un dispositivo per testare la configurazione e il trasferimento di un account sarebbe faticoso e lungo. Puoi invece eseguire un sottoinsieme della procedura di configurazione guidata per testare il trasferimento dell'account di un utente da un dispositivo a un altro.

Assicurati di avere almeno un account personalizzato sul dispositivo di origine prima di iniziare il test. Assicurati inoltre che sul dispositivo di destinazione non sia stato eseguito l'accesso ad account personalizzati. Se sul dispositivo di destinazione è già stato eseguito l'accesso a un account personalizzato quando esegui la configurazione guidata, il tentativo di aggiungere lo stesso account non riesce quando il sistema chiama il metodo AccountManager.addAccountExplicitly().

A scopo di test, devi utilizzare come dispositivo di destinazione un dispositivo con Android 8.0 (livello API 26) o versioni successive.

Puoi utilizzare come dispositivo di origine un dispositivo con Android 4.0.1 (livello API 14) o versioni successive e Google Play Services 11.2.0 o versioni successive. Per creare l'APK che stai testando, devi utilizzare l'SDK Google Play Services 11.2.0 o versioni successive.

Per testare il flusso della configurazione guidata, esegui questo comando sul dispositivo di destinazione:

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

Il comando avvia un'attività e visualizza la configurazione guidata, pronto per l'accoppiamento del dispositivo di test con un altro. Dopo che i dispositivi hanno stabilito una connessione, puoi iniziare il processo di trasferimento dell'account.