Créer des actions pour l'Assistant Google avec le SDK Actions (niveau 1)

La plate-forme pour les développeurs dédiée à l'Assistant Google vous permet de créer des logiciels visant à étendre les fonctionnalités de cet assistant personnel virtuel sur plus d'un milliard d'appareils (enceintes intelligentes, téléphones, voitures, téléviseurs, casques audio, etc.). Cet assistant simplifie la vie des utilisateurs qui lui demandent d'accomplir des tâches (par exemple, faire des courses, réserver un chauffeur, etc.). En tant que développeur, vous pouvez utiliser cette plate-forme pour créer et gérer facilement des échanges agréables et efficaces entre les utilisateurs et votre propre service de traitement tiers.

Cet atelier de programmation aborde à un niveau débutant les concepts du développement avec le SDK Actions pour l'Assistant Google. Aucune expérience préalable avec la plate-forme n'est nécessaire. Vous allez créer ici une action simple pour l'Assistant Google, qui prédit l'avenir d'un utilisateur dans sa quête sur les terres légendaires de Gryffinberg. Dans l'atelier de programmation de niveau 2 avec le SDK Actions, vous développerez cette action plus en détail pour personnaliser l'avenir de l'utilisateur en fonction de ses réponses.

Ce que vous allez faire

Vous allez créer une action simple qui intègre les fonctions suivantes :

• Répondre à l'utilisateur par un message de bienvenue
• Lui poser une question et y répondre de façon appropriée en fonction de ce qu'il aura sélectionné
• Lui proposer des chips de suggestion cliquables
• Adapter le message de bienvenue selon que l'utilisateur est nouveau ou connu

