Créer une action Interactive Canvas pour l'Assistant Google à l'aide d'Actions Builder

La plate-forme pour les développeurs Actions on Google vous permet de créer des logiciels afin d'étendre les fonctionnalités de l'Assistant Google, l'assistant personnel virtuel de Google, sur plus d'un milliard d'appareils (enceintes intelligentes, téléphones, voitures, téléviseurs, casques audio, etc.). L'assistant simplifie la vie des utilisateurs qui lui demandent d'accomplir des tâches (par exemple, faire des courses, réserver un chauffeur, etc.). Pour obtenir la liste complète des possibilités actuelles, consultez le répertoire des actions. En tant que développeur, vous pouvez utiliser Actions on Google pour créer et gérer facilement des échanges agréables et utiles entre les utilisateurs et votre propre service tiers.

Cet atelier de programmation est un module avancé. Il est destiné aux lecteurs qui ont déjà créé des actions pour l'Assistant Google. Si vous n'avez pas d'expérience dans le développement avec Actions on Google, nous vous recommandons vivement de suivre nos ateliers de programmation d'introduction (Niveau 1 et Niveau 2) pour vous familiariser avec la plate-forme. Ces modules vous guideront à travers une série de fonctionnalités qui peuvent vous aider à étendre les fonctionnalités de vos actions et à élargir votre audience.

Dans cet atelier de programmation, vous allez utiliser Interactive Canvas, un framework basé sur l'Assistant Google, pour ajouter un jeu en plein écran à une action conversationnelle. Le jeu est une application Web interactive que l'Assistant envoie en réponse à une demande de l'utilisateur dans une conversation. L'utilisateur peut ensuite jouer en utilisant la saisie vocale ou textuelle sur des écrans connectés et des appareils mobiles Android.

Au lieu de concevoir vous-même un jeu dans son intégralité, vous allez déployer un jeu partiellement prédéveloppé appelé Snow Pal et ajouter la logique du jeu au fur et à mesure de l'atelier de programmation. Snow Pal est une variante du jeu classique du pendu. Dans ce jeu, un certain nombre d'espaces vides forment un mot et vous devez deviner les lettres qui le composent. À chaque erreur, le bonhomme de neige fond un peu plus. Vous remportez le jeu si vous trouvez le mot avant que le bonhomme de neige ait complètement fondu.

Figure 1. Partie de Snow Pal en cours

Objectifs de l'atelier

Dans cet atelier de programmation, vous allez créer une action utilisant Interactive Canvas. Les caractéristiques de votre action sont les suivantes :

Les utilisateurs peuvent jouer en plein écran en mode vocal.
Les utilisateurs peuvent appuyer sur un bouton pour démarrer le jeu.
Les utilisateurs peuvent appuyer sur un bouton pour rejouer.

Le déroulement de la conversation pour votre action à l'issue de cet atelier de programmation sera le suivant :

Assistant : Welcome to Snow Pal! Would you like to start playing the game?

Utilisateur : Yes

Assistant : Try guessing a letter in the word or guessing the word.

Utilisateur : I guess the letter E

Assistant : Let's see if your guess is there...E is right. Right on! Good guess.

L'utilisateur continue de deviner les lettres ou le mot inconnu jusqu'à ce que le jeu se termine.

Points abordés

Créer et déployer une action Interactive Canvas
Mettre à jour le mot du jeu en fonction de la saisie vocale et de la saisie tactile de l'utilisateur
Transmettre des données à l'application Web de différentes manières
Déboguer l'action Interactive Canvas

Prérequis

Les prérequis pour cet atelier de programmation sont les suivants :

Un navigateur Web, par exemple Chrome
Un IDE/éditeur de texte de votre choix
NodeJS, npm et git installés sur votre ordinateur

Une connaissance de JavaScript (ES6) est vivement recommandée pour comprendre le code utilisé dans cet atelier de programmation.

(Facultatif) Récupérer l'exemple de code complet

Dans cet atelier de programmation, vous allez créer l'exemple étape par étape à partir d'une version incomplète. Si vous préférez, vous pouvez également récupérer l'exemple terminé sur le dépôt GitHub.

Interactive Canvas est un framework basé sur l'Assistant Google qui vous permet d'ajouter des animations et des éléments graphiques en plein écran à votre action conversationnelle.

Une action qui utilise Interactive Canvas est semblable à une action conversationnelle standard. Toutefois, une action Interactive Canvas permet en plus d'envoyer à l'appareil une réponse qui ouvre une application Web en plein écran.

L'utilisateur fournit des informations à l'application Web par commande vocale ou tactile jusqu'à la fin de la conversation.

Figure 2. Action créée avec Interactive Canvas

Le projet de cet atelier de programmation se divise en trois grandes parties :

Application Web : les fichiers de l'application Web contiennent le code des éléments graphiques et des animations de votre application Web, ainsi que la logique pour mettre à jour l'application Web en fonction de l'entrée utilisateur.
Action conversationnelle : l'action conversationnelle contient votre logique de conversation, qui reconnaît et traite l'entrée utilisateur, et y répond.
Webhook : le webhook gère la logique du jeu. Pour cet atelier de programmation, vous pouvez considérer le webhook comme votre serveur de jeu.

Dans chaque section de cet atelier de programmation, vous allez modifier l'application Web, l'action conversationnelle et le webhook pour ajouter des fonctionnalités à votre action Interactive Canvas.

De manière générale, l'action conversationnelle, le webhook et l'application Web dans l'action Snow Pal fonctionnent de la manière suivante :

