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 para extender 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 el Asistente durante una conversación para completar tareas, como comprar alimentos o reservar un viaje. Como desarrollador, puedes usar la plataforma para desarrolladores de Asistente a fin de crear y administrar fácilmente experiencias de conversación interesantes y eficaces entre los usuarios y tu propio servicio externo.

Este codelab abarca 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 utiliza Asistente de Google para pedirles a los usuarios que deletreen 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.
• Crear un bucle de juego para que un usuario pueda volver a interactuar con Asistente después de deletrear la palabra

Antes de que comiences a compilar, puedes decir "Hey Google, habla con las prácticas de ortografía" para interactuar con la acción en vivo en tu dispositivo compatible con el Asistente de Google. La ruta predeterminada a través de esta acción para un usuario recurrente se parece a 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 mostrar una respuesta
• Cómo usar condiciones para agregar lógica a una escena
• Cómo agregar un bucle de juego

Requisitos

Los requisitos previos para este codelab incluyen los siguientes:

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

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, asígnale el nombre Spelling-Practice.

3. Haz clic para avanzar por las opciones de creación del proyecto. Acepta las condiciones de Firebase si se te solicita. Omite la configuración de Google Analytics, ya que no utilizarás este servicio para esta aplicación.

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

Actualiza al plan de precios Blaze

Si quieres usar Cloud Functions para Firebase, deberás actualizar tu proyecto de Firebase al plan de precios Blaze. Esto significa que adjuntará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, aún tienen acceso a las cuotas de uso sin costo de Cloud Functions. Los pasos que se describen en este codelab estarán dentro de los límites de uso sin costo. Sin embargo, verás pequeños cargos ( aproximadamente $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 la 9.0.0 o posterior, de modo que tenga todas las funciones más recientes necesarias para Cloud Functions. De lo contrario, ejecuta npm install -g firebase-tools para actualizar como se muestra arriba.

4. Ejecuta el siguiente comando para autorizar Firebase CLI:

$ firebase login

5. En el directorio ortografía-functions-start, configura Firebase CLI para usar el proyecto de Firebase. Ejecuta el siguiente comando, selecciona el ID del proyecto y, luego, 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: Práctica de ortografía.

Cloud Functions te permite tener código que se ejecuta en la nube sin tener que configurar un servidor. En este codelab, te mostraremos cómo compilar funciones que reaccionen a eventos de Firebase Authentication, Cloud Storage y Firebase Realtime Database. Comencemos con Authentication.

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

$ cd functions
$ ls

El código de las 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 enumere las dependencias.

Si no estás familiarizado con Node.js, obtén más información al respecto antes de continuar con el codelab.

El archivo package.json ya enumera dos dependencias obligatorias: 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, analicemos 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ás los módulos requeridos y, luego, escribirás cuatro funciones en lugar de los TODO. 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 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 de Node.js del SDK de Actions completa los controladores del SDK de Actions para el Asistente de Google.

1. Instala el SDK de Actions ejecutando el siguiente comando npm:

$ npm install @assistant/conversation

2. En el archivo index.js, reemplaza el primer TODO con 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 siguientes cambios.

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 de Asistente.

7. Crear funciones

Obtén las definiciones de 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 comentario 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 active 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 arriba.

En el archivo index.js, reemplaza el comentario TODO para createSpellingPracticeWord con 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 de práctica de ortografía de Cloud Firestore para 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 al elemento app.handle especial es una forma de permitir el acceso a la función 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;
    });
  });
})

Escucha 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 comentario TODO para getSpellingWord con 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');
});

Permite que el juego repita la palabra

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

En el archivo index.js, reemplaza el comentario TODO para repeatSpellingWord con 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 comentario TODO para definitionOfSpellingWord con 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);
});

Cómo verificar la respuesta ortográfica del usuario

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

En el archivo index.js, reemplaza el comentario 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 funciones de Cloud Functions solo estarán activas después de que las hayas implementado 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 haz clic en el proyecto spelling-practice. Abre el panel Functions para ver el extremo de Functions.

Acabas de agregar todas las funciones obligatorias. Ahora, veamos cómo configurar Cloud Firestore.

8. Habilite Cloud Firestore

Deberás habilitar Cloud Firestore.

En la sección Compilación 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 accedieron, 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 ortográficas a Cloud Firestore

