Tutorial parte 2: Desarrolla aplicaciones de voz multiplataforma con VOXA

Cómo utilizar el VOXA-CLI para descargar intents, utterances y respuestas de una hoja de Excel de Google a tu aplicación.

Foto de Jacek Dylag en Unsplash

En el artículo anterior, expliqué brevemente lo que puedes hacer con VOXA, la herramienta voxa-cli, y la aplicación de voz que vamos a crear al final de esta serie.

En este artículo, vamos a crear la Alexa Skill y Google Action en tus cuentas. Vamos a crear las hojas de Excel que gobernarán la parte de la VUI (Voice User Interface por sus siglas en inglés) de la aplicación.

Esto es muy útil cuando estás trabajando en un equipo y otros pueden colaborar para mejorar tu VUI. Así que, !empecemos!

Puedes usar las hojas de Excel de Google para manejar la VUI (Voice User Interface por sus siglas en inglés) de tu aplicación de voz. Imagen vía www.pixabay.com

Primero que todo, necesitamos crear un proyecto usando voxa-cli. puedes encontrar el paquete npm aquí. Abre la terminal en tu ordenador y escribe:

npm i -g voxa-cli

Este comando instalará la ultima versión del voxa-cli localmente. Cuando el comando termine, puedes escribir:

voxa create

Este comando te guiará paso a paso para configurar tu proyecto con algunas opciones:

Asistente paso a paso para crear tu proyecto VOXA

Te preguntará el nombre de tu aplicación, el nombre del desarrollador, las plataformas, y el lenguaje de programación a usar (JavaScript o TypeScript). Alguna de las preguntas iniciales están relacionadas a las hojas de Excel de Google: modelo de interacción, información de publicación, y la característicacanFulfill.

También vamos a integrar nuestra aplicación con DynamoDB y las analytics de Dashbot. Así que asegúrate de responder Yes a esas preguntas.

Ahora que nuestro código base está creado, !revisémoslo! Puedes escribir en tu terminal:

cd quick-maths; code .

Esto accederá al folder principal de tu proyecto y lo abrirá usando Visual Studio Code.

Estructura básica de un proyecto VOXA creado con el voxa-cli

Ejecuta npm install o yarn install para crear el folder de losnode_modules. En nuestro caso, usaremos yarn.

El folder src/app es donde usualmente agregamos la lógica de la aplicación. Vamos a trabajar en este folder en el siguiente artículo.

El archivo src/app/index.js es el punto de entrada de la aplicación. Como explicamos en la parte 1, VOXA es un framework MVC, así que consideramos estas partes claves en los siguientes archivos:

• Modelo: El archivo src/app/model.js. En cada petición a tu proyecto, tendrás acceso a la variable model donde puedes llamar todas las funciones y acceder a las variables del modelo.
• Vistas: El archivo src/app/views.json. Si usas el voxa-cli, esta ruta cambiará a src/languageResources, donde la herramienta descargará las VIEWS del modelo de interacción de la hoja de Excel de Google incluyendo todas las locales. Si defines variables para contenido dinámico, puedes definirlas en el archivo src/app/variables.js. Los valores de estas variables serán obtenidos del modelo (archivo model.js)
• Controladores: El folder src/app/states. Puedes definir todos los intent y mandejadores de estados con la funciones voxaApp.onIntent y voxaApp.onState.

Estructura básica de un archivo de estado en VOXA

Puedes encontrar mis avances de cada artículo en este repositorio en diferentes ramas: part2, part3, part4, y part5:

El folder src/config es donde tu defines los diferentes ambientes de tu aplicación.

Voxa-cli agrega 2 archivos de ambiente: production y staging. Puedes definir el ambiente con el que quieras trabajar al modificar la variable NODE_ENV a staging, production, o el ambiente que quieras.

Voxa-cli también te permite descargar los intents, utterances, y views de la hoja de Excel de Google.

También hay otra hoja donde puedes definir la info de metadata para tu Alexa Skill: nombre de la skill, permisos, interfaces, descripciones, imágenes (URL) palabras clave, etc.

Para esta aplicación, ya he preparado estas 2 hojas de Excel de Google que están públicas y que puedes copiarlas a tu Google Drive.

Sigue aquí para acceder a la hoja de Excel de Google de la información de publicación.

Hoja de Información de Publicación de Quick Maths

En la hoja de información de publicación encontrarás 3 pestañas importantes:

• SKILL_GENERAL_INFORMATION: Define la información de metadata general para tu Alexa Skill.
• SKILL_ENVIRONMENTS_INFORMATION: Define endpoints para Alexa y Dialogflow.
• SKILL_LOCALE_INFORMATION@en-US: Define información específica de la locales como imágenes, descripciones, palabras clave, o frases de ejemplo. También puedes crear otras pestañas para otras locales, solo necesitas modificar el sufijo de la local, como: @en-GB, @de-DE, @es-ES, or @it-IT.

Accede a la hoja de Excel de Google para el modelo de interacción.

Hoja del modelo de interacción de Quick Maths

