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

1. Présentation

Avec les actions dans l'application, vous pouvez utiliser l'Assistant Google pour accéder directement aux fonctionnalités de l'application et effectuer des tâches par commande vocale. En tant que développeur Android, vous implémentez des éléments de capacités pour ajouter des actions dans l'application. Les capacités permettent à l'Assistant de savoir quelles fonctionnalités de l'application acceptent les requêtes vocales de l'utilisateur et comment elles doivent être traitées.

Cet atelier de programmation est destiné aux débutants et 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 d'intents Android pour suivre cet atelier de programmation. Si vous débutez avec Android, vous pouvez commencer par suivre l'un des ateliers de programmation concernant les Principes de base du développement Android.

Objectifs de l'atelier

Dans cet atelier de programmation, vous allez ajouter deux intents intégrés d'actions dans les applications à une application de fitness exemple sur Android. Ils permettront aux utilisateurs de démarrer et d'arrêter un minuteur en utilisant leur voix.

Points abordés

Vous apprendrez à utiliser les intents intégrés de la catégorie Santé et remise en forme pour intégrer l'Assistant à une application Android. Vous apprendrez également à utiliser le plug-in Assistant Google pour Android Studio afin de tester vos intents intégrés.

Conditions préalables

Avant de continuer, assurez-vous que votre environnement dispose des outils suivants :

• Un terminal permettant d'exécuter des commandes shell et avec git installé
• La dernière version d'Android Studio
• Un compte Google ayant accès à la [Google Play Console][]
• Un appareil Android physique ou virtuel connecté à Internet pour accéder au Play Store

Avant de continuer, assurez-vous d'utiliser le même compte Google pour Android Studio et l'appli Google sur votre appareil de test.

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 demande à l'Assistant d'effectuer une tâche à l'aide de votre application, il fait correspondre sa requête à une capability (capacité) de l'action dans l'application définie dans la ressource XML shortcuts.xml de votre application.

Terme clé : les éléments de capacité 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.

Figure 1. Schéma illustrant la façon dont l'Assistant traite une requête vocale d'action dans l'application.

Chaque élément de capacité définit :

• Un intent : l'intent vocal "Actions dans l'application" qui doit déclencher la capacité.
• Un ou plusieurs traitements : intents Android ou liens profonds générés par l'Assistant pour lancer l'application et traiter la requête vocale de l'utilisateur. Les définitions de traitement spécifient les paramètres attendus de la requête utilisateur et la manière dont ils doivent être encodés dans les instructions de lancement.

Intents

Dans la compréhension du langage naturel (NLU), un intent est un groupe de phrases utilisateur qui ont des significations similaires. Google propose des dizaines d'intents "intégrés" couvrant un large éventail de types de requêtes disponibles avec les actions dans les applications. Par exemple, l'Assistant est entraîné pour associer les phrases "Commander une pizza" ou "montre-moi la carte des desserts" à l'intent intégré ORDER_MENU_ITEM. Les actions dans les applications vous permettent d'exploiter ces intents pour associer rapidement les requêtes vocales courantes aux fonctionnalités de l'application.

Traitements

Lorsqu'une requête utilisateur déclenche une action dans l'application dans shortcuts.xml, votre activité Android doit ensuite détecter et gérer l'intent Android ou le lien profond entrant, puis fournir à l'utilisateur la fonctionnalité souhaitée. Il en résulte une expérience utilisateur basée sur les commandes vocales dans laquelle l'Assistant appelle 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 de fitness exemple pour Android. Elle permet aux utilisateurs de démarrer et d'arrêter un minuteur, et de consulter des statistiques sur leur programme d'exercices.

Télécharger vos fichiers de base

Pour obtenir les fichiers de base nécessaires à cet atelier de programmation, exécutez la commande suivante pour cloner le dépôt GitHub :

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

Une fois le dépôt cloné, ouvrez-le 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.

