Cómo crear una acción de Interactive Canvas para Asistente de Google con Actions Builder

La plataforma para desarrolladores de Actions on Google te permite crear software que extienden la funcionalidad de Asistente de Google, el asistente personal virtual de Google, en más de 1,000 millones de dispositivos, como bocinas inteligentes, teléfonos, vehículos, TVs, auriculares y muchos más. Los usuarios interactúan con Asistente de Google mediante conversaciones para completar tareas, como comprar alimentos o reservar un viaje (para obtener una lista completa de lo que puedes hacer, consulta el directorio de acciones). Como desarrollador, puedes usar Actions on Google a fin de crear y administrar fácilmente experiencias de conversación interesantes y útiles entre los usuarios y tu propio servicio externo.

Este codelab es un módulo avanzado que se diseñó para lectores que ya tienen algo de experiencia en la creación de acciones para Asistente de Google. Si no tienes experiencia previa de desarrollo con Actions on Google, te recomendamos que sigas nuestros codelabs introductorios (Nivel 1 y Nivel 2) para familiarizarte con la plataforma. Estos módulos te guiarán por una serie de funciones que pueden ayudarte a expandir la funcionalidad de tu acción y aumentar tu público.

En este codelab, usarás Interactive Canvas, un framework compilado en Asistente de Google, para agregar un juego de pantalla completa a una acción de conversación. El juego es una aplicación web interactiva que Asistente envía como respuesta al usuario durante una conversación. Luego, el usuario podrá jugar mediante entradas de voz o texto en pantallas inteligentes y dispositivos móviles Android.

En lugar de crear un juego completo, implementarás un juego parcialmente compilado de antemano que se llama Snow Pal, y agregarás la lógica del juego a medida que progreses con este codelab. Snow Pal es una variación del juego del ahorcado tradicional; muestra una cantidad de espacios en blanco que representa una palabra, y tú debes adivinar las letras que crees que podría incluir esa palabra. Con cada letra incorrecta, el muñeco de nieve se derrite un poco más. Si logras adivinar la palabra antes de que Snow Pal se derrita por completo, ganas el juego.

Figura 1: Una partida de Snow Pal en curso

Qué compilarás

En este codelab, crearás una acción que usa Interactive Canvas. La acción incluirá las siguientes funciones:

Un juego de pantalla completa al que pueden jugar los usuarios con la voz
Un botón que los usuarios pueden presionar para comenzar el juego
Un botón que los usuarios pueden presionar para volver a jugar

Cuando completes este codelab, la acción finalizada tendrá el siguiente flujo conversacional:

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

Usuario: Yes

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

Usuario: I guess the letter E

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

El usuario continúa adivinando letras, o la palabra entera, hasta que termine el juego.

Qué aprenderás

Cómo compilar e implementar una acción de Interactive Canvas
Cómo actualizar el juego de palabras según las entradas táctiles y de voz del usuario
Cómo pasar datos a la aplicación web con diferentes métodos
Cómo depurar la acción de Interactive Canvas

Requisitos

Estos son algunos requisitos del codelab:

Un navegador web, como Chrome
Un IDE o editor de texto que prefieras
La instalación de NodeJS, npm y git en tu máquina

Se recomienda familiarizarse con JavaScript (ES6) para saber interpretar el código utilizado en este codelab.

Opcional: Obtén el código de muestra completo

En este codelab, compilarás la muestra de una versión incompleta paso a paso. También puedes obtener la muestra completa en el repositorio de GitHub si así lo prefieres.

Interactive Canvas es un framework que se compiló en base a Asistente de Google y te permite agregar imágenes y animaciones de pantalla completa a tu acción de conversación.

Las acciones que usan Interactive Canvas funcionan de manera similar a las acciones de conversación. Sin embargo, las acciones de Interactive Canvas tienen la capacidad adicional de enviar una respuesta al dispositivo para abrir una aplicación web de pantalla completa.

El usuario proporciona entradas a la aplicación web mediante la voz o texto hasta que finaliza la conversación.

Figura 2: Acción creada con Interactive Canvas

En este codelab, tu proyecto se organiza en estas tres partes principales:

Aplicación web: Los archivos de la aplicación web contienen el código de las imágenes y animaciones de la app web, así como la lógica para actualizarla según la entrada del usuario.
Acción de conversación: La acción de conversación incluye tu lógica de conversación, que reconoce, procesa y responde a la entrada del usuario.
Webhook: La webhook procesa la lógica del juego. Para este codelab, puedes considerar al webhook como el servidor del juego.

