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

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 mettant en œuvre des intents intégrés de la catégorie "Santé et fitness". Les intents intégrés sont organisés en catégories représentant les types de tâches que les utilisateurs demandent fréquemment à l'Assistant.

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 [Intents intégrés courants], qui représente les tâches d'application courantes que la plupart des applications Android peuvent traiter.

Cet atelier de programmation aborde à niveau intermédiaire les concepts du développement avec les actions dans l'application. Vous devez avoir une expérience préalable du développement d'applications Android, de la gestion des liens profonds, de la création d'une ressource actions.xml et de l'utilisation du plug-in App Actions Test Tool (Outil de test des actions dans l'application). Les développeurs qui débutent avec les actions dans l'application peuvent commencer par suivre l'atelier de programmation précédent.

Ce que vous allez faire

Dans cet atelier de programmation, vous allez ajouter deux intents intégrés courants à une application de liste de tâches exemple, afin de permettre aux utilisateurs de demander à l'Assistant d'effectuer les opérations suivantes :

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

Ce que vous allez apprendre

  • Utiliser la catégorie d'intents intégrés courants pour intégrer l'Assistant à la plupart des applications Android
  • Tester les intents intégrés courants avec le plug-in App Actions Test Tool (Outil de test des actions dans l'application)

Ce dont vous avez besoin

  • Un terminal permettant d'exécuter des commandes d'interface système, avec Git installé
  • La dernière release stable d'Android Studio
  • Un compte Google ayant accès à la Google Play Console
  • Un appareil Android ou un émulateur ayant accès au Google Play Store via Internet pour tester vos actions

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

Dans cet atelier de programmation, vous allez utiliser une application de liste de tâches exemple pour Android. Les utilisateurs de cette application exemple peuvent ajouter des éléments à des listes de tâches, rechercher des éléments par catégorie et 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'application exemple :

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

Une fois le dépôt cloné, ouvrez-le dans Android Studio :

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

Pour afficher la version de l'application de liste de tâches que vous obtiendrez à la fin de cet atelier de programmation, clonez le dépôt de l'application exemple à l'aide de l'option --branch master.

Modifier l'identifiant de l'application Android pour activer les tests

Plus tard dans cet atelier de programmation, vous allez utiliser l'outil de test des actions dans l'application pour tester vos actions sur un appareil Android ou un émulateur. Pour que l'outil de test fonctionne, vous devez d'abord importer votre application dans un projet de la Google Play Console. Pour éviter une erreur du type "Duplicate package name" (Nom de package en double) lors de l'importation de l'application dans la Play Console, utilisez un nom qui vous est propre pour le paramètre applicationId de l'application exemple.

Dans app/build.gradle, remplacez la valeur "com.example.myapp" du paramètre "applicationId" par un identifiant unique, tel que "com.codelabs.myname". Si vous avez besoin d'aide pour trouver l'identifiant d'une application, consultez la page de référence Android.

build.gradle

android {
...
    defaultConfig {
        // This ID uniquely identifies your app on the device and in Google Play Store
        applicationId "com.example.myapp"
    ...
    }
}

Une fois que vous avez mis à jour le paramètre applicationId, ce message d'avertissement jaune peut s'afficher dans l'IDE : "Gradle files have changed since last project sync…" (Les fichiers Gradle ont été modifiés depuis la dernière synchronisation du projet…). Si tel est le cas, cliquez sur Sync Now (Synchroniser) dans le champ pour éviter les éventuels problèmes qui pourraient se produire lors de l'importation de votre application dans la Play Console.

Tester l'application sur votre appareil

Avant d'apporter d'autres modifications à l'application, il est utile de tester les fonctionnalités de l'application exemple. Essayez de l'exécuter sur un émulateur :

  • 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.
  • Dans la boîte de dialogue "Select Deployment Target" (Sélectionner une cible de déploiement), sélectionnez un appareil virtuel, puis cliquez sur OK. La version d'OS recommandée est Android 10 (niveau d'API 30) ou une version ultérieure, bien que les actions s'exécutent également sur des appareils fonctionnant sous Android 5 (niveau d'API 21).

Configurez l'Assistant et vérifiez qu'il fonctionne sur votre appareil en appuyant de manière prolongée sur le bouton Accueil. Si ce n'est pas déjà fait, vous devez vous connecter à l'Assistant sur votre appareil.

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

Animation illustrant l'application de liste de tâches exemple

Explorez rapidement les fonctionnalités de l'application. L'icône Plus permet de créer une tâche, tandis que les éléments de menu en haut à droite permettent de rechercher des tâches et de les filtrer selon leur état.

