Inventaire intégré

Lorsque vous implémentez des actions dans votre application Android, vous pouvez être amené à gérer des requêtes qui correspondent à différentes variantes d'un thème. Supposons que votre application de fitness implémente l'intent intégré START_EXERCISE pour permettre aux utilisateurs de démarrer un large éventail d'entraînements en soumettant des requêtes comme "Hey Google, démarre une course à pied dans l'application XXX" à l'Assistant.

Pour répondre à cet intent, la logique de mise en correspondance des requêtes doit gérer chaque type d'entraînement, y compris des variantes telles que "jogging", "sprint" ou "course". Cette logique devient rapidement fastidieuse à mesure que les types d'entraînement possibles augmentent.

Pour les intents intégrés compatibles, tels que START_EXERCISE, vous pouvez contourner cette logique de mise en correspondance complexe à l'aide d'un inventaire intégré. Un inventaire intégré est un ensemble de raccourcis Android statiques définis dans shortcuts.xml. Il représente les fonctionnalités et le contenu de votre application.

Chaque raccourci contient un identifiant d'élément et une liste de synonymes représentant les variantes liées à la façon dont les utilisateurs peuvent faire référence à cet élément. Lors de l'appel, l'intent intégré compare le paramètre fourni par l'utilisateur à la liste des synonymes. Lorsqu'une correspondance est trouvée, le paramètre d'intent intégré est remplacé par l'identifiant d'élément du raccourci correspondant.

Un inventaire intégré permet à l'Assistant Google de simplifier les valeurs de paramètres d'intent intégré fournies à votre application lors des appels d'action qui s'y produisent.

Les inventaires intégrés fonctionnent comme des tableaux de conversion des paramètres d'intent intégré. Ils représentent la manière dont les utilisateurs font référence aux fonctionnalités ou au contenu de votre application à l'aide d'identifiants d'élément que vous définissez. Ils simplifient la logique de mise en correspondance des requêtes de votre application en permettant à vos traitements de prévoir ces identifiants à partir des paramètres d'intent intégré.

Limites et alternatives

Les raccourcis d'un inventaire intégré présentent les limites suivantes :

• Nombre limite de raccourcis : vous pouvez définir jusqu'à 1 000 raccourcis par application dans un inventaire intégré.
• Nombre limite de synonymes : chaque raccourci d'un inventaire intégré peut contenir jusqu'à 20 valeurs de synonymes.
• Définition statique : les raccourcis d'un inventaire intégré sont déclarés de manière statique dans shortcuts.xml. Ils ne peuvent être mis à jour pour vos utilisateurs qu'en publiant une nouvelle version de votre application.

Étant donné qu'une configuration statique est exigée, un inventaire intégré est particulièrement adapté pour transmettre à l'Assistant des informations non personnalisées qui ne changent pas régulièrement, comme les plats d'un menu, des itinéraires de bus ou des tailles de boissons. Pour les autres types de contenu, envisagez ces alternatives :

• Inventaire Web : permet à l'Assistant d'interroger le contenu Web public lors de la mise en correspondance des requêtes utilisateur avec les identifiants de contenu d'applications compatibles. Les requêtes d'inventaire Web s'exécutent en temps réel pendant un appel, ce qui vous permet d'étendre les catalogues de produits, les posts sur les réseaux sociaux et d'autres contenus fréquemment mis à jour à l'Assistant.

• Raccourcis dynamiques : étendent un inventaire de contenus d'applications personnalisés à l'Assistant. Les raccourcis dynamiques permettent aux utilisateurs de répéter rapidement des actions courantes, comme commander à nouveau une boisson qu'ils aiment à partir d'une application de commande de repas ou afficher une liste de courses dans une application de prise de notes.

Créer un inventaire intégré

Un inventaire intégré simplifie le développement en offrant à l'Assistant un moyen pratique de traduire les différentes manières dont les utilisateurs demandent le contenu et les fonctionnalités de votre application en identifiants prévisibles attendus par celle-ci. Supposons, par exemple, que votre application propose différents entraînements que les utilisateurs peuvent lancer en le demandant à voix haute. Elle s'attend à ce qu'ils effectuent les requêtes suivantes pour le même type d'exercice :

• Hey Google, lance une course à pied dans l'application XXX.
• Hey Google, lance un jogging dans l'application XXX.

Dans le raccourci de votre inventaire intégré, définissez shortcutId sur "CARDIO_RUN", qui correspond à l'identifiant d'exercice attendu par votre application. Vous pouvez ensuite spécifier "course à pied" et "jogging" en tant que synonymes associés à shortcutId. Désormais, lorsqu'un utilisateur déclenchera une action dans l'application avec les requêtes précédentes, l'Assistant utilisera l'identifiant "CARDIO_RUN" pour le paramètre d'intent intégré lorsqu'il générera un intent de traitement.

