Intégrer une application Android à l'Assistant Google grâce aux actions dans l'application (niveau 2)

1. Présentation

Les actions dans l'application permettent aux utilisateurs d'accéder directement à des fonctionnalités spécifiques de l'Assistant Google pour vous aider à élargir l'audience de votre application Android. En tant que développeur Android, vous pouvez implémenter des capacités qui permettent à l'Assistant Google de savoir quel type de fonctionnalité est disponible pour les utilisateurs et comment vous souhaitez traiter ces requêtes.

Dans le premier atelier de programmation sur les actions dans l'application, vous avez appris à intégrer l'Assistant Google à une application de fitness exemple en implémentant des intents intégrés de la catégorie "Santé et remise en forme". Les intents intégrés sont organisés en catégories représentant les types de tâches que les utilisateurs demandent souvent à l'Assistant.

Terme clé : un intent intégré Assistant est un déclencheur prédéfini pour un type de fonctionnalité spécifique que l'utilisateur souhaite effectuer. Google crée et gère les modèles de langage pour les intents intégrés afin de comprendre un large éventail de requêtes liées à cet intent.

Dans cet atelier de programmation, vous allez apprendre à ajouter des actions dans une application à l'aide des intents intégrés de la catégorie "Common" (Courants), qui représente les tâches courantes que la plupart des applications Android peuvent réaliser.

Cet atelier de programmation de niveau intermédiaire présente les concepts de développement avec les actions dans l'application. Vous devez avoir une expérience préalable du développement d'applications Android et de l'implémentation d'intents Android.

Objectifs de l'atelier

Dans cet atelier de programmation, vous allez ajouter deux intents courants (courants) à une application exemple de liste de tâches. Les utilisateurs pourront ainsi demander à l'Assistant :

• d'accéder aux fonctionnalités de l'application avec l'intent intégré actions.intent.OPEN_APP_FEATURE ;
• de rechercher des contenus à l'aide de la recherche dans l'application avec l'intent intégré actions.intent.GET_THING.

Remarque : Les applications doivent comporter une fonctionnalité de recherche pour que l'intent intégré actions.intent.GET_THING puisse être implémenté. En savoir plus sur les exigences de déploiement des actions dans les applications

Figure 1. Trois écrans progressifs sur lesquels l'Assistant Google affiche des tâches actives dans une application.

Points abordés

Vous découvrirez comment utiliser les intents intégrés courants pour étendre l'Assistant à la plupart des applications Android. Vous apprendrez également à tester les intents intégrés courants avec le plug-in Assistant Google pour Android Studio.

Prérequis

• Un terminal permettant d'exécuter des commandes shell et avec git installé
• La dernière version stable d'Android Studio
• Un appareil Android physique ou virtuel connecté à Internet pour accéder au Google Play Store afin de tester vos actions
• Un même compte Google connecté à Android Studio, ainsi qu'à l'application Google et à l'application Assistant Google sur votre appareil de test

Remarque : Vous pouvez tester les actions dans l'application décrites dans cet atelier de programmation avec l'Assistant Google dans un nombre limité de paramètres régionaux. Consultez la documentation de référence sur les intents intégrés courants pour savoir quels intents sont disponibles selon les paramètres régionaux.

Dans cet atelier de programmation, vous allez utiliser un appareil Android (physique ou virtuel) pour tester vos actions. Si vous utilisez un appareil physique, vérifiez qu'il est connecté à votre ordinateur de développement local. Vous devez également être connecté à l'application Google sur l'appareil et à Android Studio avec le même compte Google. L'application Assistant Google doit aussi être installée sur l'appareil.

2. Principes de fonctionnement

Les actions dans l'application permettent aux utilisateurs d'accéder à l'Assistant Google depuis votre application Android. Comment cela fonctionne-t-il ?

Lorsqu'un utilisateur indique à l'Assistant qu'il souhaite utiliser votre application, l'Assistant recherche les actions enregistrées dans votre application à partir d'un fichier shortcuts.xml. Ce fichier contient les capacités de l'application, qui associent un intent intégré Assistant ou un intent personnalisé à un intent Android ou un lien profond.

