App Flip pour Android

Une fois que vous disposez d'une implémentation OAuth 2.0, vous pouvez éventuellement configurer l'App Flip basée sur OAuth, qui permet à vos utilisateurs Android d'associer plus rapidement leurs comptes dans votre système d'authentification à leurs comptes Google. Les sections suivantes expliquent comment concevoir et implémenter App Flip pour votre intégration Cloud-to-cloud sur Android.

Principes de conception

Cette section décrit les exigences et les recommandations de conception pour l'écran de consentement à l'association de compte App Flip. Une fois que Google a appelé votre application, celle-ci affiche l'écran de consentement à l'utilisateur.

Conditions requises

  1. Vous devez inclure une déclaration d'autorisation Google, par exemple "Une fois associé, Google sera autorisé à contrôler vos appareils."
  2. Vous devez indiquer que le compte de l'utilisateur est associé à Google, et non à un produit Google spécifique, tel que Google Home ou l'Assistant Google.
  3. Vous devez indiquer une incitation à l'action claire sur votre écran de consentement et utiliser la formulation "Accepter et associer" pour l'action d'association. En effet, les utilisateurs doivent comprendre quelles données ils doivent partager avec Google pour associer leurs comptes.
  4. Vous devez permettre aux utilisateurs de revenir en arrière, de refuser ou d'annuler s'ils choisissent de ne pas associer leur compte. Utilisez le terme "Annuler" pour l'action d'annulation.
  5. Vous devez implémenter ce workflow : après avoir cliqué sur "Accepter et associer", vous devez indiquer que l'association a réussi et rediriger automatiquement l'utilisateur vers l'application Google Home. L'utilisateur devrait maintenant voir l'appareil associé dans l'application Google Home avec votre action. Après avoir cliqué sur "Annuler", vous devez rediriger l'utilisateur vers l'application Google Home.

Recommandations

Nous vous recommandons d'effectuer les opérations suivantes :

  1. Affichez les règles de confidentialité de Google. Incluez un lien vers les Règles de confidentialité de Google sur l'écran de consentement.

  2. Données à partager : Utilisez un langage clair et concis pour indiquer à l'utilisateur les données dont Google a besoin et pourquoi.

  3. Possibilité de dissocier le compte. Offrez aux utilisateurs un mécanisme pour dissocier leur compte, par exemple une URL vers les paramètres de leur compte sur votre plate-forme. Vous pouvez également inclure un lien vers le compte Google où les utilisateurs peuvent gérer leur compte associé.

  4. Possibilité de modifier le compte utilisateur Suggérez aux utilisateurs une méthode pour changer de compte. Cela est particulièrement utile si les utilisateurs ont tendance à posséder plusieurs comptes.

    • Si un utilisateur doit fermer l'écran d'autorisation pour changer de compte, envoyez une erreur récupérable à Google afin qu'il puisse se connecter au compte souhaité avec l'association OAuth et le flux implicite.

  5. Incluez votre logo. Affichez le logo de votre entreprise sur l'écran de consentement. Utilisez vos consignes de style pour placer votre logo. Si vous souhaitez également afficher le logo de Google, consultez Logos et marques déposées.

Cette figure montre un exemple d'écran de consentement avec des encadrés indiquant les exigences et recommandations individuelles à suivre lorsque vous concevez un écran de consentement utilisateur.
Figure 1 : Consignes de conception de l'écran d'autorisation pour l'association de comptes.

Configurer pour App Flip basé sur OAuth

Les sections suivantes décrivent les conditions préalables à l'utilisation d'App Flip basé sur OAuth et expliquent comment configurer votre projet App Flip dans la Google Home Developer Console.

Créer une intégration cloud-to-cloud et configurer un serveur OAuth 2.0

Avant de pouvoir configurer App Flip, vous devez effectuer les opérations suivantes :

Configurer App Flip dans la Developer Console