Une fois votre action finalisée, la conversation se présentera comme suit (le texte à côté du micro correspond à l'entrée utilisateur, et celui à côté du haut-parleur à la réponse de votre action) :

Ce que vous allez apprendre

• Créer un projet dans la console Actions
• Utiliser l'outil gactions pour transférer et extraire votre projet Actions entre la console Actions et votre système de fichiers local
• Envoyer une invite à l'utilisateur lorsqu'il appelle votre action
• Traiter l'entrée utilisateur et y répondre
• Tester votre action dans le simulateur de la console Actions
• Appliquer le traitement via l'éditeur Cloud Functions

Ce dont vous avez besoin

Votre environnement doit inclure les outils suivants :

• Un IDE/éditeur de texte de votre choix
• Un terminal permettant d'exécuter des commandes d'interface système pour Node.js et npm
• Un navigateur Web tel que Google Chrome

Remarque : Si vous préférez utiliser d'autres outils visuels pour créer des actions, suivez plutôt l'atelier de programmation Créer des actions pour l'Assistant Google avec Actions Builder (niveau 1), qui permet de créer la même action à l'aide de l'IDE Actions Builder intégré dans la console.

Les sections suivantes expliquent comment configurer un environnement de développement et créer un projet Actions.

Vérifier vos paramètres d'autorisation Google

Pour tester l'action que vous allez créer dans cet atelier de programmation, vous devez accorder les autorisations nécessaires pour que le simulateur puisse y accéder.

Pour cela, procédez comme suit :

1. Accédez à la page Commandes relatives à l'activité.
2. Connectez-vous à votre compte Google (si ce n'est pas déjà fait).
3. Activez les autorisations suivantes :

• Activité sur le Web et les applications
• Sous Activité sur le Web et 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.

Créer un projet Actions

Votre projet Actions est un conteneur associé à votre action.

Pour le créer :

1. Ouvrez la Console Actions.
2. Cliquez sur New project (Nouveau projet).
3. Saisissez un nom de projet tel que actions-codelab. Ce nom interne est utilisé à titre de référence. Par la suite, vous pourrez donner un nom externe, si nécessaire.

4. Cliquez sur Create project (Créer le projet).
5. Sur la page What kind of Action do you want to build? (Quel type d'action voulez-vous créer ?), sélectionnez la fiche Custom (Personnalisée). Cliquez sur Next (Suivant).
6. Sur la page How do you want to build it? (Comment voulez-vous le créer ?), sélectionnez la fiche Blank project (Projet vide). Cliquez ensuite sur Start building (Commencer).

Enregistrer l'ID de projet associé à votre action

Cet ID est unique. Vous en aurez besoin à plusieurs étapes de cet atelier de programmation.

Pour le récupérer :

1. Dans la console Actions, cliquez sur les trois points verticaux (insérer l'icône ici) en haut à droite.
2. Cliquez sur Project settings (Paramètres du projet).

3. Copiez l'ID du projet.

Associer un compte de facturation

Vous devez associer un compte de facturation à votre projet dans Google Cloud (il vous sera utile plus tard dans cet atelier pour déployer votre traitement via Cloud Functions). Si vous en avez déjà un, vous pouvez ignorer les étapes suivantes.

Pour associer ce compte de facturation à votre projet :

1. Accédez à la page de facturation de Google Cloud Platform.
2. Cliquez sur Ajouter un compte de facturation.
3. Renseignez les informations de paiement, puis cliquez sur Démarrer l'essai gratuit ou Envoyer et activer la facturation.
4. Cliquez sur l'onglet Mes projets en haut de la page.
5. Cliquez sur les trois points sous Actions à côté du projet Actions de l'atelier de programmation.
6. Cliquez sur Modifier la facturation.
7. 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 la procédure de la section "Effacer votre projet" sur la page "Étapes suivantes" à la fin de cet atelier.

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.

Terme clé :

• CLI gactions : outil qui vous permet d'initialiser les fichiers du projet Actions, de transférer des modifications vers la console Actions, de déployer des projets Actions, etc.

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

Télécharger votre projet Actions

Pour développer votre action, téléchargez d'abord votre projet Actions depuis la console Actions.

Pour cela, procédez comme suit :

1. Pour créer un répertoire, puis y accéder, exécutez les commandes suivantes :

mkdir myproject
cd myproject

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

gactions pull --project-id <projectID>

Comprendre la structure des fichiers

Le projet Actions que vous téléchargez depuis la console Actions est représenté dans une structure de fichiers YAML dont voici une vue d'ensemble ci-dessous :

Cette structure de fichiers comprend les éléments suivants :

• actions/ : représente votre projet Actions. Le système appelle actions.yaml lorsque votre action l'est également, ce qui appelle le fichier custom/global/actions.intent.MAIN.yaml.
• custom/ : répertoire dans lequel vous modifierez votre action.
• global/ : répertoire qui contient des intents système que la plate-forme ajoute automatiquement à votre projet. Ces intents système seront traités plus en détail dans cet atelier de programmation.
• manifest.yaml : fichier qui contient des informations "transportables" (c'est-à-dire non spécifiques à projet donné et pouvant être déplacées d'un projet à un autre).
• settings/ : représente les paramètres d'un projet Actions, comme le nom à afficher, les paramètres régionaux par défaut et la catégorie.

L'utilisateur appelle votre action pour démarrer une conversation. Par exemple, si votre action s'intitule SéanceCiné, il peut l'appeler en disant Hey Google, je veux parler à SéanceCiné (Séance ciné étant le nom affiché). Ce nom est obligatoire si vous voulez déployer votre action en production. En revanche, il est facultatif pour la tester. À la place, vous pouvez utiliser l'expression Talk to my test app dans le simulateur pour appeler votre action. Ce simulateur sera traité plus en détail dans cette section.

Vous devez modifier l'appel principal pour définir ce qui se passe après qu'un utilisateur a appelé votre action.

Terme clé :

• Appel principal : point d'entrée via lequel l'utilisateur démarre une conversation avec votre action. Par exemple, si l'utilisateur dit Hey Google, je veux parler à <nom à afficher>, l'appel principal est lancé et l'utilisateur reçoit une réponse.

Par défaut, votre action fournit une invite générique au lancement de l'appel (Commencer à créer votre action en définissant l'appel principal).

Terme clé :

• Invite : elle désigne la réponse que votre action envoie à l'utilisateur. Il peut s'agir d'une simple réponse textuelle ou vocale, ou d'un message enrichi, comme une fiche et une image.

Pour transmettre à l'utilisateur des images en plein écran, vous pouvez utiliser une invite spéciale (Canvas). Pour en savoir plus sur ce Canvas, consultez la documentation sur Interactive Canvas.

Dans la section suivante, vous allez personnaliser l'invite associée à l'appel principal dans le fichier custom/global/actions.intent.MAIN.yaml.

Configurer l'appel principal

Vous pouvez changer l'invite associée à l'appel principal dans le fichier actions.intent.MAIN.yaml.

Pour modifier l'invite que votre action renvoie à l'utilisateur quand il appelle votre action :

1. Ouvrez custom/global/actions.intent.MAIN.yaml dans votre éditeur de texte.
2. Remplacez le texte du champ speech (Start building your action...) par le message de bienvenue suivant : A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: A wondrous greeting, adventurer! Welcome to the mythical land of
                Gryffinberg! Based on your clothes, you are not from around these lands.
                It looks like you're on your way to an epic journey.
transitionToScene: actions.scene.END_CONVERSATION

3. Enregistrez le fichier.

Tester l'appel principal dans le simulateur

La console Actions propose un outil Web appelé simulateur pour tester votre action. L'interface reproduit les appareils et leurs paramètres. Vous pouvez ainsi échanger avec votre action comme si elle était exécutée sur un écran connecté, un téléphone, une enceinte ou KaiOS.

Remarque : Pour avoir les toutes dernières informations sur l'utilisation du simulateur de la console Actions, lisez le guide du simulateur. Consultez-le en cas de difficultés aux prochaines étapes.

Lorsque vous appelez votre action, elle devrait maintenant renvoyer l'invite personnalisée que vous venez d'ajouter (A wondrous greeting, adventurer!…).

Vous pouvez utiliser la commande gactions deploy preview pour tester votre action dans la console sans modifier la version de votre projet Actions. Lorsque vous exécutez cette commande, aucune des modifications que vous apportez dans le système de fichiers local n'est répercutée dans les versions déployées de votre projet Actions. Toutefois, vous pouvez les tester sur une version d'aperçu.

Pour tester l'appel principal de votre action dans le simulateur :

1. Pour déployer votre projet dans la console Actions afin de le tester, exécutez la commande suivante dans le terminal :

gactions deploy preview

Remarque : Des problèmes de validation peuvent vous êtes notifiés lorsque vous exécutez cette commande. Tant que vos fichiers ont été transférés, vous pouvez ignorer cette notification.

Le résultat devrait ressembler à ceci :

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copiez l'URL fournie et collez-la dans un navigateur.
3. Pour appeler votre action dans le simulateur, saisissez Talk to my test app dans le champ Input (Entrée) en haut à gauche, puis appuyez sur Entrée.

Conseil : Vous pouvez également cliquer sur le chip de suggestion Talk to my test app sous Suggestions (lequel est traité de la même façon qu'une entrée utilisateur textuelle ou vocale) ou sur l'icône représentant un micro, puis dire Talk to my test app pour appeler votre action.

Lorsque vous lancez l'appel principal de votre action, l'Assistant répond par votre message de bienvenue personnalisé. À ce stade, la conversation se termine une fois que l'Assistant a communiqué ce message. Dans la section suivante, vous allez modifier votre action pour que la conversation se poursuive.

Afficher les journaux des événements

Dans l'onglet Test (Tester) de la console Actions, le panneau de droite affiche les journaux des événements dans lesquels figure l'historique des conversations. Chacun de ces journaux répertorie les événements survenus lors de la conversation.

Un seul journal des événements a été créé pour votre action. Il comporte à la fois l'entrée utilisateur (Talk to my test app) et la réponse de votre action. Vous trouverez ci-dessous une capture d'écran de ce journal :

Si vous cliquez sur la flèche vers le bas à côté de Talk to my test app dans le journal des événements, vous découvrirez, par ordre chronologique, les événements survenus lors de la conversation :

• userInput : correspond à l'entrée utilisateur (Talk to my test app).
• interactionMatch : correspond à la réponse à l'appel principal de votre action (lancé par l'entrée utilisateur). Si vous développez cette ligne en cliquant sur la flèche, vous verrez l'invite que vous avez ajoutée pour l'appel principal (A wondrous greeting, adventurer!...).
• endConversation : correspond à la transition sélectionnée dans l'intent Main invocation, qui met actuellement fin à la conversation. Vous en saurez davantage sur les transitions dans la section suivante de cet atelier.

Les journaux des événements permettent d'en savoir plus sur le déroulement de votre action et sont utiles pour trouver une solution en cas de bug. Pour afficher les détails d'un événement, cliquez sur la flèche à côté de son nom (voir la capture d'écran ci-dessous) :

Maintenant que vous avez défini ce qui se passe quand un utilisateur appelle votre action, vous pouvez développer le reste de la conversation. Avant de poursuivre cet atelier de programmation, familiarisez-vous avec les termes suivants pour comprendre le principe d'une conversation avec votre action :

Termes clés :

• Scène : élément constitutif de votre action, qui traite l'entrée utilisateur et génère habituellement la réponse donnée à l'utilisateur. Des intents personnalisés activent souvent d'autres scènes, mais celles-ci peuvent aussi être déclenchées autrement.
• Intent personnalisé : entrée utilisateur que votre action est capable de comprendre. Vous allez définir des expressions d'entraînement pour ces intents. Lorsqu'un utilisateur dit quelque chose qui correspond ou ressemble à une expression d'entraînement, l'intent correspondant est ciblé.
• Expression d'entraînement : exemple de ce que peut dire un utilisateur pour cibler un intent. Le moteur de compréhension du langage naturel (NLU, Natural Language Understanding) de l'Assistant développe naturellement ce type d'expressions pour en inclure d'autres similaires.
• Transition : définit la scène vers laquelle effectuer la transition une fois la condition remplie.

Votre action peut comporter une ou plusieurs scènes, et vous devez activer chaque scène avant qu'elle puisse être exécutée. L'action que vous créez dans cet atelier de programmation ne comporte qu'une seule scène, intitulée Start. La méthode la plus courante pour activer une scène consiste à configurer votre action de sorte que, quand une correspondance est établie entre une entrée utilisateur et un intent dans une scène, cet intent déclenche la transition vers une autre scène et l'active.

Par exemple, imaginez une action qui fournit à l'utilisateur des informations sur les animaux. Lorsque l'utilisateur appelle cette action, l'intent Main invocation est ciblé et déclenche la transition vers une scène intitulée Facts. Cette transition active la scène Facts, qui envoie l'invite suivante à l'utilisateur : Would you like to hear a fact about cats or dogs? Dans la scène Facts figure un intent personnalisé appelé Cat, lequel contient des expressions d'entraînement que l'utilisateur peut dire pour entendre des informations sur les chats (par exemple, Je veux écouter des informations sur les chats ou chat). Lorsque l'utilisateur demande qu'on lui donne ce type d'informations, l'intent Cat est ciblé et déclenche une transition vers une scène intitulée Cat fact. La scène Cat fact est activée, et une invite comportant des informations sur les chats est envoyée à l'utilisateur.

Figure 1. Flux de conversation type dans une action créée avec le SDK Actions.

Ensemble, les scènes, intents et transitions constituent la logique de votre conversation. Ils définissent les différents chemins que l'utilisateur peut emprunter au fil de la conversation avec votre action. Dans la section suivante, vous allez créer une scène et définir comment elle est activée après qu'un utilisateur a appelé votre action.

Ajouter une transition entre l'appel principal et une scène

Dans cette section, vous allez créer une scène intitulée Start, qui envoie une invite à l'utilisateur pour lui demander s'il veut qu'on lui prédise son avenir. Vous allez également ajouter une transition entre l'appel principal et cette nouvelle scène Start.

Pour créer cette scène et y ajouter une transition :

1. Ouvrez custom/global/actions.intent.MAIN.yaml dans votre éditeur de texte.
2. Remplacez le texte du champ transitionToScene (actions.scene.END_CONVERSATION) par le code suivant : transitionToScene: Start

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Welcome to the mythical land of  Gryffinberg! Based on your clothes,
              you are not from around these lands. It looks like you're on your way
              to an epic journey.
transitionToScene: Start

Cela indique à votre action de passer de l'appel principal à la scène Start.

3. Enregistrez le fichier.
4. Dans le terminal, créez un répertoire scenes dans le répertoire custom :

mkdir custom/scenes

5. Créez un fichier intitulé Start.yaml dans le répertoire scenes, qui représente la scène start dans votre action :

touch custom/scenes/Start.yaml

6. Ouvrez Start.yaml dans votre éditeur de texte.
7. Collez le code suivant dans le fichier Start.yaml :

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?

Dans le code du fichier Start.yaml figure un champ intitulé onEnter, qui correspond à la première étape exécutée dans le cycle de vie d'une scène.

Terme clé :

• OnEnter: : étape exécutée lors de l'activation d'une scène. OnEnter définit ce qui se passe lorsque l'utilisateur accède à la scène.

Dans ce cas, l'invite (Before you continue on your quest...) est ajoutée à la file d'attente d'invites lorsque l'utilisateur accède pour la première fois à la scène Start.

Terme clé :

• File d'attente d'invites : les invites sont ajoutées les unes aux autres dans une file d'attente. Avant que l'utilisateur puisse répondre, l'Assistant lui propose toutes les invites dans la file d'attente.

Ajouter des chips de suggestion

Les chips de suggestion proposent à l'utilisateur des suggestions cliquables que votre action traite comme des entrées utilisateur. Dans cette section, vous allez ajouter des chips de suggestion Yes et No qui s'afficheront sous l'invite que vous venez de configurer (Before you continue on your quest, would you like your fortune told?) pour aider les utilisateurs sur leurs appareils avec écran.

Pour ajouter des chips de suggestion à l'invite de la scène Start :

1. Modifiez le code dans Start.yaml afin qu'il corresponde à l'extrait de code suivant, qui inclut le code pour configurer les chips de suggestion :

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?
        suggestions:
        - title: "Yes"
        - title: "No"

2. Enregistrez le fichier.

Tester votre action dans le simulateur

À ce stade, votre action devrait passer de l'appel principal à la scène Start, puis demander à l'utilisateur s'il veut qu'on lui prédise son avenir. Les chips de suggestion devraient également apparaître sur l'écran de simulation.

Pour tester votre action dans le simulateur :

1. Dans le terminal, exécutez la commande suivante :

gactions deploy preview

Le résultat devrait ressembler à ceci :

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copiez l'URL fournie et collez-la dans un navigateur.
3. Cliquez sur Test (Tester) pour accéder au simulateur.
4. Saisissez Talk to my test app dans le champ Input (Entrée) en haut à gauche, puis appuyez sur Entrée. Votre action devrait répondre par l'invite Main invocation et l'invite de scène Start ajoutée, à savoir Before you continue on your quest, would you like your fortune told? (Avant de poursuivre votre quête, voulez-vous qu'on vous prédise votre avenir ?), avec les chips de suggestion affichées.

La capture d'écran suivante illustre cette interaction :

Remarque : Les journaux d'événements enregistrent chacune des interactions avec le simulateur dans la session en cours. Ainsi, le journal des événements associés au test que vous avez réalisé tout à l'heure dans cet atelier de programmation est affiché en premier. Pour effacer les journaux d'événements, cliquez sur Reset Test (Réinitialiser le test).

5. Cliquez sur le chip de suggestion Yes ou No pour répondre à l'invite. Vous pouvez également dire Yes ou No, ou saisir Yes ou No dans le champ Input (Entrée).

Lorsque vous répondez à l'invite, votre action renvoie un message indiquant qu'elle ne comprend pas votre entrée : Sorry, I didn't catch that. Can you try again? (Pardon, je n'ai pas compris. Pouvez-vous répéter ?). Comme vous n'avez pas encore configuré votre action pour qu'elle comprenne et réponde à l'entrée Yes ou No, elle établit une correspondance entre votre entrée et un intent NO_MATCH.

Termes clés :

• NO_MATCH : intent générique ciblé lorsque l'utilisateur dit quelque chose qui ne peut pas être associé à un autre intent dans votre action.
• Intent système : intent configuré par défaut qui gère les événements système courants (par exemple, en l'absence d'entrée utilisateur). NO_MATCH et l'intent associé à l'appel principal sont des exemples d'intents système.

Par défaut, l'intent système NO_MATCH fournit des réponses génériques. Toutefois, vous pouvez personnaliser ces réponses pour indiquer à l'utilisateur que vous n'avez pas compris son entrée. L'Assistant met fin à la conversation de l'utilisateur avec votre action quand, au bout de trois fois, il ne parvient pas à cibler l'entrée utilisateur.

Ajouter des intents yes et no

Maintenant que l'utilisateur peut répondre à la question que pose votre action, vous pouvez configurer votre action pour qu'elle comprenne les réponses de l'utilisateur (Yes ou No). Dans les sections suivantes, vous allez créer des intents personnalisés qui sont ciblés lorsque l'utilisateur dit Yes ou No, puis les ajouter à la scène Start.

Créer l'intent yes

Pour créer l'intent yes :

1. Dans le terminal, créez un répertoire intitulé intents dans le répertoire custom :

mkdir custom/intents

2. Créez un fichier intitulé yes.yaml dans le répertoire intents :

touch custom/intents/yes.yaml

3. Ouvrez yes.yaml dans votre éditeur de texte.
4. Collez l'extrait de code suivant qui contient les expressions d'entraînement dans yes.yaml :

yes.yaml

trainingPhrases:
- of course
- let's do it
- ok
- sure
- "y"
- "yes"

5. Enregistrez le fichier.

Ajouter l'intent yes à la scène Start

Votre action peut maintenant comprendre quand un utilisateur formule l'intent Yes. Vous pouvez ajouter l'intent personnalisé yes à la scène Start, car l'utilisateur répond à l'invite Start (Before you continue on your quest, would you like your fortune told?).

Pour l'ajouter à la scène Start :

1. Ouvrez custom/scenes/Start.yaml dans votre éditeur de texte.
2. Ajoutez les gestionnaires intentEvents et yes à la fin du fichier Start.yaml :

Start.yaml

intentEvents:
- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: Your future depends on the item you choose to use for your quest. Choose wisely! Farewell, stranger.
  intent: "yes"
  transitionToScene: actions.scene.END_CONVERSATION

Lorsque l'intent yes est ciblé, l'invite Your future depends on the item you choose to use for your quest (Votre avenir dépend de l'élément que vous choisissez d'utiliser pour votre quête) est ajouté à la file d'attente d'invites. La scène Start passe ensuite à la scène système actions.scene.END_CONVERSATION, qui envoie les invites dans la file d'attente et met fin à la conversation.

Tester l'intent yes dans le simulateur

À ce stade, votre action comprend quand l'utilisateur veut qu'on lui prédise son avenir et renvoie la réponse appropriée.

Pour tester cet intent dans le simulateur :

1. Dans le terminal, exécutez la commande suivante :

gactions deploy preview

Le résultat devrait ressembler à ceci :

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copiez l'URL fournie et collez-la dans un navigateur.
3. Cliquez sur Test (Tester) pour accéder au simulateur.
4. Pour tester votre action dans le simulateur, saisissez Talk to my test app dans le champ Input (Entrée) en haut à gauche, puis appuyez sur Entrée.
5. Saisissez Yes dans le champ Input (Entrée), puis appuyez sur Entrée. Vous pouvez également cliquer sur le chip de suggestion Yes.

Votre action répond à l'utilisateur et lui indique que son avenir dépend de l'aide qu'il choisit. Elle met ensuite fin à la session, car vous avez configuré la transition End conversation pour l'intent yes.

Créer l'intent no

Vous pouvez maintenant créer l'intent no pour que votre action puisse comprendre l'entrée utilisateur et y répondre si l'utilisateur ne veut pas qu'on lui prédise son avenir.

Pour créer cet intent :

1. Dans le terminal, créez un fichier intitulé no.yaml dans le répertoire intents :

touch custom/intents/no.yaml

2. Ouvrez no.yaml dans votre éditeur de texte.
3. Collez les expressions d'entraînement suivantes dans le fichier no.yaml :

no.yaml

trainingPhrases:
- nope
- I don't want
- "n"
- "no"
- nah
- no thanks

4. Enregistrez le fichier.

Ajouter l'intent no à la scène Start

Votre action est maintenant capable de comprendre quand un utilisateur dit no ou emploie une autre expression similaire, comme nope. Vous devez ajouter l'intent personnalisé no à la scène Start, car l'utilisateur répond à l'invite Start (Before you continue on your quest, would you like your fortune told?).

Pour ajouter cet intent à la scène Start :

1. Ouvrez custom/scenes/Start.yaml dans votre éditeur de texte.
2. Ajoutez le gestionnaire no suivant sous le gestionnaire yes dans Start.yaml :

Start.yaml

- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: I understand, stranger. Best of luck on your quest! Farewell.
  intent: "no"
  transitionToScene: actions.scene.END_CONVERSATION

3. Enregistrez le fichier.

Tester l'intent no dans le simulateur

À ce stade, votre action comprend quand l'utilisateur ne veut pas qu'on lui prédise son avenir et renvoie la réponse appropriée.

Pour tester cet intent dans le simulateur :

1. Dans le terminal, exécutez la commande suivante :

gactions deploy preview

Le résultat devrait ressembler à ceci :

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copiez l'URL fournie et collez-la dans un navigateur.
3. Cliquez sur Test (Tester) pour accéder au simulateur.
4. Saisissez Talk to my test app dans le champ Input (Entrée), puis appuyez sur Entrée.
5. Saisissez No dans le champ Input (Entrée), puis appuyez sur Entrée. Vous pouvez également cliquer sur le chip de suggestion No.

Au lieu de prédire l'avenir de l'utilisateur, votre action lui souhaite bonne chance dans sa quête. Elle met ensuite fin à la session, car vous avez configuré la transition End conversation pour l'intent no.

Actuellement, les réponses de votre action sont fixes. Lorsqu'une scène contenant une invite est activée, votre action envoie la même invite à chaque fois. Dans cette section, vous allez implémenter le traitement qui contient la logique permettant de créer une réponse dynamique lors d'une conversation.

Terme clé :

• Traitement : code qui contient la logique de votre action. Un webhook lance des appels à votre traitement en fonction des événements survenus dans vos actions.

Votre traitement détermine si l'utilisateur est nouveau ou déjà connu, et modifie en conséquence le message de bienvenue associé à votre action. Le message pour un utilisateur connu est plus court et mentionne son retour : A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg! (Toutes mes salutations, aventurier ! Ravi de vous revoir sur les terres légendaires de Gryffinberg).

Dans cet atelier de programmation, vous allez utiliser l'éditeur Cloud Functions pour modifier et déployer votre code de traitement.

Terme clé :

• Éditeur Cloud Functions : éditeur intégré pour les projets Actions, que vous pouvez utiliser pour modifier et déployer votre code de traitement avec Cloud Functions for Firebase.

Votre action peut déclencher des webhooks qui informent votre traitement d'un événement qui se produit pendant un appel ou des séquences spécifiques d'une scène. Lorsqu'un webhook est déclenché, votre action envoie à votre traitement une requête avec une charge utile JSON, accompagnée du nom du gestionnaire à utiliser pour traiter l'événement. Ce gestionnaire exécute une logique et renvoie une réponse JSON correspondante.

Créer le traitement

Dans cette section, vous allez modifier votre traitement afin de générer différentes invites pour les utilisateurs connus et nouveaux qui appellent votre action.

Pour ajouter cette logique à votre traitement :

1. Dans le terminal, vérifiez que vous vous trouvez dans le répertoire racine de votre projet et créez un répertoire webhooks :

mkdir webhooks

2. Créez un fichier intitulé ActionsOnGoogleFulfillment.yaml dans le répertoire webhooks :

touch webhooks/ActionsOnGoogleFulfillment.yaml

3. Ouvrez ActionsOnGoogleFulfillment.yaml dans votre éditeur de texte.
4. Ajoutez le gestionnaire greeting et le contenu inlineCloudFunction au fichier ActionsOnGoogleFulfillment.yaml :

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

Le fichier ActionsOnGoogleFulfillment.yaml définit vos gestionnaires de webhooks (tels que le gestionnaire greeting) et indique à votre action d'utiliser Cloud Functions comme point de terminaison de webhook.

5. Créez un répertoire ActionsOnGoogleFulfillment dans le répertoire webhooks :

mkdir webhooks/ActionsOnGoogleFulfillment

6. Créez un fichier intitulé index.js dans le répertoire ActionsOnGoogleFulfillment :

touch webhooks/ActionsOnGoogleFulfillment/index.js

7. Ouvrez index.js dans votre éditeur de texte.
8. Ajoutez le code suivant à index.js :

index.js

const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation({debug: true});

app.handle('greeting', conv => {
 let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Welcome to the mythical land of  Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
 }
 conv.add(message);
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

Ce code définit le gestionnaire greeting, qui envoie le message de bienvenue approprié à l'utilisateur.

9. Enregistrez le fichier.
10. Créez un fichier intitulé package.json dans le répertoire ActionsOnGoogleFulfillment :

touch webhooks/ActionsOnGoogleFulfillment/package.json

Le fichier package.json spécifie les dépendances et d'autres métadonnées pour votre webhook.

11. Ouvrez package.json dans votre éditeur de texte.
12. Copiez le code de ce dépôt GitHub et collez-le dans le fichier package.json.
13. Enregistrez le fichier.

Comprendre le code

Votre traitement, qui utilise la bibliothèque de traitement Actions on Google pour Node.js, répond aux requêtes HTTP de l'Assistant Google.

Dans l'extrait de code précédent, vous définissez le gestionnaire greeting, qui vérifie si l'utilisateur a déjà visité l'action avec la propriété lastSeenTime. Si la propriété lastSeenTime n'est pas définie, l'utilisateur est nouveau et reçoit le message de bienvenue destiné aux nouveaux utilisateurs. Dans le cas contraire, un message de bienvenue différent mentionnant le retour de l'utilisateur est généré.

Modifier l'appel principal pour déclencher un webhook

Maintenant que vous avez défini la fonction greeting, vous pouvez configurer le gestionnaire d'événements greeting dans votre intent d'appel principal pour que votre action appelle cette fonction lorsque l'utilisateur appelle votre action.

Pour configurer votre action afin d'appeler le nouveau gestionnaire greeting :

1. Ouvrez custom/global/actions.intent.MAIN.yaml dans votre éditeur de texte.
2. Remplacez le code dans actions.intent.MAIN.yaml par le code suivant :

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. Enregistrez le fichier.

Désormais, lorsque votre intent d'appel principal est ciblé, le gestionnaire du webhook greeting est appelé.

Tester dans le simulateur l'appel principal modifié

Pour tester votre action dans le simulateur :

1. Dans le terminal, exécutez la commande suivante :

Remarque : Comme cette commande déploie le webhook et installe les dépendances, cela peut prendre plus de temps que les commandes précédentes.

gactions deploy preview

Attention : Si un message d'erreur 403 lié à l'API Cloud Build ou à l'association de votre compte de facturation s'affiche, consultez la page Modifier les paramètres de facturation d'un projet pour associer un compte de facturation. Pour procéder au déploiement via Cloud Functions, vous devez associer un compte de facturation à votre projet dans Google Cloud. Une fois que vous l'avez fait, exécutez de nouveau gactions deploy preview. Pour éviter que des frais ne vous soient facturés, suivez la procédure de la section "Effacer votre projet" sur la page "Étapes suivantes" à la fin de cet atelier.

Le résultat devrait ressembler à ceci :

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copiez l'URL fournie et collez-la dans un navigateur.
3. Pour tester votre action dans le simulateur, saisissez Talk to my test app dans le champ Input (Entrée), puis appuyez sur Entrée.

Comme vous avez déjà testé votre action lors de cet atelier, vous n'êtes pas un nouvel utilisateur. Vous recevez donc le message de bienvenue abrégé suivant : A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!

Le SDK Actions est compatible avec l'IDE Web Actions Builder, intégré à la console Actions. Vous pouvez transférer votre système de fichiers local vers le brouillon de votre action dans la console à l'aide de la commande gactions push. Contrairement à gactions deploy preview, qui vous permet seulement de tester votre action dans le simulateur, gactions push déplace tout le contenu de vos fichiers locaux vers Actions Builder.

La console Actions fournit une représentation visuelle de la configuration de votre action. Visualiser votre action peut être utile pendant le développement et n'a aucune incidence sur l'action proposée pour le test.

Remarque : En exécutant gactions push, vous remplacerez le brouillon actuel de votre projet Actions si vous collaborez avec d'autres personnes sur ce projet.

Pour transférer votre projet Actions et l'afficher dans la console Actions :

1. Dans le terminal, exécutez la commande suivante pour transférer votre projet vers la console Actions :

gactions push

Le résultat devrait ressembler à ceci :

✔ Done. Files were pushed to Actions Console, and you can now view your project with this URL: https://console.actions.google.com/project/{project-id}/overview. If you want to test your changes, run "gactions deploy preview", or navigate to the Test section in the Console.

2. Copiez l'URL fournie et collez-la dans un navigateur.
3. Dans la Console Actions, cliquez sur Develop (Développer) dans la barre de navigation supérieure.
4. Cliquez sur la flèche du menu déroulant à côté de Scenes (Scènes), puis sur Start (Démarrer). Vous devriez voir une représentation visuelle de la scène Start de votre action, comme le montre cette capture d'écran :

Félicitations !

Vous connaissez maintenant les principes de base permettant de créer des actions pour l'Assistant Google avec le SDK Actions.

Sujets abordés

• Configurer un projet Actions dans la console Actions
• Utiliser le SDK Actions pour créer un projet Actions sur votre système de fichiers local
• Ajouter une invite à l'appel principal afin que l'utilisateur puisse démarrer une conversation avec votre action
• Créer une interface de conversation avec des scènes, des intents, des transitions et des suggestions, et appliquer le traitement
• Tester votre action dans le simulateur de la console Actions

Autres ressources de formation

Pour en savoir plus sur la création d'actions pour l'Assistant Google, consultez les ressources suivantes :

• Site officiel de documentation sur le développement d'actions pour l'Assistant Google
• Page GitHub consacrée à Actions on Google pour consulter des exemples de code et des bibliothèques
• Communauté Reddit officielle des développeurs qui travaillent sur l'Assistant

@ActionsOnGoogle sur Twitter pour connaître les dernières informations (envoyez un tweet à #AoGDevs pour montrer votre création !)

Effacer votre projet (recommandé)

Attention : L'atelier de programmation de niveau 2, intitulé "Créer des actions pour l'Assistant Google avec le SDK Actions (niveau 2)", s'appuie sur le projet que vous venez de créer lors du présent atelier. Si vous prévoyez de suivre l'atelier de niveau 2, ne supprimez pas votre projet tout de suite (vous pourrez le supprimer à la section "Effacer votre projet" à la fin de l'atelier de programmation de niveau 2.

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 :

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

Attention : Veillez à sélectionner le bon projet sur la page "Paramètres" de Google Cloud Platform.

2. 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.