Effectuer l'importation dans la Play Console

Vous devez impérativement importer l'application dans un projet de la Google Play Console pour pouvoir utiliser l'outil de test des actions dans l'application dans Android Studio. Créez votre application dans Android Studio et importez-la dans la Play Console en tant que version brouillon interne.

Pour créer votre application dans Android Studio, procédez comme suit :

  1. Accédez à Build > Generate Signed Bundle / APK (Créer > Générer un app bundle/APK signé).
  2. Sélectionnez "Android App Bundle", puis cliquez sur Next (Suivant).
  3. Saisissez les informations pour signer votre application, puis cliquez sur Next (Suivant).
  4. Sélectionnez la variante de build "prodRelease", puis cliquez sur Finish (Terminer).

Dans la Google Play Console, importez l'app bundle que vous venez de créer en tant que nouvelle application :

  1. Sur la page Toutes les applications, cliquez sur Créer une application.
  2. Attribuez le nom de votre choix à l'application, puis cliquez sur Créer une application. Pour cet atelier de programmation, il n'est pas nécessaire de renseigner les informations sur l'application une fois celle-ci créée.
  3. Dans le menu latéral, accédez à Tests, puis ouvrez la page Tests internes.
  4. Sur la page Tests internes, sélectionnez Créer une release.
  5. Cliquez sur Continuer pour accepter la signature de l'application par Google Play.
  6. Dans le panneau App bundles et APK, importez le fichier AAB que vous avez généré précédemment (il figure probablement dans le répertoire app/prod/release). Cliquez sur Enregistrer.

Installer le plug-in de test

Le plug-in App Actions Test Tool (Outil de test des actions dans l'application) vous permet de tester les actions dans l'application pour un seul utilisateur 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", accédez à "Marketplace" et recherchez "App Actions Test Tool" (Outil de test des actions dans l'application). Vous pouvez également télécharger et installer manuellement l'outil de test.
  3. Installez l'outil, puis redémarrez Android Studio.

Au cours de cette étape, vous allez utiliser l'intent intégré Open app feature (Ouvrir la fonctionnalité de l'application), qui permet aux utilisateurs d'afficher leurs tâches actives et terminées à l'aide de l'Assistant. Pour ce faire, vous allez intégrer les liens profonds existants pour la fonctionnalité de filtrage des tâches à l'Assistant, en définissant l'intent intégré dans actions.xml. À la fin de cette section, vous testerez l'action sur votre appareil.

Avant de mettre en œuvre votre intent intégré, assurez-vous que les liens profonds existants dans votre application sont conformes au comportement identifié pour les actions dans l'application.

Pour tester les liens profonds à l'aide de l'outil de ligne de commande Android Debug Bridge (adb), procédez comme suit :

  1. Mettez l'application à jour sur votre appareil.
  2. Ajoutez des exemples d'éléments à la liste des tâches en appuyant sur le bouton "Actualiser" situé dans le menu à développer de la barre d'application :

Menu à développer dans la barre d'outils de l'application de liste de tâches

Si vous avez la possibilité d'ouvrir les liens via Google, sélectionnez Toujours pour autoriser l'Assistant à ouvrir les liens compatibles. Vous pouvez modifier cette option à tout moment dans les paramètres de l'application.

Dans votre terminal, saisissez chacune des commandes adb suivantes pour tester les liens profonds de filtrage des tâches dans l'application :

Afficher les tâches actives

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/active-tasks"

Afficher les tâches terminées

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/completed-tasks"

Afficher toutes les tâches

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/all-tasks"

Les commandes ci-dessus permettent d'ouvrir la fonctionnalité d'affichage sous forme de liste de l'application, en affichant les tâches filtrées selon l'état spécifié dans le chemin d'accès de chaque lien profond.

Ajouter l'intent intégré

Intégrez les liens profonds de filtrage des tâches à l'Assistant Google. Pour cela, définissez l'intent intégré Open app feature, configuré pour ouvrir ces liens, dans actions.xml.

Définissez l'intent intégré en mettant à jour le fichier actions.xml, situé dans le répertoire de l'exemple de projet app/src/main/res/xml, avec le code suivant :

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        //TODO: Handle intent parameters

        //TODO: Handle action fulfillment

    </action>
</actions>

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 à partir de la requête d'un utilisateur. Par exemple, si un utilisateur dit "Hey Google, order a pizza from ExampleApp" (Hey Google, commande une pizza depuis AppliExemple), l'Assistant extrait le mot "pizza" dans un paramètre d'intent food.item de schema.org, puis transmet ce paramètre à votre action.