La section suivante explique comment configurer App Flip dans la Developer Console.

  1. Remplissez tous les champs obligatoires(*) sous Association de compte. (Si App Flip n'est pas compatible, OAuth standard est utilisé comme solution de secours.)
  2. Indiquez une URL pour l'URL de traitement dans le cloud. L'URL de traitement cloud permet de traiter vos intents de maison connectée. Cochez la case Traitement en local.
  3. Sous App Flip (facultatif), cochez Application Android.
  4. Remplissez les champs suivants :
    • ID d'application L'ID d'application est un identifiant unique que vous définissez pour votre application.
    • Signature de l'application Les applications Android doivent être "signées" avec un certificat de clé publique avant de pouvoir être installées. Pour savoir comment obtenir la signature de votre application, consultez Authentifier votre client.
    • Intention d'autorisation. Dans ce champ, saisissez une chaîne qui spécifie l'action de votre intent.
  5. Si vous souhaitez configurer votre client, ajoutez des champs d'application et cliquez sur Ajouter un champ d'application sous Champ(s) d'application (facultatif).
  6. Si votre client l'exige, sélectionnez Demander à Google de transmettre l'ID client et le code secret via l'en-tête d'authentification HTTP de base.

Vous pouvez maintenant passer à la section suivante pour implémenter App Flip dans votre application Android.

Implémenter App Flip dans vos applications natives

Pour implémenter App Flip, vous devez modifier le code d'autorisation de l'utilisateur dans votre application afin d'accepter un lien profond de Google.

L'association App Flip basée sur OAuth (App Flip) insère votre application Android dans le flux d'association de compte Google. Dans un flux d'association de comptes traditionnel, l'utilisateur doit saisir ses identifiants dans le navigateur. L'utilisation d'App Flip reporte la connexion de l'utilisateur à votre application Android, ce qui vous permet d'exploiter les autorisations existantes. Si l'utilisateur est connecté à votre application, il n'a pas besoin de saisir à nouveau ses identifiants pour associer son compte. L'implémentation d'App Flip dans votre application Android ne nécessite qu'un minimum de modifications du code.

Dans ce document, vous allez apprendre à modifier votre application Android pour qu'elle soit compatible avec App Flip.

Essayer l'exemple

L'application exemple d'association App Flip illustre l'intégration d'une association de comptes compatible avec App Flip sur Android. Vous pouvez l'utiliser pour vérifier comment répondre à un intent App Flip entrant provenant d'applications mobiles Google.

L'application exemple est préconfigurée pour s'intégrer à l'outil de test App Flip pour Android, que vous pouvez utiliser pour vérifier l'intégration de votre application Android à App Flip avant de configurer l'association du compte à Google. Cette application simule l'intent déclenché par les applications mobiles Google lorsque la fonctionnalité App Flip est activée.

Fonctionnement

Pour effectuer une intégration App Flip, procédez comme suit :

  1. L'appli Google vérifie si votre application est installée sur l'appareil à l'aide de son nom de package.
  2. L'appli Google utilise une vérification de la signature du package pour s'assurer que l'application installée est la bonne.
  3. L'appli Google crée un intent pour démarrer une activité désignée dans votre application. Cet intent inclut les données supplémentaires requises pour l'association. Il vérifie également si votre application est compatible avec App Flip en résolvant cet intent via le framework Android.
  4. Votre application vérifie que la requête provient de l'appli Google. Pour ce faire, elle vérifie la signature du package et l'ID client fourni.
  5. Votre application demande un code d'autorisation à votre serveur OAuth 2.0. À la fin de ce flux, il renvoie un code d'autorisation ou une erreur à l'appli Google.
  6. L'appli Google récupère le résultat et poursuit l'association du compte. Si un code d'autorisation est fourni, l'échange de jetons s'effectue de serveur à serveur, de la même manière que dans le flux d'association OAuth basé sur un navigateur.

Modifier votre application Android pour qu'elle soit compatible avec App Flip

Pour prendre en charge App Flip, apportez les modifications suivantes au code de votre application Android :

  1. Ajoutez un <intent-filter> à votre fichier AndroidManifest.xml avec une chaîne d'action correspondant à la valeur que vous avez saisie dans le champ App Flip Intent.

    <activity android:name="AuthActivity">
  <!-- Handle the app flip intent -->
  <intent-filter>
    <action android:name="INTENT_ACTION_FROM_CONSOLE"/>
    <category android:name="android.intent.category.DEFAULT"/>
  </intent-filter>
</activity>

  2. Validez la signature de l'application appelante.

    Vous devez faire correspondre le nom du package et la signature de toutes les applications Google que les utilisateurs peuvent utiliser pour associer leur compte. Par exemple, pour associer les applications Google Home et Recherche, ajoutez leurs noms de package et leurs signatures :

    • Package name (nom du package) : com.google.android.apps.chromecast.app
    • Certificat de traçabilité SHA-256 d'origine : 3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A
    • Certificat SHA-256 de la signature d'application Play alterné : 5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6

    et

    • Package name (nom du package) : com.google.android.googlequicksearchbox
    • Signature : F0:FD:6C:5B:41:0F:25:CB:25:C3:B5:33:46:C8:97:2F:AE:30:F8:EE:74:11:DF:91:04:80:AD:6B:2D:60:DB:83

    Les demandes d'association de maison connectée sont initiées directement par Google Home app (GHA). Si votre application limite les appelants et n'autorisait auparavant que l'application de recherche Google, vous devez ajouter com.google.android.apps.chromecast.app et ses certificats SHA-256 à votre liste d'autorisation pour qu'App Flip continue de fonctionner.

    private fun verifyFingerprint(
    expectedPackage: String,
    expectedFingerprints: List<String>
): Boolean {
    val callingPackage = callingActivity?.packageName ?: return false
    if (callingPackage != expectedPackage) return false
    return expectedFingerprints.any { hex ->
        val sha256Bytes =
            hex.split(":").map { it.toInt(16).toByte() }.toByteArray()
        packageManager.hasSigningCertificate(
            callingPackage,
            sha256Bytes,
            PackageManager.CERT_INPUT_SHA256
        )
    }
}

  3. Extrayez l'ID client des paramètres d'intent et vérifiez qu'il correspond à la valeur attendue.

    private const val EXPECTED_CLIENT = "<client-id-from-actions-console>"
private const val EXPECTED_PACKAGE = "com.google.android.apps.chromecast.app"
// Original lineage certificate (3D:7A...) and active rotated
// Play App Signing certificate (5A:AD...)
private val EXPECTED_FINGERPRINTS = listOf(
    "3D:7A:12:23:01:9A:A3:9D:9E:A0:E3:43:6A:B7:C0:89:6B:FB:4F:B6:79:F4:DE:5F:E7:C2:3F:32:6C:8F:99:4A",
    "5A:AD:2B:EE:6D:B9:5D:17:E0:5A:08:D7:D1:E6:4C:10:A1:51:18:79:15:44:83:91:6B:6A:E6:C7:FD:9C:B0:C6"
)
...

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val clientId = intent.getStringExtra("CLIENT_ID")

    if (clientId == EXPECTED_CLIENT &&
        verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINTS)) {

        // ...authorize the user...
    }
}

  4. Une fois l'autorisation accordée, renvoyez le code d'autorisation obtenu à Google.

    // Successful result