En este paso, escribirás datos de palabras en Cloud Firestore a fin de generar una lista de palabras para 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. Por cada documento nuevo en la colección de Firestore, se activará la función createSpellingPracticeWord para obtener los detalles de la palabra desde el 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 ID del documento, ingresa agreement.
5. En el cuadro de texto Campo, 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 tu función createSpellingPracticeWord para recuperar los detalles de definición de la palabra. Crea un documento nuevo para cada palabra para agregar más palabras (por ejemplo: asombro, automóvil, verdadero, contar, mejor, viajar, etc.).

10. 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, debes habilitar los permisos necesarios de modo que el simulador pueda acceder a tu acción. Para habilitar los permisos, sigue estos pasos:

1. Ve a la página Controles de actividad.
2. Si aún no lo has hecho, 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. Sigue estos pasos para crear tu proyecto de acciones para este codelab:

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

4. Escribe o selecciona la opción 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 tu 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 build.
10. Escribe Práctica ortográfica como nombre visible y haz clic en Guardar.

Los usuarios inician la conversación con tu Acción a través de una invocación. Por ejemplo, los usuarios pueden invocar tu acción con solo decir una frase como "Hey Google, habla con las prácticas de ortografía", donde 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 es necesario que definas ese nombre. En su lugar, puedes usar la frase "Hablar con mi app de prueba" en el simulador para invocar tu acción.

Configura la 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 del 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 sucede 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 bydefinition main invocation").

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

1. Haz clic en Main invocation, en el panel 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 para que puedas conversar con la acción como si se ejecutara en una pantalla inteligente, teléfono, bocina o KaiOS.

Para probar la invocación principal de tu 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 de la parte superior izquierda y, luego, presiona Intro en el teclado.

Cuando activas la invocación principal de tu Acción, Asistente responde con tu mensaje de bienvenida personalizado. En este punto, la conversación finaliza cuando Asistente responde con un saludo.

Ver registros de eventos

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

Actualmente, tu Acción tiene un registro de eventos que muestra la entrada del usuario ("Habla con las prácticas ortográficas") y la respuesta de tu Acción. En la siguiente captura de pantalla, se muestra el registro de eventos de tu Acción:

11. Crea la 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 tu acción. Las Práctica de ortografía tienen cuatro escenas que debes activar cada una antes de ejecutarla. La forma más común de activar una escena es configurar tu Acción para que, cuando un usuario coincida con un intent del usuario dentro de una escena, ese intent active la transición a otra escena y la active.

Cómo hacer la transición de la invocación principal a la escena inicial

En esta sección, crearás una nueva escena llamada Start, que enviará un mensaje al usuario preguntándole si quiere comenzar a jugar a las Práctica de ortografía. También agregarás una transición de la invocación principal a la nueva escena Start.

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

1. En la barra 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 realice 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 menú de navegación izquierdo, para ver 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...) con una pregunta para hacerle al 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 entrada 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 que usan 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. Con el mismo formato, agrega manualmente un chip de sugerencias llamado '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 Start 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 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. ¿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 al mensaje. (También puedes decir "Sí", "No" o "Ayuda con 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 que indica que no puede entender tu entrada: "Lo siento, no entendí eso. ¿Puedes volver a intentarlo?". Como aún no configuraste tu acción para que comprenda y responda a las entradas "Yes" o "No", la acción asocia la entrada a 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 detectar coincidencias con la entrada del usuario tres veces.

Cómo agregar intents fonéticos y no

Ahora que los usuarios pueden responder a la pregunta que plantea tu Acción, puedes configurarla para que comprenda las respuestas de los usuarios ("Sí", "No" o "Ayuda con fonética"). En las siguientes secciones, crearás intents de usuario que coincidan cuando el usuario diga "Sí", "No" o "Ayuda con fonética" y los agregarás a la escena Start. Usaremos el intent del sistema yes y crearemos otros intents.

Cómo crear un intent no

Ahora, debes crear el intent no para comprender al usuario y responder cuando 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 Custom Intents (Intents personalizados) en la navegación para abrir la lista de intents.
3. Al final de la lista de intents, haz clic en + (signo más). Asígnale 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 Agregar frases de entrenamiento, haz clic en el cuadro de texto Ingresar frase 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 cuándo un usuario dice "no" o algo similar a "no", como "nope". Debes agregar el intent del usuario no 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. ¿Quieres continuar?").

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

1. Haz clic en la escena Start en el panel de navegación.
2. Haz clic en el signo + (signo más) en la escena Start junto a User intent handling.
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 en tu 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

