App Flip pour Android

Une fois que vous avez implémenté OAuth 2.0, vous pouvez configurer le App Flip OAuth, ce qui permet à vos utilisateurs Android d'associer plus rapidement leurs comptes dans votre système d'authentification à leurs comptes Google. Les sections suivantes décrivent comment concevoir et implémenter App Flip pour votre action smart home.

Consignes de conception

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

Conditions requises

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

Recommandations

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

1. Afficher 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 quelles données Google lui demandent et pourquoi.

3. Incitation à l'action claire. Affichez une incitation à l'action claire sur l'écran de consentement, par exemple "Accepter et associer". En effet, les utilisateurs doivent comprendre quelles données ils doivent partager avec Google pour associer leurs comptes.

4. Annulation possible. Offrez aux utilisateurs un moyen de revenir en arrière ou de résilier leur abonnement s'ils décident de ne pas l'associer.

5. Possibilité de dissocier le compte. Proposez aux utilisateurs un mécanisme de dissociation, tel qu'une URL vers leurs paramètres de compte sur votre plate-forme. Vous pouvez également inclure un lien vers le compte Google, dans lequel les utilisateurs peuvent gérer leur compte associé.

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

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

7. Incluez votre logo. Affichez le logo de votre entreprise sur l'écran de consentement. Utilisez les consignes de style pour placer votre logo. Si vous souhaitez afficher le logo de Google, consultez la page Logos et marques.

Configurer une application basée sur OAuth

Les sections suivantes décrivent les conditions préalables pour App Flip basé sur OAuth et expliquent comment configurer votre projet App Flip dans la console Actions.

Créer une action de maison connectée et configurer un serveur OAuth 2.0

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

• Configurez un serveur OAuth 2.0. Pour en savoir plus sur la configuration d'un serveur OAuth, consultez Implémenter un serveur OAuth 2.0.
• Créez une action. Pour créer une action, suivez les instructions de la section Créer un projet Actions.

Configurer App Flip dans la console Actions

La section suivante explique comment configurer App Flip dans la console Actions.