Remarque : La commande git clone ci-dessus vérifie la branche codelab-start du dépôt, qui est le point de départ de cet atelier de programmation. Pour accéder à l'application une fois l'atelier de programmation terminé, consultez la branche principale du dépôt.

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é…). Dans cet encadré d'avertissement, cliquez sur Sync now (Synchroniser maintenant) pour éviter les problèmes susceptibles de se produire lorsque vous importerez votre application.

Essayer 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 tester l'application dans votre environnement de développement, procédez comme suit :

1. Ouvrez de votre appareil de test Android physique ou virtuel.
2. Vérifiez que l'application d'assistance fonctionne.
3. Utilisez Android Studio pour déployer et exécuter l'application exemple sur votre appareil.

Pour tester votre application, 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. Si vous utilisez un appareil virtuel, sélectionnez un appareil virtuel dans la boîte de dialogue Select Deployment Target (Sélectionner une cible de déploiement), puis cliquez sur OK. La version d'OS recommandée est Android 8 (niveau d'API 26) ou version ultérieure, bien que les actions s'exécutent sur des appareils à partir d'Android 5 (niveau d'API 21).
3. Après avoir ouvert l'application, appuyez de manière prolongée sur le bouton Accueil pour configurer l'Assistant et vérifier qu'il fonctionne. Connectez-vous à l'Assistant si ce n'est pas déjà fait.
4. Rouvrez l'application.

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

Figure 2. Application exemple "Fit Actions" affichant des statistiques sur les exercices

Parcourez l'application pour voir ses fonctionnalités. Appuyez sur l'icône Démarrer pour lancer un minuteur, puis sur l'icône X pour l'arrêter. Ce sont les tâches pour lesquelles les commandes vocales seront activées grâce aux actions dans l'application.

Installer le plug-in Assistant Google

Le plug-in Assistant Google vous permet de tester vos actions dans les applications sur un appareil de test. Pour l'ajouter à Android Studio, procédez 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).
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. Pour que les actions dans l'application fonctionnent correctement, votre appareil de test doit avoir accès au Play Store afin de mettre à jour l'appli Google.

4. Ajouter la capacité d'intent intégré "Commencer l'exercice"

L'intent intégré actions.intent.START_EXERCISE permet aux utilisateurs d'ouvrir l'application et de démarrer leur entraînement par commande vocale. Lors de cette étape, vous allez implémenter une capacité pour cet intent intégré, qui permet aux utilisateurs de demander à l'Assistant de démarrer un exercice dans l'application de remise en forme.

Définir la capacité

L'Assistant utilise les éléments capability définis dans shortcuts.xml pour traiter les commandes vocales comme suit :

1. L'Assistant associe la requête vocale de l'utilisateur à un intent intégré dans les capacités de votre application.
2. L'Assistant extrait les valeurs de la requête dans les paramètres d'intent intégré. Chaque paramètre est ajouté à un Bundle associé à un Intent généré.
3. L'Assistant utilise l'Intent pour lancer l'application, ce qui lui permet d'accéder aux paramètres groupés.

L'intent intégré START_EXERCISE est compatible avec le paramètre d'intent intégré exercise.name. Ce paramètre permettra aux utilisateurs de spécifier le type d'exercice à suivre dans l'application.

Ajoutez l'intent intégré START_EXERCISE à votre application en ajoutant la capability (capacité) à shortcuts.xml, situé dans le répertoire d'exemple de projet app/src/main/res/xml :

<!-- shortcuts.xml -->

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <parameter
      android:name="exercise.name"
      android:key="exerciseType"/>
  </intent>
</capability>

Remplacez PUT_YOUR_APPLICATION_ID_HERE par l'applicationId unique que vous avez définie à l'étape précédente.

L'exemple de code XML précédent :

• déclare une capacité pour l'intent intégré START_EXERCISE ;
• spécifie l'intent Android que l'Assistant génère pour lancer l'application.
  • Les attributs targetPackage et targetClass indiquent l'activité de réception.
  • L'attribut parameter mappe le paramètre d'intent intégré exercise.name à exerciseType dans les extras Bundle reçus par l'activité.

Gérer les paramètres d'intent intégré avec un inventaire intégré

Les paramètres d'intent intégré représentent les éléments extraits d'une requête utilisateur dans l'Assistant. Par exemple, lorsqu'un utilisateur dit "Hey Google, lance un footing sur ExampleApp", l'Assistant extrait "footing" dans le paramètre d'intent intégré schema.org de exercise.name. Pour certains intents intégrés, vous pouvez demander à l'Assistant de faire correspondre les paramètres d'intent intégré à un ensemble d'identifiants attendus par votre application.

Pour ce faire, vous devez lier les éléments de l'inventaire intégré au paramètre d'intent intégré. Un inventaire intégré est un ensemble de valeurs de paramètres d'intent intégré compatibles, telles que "footing", "randonnée" et "jogging", ainsi que l'ID de raccourci correspondant, comme EXERCISE_RUN. Lier l'inventaire permet à l'Assistant de transmettre l'ID de raccourci des paramètres correspondants (plutôt que la valeur de requête brute) à votre activité de traitement.

Certains paramètres d'intent intégré, tels que exercise.name, nécessitent un inventaire intégré pour fonctionner. Pour gérer ce paramètre, ajoutez les éléments d'inventaire shortcut suivants à shortcuts.xml :

<!-- shortcuts.xml -->

<shortcuts>
  <shortcut
    android:shortcutId="running"
    android:shortcutShortLabel="@string/activity_running">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/runningSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="walking"
    android:shortcutShortLabel="@string/activity_walking">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/walkingSynonyms"/>
    </capability-binding>
  </shortcut>

  <shortcut
    android:shortcutId="cycling"
    android:shortcutShortLabel="@string/activity_cycling">
    <capability-binding android:key="actions.intent.START_EXERCISE">
      <parameter-binding
        android:key="exercise.name"
        android:value="@array/cyclingSynonyms"/>
    </capability-binding>
  </shortcut>

  <capability> ... </capability>
</shortcuts>

Dans le code précédent, vous avez défini trois raccourcis représentant un inventaire intégré pour les types d'exercices compatibles avec l'application : course à pied, marche et vélo. Chaque raccourci est lié à la capacité comme suit :

• L'attribut android:key de chaque élément capability-binding fait référence au même intent intégré START_EXCERCISE défini pour la capacité.
• L'élément parameter-binding de chaque raccourci renvoie vers le paramètre d'intent intégré exercise.name.

Remarque : Une fois cette étape terminée, Android Studio peut vous avertir que les symboles des valeurs de synonymes ne peuvent pas être résolus. L'étape suivante vous explique comment résoudre ce problème.

Ajouter des synonymes d'inventaire intégrés

Les attributs android:value de l'élément parameter-binding dans les raccourcis d'inventaire précédents font référence à une ressource de tableau contenant des synonymes pour chaque élément d'inventaire. Les synonymes permettent d'utiliser des variantes pour un type d'élément, telles que "footing", "jogging" et "sprint", qui se réfèrent au même shortcutId. Ajoutez les entrées de synonymes suivantes à la ressource array.xml du projet :

<!-- array.xml -->
<array name="runningSynonyms">
  <item>Run</item>
  <item>Jog</item>
  <item>Jogging</item>
  <item>Sprint</item>
</array>

<array name="walkingSynonyms">
  <item>Walk</item>
  <item>Hike</item>
  <item>Hiking</item>
</array>

<array name="cyclingSynonyms">
  <item>Biking</item>
  <item>Riding</item>
  <item>Pedaling</item>
</array>

Traiter les intents Android entrants

Les intents Android sont des objets de messagerie qu'Android utilise pour demander une action auprès d'une autre application. L'Assistant traite les requêtes vocales des utilisateurs en générant un intent à partir des détails de la configuration de la capacité déclenchée. Afin de traiter les intents de la capacité START_EXERCISE, modifiez la classe cible FitMainActivity pour qu'elle gère les paramètres d'intent intégré entrants.

Commencez par remplacer la fonction Intent.handleIntent par le code suivant :

//FitMainActivity.kt

private fun Intent.handleIntent() {
  when (action) {
    // When the BII is matched, Intent.Action_VIEW will be used
    Intent.ACTION_VIEW -> handleIntent(data)
    // Otherwise start the app as you would normally do.
    else -> showDefaultView()
  }
}

Ajoutez ensuite à la classe une nouvelle fonction handleIntent avec le code suivant :

//FitMainActivity.kt

/**
 * Use extras provided by the intent to handle the different BIIs
 */

private fun handleIntent(data: Uri?) {
  // path is normally used to indicate which view should be displayed
  // i.e https://fit-actions.firebaseapp.com/start?exerciseType="Running" -> path = "start"
  var actionHandled = true

  val startExercise = intent?.extras?.getString(START_EXERCISE)
  // Add stopExercise variable here

  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  else{
   // path is not supported or invalid, start normal flow.
   showDefaultView()

   // Unknown or invalid action
   actionHandled = false
  }
  notifyActionSuccess(actionHandled)
}

Dans la fonction Intent.handleIntent précédente, lorsque ACTION_VIEW est déclenché, les données d'intent de l'action dans l'application sont transmises à la fonction handleIntent. Les paramètres d'intent intégré regroupés dans l'intent START_EXERCISE sont accessibles via intent?.extras?.getString(START_EXERCISE). Le reste de la fonction modifie le FitTrackingFragment pour afficher le type de remise en forme startExercise choisi.

Tester votre action dans l'application

Lorsque vous développez les actions dans l'application, vous utilisez le plug-in Assistant Google pour prévisualiser vos actions sur un appareil de test. Vous pouvez également utiliser le plug-in afin d'ajuster les valeurs du paramètre d'intent d'une action. Cela vous permet de voir comment votre application gère les différentes façons dont un utilisateur peut formuler une requête à l'Assistant pour votre application.

Pour tester votre action dans l'application avec le plug-in, procédez comme suit :

1. Exécutez votre application dans Android Studio. Pour ce faire, sélectionnez Run > Run App (Exécuter > Exécuter l'application) ou cliquez sur l'icône Run (Exécuter) dans la barre d'outils en haut.
2. Accédez à Tools > App Actions > Google Assistant > App Actions Test Tool (Outils > Actions dans les applications > Assistant Google > Outil de test des actions dans les applications).
3. Cliquez sur Create Preview (Créer un aperçu). Si vous y êtes invité, lisez et acceptez les règles et les conditions d'utilisation des actions dans les applications.
4. Sélectionnez l'intent intégré actions.intent.START_EXERCISE.
5. Dans le champ exercise, conservez la valeur running par défaut.
6. Cliquez sur Run App Action (exécuter l'action dans l'application). Vérifiez que l'Assistant utilise des liens profonds dans le minuteur d'exercice de l'application et que le minuteur a commencé un entraînement "running" (footing).

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

Vous avez implémenté vos premières actions dans l'application avec l'intent intégré START_EXERCISE. Félicitations ! Nous allons maintenant autoriser les utilisateurs à mettre fin à un footing dans votre application.

5. Ajouter la capacité d'intent intégré "Mettre fin à l'exercice"

L'intent intégré actions.intent.STOP_EXERCISE permet aux utilisateurs de mettre fin à une séance d'entraînement en disant, par exemple, "Hey Google, arrête mon footing sur ExampleApp". Implémentez cet intent intégré dans l'application de fitness en ajoutant un deuxième capability à shortcuts.xml :

<!-- shortcuts.xml -->

<capability android:name="actions.intent.STOP_EXERCISE">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="PUT_YOUR_APPLICATION_ID_HERE"
    android:targetClass="com.devrel.android.fitactions.FitMainActivity">
    <!-- Eg. name = "Running" -->
    <parameter
        android:name="exercise.name"
        android:key="stopExercise"/>
  </intent>
</capability>

Remplacez PUT_YOUR_APPLICATION_ID_HERE par votre applicationId unique.

Gérer les paramètres d'intent intégré avec un inventaire intégré

Cet intent intégré accepte le même paramètre exercise.name que l'intent intégré START_EXERCISE, ce qui permet aux utilisateurs d'indiquer quel entraînement actif ils souhaitent terminer. Pour activer cette fonctionnalité, ajoutez un deuxième ensemble d'éléments de raccourci d'inventaire à shortcuts.xml :

<!-- shortcuts.xml -->

<shortcut
  android:shortcutId="running"
  android:shortcutShortLabel="@string/activity_running">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/runningSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="walking"
  android:shortcutShortLabel="@string/activity_walking">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/walkingSynonyms"/>
  </capability-binding>
</shortcut>

<shortcut
  android:shortcutId="cycling"
  android:shortcutShortLabel="@string/activity_cycling">
  <capability-binding android:key="actions.intent.STOP_EXERCISE">
      <parameter-binding
          android:key="exercise.name"
          android:value="@array/cyclingSynonyms"/>
  </capability-binding>
</shortcut>

Traiter les intents Android entrants

Modifiez la classe FitMainActivity pour permettre à l'application de gérer les intents Android entrants de STOP_EXERCISE. Tout d'abord, ajoutez une variable à la fonction handleIntent pour qu'elle contienne les données d'intent STOP_EXERCISE :

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  val stopExercise = intent?.extras?.getString(STOP_EXERCISE)
  //...
}

Ensuite, modifiez la logique conditionnelle de la fonction handleIntent pour gérer les intents STOP_EXERCISE :

// FitMainActivity.kt

private fun handleIntent(data: Uri?) {
  //...
  if (startExercise != null){
    val type = FitActivity.Type.find(startExercise)
    val arguments = Bundle().apply {
      putSerializable(FitTrackingFragment.PARAM_TYPE, type)
    }
    updateView(FitTrackingFragment::class.java, arguments)
  } // Add conditional for stopExercise
  <strong>
  } else if(stopExercise != null){
    // Stop the tracking service if any and return to home screen.
    stopService(Intent(this, FitTrackingService::class.java))
    updateView(FitStatsFragment::class.java)
  }
  </strong>
  //...
}