En cada sección de este codelab, modificas la aplicación web, la acción de conversación y la webhook para agregar funcionalidad a tu acción de Interactive Canvas.

En un nivel superior, la acción de conversación, la webhook y la aplicación web de la acción de Snow Pal funcionan de la siguiente manera:

La acción de conversación le solicita al usuario que adivine una letra de la palabra o la palabra entera.
El usuario dice "Adivino la letra 'i'" a la aplicación web Snow Pal en una pantalla inteligente.
La entrada del usuario se envía a tu acción de conversación, que se define en tu proyecto de Actions Builder o SDK de Actions.
La acción de conversación procesa la entrada del usuario y, según la entrada que proporcione, se activa la lógica de la webhook que actualiza la aplicación web o se envían metadatos para actualizar la aplicación web directamente.
Se actualiza la aplicación web para mostrar dónde aparece la letra en la palabra, y se solicita al usuario que vuelva a adivinar.

Obtendrás más información sobre el funcionamiento de Interactive Canvas en la sección "Comprende la infraestructura de Interactive Canvas". Ahora que ya conoces los aspectos básicos, puedes comenzar a configurar el entorno que utilizarás en este codelab.

Cómo verificar la configuración de permisos de Google

Para probar la acción que compilarás en este codelab, debes habilitar los permisos necesarios a fin de que el simulador de la Consola de Actions pueda acceder a la acción. Sigue estos pasos para habilitar los permisos:

Ve a la página Controles de actividad.
De ser necesario, accede con tu Cuenta de Google.
Habilita estos permisos:

Actividad web y de aplicaciones
En Actividad web y de aplicaciones, marca la casilla de verificación junto a Incluir el historial de Chrome y la actividad en los sitios, apps y dispositivos que usan los servicios de Google

Cómo instalar la interfaz de línea de comandos de gactions

En este codelab, debes usar la herramienta de interfaz de línea de comandos (CLI) de gactions para sincronizar tu proyecto de acciones entre la Consola de Actions y tu sistema de archivos local.

Para instalar la CLI de gactions, sigue las instrucciones de la sección Cómo instalar la herramienta de línea de comandos de gactions.

Cómo instalar la interfaz de línea de comandos de Firebase

La interfaz de línea de comandos (CLI) de Firebase te permite implementar tu proyecto de acciones en Cloud Functions y alojar la aplicación web.

Este codelab utiliza npm para instalar la CLI de Firebase. Asegúrate de instalar npm, que se suele incluir con Node.js.

Para instalar o actualizar la CLI, abre una terminal y ejecuta el siguiente comando npm:

npm install -g firebase-tools

A fin de verificar si la CLI se instaló de forma correcta, ejecuta este comando:

firebase --version

Asegúrate de que la versión de Firebase CLI sea 8 o posterior, de modo que incluya todas las funciones más recientes que se requieren de Cloud Functions. Si la versión es anterior, ejecuta npm install -g firebase-tools para implementar la actualización.

Para acceder a Firebase, ejecuta este comando:

firebase login

Cuando accedas a Firebase, asegúrate de usar la misma Cuenta de Google que utilizas para crear el proyecto de acciones.

Cómo clonar el repositorio

En esta sección, clonarás los archivos que necesitas para este codelab. A fin de obtener los archivos, sigue estos pasos:

Abre una terminal y cambia el directorio a uno en el que sueles almacenar proyectos de codificación. Si no tienes uno de ese tipo, ve al directorio principal.
Para clonar este repositorio, ejecuta el siguiente comando en la terminal:

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

Abre el directorio start/. Este repositorio contiene los siguientes directorios importantes con los que trabajarás:

public/: Este directorio incluye el código HTML, CSS y JavaScript para tu aplicación web.
sdk/custom/: Este directorio incluye la lógica para tu acción de conversación (escenas, intents y tipos).
sdk/webhooks/: Este directorio es tu webhook y contiene la lógica del juego.

Figura 3: Estructura del código de directorio start

En esta sección, crearás y compilarás tu proyecto de acciones, enviarás el código del repositorio clonado a la Consola de Actions con la CLI de gactions e implementarás la aplicación web y la webhook.

Cómo crear un proyecto de acciones

El proyecto de Acciones es el contenedor de tu acción. Para crearlo mientras completas este codelab, sigue estos pasos:

Abre la Consola de Actions.
Haz clic en New project.
Ingresa un Project name, como canvas-codelab. El nombre es para tu referencia interna; más adelante podrás establecer un nombre externo para el proyecto.