L'action conversationnelle invite l'utilisateur à deviner une lettre du mot ou le mot entier.
L'utilisateur dit Je propose un i à l'application Web Snow Pal sur un écran connecté.
L'entrée utilisateur est transférée à l'action conversationnelle, qui est définie dans Actions Builder et/ou dans votre projet SDK Actions.
L'action conversationnelle traite l'entrée utilisateur et, en fonction de celle-ci, déclenche une logique dans le webhook qui met à jour l'application Web ou envoie des métadonnées pour mettre à jour directement l'application Web.
L'application Web est mise à jour pour afficher la lettre dans le mot, et l'utilisateur est à nouveau invité à deviner.

Pour en savoir plus sur le fonctionnement d'Interactive Canvas, consultez la section "Comprendre l'infrastructure d'Interactive Canvas". Maintenant que vous avez vu les bases, vous pouvez commencer à configurer votre environnement pour cet atelier de programmation.

Vérifier vos paramètres d'autorisation Google

Afin de tester l'action que vous créez pour cet atelier de programmation, vous devez activer les autorisations nécessaires pour que le simulateur de la console Actions puisse accéder à votre action. Pour activer les autorisations, procédez comme suit :

Accédez à la page Commandes relatives à l'activité.
Connectez-vous avec votre compte Google, si nécessaire.
Activez les autorisations suivantes :

Activité sur le Web et dans les applications
Sous Activité sur le Web et dans les applications, cochez la case Inclure l'historique Chrome et l'activité liée aux sites, aux applications et aux appareils qui utilisent les services Google.

Installer l'interface de ligne de commande gactions

Dans cet atelier de programmation, vous allez utiliser l''interface de ligne de commande (CLI) gactions pour synchroniser votre projet Actions entre la console Actions et votre système de fichiers local.

Pour installer la CLI gactions, suivez les instructions de la section Installer l'outil de ligne de commande gactions.

Installer l'interface de ligne de commande Firebase

L'interface de ligne de commande (CLI) Firebase vous permet de déployer votre projet Actions sur Cloud Functions et d'héberger votre application Web.

Cet atelier de programmation utilise npm pour installer la CLI Firebase. Veillez à installer npm, qui est généralement fourni avec Node.js.

Pour installer ou mettre à niveau la CLI, ouvrez un terminal et exécutez la commande npm suivante :

npm install -g firebase-tools

Pour vérifier que la CLI a bien été installée, exécutez la commande suivante :

firebase --version

Assurez-vous de disposer de la version 8 (ou d'une version ultérieure) de la CLI Firebase pour être certain de bénéficier des toutes dernières fonctionnalités requises pour Cloud Functions. Si ce n'est pas le cas, exécutez npm install -g firebase-tools pour la mettre à niveau.

Pour vous connecter à Firebase, exécutez la commande suivante :

firebase login

Lorsque vous vous connectez à Firebase, assurez-vous d'utiliser le même compte Google que celui dont vous vous servez pour créer votre projet Actions.

Cloner le dépôt

Dans cette section, vous allez cloner les fichiers dont vous avez besoin dans l'atelier de programmation. Pour obtenir ces fichiers, procédez comme suit :

Ouvrez un terminal et accédez au répertoire dans lequel vous stockez généralement des projets de codage. Si vous n'en avez pas, utilisez votre répertoire d'accueil.
Pour cloner ce dépôt, exécutez la commande suivante dans votre terminal :

git clone https://github.com/actions-on-google/actions-builder-canvas-codelab-nodejs

Ouvrez le répertoire start/. Ce dépôt contient les répertoires importants suivants, que vous allez utiliser :

public/ : ce répertoire contient le code HTML, CSS et JavaScript de votre application Web.
sdk/custom/ : ce répertoire contient la logique de votre action conversationnelle (scènes, intents et types).
sdk/webhooks/ : ce répertoire est votre webhook et contient la logique du jeu.

Figure 3. Structure du code du répertoire start

Dans cette section, vous allez créer et configurer votre projet Actions, transmettre le code du dépôt cloné vers la console Actions à l'aide de la CLI gactions, et déployer votre application Web et votre webhook.

Créer un projet Actions

Votre projet Actions est un conteneur pour votre action. Pour créer le projet Actions associé à cet atelier de programmation, procédez comme suit :

Ouvrez la Console Actions.
Cliquez sur New project (Nouveau projet).
Saisissez un nom de projet, par exemple canvas-codelab. Ce nom est utilisé comme référence interne. Par la suite, vous pourrez définir un nom externe pour votre projet.

Cliquez sur Create project (Créer un projet).
Sur l'écran What kind of Action do you want to build ? (Quel type d'action voulez-vous créer ?), sélectionnez la fiche Game (Jeu).
Sélectionnez Next (Suivant).
Sélectionnez la carte Blank project (Projet vide), puis cliquez sur Start build (Commencer la création).

Enregistrer l'ID de projet associé à votre action

L'ID de projet est un identifiant unique associé à votre action. Vous en aurez besoin pour plusieurs étapes de cet atelier de programmation.

Pour le récupérer, procédez comme suit :

Dans la console Actions, cliquez sur les trois points verticaux en haut à droite.
Cliquez sur Project settings (Paramètres du projet).

Copiez l'ID du projet.

Associer un compte de facturation

Pour déployer votre traitement plus tard dans cet atelier de programmation à l'aide de Cloud Functions, vous devez associer un compte de facturation à votre projet dans Google Cloud. Si vous possédez déjà un compte de facturation, vous pouvez ignorer les étapes suivantes.

