Devoluciones de llamada

Puedes implementar las siguientes devoluciones de llamada en tu acción de Interactive Canvas:

onUpdate()

La devolución de llamada onUpdate() pasa datos del webhook a la aplicación web para actualizar la aplicación de forma correcta. Solo debes usar esta devolución de llamada con el modelo de entrega del servidor del desarrollo de Interactive Canvas.

Si quieres obtener más información sobre onUpdate(), consulta Cómo pasar datos para actualizar la app web.

onTtsMark()

Se llama a la devolución de llamada onTtsMark() cuando se leen al usuario las etiquetas <mark> personalizadas incluidas en el lenguaje de marcación de síntesis de voz (SSML) de tu respuesta durante Texto a voz (TTS). Puedes usar onTtsMark() en los modelos de desarrollo de entrega del servidor y del cliente.

En los siguientes fragmentos, onTtsMark() sincroniza la animación de la app web con el resultado de TTS correspondiente. Cuando la acción le dice al usuario "Perdiste, perdiste", la app web deletrea la palabra correcta y muestra las letras al usuario.

En el siguiente ejemplo, el controlador de webhook revealWord incluye una marca personalizada en la respuesta al usuario cuando perdió el juego:

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());
});
…

Luego, el siguiente fragmento de código registra la devolución de llamada onTtsMark(), verifica el nombre de la marca y ejecuta la función revealCorrectWord(), que actualiza la app 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()

La devolución de llamada onInputStatusChanged() te notifica cuando cambia el estado de la entrada en tu acción de Interactive Canvas. Los cambios de estado de entrada indican cuándo se abre y se cierra el micrófono, o cuándo Asistente está procesando una consulta. Los siguientes eventos pueden hacer que cambie el estado de la entrada:

  • El usuario que habla con tu Acción
  • El usuario que ingresa texto en la app de Búsqueda de Google para Android (AGSA)
  • La app web que usa la API de sendTextQuery() para enviar una consulta de texto a la acción
  • Escritura de acciones en el almacenamiento de la casa y otros eventos de Asistente

El caso de uso principal para esta devolución de llamada es sincronizar tu Acción con las interacciones por voz del usuario. Por ejemplo, si un usuario está jugando un juego de Interactive Canvas y abre el micrófono, puedes pausar el juego mientras el usuario habla. También puedes esperar hasta que el micrófono esté abierto para enviar una consulta de texto a Asistente y asegurarte de que se reciba.

Esta API informa los siguientes estados:

  • LISTENING: Indica que el micrófono está abierto.
  • IDLE: Indica que el micrófono está cerrado.
  • PROCESSING: Indica que Asistente está ejecutando una consulta y que el micrófono está cerrado.

La API informa el estado de entrada a tu Acción cada vez que cambia el estado.

Si bien es posible cualquier transición entre estados, los siguientes flujos son comunes:

  • IDLE>LISTENING>PROCESSING>IDLE: El usuario dice una consulta, esta se procesa y el micrófono se cierra.
  • IDLE>PROCESSING>IDLE: La app web usa la API de sendTextQuery() para enviar una consulta de texto a la acción.
  • IDLE>LISTENING>IDLE: El usuario abre el micrófono, pero no realiza una consulta.

Para usar esta función en tu acción, agrega onInputStatusChanged() al código de tu app web, como se muestra en el siguiente fragmento:

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

La devolución de llamada onInputStatusChanged() devuelve un solo parámetro de enumeración, inputStatus. Puedes verificar este valor para ver el estado actual de la entrada. El inputStatus puede ser LISTENING, PROCESSING o IDLE.

A continuación, agrega onInputStatusChanged() al objeto callbacks para registrarlo, como se muestra en el siguiente fragmento:

 /**
  * 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);
 }
}