Inventaire Web

Grâce aux actions dans l'application, les utilisateurs peuvent accéder directement au contenu de votre application en disant, par exemple, "Hey Google, montre-moi le menu du Café de Flore sur l'appli XXX". Cette fonctionnalité, appelée lien profond, peut faciliter l'utilisation de votre application.

Pour traiter ce type de requête, l'Assistant Google génère un lien profond vers le contenu correspondant dans votre application. Si vous gérez activement votre site Web avec des informations sur le contenu ou les produits, et que vos liens profonds dans l'application sont organisés autour de ce contenu Web public, vous pouvez configurer l'Assistant pour qu'il extrait les URL pour l'exécution des actions à partir de votre site Web à l'aide d'un inventaire Web.

Un inventaire Web est l'emplacement sur le site Web des URL d'éléments compatibles avec votre application. Lorsqu'un utilisateur appelle votre action dans l'application, l'Assistant associe la requête de l'utilisateur, comme "Café de Flore", aux URL correspondantes dans l'index de recherche Google du site Web que vous spécifiez dans shortcuts.xml pour votre application Android.

Avantages

L'inventaire Web présente des avantages pour les applications comportant de grandes listes d'articles que les utilisateurs consultent ou commandent dans l'application, et qui sont régulièrement mises à jour:

  • Les données d'inventaire Web se trouvent sur votre site Web, contrairement aux données d'inventaire intégré, qui stockent des listes d'éléments dans votre application. En autorisant l'Assistant à accéder aux données Web, vous évitez le risque de données d'inventaire intégrées obsolètes, qui ne peuvent être mises à jour qu'en publiant une nouvelle version de l'application.

  • Les inventaires intégrés sont limités à 1 000 éléments. En revanche, un inventaire Web n'a pas de limite de nombre d'éléments et peut s'adapter à vos besoins.

  • Un inventaire Web peut simplifier la logique de l'application en permettant à votre traitement de s'appliquer uniquement à des URL de contenu prévisibles extraites de votre site Web. En revanche, si un inventaire n'est pas configuré, l'Assistant génère des liens profonds pour le traitement en mappant les paramètres d'intent avec des variables dans un modèle d'URL. Votre traitement devra ensuite analyser cette URL générée dynamiquement pour déterminer si un utilisateur a demandé une entité compatible dans votre application.

Fonctionnement

Lors d'une action dans l'application, l'Assistant crée des liens profonds vers le contenu de l'application via les intents intégrés que vous définissez dans shortcuts.xml. Il utilise le traitement du langage naturel pour identifier les éléments pertinents dans la requête d'un utilisateur et les extrait dans les paramètres d'intent intégré. L'Assistant génère ensuite un lien profond à l'aide des paramètres, en fonction de la configuration de votre traitement dans shortcuts.xml.

Il existe trois méthodes pour générer des liens profonds pour le traitement :

  • Mappage des paramètres : mappe les paramètres d'intent sur les espaces réservés dans un modèle d'URL de traitement.
  • Inventaire intégré : établit une correspondance entre les paramètres d'intent et une liste des éléments entities acceptés, définis dans l'application.
  • Inventaire Web : établit une correspondance entre les paramètres d'intent et le contenu trouvé dans l'index de recherche Google pour un site Web.

Un inventaire Web est un format d'URL défini par le développeur, tel que https://www.exampleapp.com/restaurants/.*, qui représente un ensemble d'entités compatibles avec une application.

Si un paramètre d'intent intégré est configuré pour un inventaire Web, l'Assistant interroge le site Web pour effectuer une correspondance d'entité avec la requête de l'utilisateur. Il transmet ensuite les résultats d'URL correspondant au format d'URL configuré, tel que https://www.exampleapp.com/restaurants/three-dot-cafe, à votre traitement.

Figure 1. Exemple de requête de l'Assistant utilisant l'inventaire Web pour récupérer un élément d'entité de restaurant

Intents intégrés compatibles

Pour certains paramètres d'intent, l'inventaire Web est pris en charge par les intents intégrés suivants :

  • [actions.intent.CREATE_REVIEW]
  • [actions.intent.GET_NEWS_ARTICLE]
  • [actions.intent.GET_REVIEW]
  • [actions.intent.GET_THING]
  • [actions.intent.ORDER_MENU_ITEM]
  • [actions.intent.GET_EXERCISE_PLAN]
  • [actions.intent.GET_DIGITAL_DOCUMENT]
  • [actions.intent.GET_ITEM_LIST]
  • [actions.intent.GET_OFFER]
  • [actions.intent.CREATE_OFFER]
  • [actions.intent.GET_PRODUCT]
  • [actions.intent.UPDATE_CART]
  • [actions.intent.CREATE_SOCIAL_MEDIA_CONNECTION]
  • [actions.intent.GET_IMAGE_OBJECT]
  • [actions.intent.GET_SOCIAL_MEDIA_POSTING]
  • [actions.intent.GET_SOCIAL_MEDIA_PROFILE]
  • [actions.intent.CREATE_TAXI_RESERVATION]
  • [actions.intent.CREATE_FLIGHT_RESERVATION]
  • [actions.intent.CREATE_LODGING_RESERVATION]
  • [actions.intent.GET_LOCAL_BUSINESS]
  • [actions.intent.GET_RESERVATION]
  • [actions.intent.UPDATE_RESERVATION]

