Intents intégrés (Dialogflow)

Un intent intégré est un identifiant unique que vous pouvez spécifier pour indiquer à l'Assistant Google que votre action peut traiter une catégorie spécifique de requêtes utilisateur. Voici quelques exemples de requêtes utilisateur que l'Assistant met en correspondance avec des intents intégrés:

  • Intent intégré"Jouer au jeu": "Ok Google. "Jouer à un jeu de mémoire"
  • Intent intégré "Obtenir l'horoscope": "Ok Google. Consulter mon horoscope"

Lors de la découverte de l'action, l'Assistant peut utiliser les métadonnées concernant votre action, y compris les intents intégrés que vous avez spécifiés, pour la recommander aux utilisateurs. Pour minimiser les allers-retours de conversation, l'Assistant tente également d'analyser les paramètres des requêtes des utilisateurs et de les transmettre à votre action.

Pour afficher la liste complète des intents intégrés compatibles avec l'Assistant, y compris leurs paramètres et des exemples de requêtes utilisateur, consultez la documentation de référence sur les intents intégrés.

Intégrer des intents intégrés

Selon la manière dont vous créez votre action, il existe différentes manières d'intégrer des intents intégrés.

Dialogflow

Si vous utilisez Dialogflow pour créer votre action, vous pouvez associer un intent intégré sous forme graphique à partir de la console Dialogflow.

Pour associer un intent intégré à Dialogflow, procédez comme suit:

  1. Ouvrez la console Dialogflow, sélectionnez votre agent, puis accédez à l'écran Intents.
  2. Créez ou sélectionnez l'intent que votre agent déclenche lorsqu'il reçoit un intent intégré spécifique. Ouvrez la section Events (Événements), puis cliquez sur Add Event (Ajouter un événement).

    Figure 1 : Ajouter un événement Dialogflow dans la console Dialogflow
  3. Dans le champ Events (Événements), saisissez le nom d'un événement d'intent intégré pour votre agent (par exemple, actions_intent_PLAY_GAME).

    Figure 2. Associer un intent intégré à votre agent dans la console Dialogflow
  4. Cliquez sur Enregistrer.

SDK Actions

Si vous utilisez le SDK Actions pour créer votre action, vous devez spécifier le mappage entre les intents intégrés et les actions de votre package d'actions.

Pour associer un intent intégré au SDK Actions, procédez comme suit:

  1. Spécifiez l'intent intégré dans le champ "Nom" de votre définition Action.
  2. Importez votre package d'actions dans votre projet Actions à l'aide de l'outil gactions, comme décrit dans la présentation du SDK Actions.

Par exemple, l'extrait de code suivant montre comment ajouter l'intent intégré CHECK_AIR_QUALITY:

{
   "actions":[
      {
         "description":"Default Welcome Intent",
         "name":"MAIN",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.MAIN"
         }
      },
      {
         "description":"Check Air Quality",
         "name":"CHECK_AIR_QUALITY",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.CHECK_AIR_QUALITY"
         }
      }
   ],
   "conversations":{
      "conversation_1":{
         "name":"conversation_1",
         "url":"https://example.com/fulfillment",
         "fulfillmentApiVersion":2
      }
   }
}

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

Lorsque votre action est appelée via un intent intégré, votre traitement peut recevoir des paramètres supplémentaires. Le schéma d'intent définit les noms des paramètres et leurs types en tant que types primitifs ou entités schema.org. Pour afficher le schéma des intents intégrés d'une action conversationnelle, consultez la documentation de référence sur les intents intégrés.

Les paramètres des intents intégrés sont facultatifs. L'Assistant gère le remplissage des paramètres avec des valeurs si celles-ci peuvent être extraites de l'appel de l'intent intégré par l'utilisateur.

Par exemple, le schéma de l'intent intégré actions.intent.CHECK_AIR_QUALITY définit quatre paramètres facultatifs:

Nom du paramètre Type
attributes Valeur de chaîne.
location Un objet schema.org/Place
temporalCoverage Un objet schema.org/Duration
timeIndicator Une EnumeratedDuration (extension spécifique à Google)

L'extrait de code suivant présente un exemple de requête de webhook de conversation (JSON) lorsqu'un utilisateur appelle votre action en disant Quelle est la qualité de l'air à San Francisco demain ?:

"inputs":[
      {
         "intent":"actions.intent.CHECK_AIR_QUALITY",
         "rawInputs":[
            {
               "inputType":"VOICE",
               "query":"what is the air quality in san francisco tomorrow"
            }
         ],
         "arguments":[
            {
               "name":"location",
               "structuredValue":{
                  "geo":{
                     "longitude":-122.41941550000001,
                     "latitude":37.7749295
                  },
                  "@context":"https://schema.org",
                  "@type":"Place",
                  "name":"san francisco"
               }
            },
            {
               "name":"temporalCoverage",
               "rawText":"2018-04-25",
               "textValue":"2018-04-25"
            }
         ]
      }
   ]

Dans cet exemple, les paramètres prennent les valeurs suivantes:

  • Le paramètre location contient la valeur schema.org/Place pour "San Francisco".
  • Le paramètre temporalCoverage contient la valeur schema.org/Duration pour la date de demain par rapport à l'heure de l'appel.
  • Aucune valeur n'est définie pour les paramètres attributes et timeIndicator, car l'expression d'appel de l'utilisateur ne contient pas ces informations.

Si vous utilisez la bibliothèque cliente Actions on Google pour Node.js, vous pouvez récupérer la valeur des paramètres comme indiqué dans l'extrait de code suivant:

app.intent('actions.intent.CHECK_AIR_QUALITY', (conv) => {
  const attributes = conv.arguments.get('attributes');
  const location = conv.arguments.get('location');
  const temporal_coverage = conv.arguments.get('temporalCoverage');
  Const time_indicator = conv.arguments.get('timeIndicator')

  // Your Action logic. If you need to use any of the parameter values,
  // you should check first that it is defined. Arguments.get returns
  // undefined if it can't find a value for a parameter.

});

Tester les intégrations avec des intents intégrés

Pour tester votre intégration, procédez comme suit:

  1. Ouvrez le simulateur d'actions avec votre action de test activée ou ouvrez l'Assistant sur votre appareil.
  2. Énoncez ou saisissez une requête associée à cet intent intégré. Par exemple : "Je veux jouer à un jeu."
  3. Dans la boîte de dialogue de sélection d'application qui s'affiche, recherchez votre action.
  4. Sélectionnez votre application pour lui envoyer un intent.
Figure 3. Boîte de dialogue de sélection d'actions résultant de
à partir d'une expression d'intent intégrée.
Figure 4. Appeler une action associée à un intent intégré

Bonnes pratiques pour l'utilisation des intents intégrés

Vous devez suivre ces bonnes pratiques lorsque vous utilisez des intents intégrés:

  • Mappez des intents intégrés à des actions spécifiques: lorsqu'un intent intégré spécifique déclenche votre action, redirigez l'utilisateur vers l'intent et la fonctionnalité spécifiques de votre action avec le moins de friction possible. Par exemple, si votre action est compatible avec l'intent intégré PLAY_GAME et reçoit cet intent, vous devez immédiatement rediriger l'utilisateur vers la fonctionnalité de jeu de votre action. Évitez de demander à l'utilisateur s'il veut jouer à un jeu.
  • Gérer les paramètres d'intent intégré: assurez-vous d'utiliser les valeurs des paramètres d'intent intégrés que l'Assistant envoie à votre traitement. Évitez de demander à nouveau l'utilisateur à fournir ces valeurs.