En la hoja del modelo de interacción encontrarás 4 pestañas importantes:

• INTENT: Define todos los intents con sus slots y tipos. También hay una columna que define los eventos de Dialogflow, comoGOOGLE_ASSISTANT_WELCOME o actions_intent_CANCEL. También puedes agregar intents específicos a una plataforma u otra, definir si un intent será unstartIntent (Dialogflow) o puede ser usado por la interfazCanFulfillIntent de Alexa automáticamente.
• UTTERANCES_MAIN: Define todas las utterances para cada intent que definiste en la pestaña INTENT.
• VIEWS_FILE@en: Define todas las respuestas de tu aplicación de voz. Puedes definir otras locales, como en la pestañaSKILL_LOCALE_INFORMATION de la hoja de información de publicación: @de, @it, @es, @ru-RU, etc.
• INVOCATION_NAMES: Define los nombres de invocación para cada ambiente que tengas. En nuestro caso, hemos definido quick maths para el ambiente de producción, y quick maths staging para staging.

Ahora, necesitamos modificar el archivo interaction.json con las URLs de las hojas de Excel de Google. Mira este gist para ver como debe lucir tu archivo:

Estructura básica del archivo interaction.json

Para descargar estos recursos, necesitamos una llave de Google Cloud. Puedes revisar el repositorio GitHub de voxa-cli y seguir las instrucciones para crear el proyecto de Google Cloud.

Cuando descargues el archivo llave, copialo en el folder principal de tu proyecto de voz, y nómbralo client_secret.json. Ahora, puedes ejecutar:

yarn interaction

Esto descargará tus utterances y respuestas. Verás 3 nuevos folders:

• /src/content: Otro contenido descargado con voxa-cli. Por ejemplo, los archivos {environment}-canfulfill-intents.json.
• /src/languageResources: Vistas descargadas de las hojas de Excel.
• /speech-assets: Modelo de interacción para Alexa y Dialogflow.

Puedes mirar nuevamente el progreso del proyecto hasta ahora en esta rama en el repositorio que estoy usando para subir mis cambios a medida que seguimos las instrucciones paso a paso.

Ahora, es tiempo de crear la Skill y Action en tus cuentas. Ve a la Consola de Desarrollador de Amazon y crea una Skill llamada Quick Maths. Y, en la Consola de Actions, crea la Action Quick Maths.

Para Alexa, ve a la pestaña Build, y en el menú JSON Editorcopia el contenido del archivo /speech-assets/alexa/en-US/{environment}-interaction.json, dependiendo del ambiente que te gustaría configurar primero.

Si has configurado el ASK CLI, puedes ejecutar este comando:

ask api update-model -s {SKILL_ID} -f speech-assets/alexa/en-US/production-interaction.json -l en-US

Para actualizar la metadata de la Skill, puedes ejecutar:

ask api update-skill -s {SKILL_ID} -f speech-assets/alexa/production-manifest.json

Para Dialogflow, ve al menú de Actions, haz click en el botón BUILD, y ve a la consola de Dialogflow.

Puedes guardar el contenido del folder /speech-assets/dialogflow/{environment}/ en un archivo zip y subirlo a Dialogflow. Haz click en el botón de configuraciones ⚙️ y haz click en la pestaña Export and Import.

Haz click en el botón RESTORE FROM ZIP y arrastra el archivo zip de tu proyecto. Finalmente, ve al menú Integrations, haz click en el botón de Google Assistant y luego haz click en el botón TEST.

Account Linking de Alexa

Empecemos con Alexa. Ve al portal de desarrollador, en la parte superior derecha de la página hay un botón con las iniciales del nombre de tu cuenta, haz click en él y luego click en Settings.

En este post del blog de Alexa, verás detallado paso a paso las instrucciones de cómo crear tu configuración con LoginWithAmazonpara tu account linking.

Paso a paso para crear la configuración de LoginWithAmazon

Ahora, ve a las configuraciones de tu skill en la consola de desarrollador. En el menú ACCOUNT LINKING, habilita Account Linking y pega los siguientes valores:

Authorization URI: https://www.amazon.com/ap/oa
Access Token URI: https://api.amazon.com/auth/o2/token
ClientID: de LoginWithAmazon
ClientSecret: de LoginWithAmazon
Client Authentication Scheme: HTTP Basic
Scopes: profile, postal_code
Domain list: amazon.com, na.account.amazon.com

Sign In de Google

Ve a la configuración de tu Action en la consola de Actions console. Bajo el menú de Account linking, sigue estos pasos:

• Account creation: Selecciona Yes, permite a los usuarios registrarse para una nueva cuenta con su voz.
• Linking type: Google Sign In.

Haz click en Save.

Paso a paso para configurar Google Sign In

Final

Con estos 2 pasos completados, hemos terminado la integración de account linking para nuestras aplicaciones de voz. En el siguiente artículo, crearemos la lógica para el juego y la competencia.

¡Gracias por leer! Asegúrate de leer los demás artículos de la serie.

Recuerda: ¡No tires basura al océano!