Juego de práctica de ortografía con Asistente de Google y Cloud Firestore

1. Descripción general

La plataforma para desarrolladores de Asistente de Google te permite crear software que extienden la funcionalidad de este asistente personal virtual 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 mediante conversaciones para completar tareas, como comprar alimentos o reservar un viaje. Como desarrollador, puedes usar la plataforma para desarrolladores del Asistente a fin de crear y administrar fácilmente experiencias de conversación interesantes y efectivas entre los usuarios y tu propio servicio externo.

En este codelab, se abordan conceptos de nivel intermedio para desarrollar con Asistente de Google, Cloud Functions y Cloud Firestore. En este codelab, compilarás un juego llamado "Práctica de ortografía" que use Asistente de Google para pedirles a los usuarios que escriban palabras.

Qué compilarás

En este codelab, compilarás un juego sofisticado con la siguiente funcionalidad:

• Recibe respuestas ortográficas del usuario y, según el valor, modifica los mensajes conversacionales.
• Responde con sugerencias relacionadas con la ortografía de la palabra, como su definición o la repetición de la palabra
• Crea un bucle de juego para que un usuario pueda interactuar con Asistente nuevamente después de deletrear la palabra.

Antes de comenzar a compilar, puedes interactuar con la acción publicada en tu dispositivo compatible con Asistente de Google cuando dices "Hey Google, habla con Spelling Practice". La ruta predeterminada a través de esta acción para un usuario recurrente se ve en la siguiente interacción:

Cuando termines este codelab, la acción completada tendrá el siguiente flujo conversacional:

Qué aprenderás

• Cómo interactuar con Cloud Firestore
• Cómo usar ranuras para recopilar datos del usuario
• Cómo procesar la entrada de un usuario y devolver una respuesta
• Cómo usar condiciones para agregar lógica a una escena
• Cómo agregar un bucle de juego

Requisitos

Estos son algunos requisitos del codelab:

• Un navegador web, como Google Chrome
• Un IDE para escribir funciones de Cloud Functions
• Una forma de pago En este codelab, se utiliza Cloud Functions para Firebase, lo que requiere que tu proyecto tenga el plan de precios Blaze de Firebase ( más información).
• Una terminal para ejecutar comandos de shell
• Node.js 10 o una versión posterior

2. Obtén el código de las funciones

Clona el repositorio de GitHub desde la línea de comandos:

$ git clone https://github.com/FirebaseExtended/codelab-actions-firestore

3. Crea un proyecto de Firebase y configura tu app

Crea un proyecto de Firebase

1. Accede a Firebase.
2. En Firebase console, haz clic en Agregar proyecto (o Crear un proyecto) y, luego, asigna el nombre Spelling-Practice a tu proyecto de Firebase.

3. Haz clic en las opciones de creación del proyecto. Si se te solicita, acepta las condiciones de Firebase. Omite la configuración de Google Analytics, ya que no utilizarás ese servicio en esta app.

Para obtener más información sobre los proyectos de Firebase, consulta la Información sobre los proyectos de Firebase.

Actualiza al plan de precios Blaze

Para usar Cloud Functions para Firebase, deberás actualizar tu proyecto de Firebase al plan de precios Blaze, lo que significa que vincularás una cuenta de Facturación de Google Cloud al proyecto. Para ello, debes proporcionar una tarjeta de crédito o alguna otra forma de pago.

Todos los proyectos de Firebase, incluidos los del plan Blaze, siguen teniendo acceso a las cuotas de uso sin costo de Cloud Functions. Los pasos que se describen en este codelab se encuentran dentro de los límites de uso sin costo. Sin embargo, verás pequeños cargos ( alrededor de $0.03) de Cloud Storage, que se usa para alojar tus imágenes de compilación de Cloud Functions.

4. Instala Firebase CLI

Firebase CLI (interfaz de línea de comandos) te permite implementar tus Cloud Functions.

Existen varias opciones para instalar Firebase CLI según tu sistema operativo y caso de uso. En los siguientes pasos, se describe la opción más común si también usas Cloud Functions.

1. Asegúrate de haber instalado npm, que se suele incluir con Node.js.
2. Ejecuta el siguiente comando npm para instalar o actualizar la CLI:

$ npm -g install firebase-tools

3. Ejecuta el siguiente comando para verificar que la CLI se haya instalado de forma correcta:

$ firebase --version

Asegúrate de que la versión de Firebase CLI sea 9.0.0 o posterior, de modo que incluya todas las funciones más recientes que se requieren de Cloud Functions. De lo contrario, ejecuta npm install -g firebase-tools para actualizar como se muestra más arriba.

4. Ejecuta el siguiente comando para autorizar Firebase CLI:

$ firebase login

5. En el directorio Orchestrator-functions-start, configura Firebase CLI para que use tu proyecto de Firebase. Ejecuta el siguiente comando, selecciona el ID de tu proyecto y sigue las instrucciones. Cuando se te solicite, puedes elegir cualquier alias, como codelab, por ejemplo.

$ firebase use --add

5. El directorio de funciones

Ahora agregarás funcionalidad con el SDK de Firebase para Cloud Functions a fin de compilar el backend del juego, la Práctica de ortografía.

Cloud Functions te permite ejecutar código en la nube sin necesidad de configurar un servidor. En este codelab, aprenderás a compilar funciones que reaccionen a eventos de Firebase Authentication, Cloud Storage y Firebase Realtime Database. Comencemos con la autenticación.

Cuando utilices el SDK de Firebase para Cloud Functions, el código de tus funciones residirá en el directorio functions (de forma predeterminada). Para facilitarte el proceso, ya creamos el archivo functions/index.js en el que irá tu código. No dudes en inspeccionar el directorio functions antes de continuar.

$ cd functions
$ ls

El código de tus funciones también es una app de Node.js y, por lo tanto, necesita un package.json que proporcione información sobre la app y enumera las dependencias.

Si no conoces Node.js, te recomendamos que obtengas más información sobre él antes de continuar con el codelab.

El archivo package.json ya muestra dos dependencias requeridas: el SDK de Firebase para Cloud Functions y el SDK de Firebase Admin. Para instalarlos de forma local, ejecuta npm install desde el directorio functions:

$ npm install

Ahora, veamos el archivo index.js:

index.js

/**
 * Copyright 2021 Google Inc. All Rights Reserved.
 * ...
 */
// TODO(DEVELOPER): Import the Cloud Functions for Firebase and Firebase Admin modules here. Also import the Actions SDK here.
// TODO(DEVELOPER): Write the getWordDetailsFromDictionaryAPI function here.
// TODO(DEVELOPER): Write the createSpellingPracticeWord function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWordList function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle repeatSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle definitionOfSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle verifySpellingWord function here.

Primero, importará los módulos obligatorios y, luego, escribirá cuatro funciones en lugar de las tareas pendientes. Continúa con el siguiente paso del codelab para importar los módulos.

6. Importa los módulos requeridos

Este codelab requiere tres módulos.

• El módulo firebase-functions nos permite escribir los activadores para nuestras funciones de Cloud Functions.
• El módulo firebase-admin nos permite usar la plataforma de Firebase en un servidor con acceso de administrador, por ejemplo, para escribir en Cloud Firestore.
• La biblioteca de entregas del SDK de Actions para Node.js entrega controladores del SDK de Actions para el Asistente de Google.

1. Para instalar el SDK de Actions, ejecuta el siguiente comando npm:

$ npm install @assistant/conversation

2. En el archivo index.js, reemplaza el primer TODO por lo siguiente:

Estos cambios importan cada uno de los módulos requeridos.

Además, el SDK de Firebase Admin se puede configurar automáticamente cuando se implementa en un entorno de Cloud Functions o en otro contenedor de Google Cloud. Esto es lo que sucede cuando llamamos a admin.initializeApp(); en los cambios que se muestran a continuación.

index.js

/**
 * Copyright 2021 Google Inc. All Rights Reserved.
 * ...
 */

// Import the Actions SDK
const {conversation} = require('@assistant/conversation');
const https = require('https');
const app = conversation();
const cors = require('cors')({origin: true});

// Import the Firebase SDK for Cloud Functions.
const functions = require('firebase-functions');
// Import and initialize the Firebase Admin SDK.
const admin = require('firebase-admin');
admin.initializeApp();
// To access Cloud Firestore
const db = admin.firestore();
// TODO(DEVELOPER): Write the getWordDetailsFromDictionaryAPI function here.
// TODO(DEVELOPER): Write the createSpellingPracticeWord function here.
// TODO(DEVELOPER): Write the shuffleWordList function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWordList function here.
// TODO(DEVELOPER): Write the app Handle getSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle repeatSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle definitionOfSpellingWord function here.
// TODO(DEVELOPER): Write the app Handle verifySpellingWord function here.

Ahora, agreguemos lógica empresarial con funciones para admitir las acciones del Asistente.

7. Crear funciones

Obtén las definiciones de las palabras y escríbelas en Cloud Firestore.

Usarás la API pública de dictionaryapi.dev para obtener las definiciones de las palabras.

En el archivo index.js, reemplaza el TODO para getWordDetailsFromDictionaryAPI con lo siguiente:

index.js

// Retrieves word definition and audio pronunciation from api.dictionaryapi.dev service
// Function uses service provided by https://dictionaryapi.dev/
async function getWordDetailsFromDictionaryAPI(word) {
  let responseData="";
  let req = https.request({
    host: 'api.dictionaryapi.dev',
    port: 443,
    path:'/api/v2/entries/en/' + word,
    method:'GET'
  }, (res) => {
    res.setEncoding('utf8');
    res.on('data', d => {
        responseData+=d;
    })
    res.on('end',function(){
        let object = JSON.parse(responseData)
        const wordListRef = db.collection('wordlist');
        wordListRef.doc(object[0].word).set(
          object[0]
        );
       return responseData;
     });
  });
  req.end();
}

Agrega un activador de Cloud Firestore

A continuación, crearás una Cloud Function que se activará cada vez que se cree un documento nuevo en Cloud Firestore. Llamará a la API de dictionaryapi.dev para obtener definiciones de palabras a través de la función getWordDetailsFromDictionaryAPI que escribimos anteriormente.

En el archivo index.js, reemplaza el TODO de createSpellingPracticeWord por lo siguiente:

index.js

// Activador de Firestore que recupera definiciones de palabras a través de getWordDetailsFromDictionaryAPI para cada documento de Firestore nuevo

exports.createSpellingPracticeWord = functions.firestore
  .document('wordlist/{word}')
  .onCreate((snap, context) => {
    const newValue = snap.data();
    const word = newValue.word;
    getWordDetailsFromDictionaryAPI(word);
});

Obtén una lista de palabras para el juego

Puedes escribir una Cloud Function que recupere una lista de palabras para practicar la ortografía desde Cloud Firestore para el Asistente. Para ello, usamos el controlador de la app.

En el archivo index.js, reemplaza el TODO para getSpellingWordList con lo siguiente.

Agregar esta función a app.handle especial es una forma de hacer que se pueda acceder a ella desde el Asistente.

index.js

// Store the list of spelling words in Assistant session
app.handle('getSpellingWordList', conv => {
  const wordListRef = db.collection('wordlist').limit(50);
  const snapshot = wordListRef;

  if (snapshot.empty) {
    console.log('No matching documents.');
    return;
  }
  VocabularyList = []

  return snapshot.get().then(snapshot => {
    snapshot.forEach(doc => {
      if (doc.data().word) {
          let definition = 'unknown';
          let audio = 'unknown';
          try {
            if(doc.data().hasOwnProperty('meanings')) {
              if(doc.data().meanings[0].hasOwnProperty('definitions')) {
                  definition = doc.data().meanings[0].definitions[0].definition;
              }
            }
            if(doc.data().hasOwnProperty('phonetics')) {
              if(doc.data().phonetics.length > 0)
                audio = doc.data().phonetics[0].audio;
            }
          } catch (error) {
            console.log(error);
          }

          let obj = {
            word: doc.data().word,
            answer: doc.data().word.split("").join(" "),
            definition: definition,
            audio: audio
          }
          VocabularyList.push(obj);
      }
      // Shuffle the array
      let currentIndex = VocabularyList.length, temporaryValue, randomIndex;
      while (0 !== currentIndex) {
        randomIndex = Math.floor(Math.random() * currentIndex);
        currentIndex -= 1;
        temporaryValue = VocabularyList[currentIndex];
        VocabularyList[currentIndex] = VocabularyList[randomIndex];
        VocabularyList[randomIndex] = temporaryValue;
      }
      conv.session.params.vocabWord = VocabularyList;
      conv.session.params.vocabWordIndex = 0;
    });
  });
})

