Rappels

Vous pouvez implémenter les rappels suivants dans votre action Interactive Canvas:

onUpdate()

Le rappel onUpdate() transmet les données de votre webhook à votre application Web pour mettre à jour l'application Web en conséquence. Vous ne devez utiliser ce rappel qu'avec le modèle de traitement côté serveur du développement d'Interactive Canvas.

Pour en savoir plus sur onUpdate(), consultez Transmettre des données pour mettre à jour l'application Web.

onTtsMark()

Le rappel onTtsMark() est appelé lorsque les balises <mark> personnalisées incluses dans le langage de balisage de synthèse vocale (SSML) de votre réponse sont lues à voix haute à l'utilisateur lors de la synthèse vocale. Vous pouvez utiliser onTtsMark() dans les modèles de développement de traitement côté serveur et côté client.

Dans les extraits de code suivants, onTtsMark() synchronise l'animation de l'application Web avec la sortie de synthèse vocale correspondante. Lorsque l'action indique à l'utilisateur "Désolé, vous avez perdu", l'application Web épelle le mot correct et affiche les lettres à l'utilisateur.

Dans l'exemple suivant, le gestionnaire de webhook revealWord inclut une marque personnalisée dans la réponse envoyée à l'utilisateur lorsqu'il perd la partie:

JavaScript

…
app.handle('revealWord', conv => {
  conv.add(new Simple(`<speak>Sorry, you lost.<mark name="REVEAL_WORD"/> The word is ${conv.session.params.word}.</speak>`));
  conv.add(new Canvas());
});
…

L'extrait de code suivant enregistre ensuite le rappel onTtsMark(), vérifie le nom de la marque et exécute la fonction revealCorrectWord(), qui met à jour l'application Web:

JavaScript

…
setCallbacks() {
    // declare Assistant Canvas Action callbacks
    const callbacks = {
        onTtsMark(markName) {
            if (markName === 'REVEAL_WORD') {
                // display the correct word to the user
                that.revealCorrectWord();
            }
        },
    }
    callbacks.onUpdate.bind(this);
}
…

onInputStatusChanged()

Le rappel onInputStatusChanged() vous avertit lorsque l'état de l'entrée change dans votre action Interactive Canvas. Les changements d'état des entrées indiquent quand le micro s'ouvre et se ferme, ou quand l'Assistant traite une requête. Les événements suivants peuvent entraîner la modification de l'état de l'entrée:

  • L'utilisateur s'adressant à votre action
  • L'utilisateur saisissant du texte dans l'application Recherche Google pour Android
  • Application Web utilisant l'API sendTextQuery() pour envoyer une requête textuelle à l'action
  • Action qui écrit dans l'espace de stockage de la maison et d'autres événements de l'Assistant

Le principal cas d'utilisation de ce rappel est la synchronisation de votre action avec les interactions vocales de l'utilisateur. Par exemple, si un utilisateur joue à un jeu Interactive Canvas et ouvre le micro, vous pouvez mettre le jeu en pause pendant que l'utilisateur parle. Vous pouvez également attendre que le micro soit ouvert pour envoyer une requête textuelle à l'Assistant et s'assurer qu'il est bien reçu.

Cette API signale les états suivants:

  • LISTENING : indique que le micro est activé.
  • IDLE : indique que le micro est fermé.
  • PROCESSING : indique que l'Assistant exécute actuellement une requête et que le micro est fermé.

L'API transmet l'état des entrées à votre action chaque fois que l'état change.

Bien qu'une transition entre les états soit possible, les flux suivants sont courants:

  • IDLE>LISTENING>PROCESSING>IDLE : l'utilisateur dit une requête, celle-ci est traitée et le micro se ferme.
  • IDLE>PROCESSING>IDLE : l'application Web utilise l'API sendTextQuery() pour envoyer une requête textuelle à l'action.
  • IDLE>LISTENING>IDLE : l'utilisateur ouvre le micro, mais n'énonce pas de requête.

Pour utiliser cette fonctionnalité dans votre action, ajoutez onInputStatusChanged() au code de votre application Web, comme indiqué dans l'extrait suivant:

onInputStatusChanged(inputStatus) {
   console.log("The new input status is: ", inputStatus);
}

Le rappel onInputStatusChanged() renvoie un seul paramètre d'énumération, inputStatus. Vous pouvez vérifier cette valeur pour voir l'état actuel de la saisie. L'élément inputStatus peut être LISTENING, PROCESSING ou IDLE.

Ajoutez ensuite onInputStatusChanged() à l'objet callbacks pour l'enregistrer, comme indiqué dans l'extrait de code suivant:

 /**
  * Register all callbacks used by the Interactive Canvas Action
  * executed during game creation time.
  */
 setCallbacks() {
   const that = this;
   // Declare the Interactive Canvas action callbacks.
   const callbacks = {
     onUpdate(data) {
       console.log('Received data', data);
     },
     onInputStatusChanged(inputStatus) {
       console.log("The new input status is: ", inputStatus);
     },
   };
   // Called by the Interactive Canvas web app once web app has loaded to
   // register callbacks.
   this.canvas.ready(callbacks);
 }
}