Ajouter un inventaire Web

Une fois que vous avez identifié un intent intégré, activez-le pour l'inventaire Web en mettant à jour shortcuts.xml avec les détails de votre site Web. Le fichier shortcuts.xml est une ressource de votre projet Android dans laquelle vous définissez les intents intégrés qui correspondent aux fonctionnalités de votre application et la manière dont chaque intent intégré doit générer des liens profonds à traiter par votre application. Pour en savoir plus sur shortcuts.xml, consultez la section Créer un fichier shortcuts.xml.

Pour utiliser l'inventaire Web pour un intent intégré compatible, procédez comme suit :

  1. Dans le fichier shortcuts.xml de votre application, ajoutez une balise <capability> avec un attribut android:name défini sur le nom d'un intent intégré que vous gérez avec un inventaire Web, par exemple : actions.intent.ORDER_MENU_ITEM.

  2. Dans la balise <capability>, ajoutez une balise <intent> avec un attribut android:action défini sur le nom de la vue à activer par cet intent.

  3. Dans la même balise <intent>, ajoutez une balise <parameter> et définissez son attribut android:name sur le paramètre d'intent intégré qui correspond le mieux à l'entité décrite par vos pages Web. Par exemple, lorsque vous fournissez l'inventaire Web pour ORDER_MENU_ITEM, vous devez associer les pages de menu à menuItem.name.

  4. Dans la nouvelle balise <parameter>, ajoutez une balise <data> et définissez son attribut android:pathPattern sur le format d'URL du chemin que vous souhaitez utiliser pour l'inventaire Web.

Lorsque vous configurez shortcuts.xml en suivant ces étapes, l'Assistant peut récupérer le contenu Web à partir de l'index de recherche Google du format d'URL que vous avez fourni dans l'attribut android:pathPattern. L'Assistant fournit ensuite une valeur d'URL à votre traitement en utilisant les résultats correspondant au format de chemin d'URL que vous avez défini. Votre application redirige ensuite l'utilisateur vers un emplacement spécifique de votre application en fonction des données d'URL fournies par l'Assistant.

Par exemple, votre site Web contient des fiches produit qui utilisent un chemin d'URL commençant par https://www.examplecafe.com/items/. Vous utilisez la valeur pathPattern https://www.examplecafe.com/items/.*, et l'Assistant utilise ce format d'URL pour rechercher une URL de traitement, comme https://www.examplecafe.com/items/item123.

Si l'Assistant trouve une URL d'inventaire Web correspondante, il la fournit dans le champ <data> de l'intent de traitement, comme s'il s'agissait d'un lien profond. Utilisez la méthode getData() de l'intent pour obtenir l'URL en tant qu'objet Uri. L'activité dans l'application qui reçoit l'intent est responsable de l'interprétation de l'URL et de l'activation de l'interface utilisateur de l'application appropriée.

Exemple de shortcuts.xml

L'exemple suivant définit un intent intégré ORDER_MENU_ITEM qui fournit un inventaire Web permettant de renvoyer des résultats d'URL pour les requêtes contenant le paramètre d'intent intégré menuItem.name :

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.ORDER_MENU_ITEM">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.OrderMenuItemActivity">
      <!-- Define URL match pattern in the pathPattern data field -->
      <parameter android:name="menuItem.name">
        <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
      </parameter>
    </intent>
  </capability>
</shortcuts>

Dans l'exemple ci-dessus, un pathPattern est spécifié pour menuItem.name, demandant à l'Assistant de ne renvoyer que les URL correspondant au format d'URL : https://www.examplecafe.com/items/.*

D'autres exemples d'intent intégré shortcuts.xml compatibles avec l'inventaire Web sont disponibles dans la documentation de référence.

Gérer les remplacements pour les résultats manquants