L'extrait suivant issu d'un exemple de fichier app/res/shortcuts.xml implémente ce cas de figure :

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

Dans l'exemple précédent, l'inventaire intégré shortcut déclare une balise <parameter-binding> dans un élément <capability-binding>, qui le lie au paramètre d'intent intégré exercise.name défini dans <capability>.

La ressource du tableau de chaînes @array/run_names spécifie une liste de synonymes dans res/values/arrays.xml que l'Assistant reconnaît et met en correspondance avec l'ID d'élément "CARDIO_RUN" :

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

Lorsqu'un élément <url-template> est fourni pour la fonctionnalité, le shortcutId d'une valeur correspondante est inséré dans l'URL générée au niveau de l'espace réservé prévu pour le paramètre. Le code suivant issu d'un exemple de fichier app/res/shortcuts.xml implémente ce cas de figure :

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://workout{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

Dans l'exemple précédent, l'Assistant génère le lien profond de traitement : myapp://workout?exercise=CARDIO_RUN.

Traitement à l'aide d'intents de raccourci

Par défaut, un raccourci fournit le shortcutId d'une valeur d'inventaire intégré correspondante à l'intent de l'élément capability auquel le raccourci est lié, comme déclaré dans la balise <capability-binding> du raccourci. Vous pouvez également spécifier qu'un intent défini dans le raccourci proprement dit doit être utilisé pour le traitement en ajoutant une balise <shortcut-fulfillment> à capability.

Le code suivant issu d'un exemple de fichier app/res/shortcuts.xml implémente le traitement des raccourcis :

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

Dans l'exemple précédent, si la requête de l'utilisateur correspond à une valeur d'inventaire intégré pour le paramètre exercise.name, la balise <shortcut-fulfillment> spécifie que l'intent du raccourci lié doit être utilisé pour le traitement.

Inventaire intégré pour les intents intégrés d'une application ouverte

Bien que l'inventaire intégré soit généralement une fonctionnalité facultative, certains intents intégrés, comme OPEN_APP_FEATURE l'exigent. Cet intent couramment utilisé permet aux utilisateurs de créer des liens profonds vers des fonctionnalités d'applications spécifiques à l'aide de l'Assistant. La fonctionnalité d'application ouverte nécessite un inventaire intégré des noms de fonctionnalités de l'application afin de vérifier qu'une fonctionnalité demandée par l'utilisateur existe avant de le rediriger vers votre application via un lien profond.

Le code suivant issu d'un exemple de fichier app/res/shortcuts.xml implémente cet intent intégré avec un seul raccourci représentant la fonctionnalité d'état d'une commande dans l'application :

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

Les ressources du tableau de chaînes dans res/values/arrays.xml, @array/order_status_names, spécifient une liste de synonymes pour cette fonctionnalité :

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

Une fois la fonctionnalité précédente en place, l'Assistant peut traiter diverses expressions pour la même fonctionnalité :

• "Hey Google, affiche l'état de ma commande dans l'application XXX."
• "Hey Google, affiche mes commandes dans l'application XXX."
• "Hey Google, affiche mon historique de commandes dans l'application XXX."

Tester l'inventaire intégré

Pour tester votre inventaire, inspectez les valeurs de paramètre d'intent intégré que l'Assistant fournit à votre application lors du traitement des fonctionnalités spécifiques à l'action dans l'application. Un inventaire intégré remplace la valeur fournie par l'utilisateur pour un paramètre d'intent intégré associé à l'inventaire par le shortcutId d'un raccourci d'inventaire intégré correspondant.

Par exemple, une fonctionnalité d'intent intégré START_EXERCISE peut utiliser un inventaire intégré pour traduire le paramètre d'intent intégré fourni par l'utilisateur, "Course à pied", en identifiant d'entraînement correspondant, "CARDIO_RUN".

Le plug-in Assistant Google vous permet de prévisualiser les actions dans l'application associées à l'inventaire intégré dans l'Assistant sur un appareil de test. Pour tester l'inventaire à l'aide du plug-in, procédez comme suit :

1. Configurez les paramètres liés à l'inventaire pour votre fonctionnalité d'intent intégré avec des valeurs de synonymes associées à votre inventaire intégré.
2. Déclenchez l'intent intégré à partir du plug-in, en l'appelant sur votre appareil de test.
3. Inspectez les valeurs de paramètres générées par l'Assistant lors du traitement de l'action dans l'application.