Haz clic en Create project.
En la pantalla What kind of Action do you want to build?, selecciona la tarjeta Game.
Haz clic en Next.
Selecciona la tarjeta Blank project y, luego, haz clic en Start building.

Cómo guardar el ID del proyecto para tu acción

El ID del proyecto es un identificador único para tu acción. Lo necesitarás para completar varios pasos en este codelab.

Para recuperar el ID del proyecto, sigue estos pasos:

En la Consola de Actions, haz clic en los tres puntos verticales ubicados en la parte superior derecha.
Haz clic en Project settings.

Copia el ID del proyecto.

Cómo asociar una cuenta de facturación

Para implementar tu entrega más adelante con Cloud Functions, debes asociar una cuenta de facturación a tu proyecto en Google Cloud. Si ya tienes una cuenta de facturación, puedes ignorar los pasos que se muestran a continuación.

A fin de asociar una cuenta de facturación a tu proyecto, haz lo siguiente:

Ve a la página de facturación de Google Cloud Platform.
Haz clic en la opción Agregar cuenta de facturación.
Completa la información de pago y haz clic en Iniciar prueba gratuita o Enviar y habilitar la facturación.
Haz clic en la pestaña Mis proyectos, en la parte superior de la página.
Haz clic en los tres puntos ubicados en Acciones, junto al proyecto de acciones del codelab.
Haz clic en Cambiar la facturación.
En el menú desplegable, selecciona la cuenta de facturación que configuraste. Haz clic en Establecer cuenta.

Para evitar que se generen gastos, sigue los pasos que se muestran en la sección "Cómo limpiar tu proyecto" de la página "Pasos siguientes", al final de este codelab.

Cómo implementar la aplicación web

En esta sección, implementarás la aplicación web (el juego Snow Pal) con Firebase CLI. Una vez que la implementas, podrás recuperar la URL de la aplicación web y observar cómo se ve el juego en un navegador.

A fin de implementar la aplicación web, sigue estos pasos:

En la terminal, navega al directorio start/.
Ejecuta el siguiente comando y reemplaza {PROJECT_ID} por el ID del proyecto:

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

Luego de algunos minutos, deberías ver el mensaje que indica que se completó la implementación; es decir que la aplicación web de Snow Pal en Firebase se implementó correctamente.

Para ver el juego Snow Pal en un navegador, sigue estos pasos:

Recupera la URL de alojamiento que se proporciona en el resultado de la terminal. La URL debería tener este formato: https://{PROJECT_ID}.web.app

Pega la URL en un navegador. Deberías ver la pantalla de inicio del juego Snow Pal con un botón Start Game:

Cómo agregar la URL de la aplicación web y el ID del proyecto al proyecto de acciones

A continuación, agrega tu URL de la aplicación web y el ID del proyecto al archivo actions.intent.MAIN.yaml. Agregar la URL de la aplicación web permite que la acción de conversación sepa a qué URL enviar datos; mientras que agregar el ID del proyecto en settings.yaml te permite enviar los archivos descargados al proyecto correcto en la Consola de Actions.

Para agregar la URL de la aplicación web y el ID del proyecto, sigue estos pasos:

Abre el archivo start/sdk/custom/global/actions.intent.MAIN.yaml en el editor de texto.
En el campo url, reemplaza la string de marcador de posición por la URL de la aplicación web.
Abre el archivo start/sdk/settings/settings.yaml en el editor de texto.
En el campo projectId, reemplaza la string de marcador de posición por el ID del proyecto.

Cómo enviar el proyecto a la Consola de Actions

A fin de actualizar la Consola de Actions con tu proyecto local, debes enviar el proyecto de acciones a la Consola de Actions. Para ello, haz lo siguiente:

Cambia al directorio sdk:

cd sdk/

Para copiar la configuración de tu sistema de archivos local a la Consola de Actions, ejecuta el siguiente comando:

gactions push

Cómo implementar la webhook

Cuando ejecutaste gactions push, importaste el código de la webhook inicial en la Consola de Actions. Para el resto de este codelab, puedes editar el código de tu webhook en la Consola de Actions. En este punto, puedes implementar la webhook desde la Consola de Actions.

Para ello, sigue estos pasos:

En la Consola de Actions, haz clic en Develop, en el menú de navegación.
Haz clic en la pestaña Webhook del panel de navegación.
Haz clic en Deploy Fulfillment.