Pour associer un compte de facturation à votre projet, procédez comme suit :

Accédez à la page de facturation de Google Cloud Platform.
Cliquez sur Ajouter un compte de facturation.
Renseignez les informations de paiement, puis cliquez sur Démarrer l'essai gratuit ou sur Envoyer et activer la facturation.
Cliquez sur l'onglet Mes projets en haut de la page.
Cliquez sur les trois points sous Actions à côté du projet Actions pour l'atelier de programmation.
Cliquez sur Modifier la facturation.
Dans le menu déroulant, sélectionnez le compte de facturation que vous avez configuré. Cliquez sur Définir le compte.

Pour éviter que des frais ne vous soient facturés, suivez les étapes de la section "Nettoyer votre projet" sur la page "Étapes suivantes" à la fin de cet atelier de programmation.

Déployer l'application Web

Dans cette section, vous allez déployer votre application Web (le jeu Snow Pal) à l'aide de la CLI Firebase. Une fois le déploiement effectué, vous pourrez récupérer l'URL de l'application Web et voir comment le jeu s'affiche dans un navigateur.

Pour déployer votre application Web, procédez comme suit :

Dans le terminal, accédez au répertoire start/.
Exécutez la commande suivante en remplaçant {PROJECT_ID} par l'ID de votre projet :

firebase deploy --project {PROJECT_ID} --only hosting

Au bout de quelques minutes, vous devriez voir le message Deploy complete! (Déploiement terminé), indiquant que l'application Web Snow Pal a bien été déployée sur Firebase.

Pour afficher le jeu Snow Pal dans un navigateur, procédez comme suit :

Récupérez l'URL d'hébergement fournie dans le résultat de votre terminal. Elle devrait ressembler à ceci : https://{PROJECT_ID}.web.app

Collez l'URL dans un navigateur. Vous devriez voir l'écran de démarrage de Snow Pal avec un bouton Start Game :

Ajouter l'URL de l'application Web et l'ID du projet au projet Actions

Ajoutez ensuite l'URL de votre application Web et l'ID de votre projet au fichier actions.intent.MAIN.yaml. Le fait d'ajouter l'URL de l'application Web permet à l'action conversationnelle de savoir à quelle URL envoyer les données, tandis que l'ajout de l'ID de projet dans settings.yaml vous permet de transférer les fichiers téléchargés vers le projet approprié dans la console Actions.

Pour ajouter l'URL de votre application Web et l'ID de votre projet, procédez comme suit :

Ouvrez le fichier start/sdk/custom/global/actions.intent.MAIN.yaml dans votre éditeur de texte.
Dans le champ url, remplacez la chaîne d'espace réservé par l'URL de votre application Web.
Ouvrez le fichier start/sdk/settings/settings.yaml dans votre éditeur de texte.
Dans le champ projectId, remplacez la chaîne d'espace réservé par l'ID de votre projet.

Transférer le projet vers la console Actions

Pour mettre à jour la console Actions avec votre projet local, vous devez transférer votre projet Actions vers la console Actions. Pour cela, procédez comme suit :

Accédez au répertoire sdk :

cd sdk/

Pour copier la configuration de votre système de fichiers local dans la console Actions, exécutez la commande suivante :

gactions push

Déployer le webhook

Lorsque vous avez exécuté gactions push, vous avez importé le code du webhook de démarrage dans la console Actions. Dans la suite de cet atelier de programmation, vous pourrez modifier le code du webhook dans la console Actions. À ce stade, déployez le webhook à partir de la console Actions.

Pour ce faire, procédez comme suit :

Dans la console Actions, cliquez sur Develop (Développer) dans le panneau de navigation.
Cliquez sur l'onglet Webhook dans le panneau de navigation.
Cliquez sur Deploy Fulfillment (Déployer le traitement).

Un délai de quelques minutes peut être nécessaire pour que Cloud Functions provisionne et déploie votre traitement. Le message Cloud Function deployment in progress (Déploiement de Cloud Function) devrait s'afficher au-dessus de l'éditeur de code. Une fois le code déployé, le message Your Cloud Function deployment is up to date (Le déploiement de Cloud Function est à jour) s'affiche.

Tester dans le simulateur

À ce stade, votre action est associée à l'application Web. Vous pouvez utiliser le simulateur de la console Actions pour vous assurer que l'application Web s'affiche lorsque vous appelez l'action.

Pour tester votre action, procédez comme suit :

Dans la barre de navigation de la console Actions, cliquez sur Test (Tester).
Saisissez Talk to Snow Pal sample dans le champ Input (Entrée), puis appuyez sur Enter.
Saisissez Yes dans le champ Input (Entrée), puis appuyez sur Enter. Vous pouvez aussi cliquer sur le bouton Start Game (Démarrer le jeu) au milieu de l'écran.

Vous n'avez pas encore configuré la logique pour deviner une lettre ou le mot. Par conséquent, si vous tentez de deviner une lettre ou un mot, vous obtenez la réponse … Incorrect. Keep on trying! It looks like we need to add more functionality to have this work properly." (Incorrect. Réessayez. Il semble que nous devions ajouter des fonctionnalités pour que le jeu fonctionne correctement.)

Pour ce projet, cette fonctionnalité est divisée en trois composants principaux : l'action conversationnelle, l'application Web et le webhook. Notez qu'il s'agit d'un modèle parmi d'autres pour configurer votre action. Il est organisé de cette façon dans le but de vous présenter les principales fonctionnalités d'Interactive Canvas.

