Cette page a été traduite par l'API Cloud Translation.

API Account Transfer

Les utilisateurs peuvent copier des comptes et des données Google depuis un appareil Android existant vers un nouvel appareil Android à l'aide de la fonctionnalité Tap & Go. L'API Account Transfer permet aux utilisateurs de copier également les identifiants des comptes personnalisés implémentés à l'aide de AbstractAccountAuthenticator et intégrés à AccountManager. Le système appelle l'API Account Transfer à partir de l'assistant de configuration Tap & Go exécuté sur le nouvel appareil. Le système appelle également l'API Account Transfer pour transférer les données d'un téléphone Android vers un Pixel à l'aide d'un câble.

L'écran Tap & Go permettant de sélectionner une source de données

Figure 1. L'API Account Transfer est appelée à partir de l'assistant de configuration Tap & Go exécuté sur un nouvel appareil.

Pour permettre le transfert de comptes personnalisés, intégrez l'API Account Transfer à votre application. Les services Google Play peuvent ensuite établir un canal chiffré bidirectionnel entre l'appareil existant, également appelé appareil source, et le nouvel appareil cible, pour transférer les données du compte, comme illustré dans la figure 2. Le canal chiffré ne repose pas sur la connexion à des serveurs tiers pour effectuer le transfert.

Tenez compte des exigences suivantes lorsque vous intégrez l'API Account Transfer à votre application :