Cloud Functions puede tardar unos minutos en proporcionar e implementar tu entrega. Deberías ver un mensaje que diga Cloud Function deployment in progress… arriba del editor de código. Cuando se implemente correctamente el código, el mensaje indicará que la implementación de tu Cloud Function está actualizada.

Cómo hacer la prueba en el simulador

En este punto, la acción está vinculada a la aplicación web. Puedes usar el simulador de la Consola de Actions para asegurarte de que la aplicación web aparezca cuando invocas la acción.

Para probar tu acción, sigue estos pasos:

En la barra de navegación de la Consola de Actions, haz clic en Test.
Escribe Talk to Snow Pal sample en el campo Input y presiona Enter.
Escribe Yes en el campo Input y presiona Enter. De manera alternativa, puedes hacer clic en el botón Start Game ubicado en el centro de la pantalla.

Aún no configuraste la lógica para adivinar una letra o la palabra, por lo que si adivinas la palabra o una letra, recibirás una respuesta que indica que la opción es incorrecta y debes seguir probando, dado que es necesario agregar otras funcionalidades para que funcione correctamente.

Para este proyecto, la funcionalidad se organiza en tres componentes principales: la acción de conversación, la aplicación web y la webhook. Ten en cuenta que este es un modelo de cómo puedes configurar la acción, y se organiza de esta manera para destacar la funcionalidad principal de Interactive Canvas.

En las próximas secciones, se detalla más sobre el funcionamiento conjunto de la acción de conversación, la webhook y la aplicación web, así como otros elementos importantes de Interactive Canvas.

Acción de conversación

El componente de acción de conversación controla el reconocimiento de la entrada del usuario, la procesa y la envía a la escena correspondiente, donde se construye una respuesta para el usuario. Por ejemplo, si un usuario dice "Adivino la letra 'e'" en el juego Snow Pal, la acción de conversación extrae la letra como un parámetro de intent y se lo pasa a la lógica adecuada del juego, que determina si la elección es correcta y actualiza la aplicación web como corresponde. Puedes ver y modificar esta lógica conversacional en Actions Builder, un IDE basado en la Web de la Consola de Actions. En la siguiente captura de pantalla, se muestra una parte de tu acción de conversación en Actions Builder:

Figura 4: Visualización de Main invocation en Actions Builder

En esta captura de pantalla, se muestra la Main invocation de tu acción, que coincide con la entrada del usuario cuando dice una frase como "Hey Google, habla con la muestra de Snow Pal". Cuando el usuario invoca tu acción, la Main invocation envía un mensaje con una respuesta de canvas, que contiene la URL de tu aplicación web.

La primera respuesta de canvas en tu acción debe incluir la URL de la aplicación web. Esa respuesta le indica a Asistente que debe renderizar la aplicación web en esa dirección, en el dispositivo del usuario. Las respuestas de canvas adicionales en Actions Builder pueden incluir un campo, send_state_data_to_canvas_app, configurado en true. Este campo envía el nombre del intent y cualquier valor del parámetro a la aplicación web cuando el intent coincide, y la aplicación web se actualiza en función de estos datos de la entrada del usuario.

Webhook

En este codelab, tu webhook contiene la lógica del juego (puedes considerar al webhook como el servidor del juego). La lógica del juego incluye elementos que permiten, por ejemplo, determinar si un usuario adivinó o no, o si el usuario ganó o perdió, y construir una respuesta basada en el resultado. Puedes modificar la webhook en Actions Builder.

Cuando tu acción necesita ejecutar lógica del juego, Actions Builder llama al webhook. Por ejemplo, el intent guess en la escena Game hace una llamada de webhook al controlador guess, que luego ejecuta lógica para determinar si el usuario adivinó o no. La webhook puede incluir respuestas de Canvas en los controladores que mapean a los archivos de la aplicación web y actualizar la Web como corresponde.

Aplicación web

Figura 5: Representación visual de la interacción entre la acción de conversación, la webhook y la aplicación web en una acción de Interactive Canvas

Los archivos de la aplicación web contienen el código de las imágenes y animaciones de la app web, así como la lógica para actualizarla según la entrada del usuario. Modifica los archivos de la aplicación web en el editor de texto e implementa los cambios con Firebase CLI.

Comunicación entre la acción de conversación y la aplicación web

Debes habilitar la comunicación entre tu acción de conversación y aplicación web para que esta pueda actualizarse según la entrada del usuario. Por ejemplo, si un usuario dice "Adivino la letra 'f'",