Les sections suivantes expliquent en détail la synergie entre l'action conversationnelle, le webhook et l'application Web, ainsi que d'autres éléments importants d'Interactive Canvas.

Action conversationnelle

Le composant Action conversationnelle de votre action gère la reconnaissance, le traitement et l'envoi de l'entrée utilisateur à la scène appropriée, où une réponse à l'utilisateur est créée. Par exemple, si un utilisateur dit Je propose le e dans Snow Pal, votre action conversationnelle extrait la lettre en tant que paramètre d'intent et la transmet à la logique de jeu appropriée, qui détermine si la proposition est correcte et met à jour l'application Web en conséquence. Vous pouvez consulter et modifier cette logique de conversation dans Actions Builder, un IDE basé sur le Web dans la console Actions. La capture d'écran suivante montre une partie de votre action conversationnelle dans Actions Builder :

Figure 4. Affichage de Main invocation dans Actions Builder

Cette capture d'écran montre Main invocation pour votre action, que les utilisateurs associent à une expression comme Ok Google, parle à l'exemple Snow Pal. Lorsque l'utilisateur appelle votre action, Main invocation envoie une invite avec une réponse canvas, qui contient l'URL de votre application Web.

La première réponse canvas de votre action doit inclure l'URL de l'application Web. Elle indique à l'Assistant qu'il doit afficher l'application Web se trouvant à cette adresse sur l'appareil de l'utilisateur. Les actions canvas supplémentaires dans Actions Builder peuvent inclure un champ send_state_data_to_canvas_app, défini sur true. Ce champ envoie le nom de l'intent et toutes les valeurs de paramètre à l'application Web lorsque l'intent est ciblé, et l'application Web se met à jour en fonction de ces données de l'entrée utilisateur.

Webhook

Pour cet atelier de programmation, votre webhook contient la logique de jeu (vous pouvez le considérer comme un serveur de jeu). La logique de jeu comprend des éléments tels que déterminer si la proposition de l'utilisateur est correcte ou non, ou bien s'il a gagné ou perdu, et générer une réponse en fonction du résultat. Vous pouvez modifier le webhook dans Actions Builder.

Lorsque votre action doit exécuter la logique de jeu, Actions Builder appelle le webhook. Par exemple, l'intent guess de la scène Game passe un appel webhook au gestionnaire guess, qui exécute ensuite la logique pour déterminer si la proposition de l'utilisateur est correcte ou non. Le webhook peut inclure des réponses Canvas dans les gestionnaires qui correspondent aux fichiers de l'application Web et mettent à jour celle-ci en conséquence.

Application Web

Figure 5. Représentation visuelle de l'interaction entre l'action conversationnelle, le webhook et l'application Web dans une action Interactive Canvas

Les fichiers de l'application Web contiennent le code des éléments graphiques et des animations de votre application Web, ainsi que la logique permettant de mettre à jour l'application Web en fonction de l'entrée utilisateur. Vous pouvez modifier ces fichiers dans votre éditeur de texte et déployer ces modifications à l'aide de la CLI Firebase.

Communication entre l'action conversationnelle et l'application Web

Vous devez activer la communication entre votre action conversationnelle et votre application Web afin que cette dernière puisse être mise à jour en fonction de l'entrée utilisateur. Par exemple, si un utilisateur dit Je propose un f,

l'action conversationnelle doit fournir la lettre f à l'application Web afin que celle-ci puisse se mettre à jour en conséquence. Pour transmettre l'entrée utilisateur depuis l'action conversationnelle vers l'application Web, vous devez charger l'API Interactive Canvas.

Le script de cette API est inclus dans /public/index.html, le fichier HTML principal du jeu Snow Pal. Ce fichier définit l'apparence et le chargement de votre interface utilisateur dans plusieurs scripts :

index.html

<!-- Load Assistant Interactive Canvas API -->
 <script type="text/javascript" src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>

Pour mettre à jour l'application Web en fonction de l'entrée utilisateur, vous devez également enregistrer et configurer des rappels dans votre fichier d'application Web. Ceux-ci permettent à votre application Web de répondre aux informations ou aux requêtes de l'action conversationnelle.

Dans /public/js/action.js, il existe une classe préconfigurée appelée Action permettant de déclarer et d'enregistrer des rappels. La classe Action est un wrapper pour l'API Interactive Canvas. Lorsque l'application Web est créée avec la fonction create() dans scene.js, une nouvelle instance Action est créée et setCallbacks() est appelé, comme illustré dans l'extrait de code suivant :

scene.js

// Set assistant at game level.
this.assistant = new Action(this);
// Call setCallbacks to register assistant action callbacks.
this.assistant.setCallbacks();