val data = Intent().apply {
    putExtra("AUTHORIZATION_CODE", authCode)
}
setResult(Activity.RESULT_OK, data)
finish()

  5. Si une erreur s'est produite, renvoyez un résultat d'erreur à la place.

    // Error result
val error = Intent().apply {
    putExtra("ERROR_TYPE", 1)
    putExtra("ERROR_CODE", 1)
    putExtra("ERROR_DESCRIPTION", "Invalid Request")
}
setResult(-2, error)
finish()

Contenu de l'intent de lancement

L'intent Android qui lance votre application inclut les champs suivants :

  • CLIENT_ID (String) : Google client_id enregistré sous votre application.
  • SCOPE (String[]) : liste des champs d'application demandés.
  • REDIRECT_URI (String) : URL de redirection.

Contenu des données de réponse

Les données renvoyées à l'appli Google sont définies dans votre application en appelant setResult(). Ces données incluent les éléments suivants :

  • AUTHORIZATION_CODE (String) : valeur du code d'autorisation.
  • resultCode (int) : indique la réussite ou l'échec du processus et prend l'une des valeurs suivantes :
    • Activity.RESULT_OK : indique que l'opération a réussi. Un code d'autorisation est renvoyé.
    • Activity.RESULT_CANCELLED : erreur récupérable. Indique que l'utilisateur a annulé le processus. Dans ce cas, l'appli Google tentera à nouveau d'associer le compte à l'aide de votre URL d'autorisation.
    • -2 : indique qu'une erreur s'est produite. Les différents types d'erreurs sont décrits ci-dessous.
  • ERROR_TYPE (int) : type d'erreur, qui prend l'une des valeurs suivantes :
    • 1 : erreur récupérable. L'appli Google tentera d'associer le compte à l'aide de l'URL d'autorisation.
    • 2 : erreur irrécupérable. L'appli Google interrompt l'association du compte.
    • 3 : paramètres de requête non valides ou manquants.
  • ERROR_CODE (int) : entier représentant la nature de l'erreur. Pour connaître la signification de chaque code d'erreur, consultez le tableau des codes d'erreur.

  • ERROR_DESCRIPTION (String, facultatif) : message d'état lisible par l'humain décrivant l'erreur.