la acción debe proporcionar la letra "f" a la aplicación web para que esta se actualice según corresponda. A fin de pasar la entrada del usuario de la acción de conversación a la aplicación web, debes cargarla en la API de Interactive Canvas.

La secuencia de comandos de esta API se incluye en /public/index.html, que es el archivo HTML principal del juego Snow Pal. En este archivo se define la apariencia de tu IU y cómo se carga en diferentes secuencias de comandos:

index.html

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

Para actualizar la aplicación web según la entrada del usuario, también debes registrar y configurar devoluciones de llamada en el archivo de tu aplicación web. Las devoluciones de llamada le permiten a la app responder a la información o las solicitudes de la acción de conversación.

En /public/js/action.js, hay una clase configurada previamente que se llama Action y sirve para declarar y registrar devoluciones de llamada. La clase Action está encapsulada en la API de Interactive Canvas. Cuando se crea la aplicación web con la función create() en scene.js, se crea una nueva instancia de Action y se llama a setCallbacks(), como se muestra en el siguiente fragmento:

scene.js

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

La función setCallbacks() se define en la clase Action de /public/js/action.js. Esa función declara las devoluciones de llamada y las registra con la API de Interactive Canvas en la creación del juego:

  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 función setCallbacks() declara la devolución de llamada onUpdate(), a la que se llama cada vez que envías una respuesta de Canvas.

En la siguiente sección, se describe cómo se configura el código específico de este proyecto para pasar datos de la acción de conversación a la aplicación web.

Cómo actualizar la aplicación web según las entradas del usuario

En este codelab, usarás un mapa de comandos para actualizar la aplicación web según las entradas del usuario. Por ejemplo, cuando el intent start_game encuentra una coincidencia en la escena Welcome, la respuesta de canvas incluida en el mensaje se envía a la aplicación web. onUpdate() analiza los metadatos de la respuesta de canvas y llama al comando START_GAME, que, a su vez, llama a la función start() en scene.js y actualiza la aplicación web para comenzar una nueva sesión del juego.

La función start() en scene.js también llama a una función (updateCanvasState()), que usa un método llamado setCanvasState() para agregar datos de estado a los que puede acceder tu webhook.

Al final de cada comando (los cuales agregarás durante el codelab), se llama al método updateCanvasState() y se actualiza el estado de la aplicación web. Cada vez que se llama a updateCanvasState(), se actualizan los valores de displayedWord y incorrectGuesses en función del estado actual:

scene.js

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

El estado actualizado estará disponible para el próximo turno de la conversación. Puedes acceder a este estado en la webhook mediante conv.context.canvas.state, como se muestra en el siguiente fragmento de código:

index.js

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

En esta sección, agregarás la funcionalidad guess a tu acción, que permitirá que el usuario adivine letras de la palabra o la palabra entera.

Acción de conversación

En la sección "Cómo hacer la prueba en el simulador", recibiste una respuesta que incluía un mensaje para explicar que se requería agregar otras funcionalidades para que funcione correctamente. Ahora puedes borrar ese mensaje en la Consola de Actions para que se llame únicamente a la webhook (en la escena Game, el intent guess ya está configurado para hacer una llamada a la webhook cuando se encuentra una coincidencia).

Para quitar el mensaje estático cuando se asocia el intent guess, sigue estos pasos:

En la Consola de Actions, haz clic en Scenes, en el menú de navegación.
Haz clic en Game para ir a la escena Game.
Haz clic en la opción When guess is matched, en Custom intent handling. Borra Send prompts para quitar la solicitud.
Haz clic en Save.

Webhook

En esta sección, actualizarás tu webhook con lógica que mapea la elección correcta o incorrecta del usuario a la lógica de un archivo de aplicación web, que luego actualiza la app web como corresponde. El controlador del intent guess ya está configurado en la webhook, por lo que solo necesitas agregar las respuestas de Canvas a este intent para activar la lógica que actualiza la aplicación web.

Para actualizar tu webhook, sigue estos pasos:

En la Consola de Actions, haz clic en Webhook, en el menú de navegación.
Agrega el siguiente código a index.js en el controlador guess:

index.js (sección A):

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

index.js (sección B):

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

Haz clic en Save Fulfillment.
Haz clic en Deploy Fulfillment. Cuando se complete la implementación, verás un mensaje sobre tu editor que indicará que la implementación de tu Cloud Function está actualizada.

Aplicación web

Ahora puedes configurar tu aplicación web para controlar los comandos CORRECT_ANSWER y INCORRECT_ANSWER.