La fonction setCallbacks() est définie dans la classe Action de /public/js/action.js. Elle déclare des rappels et les enregistre avec l'API Interactive Canvas lors de la création du jeu :

  setCallbacks() {
    // Declare the Interactive Canvas action callbacks.
    const callbacks = {
      onUpdate: (data) => {
     ...
    // Called by the Interactive Canvas web app once web app has loaded to
    // register callbacks.
    this.canvas.ready(callbacks);
  }

La fonction setCallbacks() déclare le rappel onUpdate(), qui est exécuté chaque fois que vous envoyez une réponse Canvas.

La section suivante décrit comment le code spécifique de ce projet est configuré pour transmettre les données de l'action conversationnelle à l'application Web.

Mettre à jour l'application Web en fonction de l'entrée utilisateur

Dans cet atelier de programmation, vous allez utiliser un mappage de commandes pour mettre à jour l'application Web en fonction de l'entrée utilisateur. Par exemple, lorsque l'intent start_game est ciblé dans la scène Welcome, la réponse canvas incluse dans l'invite est envoyée à l'application Web. onUpdate() analyse les métadonnées de la réponse canvas et appelle la commande START_GAME, qui, à son tour, appelle la fonction start() dans scene.js et met à jour l'application Web pour lancer une nouvelle partie.

La fonction start() de scene.js appelle également une fonction updateCanvasState(), qui utilise une méthode appelée setCanvasState() pour ajouter des données d'état auxquelles votre webhook peut accéder.

La méthode updateCanvasState() est appelée à la fin de chaque commande (vous ajouterez ces commandes dans l'atelier de programmation) et met à jour l'état de l'application Web. Chaque fois que updateCanvasState() est appelé, les valeurs de displayedWord et de incorrectGuesses sont mises à jour en fonction de l'état actuel :

scene.js

...
  updateCanvasState() {
    window.interactiveCanvas.setCanvasState({
      correctWord: this.word.text,
      displayedWord: this.word.displayText.text,
      incorrectGuesses: this.incorrectGuesses,
    });

L'état mis à jour est ensuite disponible pour le prochain tour de conversation. Vous pouvez accéder à cet état dans le webhook via conv.context.canvas.state, comme illustré dans l'extrait de code suivant :

index.js

...
  let displayedWord = conv.context.canvas.state.displayedWord;
...

Dans cette section, vous allez ajouter la fonctionnalité guess à votre action, qui permet à l'utilisateur de deviner des lettres du mot ou le mot lui-même.

Action conversationnelle

Dans la section "Tester dans le simulateur", vous avez reçu la réponse It looks like we need to add more functionality to have this work properly (Il semble que nous devions ajouter des fonctionnalités pour que le jeu fonctionne correctement). Vous pouvez à présent supprimer cette invite dans la console Actions afin d'appeler uniquement le webhook (dans la scène Game, l'intent guess est déjà configuré pour passer un appel webhook en cas de ciblage).

Pour supprimer l'invite statique lorsque l'intent guess est ciblé, procédez comme suit :

Dans la console Actions, cliquez sur Scenes (Scènes) dans le panneau de navigation.
Cliquez sur Game (Jeu) pour accéder à la scène Game.
Cliquez sur When guess is matched (Lorsque la proposition est correcte) sous Custom intent handling (Gestion des intents personnalisés). Désactivez l'option Send prompts (Envoyer des invites) pour supprimer l'invite.
Cliquez sur Save (Enregistrer).

Webhook

Dans cette section, vous allez mettre à jour votre webhook avec une logique qui mappe la proposition correcte ou incorrecte d'un utilisateur à la logique d'un fichier d'application Web, qui met ensuite à jour l'application Web en conséquence. Le gestionnaire d'intent guess est déjà configuré dans le webhook. Il vous suffit donc d'ajouter des réponses Canvas à cet intent pour déclencher la logique qui met à jour l'application Web.

Pour mettre à jour votre webhook, procédez comme suit :

Dans la console Actions, cliquez sur Webhook dans le panneau de navigation.
Ajoutez le code suivant à index.js sous le gestionnaire guess :

index.js (section A) :

// Add SECTION A `conv.add(new Canvas({` content here
conv.add(new Canvas({
  data: {
    command: 'CORRECT_ANSWER',
    displayedWord: displayedWord
  },
}));

index.js (section B) :

// Add SECTION B `conv.add(new Canvas({` content here
conv.add(new Canvas({
  data: {
    command: 'INCORRECT_ANSWER',
  },
}));

Cliquez sur Save Fulfillment (Enregistrer le traitement).
Cliquez sur Deploy Fulfillment (Déployer le traitement). Une fois le déploiement effectué, le message Your Cloud Function deployment is up to date (Votre déploiement de Cloud Function est à jour) s'affiche au-dessus de votre éditeur.

Application Web

Vous pouvez à présent configurer votre application Web pour gérer les commandes CORRECT_ANSWER et INCORRECT_ANSWER.

Ouvrez public/js/action.js dans votre éditeur de texte.
Mettez à jour l'application Web pour gérer les commandes CORRECT_ANSWER et INCORRECT_ANSWER :

action.js (section C) :

// Add SECTION C `CORRECT_ANSWER: (params) => {` content here
      CORRECT_ANSWER: (params) => {
        this.gameScene.correctAnswer(params);
      },
      INCORRECT_ANSWER: (params) => {
        this.gameScene.incorrectAnswer();
      },

Exécutez la commande suivante pour mettre à jour l'application Web :

firebase deploy --project {PROJECT_ID} --only hosting

Tester votre action dans le simulateur

À ce stade, votre action peut reconnaître si une proposition est correcte ou non, et mettre à jour l'application Web en conséquence.

Pour tester votre action, procédez comme suit :

Dans la barre de navigation, cliquez sur Test (Tester).
Saisissez Talk to Snow Pal sample dans le champ Input (Entrée), puis appuyez sur Enter.
Saisissez "Yes" (Oui) dans le champ Input (Entrée), puis appuyez sur Enter. Vous pouvez aussi cliquer sur le bouton Yes (Oui).
Saisissez la lettre que vous souhaitez deviner dans le champ de saisie, puis appuyez sur Enter.

Comprendre le code

Dans la section précédente, vous avez ajouté un code qui permet aux utilisateurs de deviner des lettres dans votre jeu et de voir ces propositions reflétées dans le mot ou par la fonte du bonhomme de neige. En règle générale, vous passez un appel webhook dans Actions Builder lorsque l'intent guess est ciblé et les données transférées à votre application Web pour que celle-ci soit mise à jour en conséquence. Par exemple, dans le jeu Snow Pal, si l'utilisateur devine une lettre que le mot contient effectivement, l'application Web se met à jour pour afficher la lettre à la bonne position dans le mot.

Pour les actions qui utilisent Interactive Canvas, le flux général de transmission des données entre le webhook et l'application Web est le suivant :

L'entrée utilisateur correspond à un intent qui inclut une réponse Canvas.
L'action conversationnelle ou le webhook envoie la réponse Canvas, qui déclenche le rappel onUpdate().
Le rappel onUpdate() est mappé à une logique personnalisée qui met à jour l'application Web en conséquence.

Pour ce projet, le code fonctionne ainsi :

Lorsque l'entrée utilisateur correspond à l'intent guess, Actions Builder extrait la lettre de l'entrée utilisateur sous la forme d'un paramètre.
Actions Builder appelle le gestionnaire guess dans votre webhook, qui contient la logique permettant de déterminer si la lettre que l'utilisateur propose est contenue dans le mot.
Le gestionnaire guess contient deux réponses Canvas : une qui s'exécute lorsque la lettre est correcte et l'autre qui s'exécute lorsqu'elle est incorrecte. Chaque réponse Canvas transmet les données appropriées (la commande CORRECT_ANSWER ou INCORRECT_ANSWER) à l'application Web.
Les données contenues dans le champ data de la réponse Canvas sont transmises à la méthode onUpdate() dans action.js. onUpdate() appelle la commande appropriée dans le mappage de commandes de scene.js.
Le mappage de commandes procède au mappage avec les fonctions correctAnswer() et incorrectAnswer() de scene.js. Ces fonctions mettent à jour l'application Web en conséquence pour refléter la proposition de l'utilisateur et appellent setCanvasState() pour envoyer les données d'état de votre application Web à votre webhook.

Dans cette section, vous allez ajouter la fonctionnalité de victoire et de défaite à votre action, qui comprend une logique qui détermine si l'utilisateur a gagné ou perdu, et qui met à jour l'image de l'application Web en fonction du résultat de l'utilisateur.

Action conversationnelle

La fonctionnalité qui gère la victoire ou la défaite de l'utilisateur est configurée dans l'intent guess. Vous n'avez donc rien d'autre à configurer dans Actions Builder.

Webhook

Dans cette section, vous allez mettre à jour votre webhook avec une logique qui gère la victoire et la défaite de l'utilisateur, et qui effectue un mappage avec la logique de l'application Web qui met à jour le jeu avec l'écran de victoire ou de défaite approprié.

Pour mettre à jour votre webhook, procédez comme suit :

Dans la console Actions, cliquez sur Webhook dans le panneau de navigation.
Ajoutez le code suivant à index.js sous le gestionnaire guess :

index.js (section D) :

// Add SECTION D `if (userHasWon)` content here
    if (userHasWon) {
      conv.add(`<speak>Let's see if your guess is there...<break
        time='2500ms'/> ${guess} is right. That spells ${correctWord}!
        ${randomArrayItem(WIN_RESPONSES)}</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'WIN_GAME',
          displayedWord: displayedWord
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (section E) :

// Add SECTION E `}` here
}

index.js (section F) :

// Add SECTION F `Check if the user has exceeded the maximum` content here
// Check if the user has exceeded the maximum amount of max guesses allowed.
    const userHasLost = conv.context.canvas.state.incorrectGuesses + 1 >= MAX_INCORRECT_GUESSES;
    if (userHasLost) {
      conv.add(`<speak>Let's see if your guess is there...<break
      time='2500ms'/> ${guess} is wrong. Sorry you lost. The word is ${correctWord}!</speak>`);
      conv.add(new Canvas({
        data: {
          command: 'LOSE_GAME',
        },
      }));
      conv.add(`<speak>${PLAY_AGAIN_INSTRUCTIONS}</speak>`);
    } else {

index.js (section G) :

// Add SECTION G `}` here
}

Cliquez sur Save Fulfillment (Enregistrer le traitement).
Cliquez sur Deploy Fulfillment (Déployer le traitement). Une fois le déploiement effectué, le message Your Cloud Function deployment is up to date (Votre déploiement de Cloud Function est à jour) s'affiche au-dessus de votre éditeur.

Ici, vous avez ajouté deux réponses Canvas avec les commandes WIN_GAME et LOSE_GAME pour gérer le moment où les utilisateurs gagnent ou perdent la partie. Dans la section suivante, vous allez ajouter une fonctionnalité qui met à jour l'application Web selon que l'utilisateur a gagné ou perdu.

Application Web

Vous pouvez désormais configurer la mise à jour de votre application Web selon que l'utilisateur a gagné ou perdu. Pour mettre à jour votre application Web, procédez comme suit :

Ouvrez public/js/action.js dans votre éditeur de texte.
Mettez à jour votre application Web pour gérer les commandes WIN_GAME et LOSE_GAME :

action.js (section H) :

// Add SECTION H `WIN_GAME: (params) => {` content here
      WIN_GAME: (params) => {
        this.gameScene.winGame(params);
      },
      LOSE_GAME: (params) => {
        this.gameScene.loseGame();
      },

Exécutez la commande suivante pour mettre à jour l'application Web :

firebase deploy --project {PROJECT_ID} --only hosting

Tester votre action dans le simulateur

À ce stade, votre action peut gérer la victoire ou la défaite de l'utilisateur et afficher l'écran approprié pour chaque résultat.

Pour tester votre action, procédez comme suit :

Dans la barre de navigation de la console Actions, cliquez sur Test (Tester).
Saisissez Talk to Snow Pal sample dans le champ Input (Entrée), puis appuyez sur Enter.
Saisissez "Yes" (Oui) dans le champ Input (Entrée), puis appuyez sur Enter. Vous pouvez aussi cliquer sur le bouton Start Game (Démarrer le jeu).
Essayez de deviner des lettres et des mots jusqu'à ce que vous gagniez ou perdiez.

Si vous êtes invité à rejouer, vous recevez un message indiquant que la fonctionnalité nécessaire pour rejouer n'a pas encore été ajoutée. Vous ajouterez cette fonctionnalité dans la section suivante.

Comprendre le code

La fonctionnalité de victoire et de défaite fonctionne de la même manière que la fonctionnalité de proposition : la proposition de l'utilisateur est associée à l'intent guess et votre webhook l'évalue. Si elle est correcte, le code vérifie si l'utilisateur a gagné. Si oui, la commande WIN_GAME est envoyée à l'application Web. Si la proposition est incorrecte, le code vérifie si l'utilisateur a perdu. Si oui, la commande LOSE_GAME est envoyée à l'application Web. Ces commandes déclenchent les fonctions winGame() et loseGame() dans scene.js, qui mettent à jour l'application Web afin d'afficher l'écran de victoire ou de défaite et de mettre à jour l'état du jeu.

Dans cette section, vous allez ajouter une fonctionnalité qui permet à l'utilisateur de dire Rejouer ou de cliquer sur le bouton Play Again de l'application Web pour commencer une nouvelle partie. Vous allez modifier l'intent play_again dans Actions Builder pour envoyer une réponse canvas qui met à jour l'application Web en conséquence. Vous allez également ajouter une logique qui déclenche l'intent play_again lorsque l'utilisateur clique sur le bouton Play Again.

Action conversationnelle

Lorsque vous avez testé votre action dans la section précédente, vous avez reçu l'invite suivante lorsque vous avez tenté de faire une nouvelle partie : That would be great, but we will build this functionality in a later section. For now, just reset the Action (Ce serait super, mais nous allons créer cette fonctionnalité dans une prochaine section. Pour le moment, réinitialisez simplement l'action.). Vous pouvez à présent supprimer cette invite et la remplacer par l'invite Okay, here's another game! (OK, commençons une nouvelle partie !), qui s'affiche lorsque l'utilisateur demande à rejouer et qui inclut une réponse canvas qui déclenche le lancement d'une nouvelle partie par l'application Web.

Pour configurer l'invite qui s'affiche lorsque l'utilisateur souhaite rejouer, procédez comme suit :

Dans la console Actions, cliquez sur la liste déroulante Scene (Scenes).
Cliquez sur la scène Game.
Cliquez sur When play_again is matched sous Custom intent handling (Gestion des intents personnalisés).
Remplacez l'invite par celle-ci :

candidates:
  - first_simple:
      variants:
        - speech: 'Okay, here's another game!'
    canvas:
      sendStateDataToCanvasApp: true

Cliquez sur Save (Enregistrer).

Webhook

Dans cet atelier de programmation, le webhook gère la logique de jeu. Comme la fonctionnalité pour rejouer ne nécessite aucun type de validation logique, vous n'avez pas besoin d'appeler le webhook. À la place, vous pouvez envoyer une réponse canvas directement depuis Actions Builder pour transmettre les données nécessaires à l'application Web (vous avez configuré ceci dans la section précédente).

Application Web

Vous pouvez à présent modifier vos fichiers d'application Web afin qu'ils se mettent à jour correctement lorsque l'utilisateur demande à rejouer. Pour ajouter cette fonctionnalité, procédez comme suit :

Ouvrez public/js/action.js dans votre éditeur de texte.
Mettez à jour l'application Web pour gérer la commande PLAY_AGAIN :

action.js (section I) :

// Add SECTION I `PLAY_AGAIN: (params) => {` content here
      PLAY_AGAIN: (params) => {
        this.gameScene.start();
      },

Ouvrez public/js/scene.js dans votre éditeur de texte.
Mettez à jour l'application Web pour lancer une nouvelle session de jeu lorsque l'utilisateur clique sur le bouton "Play Again" (Rejouer) :

scene.js (section J) :

// Add SECTION J `sendTextQuery` content here
     window.interactiveCanvas.sendTextQuery('Play again');

Exécutez la commande suivante pour mettre à jour l'application Web :

firebase deploy --project {PROJECT_ID} --only hosting

Tester votre action dans le simulateur

Votre action peut désormais lancer une nouvelle session de jeu lorsque l'utilisateur dit ¨Play again (Rejouer) ou appuie sur le bouton "Play again".

Pour tester votre action, procédez comme suit :

Dans la barre de navigation, cliquez sur Test (Tester).
Saisissez Talk to Snow Pal sample dans le champ Input (Entrée), puis appuyez sur Enter.
Saisissez "Yes" (Oui) dans le champ Input (Entrée), puis appuyez sur Enter. Vous pouvez aussi cliquer sur le bouton Start Game (Démarrer le jeu).
Essayez de deviner des lettres et des mots jusqu'à ce que vous gagniez ou perdiez.
Saisissez à nouveau "Play Again" (Rejouer) dans le champ Input (Entrée), puis appuyez sur Enter. Vous pouvez aussi cliquer sur le bouton Play Again (Rejouer).

Comprendre le code

Lorsque vous avez testé votre action, vous avez pu lancer une nouvelle partie soit en utilisant la saisie vocale Play again (Rejouer), soit en utilisant la saisie tactile, c'est-à-dire en cliquant sur le bouton "Play Again".

Dans le cas de la saisie vocale, lorsque l'utilisateur dit Play again ou une phrase similaire, l'intent play_again est ciblé et ajoute l'invite Okay, here's another game (OK, commençons une nouvelle partie) à la file d'attente d'invites. La réponse canvas incluse dans l'invite envoie le nom de l'intent et d'autres métadonnées à l'application Web. Le nom de l'intent est transmis au rappel onUpdate(), qui mappe la commande correspondante, PLAY_AGAIN, au mappage de commandes de action.js. La commande PLAY_AGAIN déclenche la fonction start() dans scene.js et met à jour l'application Web avec une nouvelle partie.

Dans le cas de la saisie tactile, vous utilisez sendTextQuery(), une API interactive Canvas qui vous permet de déclencher un intent via la saisie tactile pour faire fonctionner le bouton.

Dans cet atelier de programmation, vous utilisez sendTextQuery() pour appeler l'intent play_again lorsque l'utilisateur clique sur le bouton "Play Again" (Rejouer). L'argument Play again correspond à une phrase d'entraînement de l'intent play_again et déclenche cet intent de la même manière que si l'utilisateur disait Play again (Rejouer). L'intent play_again déclenche ensuite une logique qui met à jour l'application Web et démarre une nouvelle partie.

Dans cette section, vous allez mettre à jour l'appel implicite PLAY_GAME.

L'appel implicite PLAY_GAME permet aux utilisateurs d'appeler votre action lorsqu'ils effectuent une demande générale, par exemple I want to play a game (Je veux jouer à un jeu).

Le code source contient l'intent global PLAY_GAME, qui se trouve à l'adresse /sdk/custom/global/actions.intent.PLAY_GAME.yaml. Vous le retrouvez dans la console sous Invocation (Appel) sous la forme PLAY_GAME, comme illustré dans la capture d'écran suivante :

Pour permettre aux utilisateurs d'appeler votre action via cet appel implicite, vous devez ajouter à l'appel implicite PLAY_GAME une réponse canvas avec l'URL de l'application Web. Pour cela, procédez comme suit :

Dans la console Actions, cliquez sur PLAY_GAME dans le panneau de navigation.
Mettez à jour l'invite pour inclure l'URL de votre application Web, comme indiqué dans l'extrait de code suivant :

candidates:
  - canvas:
      url: 'https://<PROJECT_ID>.web.app'

Cliquez sur Save (Enregistrer).

Tester votre action dans le simulateur

Votre action accepte désormais l'appel implicite PLAY_GAME.

Pour tester votre action, procédez comme suit :

Dans la barre de navigation, cliquez sur Test (Tester).
Cliquez sur Test fulfillment for system intents (Tester le traitement pour les intents système).
Cliquez sur Invoke Action (Appeler l'action).

Votre action devrait être appelée dans le simulateur.

Dans cette section, vous allez apprendre à déboguer votre action Interactive Canvas lorsque celle-ci ne fonctionne pas correctement. Le projet Snow Pal est fourni avec un calque de débogage que vous pouvez activer. Le calque affiche tous les résultats console.log() et console.error() en bas à droite de l'écran, comme illustré dans la capture d'écran suivante :

Pour activer ce calque, ouvrez le fichier /public/css/main.css et commentez la ligne display: none !important;, comme indiqué dans l'extrait de code suivant :

main.css

.debug {
 display: flex;
 flex-direction: column;

/* Comment below to view debug overlay */
/* display: none !important; */

 width: 500px;
 height: 150px;
 right: 0;
 bottom: 0;
 position: absolute;
}

Félicitations !

Vous avez terminé l'atelier de programmation Interactive Canvas. Vous disposez désormais des compétences nécessaires pour créer votre propre action Interactive Canvas.

Points abordés

Créer, déployer et tester une action Interactive Canvas
Mettre à jour l'application Web à l'aide de réponses Canvas
Améliorer votre action par différentes méthodes, comme sendTextQuery() et setCanvasState()
Déboguer votre action

Autres ressources de formation

Pour en savoir plus sur Interactive Canvas, consultez les ressources suivantes :

Documentation Interactive Canvas : documentation officielle d'Actions on Google pour Interactive Canvas.
Exemple d'Interactive Canvas : le code d'un jeu Interactive Canvas simple qui vous permet de faire tourner un triangle et de modifier ses couleurs.

Effacer votre projet (recommandé)

Pour éviter de vous facturer des frais, nous vous recommandons de supprimer les projets que vous ne comptez pas utiliser. Pour supprimer ceux que vous avez créés dans cet atelier de programmation, procédez comme suit :

Suivez la procédure décrite dans la section Arrêter (supprimer) des projets pour supprimer le projet Cloud et ses ressources.

Facultatif : suivez la procédure décrite dans la section Supprimer un projet pour supprimer immédiatement votre projet de la console Actions. Si vous ne le faites pas, votre projet sera supprimé automatiquement après un délai de 30 jours environ.

Enquête

Avant de partir, veuillez répondre à une courte enquête sur votre expérience.