Terme clé : les capacités sont des modèles que vous définissez dans shortcuts.xml pour déclarer les types d'actions que les utilisateurs peuvent effectuer afin de lancer votre application et accéder directement à une tâche spécifique. Pour en savoir plus, consultez la documentation Android sur les capacités.

Lorsqu'un utilisateur prononce une requête à l'Assistant, elle est analysée par l'Assistant, qui la met en correspondance avec un intent App Actions (Actions dans les applications). Dans cet atelier de programmation, il s'agira d'un intent intégré. L'Assistant sait quelles capacités sont compatibles d'après votre fichier shortcuts.xml dans votre application Android. Avec la mise en correspondance d'intent, la capacité associée à l'intent intégré contient la manière dont vous souhaitez répondre à cette requête. Dans cet atelier de programmation, le traitement est un intent Android qui lance une activité dans votre application.

Le schéma suivant illustre ce flux de l'Assistant :

Figure 2. Flux décrivant comment l'Assistant Google traite une requête vocale.

Le fichier de projet shortcuts.xml contient les informations suivantes pour chaque action dans l'application :

• Intent intégré ou intent personnalisé utilisé par l'action dans l'application
• Activité Android ou lien profond à fournir à l'utilisateur
• Correspondance entre les paramètres de l'intent intégré et les informations fournies à l'Assistant par l'utilisateur

Votre activité Android filtre et gère l'intent Android ou le lien profond fourni pour que l'utilisateur obtienne la fonctionnalité souhaitée. Il en résulte une expérience utilisateur dans laquelle l'Assistant appelle la fonctionnalité de votre application en réponse à la requête de l'utilisateur.

3. Préparer votre environnement de développement

Cet atelier de programmation utilise l'application exemple de liste de tâches pour Android. Cette application exemple permet de dresser des listes de tâches, de rechercher des éléments de ces listes par catégorie et d'afficher des informations sur les tâches terminées.

Télécharger vos fichiers de base

Exécutez la commande suivante pour cloner le dépôt GitHub de l'exemple d'application :

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

Une fois le dépôt cloné, procédez comme suit pour l'ouvrir dans Android Studio :

1. Dans la boîte de dialogue Welcome to Android Studio (Bienvenue dans Android Studio), cliquez sur Import project (Importer un projet).
2. Recherchez et sélectionnez le dossier dans lequel vous avez cloné le dépôt.

Pour voir une version de l'application représentant l'atelier de programmation terminé, clonez le dépôt de l'exemple d'application à l'aide de l'indicateur --branch master.

Modifier l'ID d'application Android

Modifier l'ID de l'application permet d'identifier de manière unique l'application sur votre appareil de test et d'éviter une erreur "Duplicate package name" (Nom de package en double) si l'application est importée dans la Play Console. Pour modifier l'ID application, ouvrez app/build.gradle :

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

Dans le champ applicationId, remplacez "MYUNIQUENAME" par un nom qui vous est propre.

Remarque : Une fois que vous avez modifié applicationId, l'avertissement suivant s'affiche dans Android Studio : "Gradle files have changed from last project sync…" (Les fichiers Gradle ont été modifiés depuis la dernière fois que le projet a été synchronisé…). Cliquez sur Sync now (Synchroniser maintenant) pour éviter les problèmes susceptibles de se produire lorsque vous importerez votre application.

Tester l'application sur votre appareil

Avant d'apporter d'autres modifications au code de l'application, il peut être utile de la tester pour vous faire une idée de ses fonctionnalités. Pour exécuter l'application sur votre émulateur, procédez comme suit :

1. Dans Android Studio, sélectionnez Run > Run app (Exécuter > Exécuter l'application) ou cliquez sur Run  (Exécuter) dans la barre d'outils.
2. Dans la boîte de dialogue Select Deployment Target (Sélectionner une cible de déploiement), sélectionnez un appareil, puis cliquez sur OK. La version d'OS recommandée est Android 10 (niveau d'API 30) ou version ultérieure, bien que les actions fonctionnent sur des appareils à partir d'Android 5 (niveau d'API 21).
3. Appuyez de manière prolongée sur le bouton Accueil pour configurer l'Assistant et vérifier qu'il fonctionne. Vous devrez vous connecter à l'Assistant sur votre appareil si ce n'est pas déjà fait.