Une valeur pour AUTHORIZATION_CODE est attendue lorsque resultCode == Activity.RESULT_OK. Dans tous les autres cas, la valeur de AUTHORIZATION_CODE doit être vide. Si resultCode == -2, la valeur ERROR_TYPE doit être renseignée.

Tableau des codes d'erreur

Le tableau ci-dessous présente les différents codes d'erreur et indique s'il s'agit d'une erreur récupérable ou irrécupérable :

Code d'erreur Signification Restauration possible Irrécupérable
1 INVALID_REQUEST ✔
2 NO_INTERNET_CONNECTION ✔
3 OFFLINE_MODE_ACTIVE ✔
4 CONNECTION_TIMEOUT ✔
5 INTERNAL_ERROR ✔
6 AUTHENTICATION_SERVICE_UNAVAILABLE ✔
8 CLIENT_VERIFICATION_FAILED ✔
9 INVALID_CLIENT ✔
10 INVALID_APP_ID ✔
11 INVALID_REQUEST ✔
12 AUTHENTICATION_SERVICE_UNKNOWN_ERROR ✔
13 AUTHENTICATION_DENIED_BY_USER ✔
14 CANCELLED_BY_USER ✔
15 FAILURE_OTHER ✔
16 USER_AUTHENTICATION_FAILED ✔

Pour tous les codes d'erreur, vous devez renvoyer le résultat de l'erreur via setResult pour vous assurer que le remplacement approprié est déclenché.

Tester App Flip sur votre appareil

Maintenant que vous avez créé une intégration cloud-to-cloud et configuré App Flip dans la console et dans votre application, vous pouvez tester App Flip sur votre appareil mobile. Vous pouvez utiliser l'application Google Home pour tester App Flip.

Pour tester App Flip à partir de l'application Google Home, procédez comme suit :

  1. Accédez à la Developer Console et sélectionnez votre projet.
  2. Accédez à Cloud-to-cloud > Test.
  3. Déclenchez le flux d'association de compte depuis l'application Home :
    1. Ouvrez Google Home app (GHA).
    2. Cliquez sur le bouton +.
    3. Cliquez sur Configurer un appareil.
    4. Cliquez sur Vous avez déjà configuré des appareils ?.
    5. Sélectionnez votre intégration cloud-à-cloud dans la liste des fournisseurs. Il sera précédé de "[test]" dans la liste. Lorsque vous sélectionnez votre intégration [test] dans la liste, votre application doit s'ouvrir.
    6. Vérifiez que votre application a été lancée et commencez à tester votre flux d'autorisation.
Précédent
Créer une intégration cloud à cloud
Suivant
iOS