L'intent intégré Open app feature est compatible avec le paramètre feature, qui représente la fonctionnalité de l'application extraite à partir de la requête de l'utilisateur. Un inventaire intégré est requis pour ce paramètre. Il fournit à l'Assistant un ensemble de noms de fonctionnalités compatibles à associer à la valeur du paramètre.

Pour gérer le paramètre d'intent feature, mettez à jour le fichier actions.xml avec le code suivant :

actions.xml

<?xml version="1.0" encoding="utf-8"?>

<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        <parameter name="feature">
            <entity-set-reference entitySetId="FeatureEntitySet" />
        </parameter>

        //TODO: Handle action fulfillment

    </action>
</actions>

Dans l'exemple de code ci-dessus, vous avez demandé à l'Assistant de faire correspondre les valeurs des paramètres de fonctionnalités à un inventaire intégré, FeatureEntitySet, défini comme entity-set-reference dans le tag du paramètre.

Définissez l'inventaire intégré pour votre intent intégré en ajoutant le paramètre entity-set suivant au fichier actions.xml, sous l'élément action :

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action>
       ...
    </action>

    <entity-set entitySetId="FeatureEntitySet">
        <entity  url="https://todo.androidappactions.com/completed-tasks"
            name="completed tasks" alternateName="@array/completed_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/active-tasks"
            name="active tasks" alternateName="@array/active_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/all-tasks"
            name="all tasks" alternateName="@array/all_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/statistics"
            name="statistics" alternateName="@array/statistics_synonyms"/>
    </entity-set>
</actions>

Dans le code ci-dessus, vous avez défini un inventaire intégré, représenté par un élément entity-set contenant quatre éléments entity. Lorsqu'un utilisateur active cet intent intégré avec une requête, l'Assistant associe la valeur du paramètre feature à l'attribut name d'une entité (entity), en transmettant l'url d'une entité (entity) correspondante à votre traitement.