L'appareil source doit être équipé d'Android 4.0.1 (niveau d'API 14) ou version ultérieure.
L'appareil cible doit être équipé d'Android 8.0 (niveau d'API 26) ou version ultérieure.
Les appareils source et cible doivent exécuter les services Google Play 11.2.0 ou version ultérieure.
Vous devez compiler votre application à l'aide du SDK des services Google Play version 11.2.0 ou ultérieure.

Illustration du transfert de compte de l'appareil source vers l'appareil cible.

Figure 2. Le transfert s'effectue via un canal chiffré que les services Google Play établissent entre les appareils source et cible.

Ajouter l'API Account Transfer à votre projet

Pour utiliser l'API Account Transfer dans votre projet, vous devez d'abord configurer votre projet avec le SDK des services Google Play. Pour obtenir des instructions détaillées sur la configuration du SDK des services Google Play, consultez Configurer les services Google Play.

Si vous souhaitez compiler de manière sélective l'API Google Account Transfer dans votre application, ajoutez la règle de compilation suivante au bloc dependencies du fichier build.gradle à l'intérieur du répertoire de votre module d'application:

Groovy

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>")
}

Pour permettre le transfert de comptes personnalisés, vous devez déclarer le broadcast receiver START_ACCOUNT_EXPORT pour votre service d'authentification dans le fichier manifeste de votre application :

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

Si votre application n'est pas installée dans une image système OEM et que vous ne prévoyez pas de la placer dans une image système OEM, assurez-vous de vous enregistrer pour écouter la diffusion ACTION_START_ACCOUNT_EXPORT sur l'appareil source afin d'exporter les données du compte comme décrit ci-dessus.

Si vous installez votre application dans une image système OEM, vous devez également vous enregistrer pour les diffusions suivantes :

Sur l'appareil source, enregistrez-vous pour écouter la diffusion ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE.
Sur l'appareil cible, enregistrez-vous pour écouter la diffusion ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE.

Transférer les données du compte

Lorsqu'un utilisateur choisit de restaurer du contenu à partir de son appareil existant, le système envoie la diffusion ACTION_START_ACCOUNT_EXPORT aux packages associés aux comptes concernés sur l'appareil source.

Envoyer les données du compte

Pour envoyer des données de compte, démarrez un service d'authentification sur l'appareil source et appelez sendData() une fois que le service a reçu la diffusion ACTION_START_ACCOUNT_EXPORT. Vous pouvez obtenir une référence à un objet AccountTransferClient en appelant getAccountTransferClient(Context) ou getAccountTransferClient(Activity). L'extrait de code suivant montre comment envoyer des données depuis l'appareil source:

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

L'assistant de configuration sur l'appareil cible reçoit les données du compte.

Recevoir les données du compte

Si le même service d'authentification est installé sur cet appareil et a manifesté son intérêt en écoutant la diffusion ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, l'appareil cible envoie la diffusion ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE aux packages correspondants.

À la réception de la diffusion ACTION_ACCOUNT_IMPORT_DATA_AVAILABLE, démarrez un service et appelez retrieveData() sur l'appareil cible pour récupérer les données envoyées depuis l'appareil source. L'extrait de code suivant montre comment récupérer des données sur l'appareil cible:

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

Terminer le transfert

Si nécessaire, le service d'authentification sur l'appareil cible peut aussi transférer des données vers l'appareil source en appelant sendData().

Pour recevoir des données sur l'appareil source, votre service d'authentification doit écouter la diffusion ACTION_ACCOUNT_EXPORT_DATA_AVAILABLE. De même, votre service d'authentification sur l'appareil source peut envoyer d'autres messages à l'appareil cible.

Une fois le transfert terminé, votre service d'authentification doit appeler notifyCompletion() avec l'état d'avancement approprié.

Si vous avez besoin de plus de sécurité, vous pouvez émettre une demande d'authentification destinée aux utilisateurs sur l'appareil source ou cible. Tout d'abord, vérifiez si les défis peuvent être affichés en appelant getDeviceMetaData() et en inspectant le résultat. Si le service d'authentification sur l'appareil cible prend en charge les questions d'authentification, appelez showUserChallenge() pour afficher la question d'authentification.

Si le service d'authentification requis n'est pas installé sur l'appareil cible au moment du transfert, le système stocke les données transférées dans un espace de stockage local temporaire. Lorsque l'application est installée et ouverte pour la première fois, elle peut appeler retrieveData() pour vérifier si des données sont disponibles dans l'espace de stockage local temporaire. Si des données sont disponibles, l'API Account Transfer les renvoie. Sinon, l'appel échoue. Si aucune donnée n'est disponible dans le stockage local temporaire, toute autre tentative de récupération des données peut échouer. N'appelez pas notifyCompletion(), car cela pourrait échouer.

Illustration de l'appareil cible stockant les données transférées dans un espace de stockage local temporaire.

Figure 3. Si le service d'authentification requis n'est pas installé sur l'appareil cible, le système stocke les données transférées dans un espace de stockage local temporaire.

Tester le transfert de compte

L'assistant de configuration s'exécute lorsque vous configurez un nouvel appareil. Rétablir régulièrement la configuration d'usine d'un appareil pour tester la configuration et le transfert d'un compte serait fastidieux et chronophage. Vous pouvez exécuter une partie du flux de l'assistant de configuration pour tester le transfert du compte d'un utilisateur d'un appareil à un autre.

Assurez-vous d'avoir au moins un compte personnalisé sur votre appareil source avant de commencer le test. Assurez-vous également que l'appareil cible n'est connecté à aucun compte personnalisé. Si l'appareil cible est déjà connecté à un compte personnalisé lorsque vous exécutez l'assistant de configuration, la tentative d'ajout du même compte échoue lorsque le système appelle la méthode AccountManager.addAccountExplicitly().

Pour effectuer des tests, vous devez utiliser un appareil cible équipé d'Android 8.0 (niveau d'API 26) ou version ultérieure.

Vous pouvez utiliser un appareil source équipé d'Android 4.0.1 (niveau d'API 14) ou version ultérieure, ainsi que les services Google Play 11.2.0 ou version ultérieure. Pour compiler l'APK que vous testez, vous devez utiliser le SDK des services Google Play version 11.2.0 ou ultérieure.

Pour tester le flux de l'assistant de configuration, exécutez la commande suivante sur votre appareil cible :

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

La commande lance une activité et affiche l'assistant de configuration, prêt à associer l'appareil de test à un autre. Une fois que les appareils ont établi une connexion, vous pouvez lancer le processus de transfert de compte.