Cómo obtener una palabra de la sesión de Asistente

Puedes escribir una Cloud Function que muestre la siguiente palabra ortográfica de la lista de palabras.

En el archivo index.js, reemplaza el TODO de getSpellingWord por lo siguiente:

index.js

// Returns a spelling practice word to Google Assistant and uses Speech Synthesis Markup Language (SSML) to format the response
app.handle('getSpellingWord',  conv => {
  if (!conv.session.params.vocabWord.empty) {
    conv.session.params.vocabWordIndex+=1;
    const ssml = '<speak>' +
    '<audio src="'+ conv.session.params.vocabWord[conv.session.params.vocabWordIndex].audio +'">Use phonetics to spell the word.</audio> ' +
    '</speak>';
    conv.add(ssml);
  }
  else
    conv.add('Great job! You completed the Spelling practice');
});

Habilita el juego para que repita la palabra

Puedes escribir una Cloud Function que repita la palabra actual del juego.

En el archivo index.js, reemplaza el TODO de repeatSpellingWord por lo siguiente:

index.js

// Returns current spelling word
app.handle('repeatSpellingWord',  conv => {
  if (!conv.session.params.vocabWord.empty) {
    const ssml = '<speak>' +
    '<audio src="'+ conv.session.params.vocabWord[conv.session.params.vocabWordIndex].audio +'">Use phonetics to spell the word. </audio> ' +
    '</speak>';
    conv.add(ssml);
  }
  else
    conv.add('Great job! You completed the Spelling practice');
});

Obtén la definición de la palabra

Puedes escribir una Cloud Function que proporcione la definición de la palabra actual para el juego.

En el archivo index.js, reemplaza el TODO de definitionOfSpellingWord por lo siguiente:

index.js

// Returns spelling word definition from Assistant session parameter
app.handle('definitionOfSpellingWord',  conv => {
  conv.add( 'It means ' + conv.session.params.vocabWord[conv.session.params.vocabWordIndex].definition);
});

Revisar la respuesta ortográfica del usuario

Puedes escribir una Cloud Function que verifique la respuesta del usuario sobre cómo deletrear la palabra actual para el juego.

En el archivo index.js, reemplaza el TODO para verifySpellingWord con lo siguiente:

index.js

// Verifies user spelling response
app.handle('verifySpellingWord', conv => {
  try {
    userResponse = conv.intent.params.userresponse.resolved.join("");
    if (userResponse.toLowerCase() === conv.session.params.vocabWord[conv.session.params.vocabWordIndex].word.toLowerCase()) {
      conv.add('You are correct. Say next to continue.');
    }
    else {
      conv.add('Sorry, wrong answer. The correct answer is ' + conv.session.params.vocabWord[conv.session.params.vocabWordIndex].answer + ' . Say next to continue.');
    }
  } catch (error) {
    conv.add('Sorry. I did not understand your response' );
  }
});
exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

Implementa todas tus funciones

Tus Cloud Functions solo estarán activas después de que las implementes en Firebase.

Desde la raíz del directorio spelling-functions-start, ejecuta el siguiente comando:

$ firebase deploy --only functions

Este es el resultado que debería ver en la consola:

i  deploying functions
i  functions: ensuring necessary APIs are enabled...
⚠  functions: missing necessary APIs. Enabling now...
i  env: ensuring necessary APIs are enabled...
⚠  env: missing necessary APIs. Enabling now...
i  functions: waiting for APIs to activate...
i  env: waiting for APIs to activate...
✔  env: all necessary APIs are enabled
✔  functions: all necessary APIs are enabled
i  functions: preparing functions directory for uploading...
i  functions: packaged functions (X.XX KB) for uploading
✔  functions: functions folder uploaded successfully
i  starting release process (may take several minutes)...
i  functions: creating function createSpellingPracticeWord(us-central1)...
✔  functions[createSpellingPracticeWord(us-central1)]: Successful create operation.
i  functions: creating function ActionsOnGoogleFulfillment(us-central1)...
✔  functions[ActionsOnGoogleFulfillment(us-central1)]: Successful create operation.

✔  Deploy complete!
Project Console: https://console.firebase.google.com/project/spelling-practice-1234/overview

Toma nota de la URL del extremo HTTP de la función ActionsOnGoogleFulfillment para usarla más adelante. Para obtener el extremo, abre Firebase console y, luego, haz clic en el proyecto spelling-practice. Abre el panel de Functions para ver el extremo de las funciones.

Completaste la adición de todas las funciones requeridas. Ahora, pasemos a configurar Cloud Firestore.

8. Habilita Cloud Firestore

Deberás habilitar Cloud Firestore.

En la sección Build de Firebase console, haz clic en Firestore. Luego, haz clic en Crear base de datos.

Las reglas de seguridad controlan el acceso a los datos en Cloud Firestore. Primero, debes establecer algunas reglas básicas en los datos para comenzar. Haz clic en Firestore y, luego, en la pestaña Reglas de Firebase console, agrega las siguientes reglas y, luego, haz clic en Publicar.

Las siguientes reglas restringen el acceso a los datos a los usuarios que acceden a su cuenta, lo que impide que los usuarios no autenticados lean o escriban.

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /{document=**} {
      //
      // WARNING: These rules are insecure! We will replace them with
      // more secure rules later in the codelab
      //
      allow read, write: if request.auth != null;
    }
  }
}

9. Agrega datos de palabras de ortografía a Cloud Firestore

En este paso, escribirás datos de palabras de ortografía en Cloud Firestore para poder generar una lista de palabras para el Asistente (y el juego).