Par exemple, si un utilisateur dit "Hey Google, show my completed tasks in ExampleApp" (Hey Google, affiche mes tâches terminées dans AppliExemple), l'Assistant associe la valeur du paramètre d'intent de la fonctionnalité (feature), "completed tasks" (tâches terminées), à l'entité (entity) correspondante de l'inventaire. L'Assistant transmet ensuite l'URL associée (https://todo.androidappactions.com/completed-tasks) à votre traitement.

Définir le traitement de l'action

Pour traiter l'action, vous devez définir un élément fulfillment dans le fichier actions.xml pour gérer l'URL transmise par l'Assistant. Ajoutez un traitement (fulfillment) à votre action à l'aide du code suivant :

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        ... //Parameter definition

        <fulfillment urlTemplate="{@url}"/>
        <fulfillment urlTemplate="https://todo.androidappactions.com/all-tasks"/>

    </action>
   ...
</actions>

Dans l'exemple ci-dessus, vous avez défini deux éléments fulfillment. Le premier déclenche le lien profond généré par l'Assistant Google à partir du paramètre feature, représenté sous la forme d'un espace réservé {@url} dans l'attribut urlTemplate. Le deuxième traitement (fulfillment) est utilisé en remplacement. Il permet d'ouvrir une liste de tâches non filtrée pour les cas où le paramètre feature est manquant ou si aucun élément (element) de l'inventaire intégré correspondant n'a pu être trouvé.

Tester votre action dans l'application

Au cours des phases de développement et de test, vous utilisez l'outil de test des actions dans l'application pour prévisualiser votre action dans l'application avec l'Assistant sur un appareil de test. Cet outil vous permet également d'ajuster les paramètres d'intent pour une action dans l'application, afin de tester les différentes manières dont votre action gère les requêtes d'un utilisateur.

Testez l'action dans votre application avec l'outil de test en procédant comme suit :

  1. Connectez votre appareil de test Android physique ou démarrez votre émulateur Android.
  2. Accédez à Tools > App Actions > App Actions Test Tool (Outils > Actions dans l'application > Outil de test des actions dans l'application). Vous serez peut-être invité à vous connecter à Android Studio. Utilisez le même compte que celui utilisé précédemment dans la Google Play Console.
  3. Dans le champ Invocation Name (Nom de l'appel), saisissez "Task List" (Liste de tâches).
  4. Si l'Assistant n'est pas défini dans la langue "Anglais (en)", saisissez les paramètres régionaux correspondant à la langue de l'Assistant dans le champ "Locale" (Paramètres régionaux).
  5. Cliquez sur Create Preview (Créer un aperçu).
  6. Dans la liste déroulante Configure (Configurer), sélectionnez l'intent intégré actions.intent.OPEN_APP_FEATURE.
  7. Dans le champ feature (fonctionnalité), remplacez la valeur par défaut "History" (Historique) par "Completed tasks" (Tâches terminées).
  8. Cliquez sur "Run" (Exécuter).

Vous pouvez également utiliser le nom d'appel directement dans l'application de l'Assistant sur votre appareil pour tester votre action dans l'application. Par exemple, vous pouvez dire "Hey Google, show completed tasks in Task List" (Hey Google, affiche les tâches terminées dans la liste des tâches).

L'intent intégré Get thing (Faire une recherche) intègre les fonctionnalités de recherche de l'application à l'Assistant Google. Au cours de cette étape, vous allez mettre en œuvre et tester l'intent intégré Get thing, qui permet aux utilisateurs de rechercher des tâches spécifiques dans l'application exemple.

L'application exemple dispose d'un lien profond existant pour ses fonctionnalités de recherche. Avant de mettre en œuvre votre intent intégré, utilisez adb pour vérifier que ce lien profond est conforme au comportement identifié pour les actions dans l'application.

Testez le lien profond de la recherche avec la commande adb suivante :

# GET_THING deep link: in-app search
adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/search?q=milk"

La commande ci-dessus déclenche un lien profond qui charge la liste d'éléments filtrée sur les éléments contenant la requête "home".

Ajouter l'intent intégré

Lors d'une action dans l'application liée à la recherche, l'Assistant extrait les termes de recherche de la requête de l'utilisateur dans un paramètre d'intent thing.name. L'Assistant génère ensuite une URL pour le traitement en mappant le paramètre dans un modèle d'URL que vous définissez dans un élément fulfillment.

Pour définir l'intent intégré Get thing dans votre application, mettez à jour le fichier actions.xml avec cette nouvelle action :

Actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
   <action intentName="actions.intent.OPEN_APP_FEATURE">...</action>

   <action intentName="actions.intent.GET_THING">

        <parameter-mapping
                intentParameter="thing.name"
                urlParameter="q"/>

        <fulfillment urlTemplate="https://todo.androidappactions.com/search?q={q}">
        </fulfillment>

   </action>

   ...
</actions>

Dans l'exemple ci-dessus, l'élément parameter-mapping attribue le paramètre d'intent thing.name à la valeur "q" de l'attribut urlParameter de l'élément fulfillment. L'Assistant génère ensuite le lien profond en mappant la valeur urlParameter sur l'espace réservé "{q}" dans le modèle urlTemplate fulfillment.

Tester votre action dans l'application

Pour tester les fonctionnalités de recherche dans votre application depuis l'Assistant, procédez comme suit :

  1. Connectez votre appareil de test Android physique ou démarrez votre émulateur Android.
  2. Accédez à Tools > App Actions > App Actions Test Tool (Outils > Actions dans l'application > Outil de test des actions dans l'application).
  3. Cliquez sur Update Preview (Mettre à jour l'aperçu).
  4. Dans la liste déroulante "Configure" (Configurer), sélectionnez l'intent actions.intent.GET_THING. Dans le paramètre "name" (nom), remplacez la valeur "running shoes" (chaussures de sport) par "milk" (lait).
  5. Cliquez sur Run (Exécuter).

Au cours de ce test, l'intent intégré Get thing utilise l'attribut name pour rechercher les tâches contenant "home" dans l'application. Comme pour l'action précédente, vous pouvez tester votre action à l'aide de l'outil de test. Sinon, vous pouvez simplement dire "Hey Google, search for cake mix in Task List" (Hey Google, recherche une préparation pour gâteau dans la liste des tâches) ou énoncer d'autres expressions de recherche sur votre appareil de test.

Félicitations !

Grâce aux intents intégrés courants, vous pouvez désormais utiliser l'Assistant Google avec la plupart des applications Android.

Points abordés

Dans cet atelier de programmation, vous avez appris ce qui suit :

  • Comment permettre aux utilisateurs d'exploiter au maximum les fonctionnalités de l'application avec l'Assistant
  • Comment les utilisateurs peuvent accéder à la recherche dans l'application depuis l'Assistant
  • Comment tester les intents intégrés courants à l'aide de l'outil de test des actions dans l'application

É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 –master branch sur GitHub.

Voici quelques suggestions pour vous aider à développer cette application avec des actions dans l'application :

Pour continuer à explorer Actions on Google, consultez les ressources suivantes :

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

Enquête

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