Dans les cas où les résultats de l'inventaire Web ne sont pas renvoyés à votre traitement, votre application doit implémenter une logique de remplacement pour effectuer l'action avec la meilleure expérience utilisateur possible. Voici les situations qui peuvent expliquer l'absence de résultats :

  • Paramètre d'intent manquant: l'utilisateur a omis un paramètre attendu dans sa requête ou l'Assistant n'a pas compris ce paramètre dans la requête de l'utilisateur.
  • Résultat d'URL manquant : l'Assistant n'a trouvé aucune entité de votre site Web correspondant à la requête de l'utilisateur.

Vous pouvez gérer les valeurs de paramètres manquantes en définissant plusieurs éléments <intent> pour une fonctionnalité. Si l'Assistant ne peut pas satisfaire le premier intent, il passe à l'intent suivant, et ainsi de suite.

Les intents de remplacement ne doivent pas nécessiter de paramètres. À la place, ils doivent fournir un lien profond plus générique, tel que l'affichage des résultats de recherche pour la requête de l'utilisateur.

Dans l'exemple shortcuts.xml suivant, un intent intégré ORDER_MENU_ITEM définit deux traitements: le premier attend une URL pour le paramètre menuItem.name. Le second ne requiert aucun paramètre. L'utilisateur est dirigé vers une page qui affiche tous les éléments du menu.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
    </parameter>
  </intent>
  <!-- Fallback intent with no required parameters -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ViewMenuActivity">
    <url-template android:value="myapp://app.examplecafe.com/menu/all-items" />
  </intent>
</capability>

Dans les cas où aucune URL d'inventaire Web n'est renvoyée, le contenu de la requête utilisateur peut toujours être utilisé dans les intents de remplacement, par exemple pour afficher les résultats de recherche.

Dans l'exemple shortcuts.xml suivant, deux éléments d'intent sont définis :

  1. Le premier nécessite un lien profond d'inventaire Web à partir du paramètre menuItem.name.
  2. Si aucun lien profond n'est renvoyé, le second intent affiche les résultats de recherche à l'aide de la requête utilisateur de menuItem.name, le cas échéant.
<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- Fallback intent displaying search results, using "menuItem.name" -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.SearchMenuActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

Ajouter la recherche dans l'application avec l'inventaire Web

Vous pouvez permettre aux utilisateurs de rechercher du contenu Web dans votre application en combinant l'inventaire Web avec une implémentation de l'intent intégré actions.intent.GET\_THING.

Cet intent intégré recherche du contenu ou des entités à l'aide de la fonctionnalité de recherche dans l'application par défaut dans une application, ce qui active des requêtes telles que "Hey Google, montre-moi des randonnées en cascade sur SampleApp". Si vous configurez l'inventaire Web pour le paramètre de fonctionnalité thing.name transmis par l'intent intégré GET_THING, les résultats d'entité correspondants provenant de votre site Web sont transmis pour le traitement.

Pour obtenir des exemples d'inventaire Web shortcuts.xml, consultez la documentation de référence sur l'intent intégré GET\_THING.

Tester l'inventaire Web

Lorsque vous définissez un inventaire Web pour un intent intégré, l'Assistant génère un lien profond à l'aide des résultats Web correspondant au format urlTemplate que vous avez défini pour le paramètre d'intent intégré spécifié. Si aucun résultat d'inventaire Web n'est disponible, l'Assistant génère une URL correspondant au format urlTemplate de votre intent de remplacement. Vous pouvez tester l'implémentation de votre inventaire Web en vérifiant que les liens fournis par l'Assistant sont des URL qui correspondent aux formats urlTemplate de votre inventaire Web.

Dans l'exemple d'intent intégré ORDER_MENU_ITEM suivant, l'Assistant génère des liens de traitement de l'inventaire Web correspondant au format urlFilter spécifié dans le paramètre menuItem.name. Exemple : https://www.examplecafe.com/items/nuggets. Le deuxième intent prend la valeur de menuItem.name et effectue une recherche si le premier intent ne correspond pas au format d'URL.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <!-- web inventory fulfillment -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- search intent -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MenuSearchActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

Utilisez l'outil de test des actions dans les applications pour tester l'inventaire Web sur un appareil physique ou virtuel.

Pour utiliser l'outil de test, procédez comme suit :

  1. Connectez votre appareil de test à votre application en cours d'exécution.
  2. Dans Android Studio, 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 Create Preview (Créer un aperçu).
  4. Dans Android Studio, exécutez votre application sur votre appareil de test.
  5. Utilisez l'application Assistant sur votre appareil de test pour tester votre action dans l'application. Par exemple, vous pouvez dire "Hey Google, commande des nuggets sur ExampleCafe".
  6. Observez le comportement de votre application ou utilisez le débogueur Android Studio pour vérifier le résultat d'action souhaité.