Pour en savoir plus sur les appareils virtuels Android, consultez Créer et gérer des appareils virtuels.

Figure 3. Animation illustrant l'application exemple de liste de tâches

Parcourez l'application pour en voir les fonctionnalités. Appuyez sur l'icône Plus pour créer une tâche. Les éléments de menu en haut à droite vous permettent de rechercher et de filtrer les tâches par état.

Installer le plug-in de test

Le plug-in Assistant Google vous permet de tester vos actions dans les applications sur un appareil de test. Si vous ne possédez pas encore l'outil de test, installez-le en procédant comme suit :

1. Accédez à File > Settings (Fichier > Paramètres), ou à Android Studio > Preferences (Android Studio > Préférences) sous macOS.
2. Dans la section "Plugins" (Plug-ins), accédez à Marketplace et recherchez "Google Assistant" (Assistant Google). Vous pouvez aussi télécharger et installer manuellement l'outil de test.
   • Si vous ne trouvez pas le plug-in sur Marketplace, téléchargez-le manuellement et suivez les instructions figurant sur la page Installer le plug-in depuis un disque.
3. Installez l'outil, puis redémarrez Android Studio.

Remarque : Le plug-in de test envoie des informations à l'Assistant via l'appli Google sur votre appareil Android.

4. Ajouter la capacité d'intent intégré "Get Thing" (Faire une recherche)

L'intent intégré actions.intent.GET_THING étend vos fonctionnalités de recherche dans l'application à l'Assistant Google. À cette étape, vous allez implémenter et tester l'intent intégré GET_THING, qui permet aux utilisateurs de rechercher des tâches spécifiques dans l'application exemple.

Conseil : L'intent intégré GET_THING permet de rechercher du contenu ou des entités à l'aide de la fonctionnalité de recherche dans l'application par défaut. Renseignez les critères de recherche avec le nom du contenu ou de l'entité à l'aide du paramètre d'intent thing.name, puis présentez les résultats de recherche les plus pertinents à l'utilisateur.

Définir la capacité "Get Thing" (Faire une recherche)

Lors d'une action de recherche dans l'application, l'Assistant extrait les termes de recherche de la requête utilisateur dans le paramètre d'intent intégré thing.name, puis transmet cette valeur à l'application Android.

Pour ajouter l'intent intégré GET_THING à votre application, mettez à jour shortcuts.xml, situé dans le répertoire d'exemple de projet app/src/main/res/xml, avec un élément <capability> dans le tag de premier niveau <shortcuts> :

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

La configuration ci-dessus :

1. indique que l'application répond à l'intent intégré GET_THING ;
2. spécifie comment créer un intent Android qui lance l'application en réponse à cet intent intégré.
   • L'activité est identifiée à l'aide de targetPackage et targetClass.
   • Le paramètre d'intent intégré thing.name est mappée dans l'intent supplémentaire nomméq.

L'activité nommée doit être présente dans le fichier manifeste de l'application et exportée.

L'application Android fournie contient des métadonnées. Le fichier AndroidManifest est donc informé du fichier shortcuts.xml :

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

Tester votre action dans l'application

Pour tester la recherche dans votre application depuis l'Assistant :