En este punto, tu Acción entiende cuándo el usuario no quiere jugar y muestra la respuesta correcta.

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

1. En la barra de navegación, haz clic en Probar.
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 Sin sugerencias.

Agrega el intent YES del sistema a la escena Start

Ahora, agregaremos el intent "YES" del SISTEMA a la escena Start, ya que el usuario responde que sí a la instrucción de Start ("Te damos la bienvenida a la práctica de ortografía. 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 de usuario a la escena Start, sigue estos pasos:

1. Haz clic en la escena Start en el panel de navegación.
2. Haz clic en el signo + (signo más) en la escena Start junto a User intent handling.
3. En All System Intents, selecciona YES 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 anteriormente: getSpellingWordList.
5. En la sección Transition, haz clic en el menú 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 entiende cuándo el usuario quiere jugar el juego y muestra la respuesta adecuada.

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

1. En la barra de navegación, haz clic en Probar.
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.

Cómo crear un 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 Custom Intents (Intents personalizados) en la navegación para abrir la lista de intents.
3. Al final de la lista de intents, haz clic en + (signo más). 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 "fonética". Puedes agregar el intent del usuario phonetics a la escena Start, ya que el usuario está respondiendo al mensaje de 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 de usuario a la escena Start, sigue estos pasos:

1. Haz clic en la escena Start en el panel de navegación.
2. Haz clic en el signo + (signo más) de la escena Start junto a User intent handling.
3. Selecciona fonética en el menú desplegable de intents.

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

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

En esta sección, crearás una nueva escena llamada Ortografía, que envía 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 la barra 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 User intent handling, haz clic en when actions.intent.YES is matched y, a la derecha, en la sección transition, 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 una transición a la escena Spelling después de la coincidencia con el intent SÍ.
4. Expande Scenes en la barra de navegación izquierda para ver la lista de escenas.
5. En Scenes, haz clic en Ortografía para ver la escena Spelling.
6. Haz clic en + en la sección On enter de la escena Spelling.
7. Haz clic en Call your webhook y, luego, ingresa getSpellingWord en el cuadro de texto del controlador de eventos.
8. Selecciona Send prompts.
9. Reemplaza la oración en el campo speech (Enter the response that users will see or hear...) por {}. webhook completará la solicitud real.

Los chips de sugerencias ofrecen sugerencias en las que el usuario puede hacer clic y que tu acción procesa como entrada 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. Con el mismo formato, agrega manualmente un chip de sugerencias llamado 'Skip'.
13. Con el mismo formato, agrega manualmente un chip de sugerencias llamado 'Quit'. El código debería verse como el siguiente fragmento:
14. Haz clic en Guardar.

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

Cómo crear un 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 Custom Intents (Intents personalizados) en la navegación para abrir la lista de intents.
3. Al final de la lista de intents, haz clic en + (signo más). Asígnale el nombre repeat al intent nuevo y presiona Enter.
4. Haz clic en el intent repeat para abrir la página del intent 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:

• 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 "repetir". Puedes agregar el intent del usuario repeat a la escena Spelling, ya que el usuario responde al mensaje Spelling ("Deletrea la palabra con el alfabeto fonético").

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

1. En el panel de navegación, haz clic en la escena Ortografía.
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 (Llamar a tu webhook) y, luego, ingresa RepeatSpellingWord en el cuadro de texto del controlador de eventos para obtener la definición de la palabra.
5. Marca 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.

Cómo agregar chips de sugerencias a "Cuando la repetición coincide"

7. En "Cuando se detecta una coincidencia con la repetición", en la sección Control de intents de 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. Con el mismo formato, agrega manualmente un chip de sugerencias llamado 'Quit'.El código debería verse como el siguiente fragmento:

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

10. Haz clic en Save.

Cómo crear un 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 Custom Intents (Intents personalizados) en la navegación para abrir la lista de intents.
3. Al final de la lista de intents, haz clic en + (signo más). Asígnale el nombre definition al intent nuevo y presiona Enter.
4. Haz clic en el intent definition para abrir la página del intent 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 el alfabeto fonético").

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

1. En el panel de navegación, haz clic en la escena Ortografía.
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 de intents.

4. Marca la opción Call your webhook y, luego, ingresa definitionOfMappingWord en el cuadro de texto del controlador de eventos para obtener la definición de la palabra.
5. Marca 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.

Cómo agregar chips de sugerencias a la respuesta de 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 manualmente un chip de sugerencias llamado 'Quit'.El código debería verse como el siguiente fragmento:

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

10. Haz clic en Guardar.

Cómo crear un intent skip

Para crear el intent skip, sigue estos pasos:

1. En el menú de navegación, haz clic en Develop.
2. En la navegación, haz clic en Intents para abrir la lista de intents.
3. Al final de la lista de intents, haz clic en + (signo más). Asígnale el nombre skip al intent nuevo y presiona Enter.
4. Haz clic en el intent skip para abrir la página del intent skip.
5. En la sección Agregar frases de entrenamiento, haz clic en el cuadro de texto Ingresar frase 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 "skip". Puedes agregar el intent del usuario skip a la escena Spelling, ya que el usuario responde al mensaje Spelling ("Deletrea la palabra con el alfabeto fonético").

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

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

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

5. Haz clic en Guardar.

Cómo crear un intent quit

Para crear el intent Quit, sigue estos pasos:

1. En el menú de navegación, haz clic en Develop.
2. En la navegación, haz clic en Intents para abrir la lista de intents.
3. Al final de la lista de intents, haz clic en + (signo más). Asígnale el nombre Quit al intent nuevo y presiona Enter.
4. Haz clic en el intent Quit para abrir la página de intents de definición.
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 quit
• Goodbye
• Cancel
• Exit
• Quit

6. Haz clic en Save.

Agrega el intent Quit a la escena Spelling

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

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

1. En el panel de navegación, haz clic en la escena Ortografía.
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 de intents.

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 del 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 Agregar entradas:

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

8. Haz clic en Guardar.

Configura el relleno de ranuras

A continuación, debes configurar el relleno de espacios en la escena de ortografía. Para configurar la lógica de relleno de ranuras, sigue estos pasos:

1. En el panel de navegación, haz clic en la escena Ortografía.
2. Haz clic en el signo + (signo más) en la escena Spelling correspondiente al Relleno de ranuras.
3. En el campo Enter ranura name, agrega userresponse como nombre del espacio.
4. En el menú desplegable Select type, selecciona phonetic_alphabet como el tipo de ranura.
5. Marca Esta ranura acepta una lista de valores.
6. Marca Este espacio es obligatorio.
7. Selecciona la opción Customize ranura value writeback y, luego, ingresa userresponse 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 Ortografía.
2. Haz clic en el signo + (signo más) en la escena Spelling junto a Condition.
3. Ingresar scene.slots.status == "FINAL" como condición
4. Marca la casilla Call your webhook y, luego, ingresa verifySpellingWord en el cuadro de texto del controlador de eventos para verificar la respuesta del usuario.
5. Marca Send prompts.
6. Reemplaza la oración en el campo speech (Enter the response that users will see or hear...) por {}. El webhook completará el mensaje real.

Cómo agregar chips de sugerencias a la respuesta de 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. Con el mismo formato, agrega manualmente un chip de sugerencias llamado 'Quit'.El código debería verse como el siguiente fragmento:

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

10. Haz clic en Guardar.

12. Prueba las prácticas ortográficas en el simulador

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 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. ¿Quieres continuar?”.
4. Di Sí para continuar
5. El simulador reproducirá un sonido para deletrear
6. Puedes deletrear la palabra usando alfabetos fonéticos. Por ejemplo, para mejor, di o escribe "bravo echo tango tango tango echo romeo".
7. El simulador responderá con la respuesta correcta o incorrecta.
8. Di siguiente para continuar con la siguiente palabra o di salir para salir del bucle de juego.

13. ¡Felicitaciones!

Felicitaciones, compilaste correctamente tu juego, Práctica de ortografía.

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

Temas que se abordaron

• Cómo interactuar con Cloud Firestore
• Cómo usar ranuras para recopilar datos del usuario
• Cómo procesar la entrada de un usuario y mostrar 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 aprender a 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 de 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 que quites los proyectos que no quieras usar. Para borrar los proyectos que creaste en este codelab, sigue estos pasos:

1. Para borrar tu proyecto y los recursos de Firebase, completa los pasos que se indican en la sección Cómo cerrar (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, tu proyecto se quitará automáticamente después de aproximadamente 30 días.

Sigue a @ActionsOnGoogle y @Firebase en Twitter para mantenerte al tanto de nuestros anuncios más recientes y envía un tweet a #GoogleIO para compartir tus compilaciones.