Dans le code précédent, vous avez modifié la fonction handleIntent pour rechercher l'intent intégré STOP_EXERCISE dans l'intent Android entrant. Si elle est trouvée, la fonction arrête le minuteur actif et redirige l'utilisateur vers l'écran d'accueil.

Tester votre action dans l'application

Pour tester votre action dans l'application à l'aide du plug-in Assistant Google, procédez comme suit :

1. Exécutez votre application dans Android Studio. Pour ce faire, sélectionnez Run > Run App (Exécuter > Exécuter l'application) ou cliquez sur l'icône Run (Exécuter) dans la barre d'outils en haut.
2. Dans l'application, lancez un nouvel exercice "running" (footing).
3. Ouvrez le plug-in dans Android Studio : accédez à Tools > App Actions > Google Assistant > App Actions Test Tool (Outils > Actions dans l'application > Assistant Google > Outil de test des actions dans l'application).
4. Cliquez sur Create Preview (Créer un aperçu).
5. Sélectionnez l'intent intégré actions.intent.STOP_EXERCISE.
6. Dans le champ exercise, conservez la valeur running par défaut.
7. Cliquez sur Run App Action (exécuter l'action dans l'application). Vérifiez que l'Assistant met fin à la séance et vous redirige vers l'écran d'accueil.

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

6. Étapes suivantes

Félicitations !

Vous savez maintenant activer les commandes vocales dans une application Android à l'aide des intents intégrés de l'Assistant. 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 ;
• utiliser l'inventaire intégré ;
• tester les intents intégrés à l'aide du plug-in Assistant Google.

Étapes suivantes

À présent, vous pouvez essayer d'affiner votre application de fitness. Pour référencer le projet terminé, consultez la branche principale sur GitHub.

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

• Consultez nos autres ateliers de programmation sur les 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 intents à utiliser pour 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 #appactions 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.