1. Vérifiez que votre appareil Android est connecté.
2. Accédez à Tools > Google Assistant > App Actions Test Tool (Outils > Assistant Google > Outil de test des actions dans l'application).
3. Cliquez sur Create Preview (Créer un aperçu) pour accepter les valeurs par défaut de App name (Nom de l'application) et locale (paramètres régionaux). Si vous y êtes invité, lisez et acceptez les règles et les conditions d'utilisation des actions dans les applications.
4. Lors de la première étape, quand l'outil vous demande de sélectionner et de configurer un intent intégré, sélectionnez actions.intent.GET_THING. Remplacez la valeur running shoes de name par milk.
5. Cliquez sur Run App Action (exécuter l'action dans l'application).

Dans ce test, l'intent intégré GET_THING utilise l'attribut name pour rechercher des tâches dans l'application qui contiennent le terme "milk" (lait). Comme pour l'action dans l'application précédente, vous pouvez tester celle-ci à l'aide de l'outil de test, ou simplement dire Hey Google, recherche "préparation gâteau" dans la liste des tâches ou d'autres expressions de recherche sur votre appareil de test.

Conseil : Si vous rencontrez des problèmes lors de l'exécution de l'outil de test, consultez le guide de dépannage.

5. Ajouter la capacité d'intent intégré "Open app" (Ouvrir l'application)

À cette étape, vous allez implémenter la capacité d'intent intégré "Open app" (Ouvrir l'application), qui permet aux utilisateurs d'afficher leurs tâches actives et terminées à l'aide de l'Assistant. Pour ce faire, complétez la capacité dans shortcuts.xml. Elle contient des informations sur le déclenchement de la capacité, la transmission de paramètres et les intents Android à appeler. Pour cet atelier de programmation, vous utiliserez l'intent intégré OPEN_APP_FEATURE. Une fois que vous aurez implémenté cet intent intégré, vous testerez l'action sur votre appareil.

Remarque : Cet intent intégré lance une fonctionnalité de l'application. Il est particulièrement utile pour aider les utilisateurs à accéder à des fonctionnalités de votre application qui, sinon, pourraient être difficiles à trouver ou nécessiter plusieurs appuis. Vous devez spécifier l'inventaire intégré pour le paramètre de la fonctionnalité.