1. Remplissez tous les champs sous Informations sur le client OAuth. (Si App Flip n'est pas compatible, le protocole OAuth standard est utilisé en remplacement.)
2. Sous Utiliser votre application pour associer un compte (facultatif), cochez Activer pour Android.
3. Remplissez les champs suivants:
• ID de l'application. L'ID application est un identifiant unique que vous définissez pour votre application.
• Signature d'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.
• Intent d'autorisation. Dans ce champ, saisissez une chaîne spécifiant votre action d'intent.
4. Si vous souhaitez configurer votre client, ajoutez des champs d'application. Ensuite, cliquez sur Ajouter un champ d'application sous Configurer votre client (facultatif).
5. Cliquez sur Enregistrer.

Implémenter App Flip dans vos applications Android

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

L'association de comptes App Flip basée sur OAuth insère votre application Android dans le flux d'association de comptes Google. Avec un flux d'association de compte classique, l'utilisateur doit saisir ses identifiants dans le navigateur. L'utilisation d'App Flip reporte la connexion des utilisateurs à 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. Un minimum de modifications de code sont nécessaires pour implémenter App Flip sur votre application Android.

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

Essayer l'exemple

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

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

Comment ça marche ?

Les étapes suivantes sont nécessaires pour effectuer une intégration d'App Flip:

1. L'appli Google vérifie si votre application est installée sur l'appareil à l'aide du nom du package.
2. L'appli Google utilise une vérification de signature de package pour vérifier que l'application installée est la bonne.
3. L'appli Google crée un intent pour lancer une activité désignée dans votre application. Cet intent inclut des 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, un code d'autorisation ou une erreur est renvoyé à 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.

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

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

1. Ajoutez un fichier <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 (Intent de conversion d'application).

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

   private fun verifyFingerprint(
           expectedPackage: String,
           expectedFingerprint: String,
           algorithm: String
   ): Boolean {
   
       callingActivity?.packageName?.let {
           if (expectedPackage == it) {
               val packageInfo =
                   packageManager.getPackageInfo(it, PackageManager.GET_SIGNATURES)
               val signatures = packageInfo.signatures
               val input = ByteArrayInputStream(signatures[0].toByteArray())
   
               val certificateFactory = CertificateFactory.getInstance("X509")
               val certificate =
                   certificateFactory.generateCertificate(input) as X509Certificate
               val md = MessageDigest.getInstance(algorithm)
               val publicKey = md.digest(certificate.encoded)
               val fingerprint = publicKey.joinToString(":") { "%02X".format(it) }
   
               return (expectedFingerprint == fingerprint)
           }
       }
       return false
   }
   

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 = "<google-app-package-name>"
   private const val EXPECTED_FINGERPRINT = "<google-app-signature>"
   private const val ALGORITHM = "SHA-256"
   ...
   
   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
   
       val clientId = intent.getStringExtra("CLIENT_ID")
   
       if (clientId == EXPECTED_CLIENT &&
           verifyFingerprint(EXPECTED_PACKAGE, EXPECTED_FINGERPRINT, ALGORITHM)) {
   
           // ...authorize the user...
       }
   }
   

4. Une fois l'autorisation réussie, 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.

   // 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 appli en appelant setResult(). Ces données incluent les éléments suivants:

• AUTHORIZATION_CODE (String): valeur du code d'autorisation.
• resultCode (int): indique le succès ou l'échec du processus et accepte l'une des valeurs suivantes :
  • Activity.RESULT_OK: indique la réussite de l'opération. Un code d'autorisation est renvoyé.
  • Activity.RESULT_CANCELLED : indique que l'utilisateur a annulé le processus. Dans ce cas, l'appli Google tente d'associer les comptes à l'aide de votre URL d'autorisation.
  • -2 : 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 tente d'associer le compte à l'aide de l'URL d'autorisation.
  • 2 : erreur irrécupérable. L'appli Google annule 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, reportez-vous au tableau des codes d'erreur.

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

Une valeur pour AUTHORIZATION_CODE est attendue lorsque resultCode == Activity.RESULT_OK. Dans tous les autres cas, la valeur pour AUTHORIZATION_CODE doit être vide. Si la valeur est 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	Récupérable	Date limite de récupération
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 la création de remplacement appropriée est déclenchée.

Tester App Flip sur votre appareil

Maintenant que vous avez créé une action 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 Assistant Google ou l'application Google Home pour tester App Flip.

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

1. Accédez à la console Actions, puis sélectionnez votre projet.
2. Cliquez sur Test dans la barre de navigation supérieure.
3. Déclenchez le parcours d'association de compte depuis l'application Assistant:
1. Ouvrez l'application Assistant Google.
2. Cliquez sur Paramètres.
3. Dans l'onglet "Assistant", cliquez sur Contrôle de la maison.
4. Cliquez sur Ajouter(+).
5. Sélectionnez votre action dans la liste des fournisseurs. Le nom de l'instance commence par "[test]" dans la liste. Lorsque vous sélectionnez votre action [test] dans la liste, elle devrait ouvrir votre application.
6. Vérifiez que votre application a été lancée et commencez à tester votre flux d'autorisation.

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

1. Accédez à la console Actions, puis sélectionnez votre projet.
2. Cliquez sur Test dans la barre de navigation supérieure.
3. Déclenchez le flux d'association de comptes depuis l'application Home:
1. Ouvrez l'application Google Home.
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 action pour maison connectée dans la liste des fournisseurs. Le nom de l'instance commence par "[test]" dans la liste. Lorsque vous sélectionnez votre action [test] dans la liste, elle devrait ouvrir votre application.
6. Vérifiez que votre application a été lancée et commencez à tester votre flux d'autorisation.