Los datos de Cloud Firestore se estructuran en colecciones, documentos, campos y subcolecciones. Cada palabra del juego se almacenará como su propio documento en una colección de nivel superior llamada wordlist. Para cada documento nuevo en la colección de Firestore, se activará la función createSpellingPracticeWord para obtener los detalles de la palabra del servicio de la API de Dictionary.

Crea una colección de Cloud Firestore

1. En Firebase console, navega a la sección Cloud Firestore.
2. Haz clic en + Iniciar colección.
3. En el cuadro de texto ID de la colección, ingresa wordlist y, luego, haz clic en Siguiente.

A continuación, crearemos un documento para una palabra: acuerdo.

4. En el cuadro de texto Document ID, ingresa agreement.
5. En el cuadro de texto Campo (Field), ingresa word y, en el cuadro de texto Valor, ingresa agreement.
6. Haz clic en Guardar.

Cuando agregas este documento a Cloud Firestore, se activa la función createSpellingPracticeWord para recuperar los detalles de la definición de la palabra. Crea un documento nuevo para cada palabra para agregar más palabras (por ejemplo: asombro, auto, verdadero, contar, mejor, viaje diario, etcétera).

10. Cómo configurar Asistente de Google

En las siguientes secciones, se describe cómo configurar tu entorno de desarrollo del Asistente de Google y cómo crear un proyecto de Acciones.

Verifique su configuración de permisos de Google

Para probar la acción que compiles en este codelab, deberás habilitar los permisos necesarios a fin de que el simulador pueda acceder a ella. Para habilitar los permisos, sigue estos pasos:

1. Ve a la página Controles de actividad.
2. Si aún no lo hiciste, accede con tu Cuenta de Google.
3. Habilita los siguientes permisos:

• Actividad web y de aplicaciones
• En Actividad web y de aplicaciones, selecciona 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.

Cree un proyecto de Actions

El proyecto de Acciones es el contenedor de tu acción. Para crear tu proyecto de acciones destinado a este codelab, sigue estos pasos:

1. Abre la Consola de Actions.
2. Haz clic en Proyecto nuevo.
3. Aceptar las Condiciones del servicio

4. Escribe o selecciona spelling-practice-codelab, que creaste con Firebase console. (El nombre es para tu referencia interna. más adelante podrás establecer un nombre externo para el proyecto.)

5. Haz clic en Importar proyecto.
6. En la pantalla What kind of Action do you want to build?, selecciona la tarjeta Custom.
7. Haz clic en Siguiente.
8. Selecciona la tarjeta Blank project.
9. Haz clic en Start building.
10. Ingresa Práctica de ortografía para el nombre visible y haz clic en Guardar.

Los usuarios inician la conversación con tu acción mediante una invocación. Por ejemplo, los usuarios pueden invocar tu acción diciendo una frase como "Hey Google, habla con Práctica de Ortografía", en la que Práctica de Ortografía es el nombre visible.

Tu acción debe tener un nombre visible si quieres implementarla en producción. Sin embargo, para probar tu Acción, no necesitas definir el nombre visible. En su lugar, puedes usar la frase "Habla con la app de prueba" en el simulador para invocar la acción.

Configurar entrega

Debes conectar al Asistente los controladores de eventos para las funciones de Cloud Functions que escribiste e implementaste anteriormente en este codelab.

Para configurar la entrega, sigue estos pasos:

1. Haz clic en Webhook en el panel de navegación lateral.
2. Selecciona Extremo HTTPS como opción de entrega:

3. Ingresa la URL del extremo de tu función en el cuadro de texto Extremo HTTP y, luego, haz clic en Guardar.

En la siguiente sección, personalizarás el mensaje de tu invocación principal en la Consola de Actions.

Cómo configurar la invocación principal

Debes editar la invocación principal para definir lo que ocurre después de que un usuario invoca tu acción.

De forma predeterminada, Actions Builder proporciona un mensaje genérico cuando se activa tu invocación: "Start build your Action by definition main invocation." (Comienza a compilar tu acción definiendo la invocación principal).

Para modificar el mensaje que tu acción envía de vuelta al usuario cuando la invoca, sigue estos pasos:

1. Haz clic en Main invocation, en el menú de navegación.

2. Marca Call your webhook y agrega el nombre del controlador de eventos getSpellingWordList en el cuadro de texto.
3. En el editor de código, reemplaza el texto del campo speech por el siguiente mensaje de bienvenida: Welcome to Spelling Practice

Nota: Puedes usar el formato YAML o JSON para editar los mensajes.

4. Haz clic en Guardar.

Cómo probar la invocación principal en el simulador

La Consola de Actions proporciona una herramienta web llamada simulador para probar tu acción. La interfaz simula dispositivos de hardware y su configuración, por lo que puedes conversar con tu Action como si se ejecutara en una pantalla inteligente, un teléfono, una bocina o KaiOS.

Para probar la invocación principal de la acción en el simulador, sigue estos pasos:

1. En la barra de navegación superior, haz clic en Test para ir al simulador.
2. Para invocar la acción en el simulador, escribe Talk to Spelling Practice en el campo de entrada ubicado en la parte superior izquierda y, luego, presiona Intro en el teclado.

Cuando activas la invocación principal de la acción, Asistente responde con tu mensaje de bienvenida personalizado. En este punto, la conversación finalizará después de que Asistente responda con un saludo.

Ver registros de eventos

En la pestaña Test, en el panel de la derecha, aparecen los registros de eventos, que muestran el historial de conversaciones como registros de eventos. Cada registro muestra los eventos que ocurren durante ese turno de la conversación. Para ver el registro de eventos, haz clic en el ícono gris que se encuentra antes del evento.

Actualmente, tu acción tiene un registro de eventos que muestra la entrada del usuario ("Habla con la práctica de ortografía") y la respuesta de la acción. En la siguiente captura de pantalla, se muestra el registro de eventos de tu acción:

11. Crea una conversación para la práctica de ortografía