Ajouter la capacité "Open app" (Ouvrir l'application)

Ajoutez une deuxième capacité "Open app" (Ouvrir l'application) dans shortcuts.xml sous l'élément de capacité "Get Thing" (Faire une recherche) :

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

Cette capacité permet de mapper l'intent intégré d'ouverture de l'application et l'intent Android. Ainsi, lorsque la fonctionnalité d'ouverture de l'application est déclenchée, l'intent Android se déclenche.

Avant de déclencher l'intent Android, les paramètres compatibles sont extraits de l'entrée utilisateur. L'intent intégré OPEN_APP_FEATURE accepte un paramètre, feature, qui représente la fonctionnalité de l'application extraite de la requête utilisateur. Cette application prendra en charge deux types de fonctionnalités : Active Task (Tâche active) et Completed Task (Tâche terminée). Elles permettent aux utilisateurs d'ouvrir l'application avec une vue filtrée de leur liste de tâches. Vous devez utiliser l'inventaire intégré pour prendre en charge ces fonctionnalités.

Terme clé : un inventaire intégré guide l'extraction des entités pour les intents intégrés en fournissant un ensemble d'entités qu'une application comprend pour un paramètre d'intent intégré compatible avec l'inventaire intégré. Pour en savoir plus, consultez la section Inventaire intégré pour les actions dans les applications.

Gérer les paramètres d'intent à l'aide de l'inventaire intégré

Les paramètres d'intent représentent les éléments extraits d'une requête utilisateur. Par exemple, si un utilisateur dit Hey Google, commande une pizza chez ExampleApp, l'Assistant extrait "pizza" dans un intent schema.org food.item, puis le transmet à votre action à gérer.

L'intent intégré d'ouverture de l'application accepte un paramètre, feature, qui représente la fonctionnalité de l'application extraite de la requête utilisateur. Un inventaire intégré est requis pour ce paramètre. Il fournit à l'Assistant un ensemble de noms de fonctionnalités d'application compatibles correspondant à la valeur du paramètre.

Pour gérer le paramètre d'intent feature, ajoutez un raccourci vers votre shortcuts.xml avec le code suivant au-dessus de la capacité de la fonctionnalité d'ouverture de l'application :

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

Dans le code ci-dessus, vous avez défini un inventaire intégré, représenté par des éléments shortcut avec des liaisons de paramètres et de capacités. Les raccourcis peuvent servir d'inventaire pour les paramètres d'intent intégré. L'Assistant Google fait correspondre la requête utilisateur avec les valeurs de la liaison de paramètres des raccourcis. Pour une valeur de paramètre correspondante, shortcutId sera ajouté à l'intent de traitement. Lorsqu'un utilisateur active l'intent intégré OPEN_APP_FEATURE avec une requête, l'Assistant associe la valeur du paramètre de fonctionnalité à l'attribut de valeur d'un raccourci, transmettant la valeur à targetClass en tant que parameter dans Extra.

Par exemple, si un utilisateur dit Hey Google, affiche mes tâches terminées dans ExampleApp, l'Assistant associe la valeur du paramètre d'intent de la fonctionnalité, "tâches terminées", au raccourci d'inventaire correspondant, qui transmet cette valeur à la capacité OPEN_APP_FEATURE. L'Assistant déclenche ensuite l'intent Android.

Tester votre action dans l'application

Pendant les phases de développement et de test, utilisez le plug-in Assistant Google pour prévisualiser vos actions dans l'application via l'Assistant sur un appareil de test. Vous pouvez également utiliser l'outil afin d'ajuster les paramètres d'intent pour une action dans l'application. Cela vous permet de voir comment votre action gère les différentes façons dont un utilisateur peut demander à l'Assistant de l'exécuter.

Pour tester votre action dans l'application avec l'outil de test :

1. Connectez votre appareil de test Android ou démarrez votre émulateur Android
2. Si l'outil de test n'est pas visible, ouvrez-le en accédant à Tools > Google Assistant > App Actions Test Tool (Outils > Assistant Google > Outil de test des actions dans l'application).
3. Cliquez sur le bouton Update (Mettre à jour) pour actualiser l'aperçu.
4. Lors de la première étape, quand l'outil vous demande de sélectionner et de configurer un intent intégré, sélectionnez actions.intent.OPEN_APP_FEATURE.
5. Dans le champ feature (fonctionnalité), remplacez la valeur par défaut (History) par Completed tasks.
6. Cliquez sur Run App Action (exécuter l'action dans l'application).

Conseil : Si vous rencontrez des problèmes lors de l'exécution de l'outil de test, consultez le guide de dépannage.

Vous pouvez également utiliser le nom d'appel directement dans l'application Assistant sur votre appareil pour tester votre action dans l'application. Par exemple, vous pouvez dire Hey Google, affiche les tâches terminées dans la liste de tâches.

6. Étapes suivantes

Félicitations !

Vous pouvez désormais permettre à presque toutes les applications Android de fonctionner avec l'Assistant Google à l'aide des intents intégrés courants.

Points abordés

Dans cet atelier de programmation, vous avez appris :

• à permettre aux utilisateurs d'accéder à des fonctionnalités spécifiques de l'application à l'aide de l'Assistant ;
• comment les utilisateurs peuvent accéder à la recherche dans l'application avec l'Assistant ;
• à tester les intents intégrés courants à l'aide du plug-in Assistant Google.

Étapes suivantes

À présent, vous pouvez essayer d'affiner votre application de liste de tâches. Pour référencer le projet terminé, consultez le dépôt principal sur GitHub.

Voici quelques suggestions pour en savoir plus sur l'intégration d'actions dans l'application :

• Consultez l'exemple de liste de tâches avec Google Analytics pour Firebase pour découvrir comment suivre les performances de vos actions dans les applications.
• Consultez la documentation de référence sur les intents intégrés concernant les actions dans les applications et découvrez d'autres façons d'intégrer l'Assistant à vos applications.

Pour poursuivre votre parcours Actions on Google, consultez les ressources suivantes :

• developers.google.com/assistant : site de documentation officiel d'Actions on Google
• Exemple d'index des actions dans l'application : exemples d'applications et de code pour découvrir les fonctionnalités des actions dans les applications
• Dépôt GitHub sur Actions on Google : exemples de code et de bibliothèques
• r/GoogleAssistantDev : communauté Reddit officielle des développeurs qui utilisent l'Assistant Google

Suivez-nous sur Twitter (@ActionsOnGoogle) pour connaître les dernières informations, et tweetez avec le #AoGDevs pour montrer votre création.

Enquête

Pour terminer, veuillez répondre à cette enquête afin de nous faire part de vos commentaires sur cet atelier de programmation.