Abre public/js/action.js en tu editor de texto.
Actualiza la aplicación web para controlar los comandos CORRECT_ANSWER y INCORRECT_ANSWER:

action.js (sección C):

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

Ejecuta el siguiente comando para actualizar la aplicación web:

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

Cómo probar tu acción en el simulador

En este punto, tu acción puede reconocer si el usuario adivinó o no y actualizar la aplicación web como corresponda.

Para probar tu acción, sigue estos pasos:

En la barra de navegación, haz clic en Test.
Escribe Talk to Snow Pal sample en el campo Input y presiona Enter.
Escribe "Yes" en el campo Input y presiona Enter. De manera alternativa, puedes hacer clic en el botón Yes.
Escribe la letra que quieras adivinar en el campo de entrada y presiona Enter.

Cómo interpretar el código

En la sección anterior, agregaste código que permite que los usuarios adivinen letras en tu juego y verlas reflejadas en la palabra o el muñeco de nieve. En un nivel superior, puedes hacer una llamada de webhook en Actions Builder cuando se asocia el intent guess, que pasa datos a tu aplicación web para actualizarla correctamente. Por ejemplo, si el usuario adivina una letra que existe en la palabra del juego Snow Pal, se actualiza la aplicación web para mostrar la letra en la posición correspondiente de la palabra.

En el caso de acciones que usan Interactive Canvas, el flujo general de cómo se pasan los datos de la webhook a la aplicación web es el siguiente:

La entrada del usuario coincide con un intent que incluye una respuesta de Canvas.
La acción de conversación o la webhook envía la respuesta de Canvas, que activa la devolución de llamada onUpdate().
onUpdate() mapea a la lógica personalizada que actualiza la aplicación web como corresponde.

Para este proyecto en particular, el código funciona de esta manera:

Cuando el usuario brinda una coincidencia con el intent guess, Actions Builder extrae la letra de la entrada del usuario como parámetro.
Actions Builder llama al controlador guess en tu webhook, que contiene lógica para determinar si la letra que adivinó el usuario aparece en la palabra.
El controlador de guess contiene dos respuestas de Canvas; una que se ejecuta cuando la letra es correcta y otra que se ejecuta cuando es incorrecta. Cada respuesta de Canvas pasa los datos adecuados (el comando CORRECT_ANSWER o INCORRECT_ANSWER) a la aplicación web.
Los datos que contiene el campo data de la respuesta de Canvas se pasan al método onUpdate() en action.js. onUpdate() llama al comando adecuado en el mapa de comandos, en scene.js.
El mapa de comandos se asigna a las funciones correctAnswer() y incorrectAnswer() en scene.js. Estas funciones actualizan la aplicación web como corresponde para reflejar las elecciones del usuario y llamar a setCanvasState() para enviar los datos de estado de tu aplicación web a tu webhook.

En esta sección, agregas la funcionalidad para ganar y para perder a tu acción, que incluye lógica que determina si el usuario ganó o perdió y lógica para actualizar la imagen de la aplicación web según el resultado del usuario.

Acción de conversación

La funcionalidad que procesa si el usuario ganó o perdió el juego se configurará en el intent guess, por lo que no necesitas realizar ninguna configuración adicional en Actions Builder.

Webhook

En esta sección, actualizarás tu webhook con lógica que procesa el resultado ganador o perdedor del usuario y que mapea a la lógica de la aplicación web que actualiza el juego con la pantalla correspondiente al resultado.

Para actualizar tu webhook, sigue estos pasos:

En la Consola de Actions, haz clic en Webhook, en el menú de navegación.
Agrega el siguiente código a index.js en el controlador guess:

index.js (sección 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 (sección E):

// Add SECTION E `}` here
}

index.js (sección 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 (sección G):

// Add SECTION G `}` here
}

Haz clic en Save Fulfillment.
Haz clic en Deploy Fulfillment. Cuando se complete la implementación, verás un mensaje sobre tu editor que indicará que la implementación de tu Cloud Function está actualizada.

Aquí agregaste dos respuestas de Canvas con los comandos WIN_GAME y LOSE_GAMEpara procesar cuando los usuarios ganan o pierden la partida. En la próxima sección, agregarás funcionalidad que actualiza la aplicación web según el resultado ganador o perdedor.

Aplicación web

Ahora puedes configurar tu aplicación web para que se actualice según si el usuario ganó o perdió. A fin de actualizar tu aplicación web, sigue estos pasos:

Abre public/js/action.js en tu editor de texto.
Actualiza la aplicación web para que procese los comandos WIN_GAME y LOSE_GAME:

action.js (sección H):

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

Ejecuta el siguiente comando para actualizar la aplicación web:

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

Cómo probar tu acción en el simulador

En este punto, tu acción puede procesar el resultado del usuario si gana o pierde y mostrar la pantalla correspondiente a cada uno.

Para probar tu acción, sigue estos pasos:

En la barra de navegación de la Consola de Actions, haz clic en Test.
Escribe Talk to Snow Pal sample en el campo Input y presiona Enter.
Escribe "Yes" en el campo Input y presiona Enter. De manera alternativa, haz clic en botón Start Game.
Adivina letras y palabras hasta ganar o perder.

Si solicitas volver a jugar, recibirás un mensaje en el que se indica que aún no se agregó la funcionalidad requerida para volver a jugar. La incluirás en la próxima sección.

Cómo interpretar el código

La funcionalidad para ganar y perder es similar a la de adivinar: el usuario brinda una coincidencia con el intent guess, y tu webhook evalúa la entrada del usuario. Si el usuario acierta, el código verifica si el usuario ganó; en ese caso, se envía el comando WIN_GAME a la aplicación web. En cambio, si el usuario no adivina, el código verifica si perdió; en ese caso, se envía el comando LOSE_GAME a la app web. Estos comandos activan las funciones winGame() y loseGame() en scene.js que actualizan la aplicación web para que se muestre la pantalla ganadora o perdedora y se actualice el estado del juego.

En esta sección, agregarás funcionalidad que permite al usuario solicitar volver a jugar o hacer clic en el botón Play Again de la aplicación web para comenzar una partida nueva. Modificarás el intent play_again en Actions Builder para enviar una respuesta de canvas que actualiza la aplicación web como corresponde, y agregarás lógica que activa el intent play_again cuando el usuario hace clic en el botón Play Again.

Acción de conversación

Cuando probaste tu acción en la sección anterior, si intentabas volver a jugar, recibías un mensaje que indicaba que compilarías esa funcionalidad más adelante en otra sección y que debías restablecer la acción hasta entonces. Ahora puedes borrar ese mensaje y reemplazarlo con uno que le responda al usuario cuando solicita otro juego (en el que proporciona otro juego) y que incluya una respuesta de canvas para activar la aplicación web a fin de iniciar un juego nuevo.

Para actualizar el mensaje cuando el usuario quiere volver a jugar, sigue estos pasos:

En la Consola de Actions, haz clic en la opción Scene desplegable.
Haz clic en la escena Game.
Haz clic en When play_again is matched, en Custom intent handling.
Reemplaza el mensaje de la siguiente forma:

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

Haz clic en Save.

Webhook

En este codelab, la webhook administra la lógica del juego. Dado que la funcionalidad para volver a jugar no requiere ninguna validación de lógica, no necesitas llamar a la webhook. En su lugar, puedes enviar una respuesta de canvas directamente desde Actions Builder para pasar los datos necesarios a la aplicación web (configuraste esto en la sección anterior).

Aplicación web

Ahora puedes modificar los archivos de tu aplicación web para que se actualice correctamente cuando el usuario solicite volver a jugar. A fin de agregar esta funcionalidad, sigue estos pasos:

Abre public/js/action.js en tu editor de texto.
Actualiza la aplicación web para que procese el comando PLAY_AGAIN:

action.js (sección I):

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

Abre public/js/scene.js en tu editor de texto.
Actualiza la aplicación web a fin de que se inicie una nueva sesión de juego cuando el usuario haga clic en el botón para volver a jugar:

scene.js (sección J):

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

Ejecuta el siguiente comando para actualizar la aplicación web:

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

Cómo probar tu acción en el simulador

La acción ahora puede iniciar una sesión de juego nueva cuando el usuario solicita volver a jugar o presiona el botón correspondiente.

Para probar tu acción, sigue estos pasos:

En la barra de navegación, haz clic en Test.
Escribe Talk to Snow Pal sample en el campo Input y presiona Enter.
Escribe "Yes" en el campo Input y presiona Enter. De manera alternativa, haz clic en botón Start Game.
Adivina letras y palabras hasta ganar o perder.
Escribe "Play Again" en el campo Input y presiona Enter. De manera alternativa, puedes hacer clic en el botón para volver a jugar.

Cómo interpretar el código

Cuando probaste la acción, podías iniciar un juego nuevo mediante la entrada de voz (solicitando volver a jugar) la entrada táctil (haciendo clic en el botón para volver a jugar).

