Bienvenue dans le centre Google Home pour les développeurs, la nouvelle destination pour apprendre à développer des actions pour la maison connectée. Remarque:Vous continuerez de créer des actions dans la console Actions.

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.

Design guidelines

This section describes the design requirements and recommendations for the App Flip account linking consent screen. After Google calls your app, your app displays the consent screen to the user.

Requirements

  1. You must communicate that the user's account is being linked to Google, not to a specific Google product, such as Google Home or Google Assistant.

Recommendations

We recommend that you do the following:

  1. Display Google's Privacy Policy. Include a link to Google's Privacy Policy on the consent screen.

  2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

  3. Clear call-to-action. State a clear call-to-action on your consent screen, such as "Agree and link." This is because users need to understand what data they're required to share with Google to link their accounts.

  4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

  5. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

  6. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

    • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking and the implicit flow.

  7. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

This figure shows an example consent screen with call-outs to the individual requirements and recommendations to be followed when you design a user consent screen.
Figure 1: Account linking consent screen design guidelines.

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:

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.
Précédent
Créer un projet Actions
Suivant
Identifier et synchroniser