Ahora que definiste lo que sucede después de que un usuario invoca tu acción, puedes compilar el resto de la conversación de esta. Spelling Practice tiene cuatro escenas, y debes activar cada una para poder ejecutarla. La manera más común de activar una escena es configurar la acción de modo que, cuando un usuario coincida con un intent de usuario dentro de una escena, ese intent active la transición a otra escena para ejecutarla.

Cómo pasar de la invocación principal a la escena inicial

En esta sección, crearás una escena nueva llamada Start, que envía un mensaje al usuario para preguntarle si quiere comenzar a jugar a Spelling Practice. También agregarás una transición desde la invocación principal hacia la nueva escena Start.

Para crear esta escena y agregarle una transición, sigue estos pasos:

1. En el menú de navegación superior, haz clic en Develop. Luego, haz clic en Main invocation, en el panel de navegación izquierdo.
2. En la sección Transition, a la derecha, haz clic en el menú desplegable y, luego, escribe Start en el campo de texto.

3. Haz clic en Agregar. Esto crea una escena llamada Start y le indica a la acción que debe realizar la transición a la escena Start después de que la acción le muestre el mensaje de bienvenida al usuario.
4. Haz clic en Scenes en el panel de navegación izquierdo para mostrar la lista de escenas.
5. En Scenes, haz clic en Start para ver la escena Start.
6. Haz clic en + en la sección On enter de la escena Start.
7. Selecciona Send prompts.
8. Reemplaza la oración del campo speech (Enter the response that users will see or hear...) por una pregunta para el usuario: Use phonetic alphabet to spell the word. For example alpha for a, bravo for b, charlie for c etc. Do you want to continue?

Los chips de sugerencias ofrecen sugerencias en las que el usuario puede hacer clic y que tu acción procesa como entradas del usuario. En esta sección, agregarás chips de sugerencias que aparecen debajo del mensaje que acabas de configurar (Do you want to play).

Spelling Practice

?) para admitir usuarios en dispositivos con pantallas.

Para agregar chips de sugerencias al mensaje de la escena Start, sigue estos pasos:

9. En la escena Start, haz clic en las sugerencias debajo del editor de código. Esta acción agrega un solo chip de sugerencias.
10. En el campo title, reemplaza Suggested Response por 'Yes'.
11. Usa el mismo formato para agregar manualmente un chip de sugerencias titulado 'No' y 'Help with Phonetics'. El código debería verse como el siguiente fragmento:
12. Haz clic en Guardar.

Cómo probar tu acción en el simulador

En este punto, tu acción debería pasar de la invocación principal a la escena Iniciar y preguntarle al usuario si quiere continuar. Los chips de sugerencias también deberían aparecer en la pantalla simulada.

Para probar tu acción en el simulador, sigue estos pasos:

1. En la barra de navegación, haz clic en Test para ir al simulador.
2. Para probar la acción en el simulador, escribe Talk to Spelling Practice en el campo de entrada.
3. Presiona Intro. Tu acción debería responder con el mensaje Main invocation y el mensaje de la escena Start agregado: "Welcome to Spelling Practice. Usa el alfabeto fonético para deletrear la palabra. Por ejemplo, alfa para a, bravo para b, charlie para c, etcétera. ¿Quieres continuar?".

En la siguiente captura de pantalla, se muestra esta interacción:

4. Haz clic en el chip de sugerencias Yes, No o Help with Phonetics para responder el mensaje. (También puedes decir "Sí", "No" o "Ayuda con la fonética", o bien ingresar Yes, No o Help with Phonetics en el campo Entrada).

Cuando respondes el mensaje, tu acción responde con un mensaje en el que se indica que no comprende tu entrada: "Sorry, I didn't catch that. Can you try again?" ("Lo siento, no entendí. ¿Puedes volver a intentarlo?"). Dado que aún no configuraste tu acción para que comprenda y responda a las entradas "Yes" o "No", la acción hará coincidir la entrada con un intent NO_MATCH.

De forma predeterminada, el intent del sistema NO_MATCH proporciona respuestas genéricas, pero puedes personalizarlas para indicarle al usuario que no comprendiste su entrada. Asistente finalizará la conversación del usuario con tu acción cuando no pueda asociar la entrada del usuario tres veces.

Cómo agregar intents de no y fonética

Ahora que los usuarios pueden responder a la pregunta que les plantea tu acción, puedes configurarla para que comprenda las respuestas de los usuarios ("Yes" o "No" o "Help with Phonetics"). En las siguientes secciones, crearás intents del usuario que coincidan cuando el usuario diga "Yes", "No" o "Help with Phonetics", y los agregarás a la escena Start. Usaremos el intent del sistema yes y crearemos otros intents.

Crea el intent no

Ahora, debes crear el intent no para comprender y responder cuando el usuario no quiera jugar. Para crear este intent, sigue estos pasos:

1. En el menú de navegación, haz clic en Develop.
2. Haz clic en Intents personalizados, en el panel de navegación, para abrir la lista de intents.
3. Haz clic en el signo + (signo más) al final de la lista de intents. Asigna el nombre no al intent nuevo y presiona Intro.
4. Haz clic en no para abrir la página del intent no.
5. En la sección Add training phrases, haz clic en el cuadro de texto Enter Phrase y, luego, ingresa las siguientes frases:

• No
• N
• I don't want
• nope

6. Haz clic en Guardar.

Agrega el intent no a la escena Start