Para la opción de entrada de voz, cuando el usuario pide volver a jugar o algo parecido, se asocia el intent play_again y se agrega un mensaje a la cola (para proporcionarle al usuario otro juego). La respuesta de canvas incluida en el mensaje envía el nombre del intent y otros metadatos a la aplicación web. El nombre del intent se pasa a la devolución de llamada onUpdate(), que mapea el comando correspondiente (PLAY_AGAIN) al mapa de comandos en action.js. El comando PLAY_AGAIN activa la función start() en scene.js, y se actualiza la aplicación web con una nueva sesión de juego.

Para la opción de entrada táctil, usas sendTextQuery(), una API de Interactive Canvas que te permite activar un intent a través de la entrada táctil, a fin de que funcione el botón.

En este codelab, usarás sendTextQuery() para invocar el intent play_again cuando un usuario haga clic en el botón para volver a jugar. El argumento Play again coincide con una frase de entrenamiento en el intent play_again y activa el intent de la misma manera que cuando un usuario pide volver a jugar. A continuación, el intent play_again activa una lógica que actualiza la aplicación web e inicia una sesión de juego nueva.

En esta sección, actualizarás la invocación implícita PLAY_GAME.

La invocación implícita PLAY_GAME permite que los usuarios invoquen tu acción cuando hacen una solicitud general, como pedir comenzar un juego.

El código fuente contiene el intent global PLAY_GAME, que se encuentra en /sdk/custom/global/actions.intent.PLAY_GAME.yaml. Esto queda reflejado en la consola, en Invocation como PLAY_GAME, como se muestra en la siguiente captura de pantalla:

Para permitir que los usuarios invoquen tu acción mediante esta invocación implícita, debes agregar una respuesta de canvas con la URL de la aplicación web a la invocación implícita PLAY_GAME. Para ello, haz lo siguiente:

En la Consola de Actions, haz clic en PLAY_GAME, en el menú de navegación.
Actualiza el mensaje para incluir la URL de la aplicación web, como se muestra en el siguiente fragmento:

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

Haz clic en Save.

Cómo probar tu acción en el simulador

Ahora, la acción admite la invocación implícita PLAY_GAME.

Para probar tu acción, sigue estos pasos:

En la barra de navegación, haz clic en Test.
Haz clic en Test fulfillment for system intents.
Haz clic en Invoke Action.

Se debe invocar tu acción en el simulador.

En esta sección, aprenderás a depurar tu acción de Canvas Interactive cuando no funcione correctamente. El proyecto Snow Pal incluye una superposición de depuración que puedes habilitar. La superposición muestra todos los resultados console.log() y console.error() en la parte inferior derecha de la pantalla, como se ve en la siguiente captura:

Para habilitar esta superposición, abre el archivo /public/css/main.css y comenta la línea display: none !important;, como se muestra en el siguiente fragmento:

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;
}

Felicitaciones.

Completaste el codelab introductorio de Interactive Canvas y, ahora, cuentas con las habilidades necesarias para compilar tu propia acción de Interactive Canvas.

Qué aprendiste

Cómo compilar, implementar y probar una acción de Interactive Canvas
Cómo usar las respuestas de Canvas para actualizar la aplicación web
Cómo usar diferentes métodos para mejorar tu acción, como sendTextQuery() y setCanvasState()
Cómo depurar tu acción

Recursos de aprendizaje adicionales

Consulta los recursos que se indican a continuación para obtener más información sobre Interactive Canvas:

Documentación de Interactive Canvas: Es la documentación oficial de Actions on Google sobre Interactive Canvas.
Muestra de Interactive Canvas: Es el código de un juego simple de Interactive Canvas que te permite girar un triángulo y modificar los colores.

Cómo limpiar tu proyecto (recomendado)

A fin de evitar incurrir en posibles cargos, te recomendamos quitar los proyectos que no quieras usar. Para borrar los proyectos que creaste en este codelab, sigue estos pasos:

Si quieres borrar el proyecto de la nube y los recursos, completa los pasos indicados en la sección Cómo apagar (borrar) proyectos.

Opcional: Para quitar un proyecto de la Consola de Actions de forma inmediata, completa los pasos indicados en la sección Cómo borrar un proyecto. Si no sigues este paso, se quitará automáticamente el proyecto después de alrededor de 30 días.

Encuesta de opinión

Antes de irte, completa una breve encuesta sobre tu experiencia.