Ahora, la acción puede comprender si el usuario dice "no" o algo parecido a "no", como "nope". Debes agregar el intent de usuario no a la escena Start porque el usuario responde a la instrucción Start ("Welcome to Spelling Practice. Usa el alfabeto fonético para deletrear la palabra. por ejemplo, alfa para a, bravo para b, charlie para c, etc. ¿Quieres continuar?).

Para agregar este intent a la escena Start, sigue estos pasos:

1. En el menú de navegación, haz clic en la escena Start.
2. Haz clic en el signo + (signo más) en la escena Start junto a Control de intents del usuario.
3. En la sección Intent, selecciona no en el menú desplegable.

4. Haz clic en Send prompts y actualiza el campo speech con el siguiente texto: Good Bye.

El código del editor debería verse como el siguiente fragmento:

candidates:
  - first_simple:
      variants:
        - speech: >-
             Goodbye.

5. En la sección Transition, selecciona End conversation en el menú desplegable.
6. Haz clic en Guardar.

Cómo probar el intent no en el simulador

Ahora, tu acción comprende si el usuario no quiere jugar y muestra una respuesta adecuada.

Para probar este intent en el simulador, sigue estos pasos:

1. En la barra de navegación, haz clic en Test.
2. Escribe Talk to Spelling Practice en el campo Input y presiona Enter.
3. Escribe No en el campo Input y presiona Intro. También puedes hacer clic en el chip No sugerir.

Agrega el intent YES del sistema a la escena Start

Ahora, agregaremos el intent SYSTEM "YES" a la escena Start, ya que el usuario responde afirmativamente a la instrucción Start ("Welcome to Spelling Practice. Usa el alfabeto fonético para deletrear la palabra. Por ejemplo, alfa para a, bravo para b, charlie para c, etcétera. ¿Quieres continuar?").

Para agregar este intent del usuario a la escena Start, sigue estos pasos:

1. En el panel de navegación, haz clic en la escena Start.
2. Haz clic en el signo + (signo más) en la escena Start junto a User intent handling.
3. En Todos los intents del sistema, selecciona SÍ en el menú desplegable de intents.

4. Haz clic en Call your webhook y actualiza el cuadro de texto event handler con la función que creaste antes: getSpellingWordList
5. En la sección Transition, haz clic en el panel desplegable y selecciona End conversation.
6. Haz clic en Guardar.

Cómo probar el intent YES en el simulador

En este punto, tu acción comprende si el usuario quiere jugar y muestra una respuesta adecuada.

Para probar este intent en el simulador, sigue estos pasos:

1. En la barra de navegación, haz clic en Test.
2. Para probar la acción en el simulador, escribe Talk to Spelling Practice en el campo Input y presiona Intro.
3. Escribe Yes en el campo Input y presiona Intro. También puedes hacer clic en el chip de sugerencias Yes.

Tu acción recupera una lista de todas las palabras de práctica de ortografía y las almacena en la sesión. Luego, la acción finaliza la sesión porque seleccionaste la transición End conversation para el intent YES.

Crea el intent Phonetics

Para crear el intent Phonetics, sigue estos pasos:

1. En el menú de navegación, haz clic en Develop.
2. Haz clic en Intents personalizados, en el panel de navegación, para abrir la lista de intents.
3. Haz clic en el signo + (signo más) al final de la lista de intents. Asígnale el nombre phonetics al intent nuevo y presiona Enter.
4. Haz clic en el intent phonetics para abrir la página del intent phonetics.
5. En la sección Agregar frases de entrenamiento, haz clic en el cuadro de texto Ingresar frase y, luego, ingresa las siguientes frases:

• how do I spell words
• phonetics
• help me with phonetics
• phonetic alphabet

6. Haz clic en Guardar.

Agrega el intent phonetics a la escena Start

Ahora, la acción puede comprender cuándo un usuario expresa un intent de "phonetics". Puedes agregar el intent de usuario phonetics a la escena Start, ya que el usuario responde al mensaje Start ("Welcome to Spelling Practice. Usa el alfabeto fonético para deletrear la palabra. Por ejemplo, alfa para a, bravo para b, charlie para c, etcétera. ¿Quieres continuar?").

Para agregar este intent del usuario a la escena Start, sigue estos pasos:

1. En el menú de navegación, haz clic en la escena Start.
2. Haz clic en el signo + (más) en la escena Start junto a Control de intents del usuario.
3. Selecciona phonetics en el menú desplegable del intent.

4. En la sección Transition, haz clic en el panel desplegable y selecciona End conversation.
5. Haz clic en Guardar.

Transición de la escena de inicio a la escena de ortografía

En esta sección, crearás una escena nueva llamada Ortografía, que le enviará un mensaje al usuario para que deletree la palabra con el alfabeto fonético.

Para crear esta escena y agregarle una transición, sigue estos pasos:

1. En el menú de navegación superior, haz clic en Develop. Luego, haz clic en la escena Start en el panel de navegación izquierdo.
2. En la sección Manejo de intents de usuario, haz clic en when actions.intent.YES is matched y, a la derecha, en la sección de transición, haz clic en el menú desplegable y escribe Spelling en el campo de texto.
3. Haz clic en Agregar. Esto crea una escena llamada Spelling y le indica a la acción que realice la transición a la escena Spelling después de la coincidencia con el intent YES.
4. Expande Scenes en el panel de navegación izquierdo para mostrar la lista de escenas.
5. En Scenes, haz clic en Spelling para ver la escena Spelling.
6. Haz clic en + en la sección On enter de la escena Spelling.
7. Haz clic en Llamar a tu webhook y, luego, ingresa getSpellingWord en el cuadro de texto del controlador de eventos.
8. Selecciona Send prompts.
9. Reemplaza la oración del campo speech (Enter the response that users will see or hear...) por {}. El webhook propagará la instrucción real.

Estos chips ofrecen sugerencias en las que el usuario puede hacer clic y que tu acción procesa como entradas del usuario.

Para agregar chips de sugerencias al mensaje de la escena Spelling, sigue estos pasos:

10. En la escena Spelling, haz clic en las sugerencias debajo del editor de código. Esta acción agrega tres chips de sugerencias.
11. En el campo title, reemplaza Suggested Response por 'Repeat'.
12. Usa el mismo formato para agregar manualmente un chip de sugerencias llamado 'Skip'.
13. Usa el mismo formato para agregar de forma manual un chip de sugerencias titulado 'Quit'. El código debería verse como el siguiente fragmento:
14. Haz clic en Guardar.

suggestions:
      - title: 'Repeat'
      - title: 'Skip'
      - title: 'Quit'

Crea el intent Repeat

Para crear el intent repeat, sigue estos pasos:

1. En el menú de navegación, haz clic en Develop.
2. Haz clic en Intents personalizados, en el panel de navegación, para abrir la lista de intents.
3. Haz clic en el signo + (signo más) al final de la lista de intents. Asígnale el nombre repeat al intent nuevo y presiona Enter.
4. Haz clic en el intent repeat para abrir la página de intents definition.
5. En la sección Add training phrases, haz clic en el cuadro de texto Enter Phrase y, luego, ingresa las siguientes frases:

• one more time please
• say the word again
• repeat the word
• tell me again
• repeat

6. Haz clic en Guardar.

Agrega el intent repeat a la escena Spelling

Ahora, la acción puede comprender cuándo un usuario expresa un intent de repetición. Puedes agregar el intent de usuario repeat a la escena Spelling, dado que el usuario responde a la instrucción Spelling ("Spell the word using phonetic alphabet").

Para agregar este intent del usuario a la escena Spelling, sigue estos pasos:

1. En el panel de navegación, haz clic en la escena Spelling.
2. Haz clic en el signo + (signo más) en la escena Spelling junto a User intent handling.
3. Selecciona repetir en el menú desplegable de intents.

4. Marca la opción Call your webhook y, luego, ingresa repeatSpellingWord en el cuadro de texto del controlador de eventos para obtener la definición de la palabra.
5. Marca la opción Send prompts.
6. Reemplaza la oración en el campo speech (Enter the response that users will see or hear...) por ‘'. El webhook propagará el mensaje real.

Agrega chips de sugerencias a "Cuando se detecta una coincidencia con la repetición"

7. En "Cuando se detecta una coincidencia con la repetición", En Administración de intents del usuario, haz clic en sugerencias debajo del editor de código. Esta acción agrega tres chips de sugerencias.
8. En el campo title, reemplaza Suggested Response por 'Skip'.
9. Usa el mismo formato para agregar manualmente un chip de sugerencias titulado 'Quit'.El código debería verse como el siguiente fragmento:

suggestions:
      - title: 'Skip'
      - title: 'Quit'

10. Haz clic en Guardar.

Crea el intent definition

Para crear el intent definition, sigue estos pasos:

1. En el menú de navegación, haz clic en Develop.
2. Haz clic en Intents personalizados, en el panel de navegación, para abrir la lista de intents.
3. Haz clic en el signo + (signo más) al final de la lista de intents. Asígnale el nombre definition al intent nuevo y presiona Enter.
4. Haz clic en el intent definition para abrir la página de intents definition.
5. En la sección Agregar frases de entrenamiento, haz clic en el cuadro de texto Ingresar frase y, luego, ingresa las siguientes frases:

• I would like to know the definition
• tell me the definition
• what does it mean
• meaning
• definition
• what is the definition?

6. Haz clic en Guardar.

Agrega el intent definition a la escena Spelling

Ahora, la acción puede comprender cuándo un usuario expresa un intent de definición. Puedes agregar el intent del usuario definition a la escena Spelling, ya que el usuario responde al mensaje Spelling ("Deletrea la palabra con alfabeto fonético").

Para agregar este intent del usuario a la escena Spelling, sigue estos pasos:

1. En el panel de navegación, haz clic en la escena Spelling.
2. Haz clic en el signo + (signo más) en la escena Spelling junto a User intent handling.
3. Selecciona definition en el menú desplegable del intent.

4. Marca la opción Call your webhook y, luego, ingresa definitionOfSpellingWord en el cuadro de texto del controlador de eventos para obtener la definición de la palabra.
5. Marca la opción Send prompts.
6. Reemplaza la oración en el campo speech (Enter the response that users will see or hear...) por “‘”. El webhook propagará el mensaje real.

Agrega chips de sugerencias a la respuesta del webhook

7. En la escena Start, haz clic en sugerencias debajo del editor de código. Esta acción agrega tres chips de sugerencias.
8. En el campo title, reemplaza Suggested Response por 'Skip'.
9. Con el mismo formato, agrega de forma manual un chip de sugerencias titulado 'Quit'. Tu código debería verse como el siguiente fragmento:

suggestions:
      - title: 'Skip'
      - title: 'Quit'

10. Haz clic en Guardar.

Crea el intent skip

Para crear el intent skip, sigue estos pasos:

1. En el menú de navegación, haz clic en Develop.
2. Haz clic en Intents, en el panel de navegación, para abrir la lista de intents.
3. Haz clic en el signo + (signo más) al final de la lista de intents. Asigna el nombre skip al intent nuevo y presiona Enter.
4. Haz clic en el intent skip para abrir la página de intents skip.
5. En la sección Add training phrases, haz clic en el cuadro de texto Enter Phrase y, luego, ingresa las siguientes frases:

• next word
• go next
• next
• skip
• skip word

6. Haz clic en Guardar.

Agrega el intent Skip a la escena Spelling

Ahora, la acción puede comprender cuándo un usuario expresa un intent de "omitir". Puedes agregar el intent de usuario skip a la escena Spelling, dado que el usuario responde a la instrucción Spelling ("Spell the word using phonetic alphabet").

Para agregar este intent del usuario a la escena Spelling, sigue estos pasos:

1. En el panel de navegación, haz clic en la escena Spelling.
2. Haz clic en el signo + (signo más) en la escena Spelling junto a Control de intents del usuario.
3. Selecciona skip en el menú desplegable del intent.

4. En la sección Transition, a la derecha, haz clic en el menú desplegable y selecciona Spelling.

5. Haz clic en Guardar.

Crea el intent quit

Para crear el intent Quit, sigue estos pasos:

1. En el menú de navegación, haz clic en Develop.
2. Haz clic en Intents, en el panel de navegación, para abrir la lista de intents.
3. Haz clic en el signo + (signo más) al final de la lista de intents. Asígnale el nombre Quit al intent nuevo y presiona Enter.
4. Haz clic en el intent Quit para abrir la página del intent de definición.
5. En la sección Add training phrases, haz clic en el cuadro de texto Enter Phrase y, luego, ingresa las siguientes frases:

• I quit
• Goodbye
• Cancel
• Exit
• Quit

6. Haz clic en Guardar.

Agrega el intent Quit a la escena Spelling

Ahora, la acción puede comprender cuándo un usuario expresa un intent de salida. Puedes agregar el intent de usuario quit a la escena Spelling, dado que el usuario responde a la instrucción Spelling ("Spell the word using phonetic alphabet").

Para agregar este intent del usuario a la escena Spelling, sigue estos pasos:

1. En el panel de navegación, haz clic en la escena Spelling.
2. Haz clic en el signo + (signo más) en la escena Spelling junto a User intent handling.
3. Selecciona quit en el menú desplegable del intent.

4. En la sección Transition, a la derecha, haz clic en el menú desplegable y selecciona End conversation .
5. Haz clic en Guardar.

Crea el tipo phonetic_alphabet

En esta sección, crearás un nuevo tipo llamado phonetic_alphabet, que especifica las opciones de alfabeto fonético que los usuarios pueden elegir para deletrear la palabra. También puedes definir algunos sinónimos para estas opciones, en caso de que un usuario diga algo similar. En una sección posterior, agregarás el tipo phonetic_alphabet a un espacio para especificar que deseas obtener la respuesta del usuario.

Para crear el tipo phonetic_alphabet, sigue estos pasos:

1. En el menú de navegación, haz clic en Develop.
2. Haz clic en el signo + (signo más) en Tipos.
3. Escribe phonetic_alphabet y presiona Enter.
4. Haz clic en phonetic_alphabet para abrir las opciones.
5. En la sección ¿Qué tipo de valores admitirá este tipo?, selecciona la opción Palabras y sinónimos.
6. Ingresa las siguientes entradas y los valores correspondientes en la sección Add entries:

Tu tabla de pares clave-valor debería verse de la siguiente manera:

8. Haz clic en Guardar.

Configura el llenado de ranuras

A continuación, debes configurar el relleno de espacios en la escena Spelling. Para configurar la lógica de relleno de espacios, haz lo siguiente:

1. Haz clic en la escena Ortografía en el menú de navegación.
2. Haz clic en el signo + (signo más) en la escena Spelling para Slot filling.
3. En el campo Ingresa el nombre del espacio, agrega userresponse como nombre del espacio.
4. En el menú desplegable Seleccionar tipo, selecciona phonetic_alphabet como tipo de ranura.
5. Marca Este horario disponible admite una lista de valores.
6. Marca Este espacio es obligatorio.
7. Selecciona la opción Personalizar la reescritura del valor de ranura y, luego, ingresa la respuesta del usuario en el cuadro de texto del parámetro de sesión.

8. Haz clic en Guardar.

Agregar condición a la pantalla Spelling

Para agregar Condition a la escena Spelling, sigue estos pasos:

1. En el panel de navegación, haz clic en la escena Spelling.
2. Haz clic en el signo + (signo más) en la escena Spelling junto a Condition.
3. Ingresa scene.slots.status == "FINAL" como condición.
4. Marca la opción Call your webhook y, luego, ingresa verifySpellingWord en el cuadro de texto del controlador de eventos para verificar la respuesta del usuario.
5. Marca la opción Send prompts.
6. Reemplaza la oración en el campo speech (Enter the response that users will see or hear...) por {}. El webhook propagará el mensaje real.

Agrega chips de sugerencias a la respuesta del webhook

7. En la escena Start, haz clic en sugerencias debajo del editor de código. Esta acción agrega tres chips de sugerencias.
8. En el campo title, reemplaza Suggested Response por 'Next'.
9. Usa el mismo formato para agregar manualmente un chip de sugerencias titulado 'Quit'.El código debería verse como el siguiente fragmento:

suggestions:
      - title: 'Next'
      - title: 'Quit'

10. Haz clic en Guardar.

12. Cómo probar la práctica de ortografía en el simulador

Para probar la acción en el simulador, sigue estos pasos:

1. En la barra de navegación, haz clic en Test para ir al simulador.
2. Para probar la acción en el simulador, escribe Talk to Spelling Practice en el campo de entrada.
3. Presiona Intro. Tu acción debería responder con el mensaje Main invocation y el mensaje agregado con la escena Start: "Welcome to Spelling Practice. Usa el alfabeto fonético para deletrear la palabra. Por ejemplo, alfa para a, bravo para b, charlie para c, etcétera. ¿Quieres continuar?".
4. Di Sí para continuar.
5. El simulador reproducirá sonidos de palabras para deletrear
6. Puedes deletrear la palabra con alfabetos fonéticos. Por ejemplo, en mejor, di o escribe "bravo echo tango tango echo echo romeo".
7. El simulador responderá con la respuesta correcta o incorrecta.
8. Di next para continuar con la siguiente palabra o quit para salir del bucle de juego.

13. Felicitaciones

Felicitaciones, compilaste correctamente tu juego, Spelling Practice.

Ahora conoces los pasos clave necesarios para compilar un juego con Cloud Firestore, Cloud Functions y Action Builder de Asistente de Google.

Temas abordados

• Cómo interactuar con Cloud Firestore
• Cómo usar ranuras para recopilar datos del usuario
• Cómo procesar la entrada de un usuario y devolver una respuesta
• Cómo usar condiciones para agregar lógica a una escena
• Cómo agregar un bucle de juego

Recursos de aprendizaje adicionales

Puedes explorar estos recursos y obtener información para crear Acciones para Asistente de Google:

• Documentación sobre el desarrollo de acciones para Asistente de Google
• Página de GitHub de Actions on Google con código de muestra y bibliotecas
• La comunidad de Reddit oficial para desarrolladores que trabajan con Asistente de Google
• Lineamientos sobre el diseño de conversaciones para conocer las prácticas recomendadas y los lineamientos relacionados con las Acciones de conversación
• Introducción a Cloud Firestore

Limpia tu proyecto [recomendado]

Para 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:

1. Para borrar el proyecto y los recursos de Firebase, completa los pasos que se indican en la sección Cómo apagar (borrar) proyectos.

Precaución: Asegúrate de seleccionar el proyecto correcto para borrarlo en la página Configuración de la consola de Google Cloud.

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

Sigue a @ActionsOnGoogle y @Firebase en Twitter para mantenerte al tanto de nuestros anuncios más recientes y utiliza el hashtag #GoogleIO para compartir tus compilaciones.