Cómo crear acciones para Asistente de Google con Actions Builder (nivel 1)

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 mucho 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 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 principiante para desarrollar con Asistente de Google, por lo que no necesitas experiencia previa usando la plataforma a fin de completarlo. En él, compilarás una acción simple para Asistente de Google que les leerá su fortuna a los usuarios cuando embarcan en la aventura de la tierra mítica de Gryffinberg. En el codelab de Actions Builder (nivel 2), seguirás compilando la acción para personalizar la fortuna del usuario según las entradas.

Qué compilarás

En este codelab, compilarás una acción simple con las siguientes funciones:

  • Responder al usuario con un saludo
  • Hacer una pregunta al usuario y responder como corresponda a la selección que haga para contestar la pregunta
  • Proporcionar sugerencias al usuario en las que pueda hacer clic para proporcionar una entrada
  • Modificar el saludo al usuario según si se trata de un usuario recurrente

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

1c1e79902bed7230.png

18ef55647b4cb52c.png

Qué aprenderás

  • Cómo crear un proyecto en la Consola de Actions
  • Cómo enviar un mensaje al usuario después de que invoca tu acción
  • Cómo procesar las entradas del usuario y mostrar respuestas
  • Cómo probar tu acción en el simulador de acciones
  • Cómo implementar la entrega con el editor de Cloud Functions

Requisitos

Tu entorno debe incluir la siguiente herramienta:

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

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

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

  1. Ve a la página Controles de actividad.
  2. Si aún no lo hiciste, accede a tu Cuenta de Google.
  3. Habilita estos 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

Cómo crear un proyecto de Acciones

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

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

8cd05a84c1c0a32f.png

  1. Haz clic en Create project.
  2. En la pantalla What kind of Action do you want to build?, selecciona la tarjeta Custom.
  3. Haz clic en Next.
  4. Selecciona la tarjeta Blank project.
  5. Haz clic en Start building.

Cómo asociar una cuenta de facturación

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

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

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

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

Los usuarios inician la conversación con tu acción mediante una invocación. Por ejemplo, si tienes una acción llamada HoraDePelícula, los usuarios la pueden invocar con una frase como "Hey Google, habla con HoraDePelícula", en la que HoraDePelícula es elnombre visible. Tu acción debe incluir un nombre visible si quieres implementarla en producción. Sin embargo, para probar la acción, no es necesario que definas ese nombre. En su lugar, puedes usar la frase "Habla con la app de prueba" en el simulador para invocar la acción.

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

Según la configuración predeterminada, Actions Builder proporciona un mensaje genérico cuando se activa tu invocación: "Start building your Action by defining main invocation" (Comienza a compilar tu acción mediante la definición de una invocación principal).

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

Cómo configurar la invocación principal

Para modificar el mensaje que muestra tu acción al usuario cuando este la invoca, sigue estos pasos:

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

966d037e1d7914df.png

  1. En el editor de código, reemplaza el texto del campo speech (Start building your action...) por el siguiente mensaje de bienvenida: A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.
  1. Haz clic en Save.

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 estuviera ejecutando en una pantalla inteligente, un teléfono, una bocina o KaiOS.

Cuando invocas tu acción, debería responder con el mensaje personalizado que agregaste ("A wondrous greeting, adventurer!…").

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. A fin de invocar la acción en el simulador, escribe Talk to my test app en el campo Input ubicado en la parte superior izquierda y presiona Intro.

656f5736af6a5a07.png

Cuando activas la invocación principal de la acción, Asistente responde con tu mensaje de bienvenida personalizado. En este punto, la conversación termina cuando Asistente responde con un saludo. En la siguiente sección, modificarás la acción para que la conversación continúe.

Cómo 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 se ejecutan durante ese turno de la conversación.

Actualmente, tu acción tiene un registro de eventos que muestra la entrada del usuario ("Habla con la app de prueba") y la respuesta de la acción. Puedes ver el registro de eventos de tu acción en la siguiente captura de pantalla:

443129bdcbecc593.png

Si haces clic en la flecha hacia abajo, en el evento de registros, verás los eventos que se ejecutaron en ese turno de la conversación en orden cronológico:

  • userInput: Corresponde a la entrada del usuario ("Habla con la app de prueba").
  • interactionMatch: Corresponde a la respuesta de la invocación principal de tu acción, que se activa mediante la entrada del usuario. Si haces clic en la flecha para expandir esta fila, verás el mensaje que agregaste a la invocación principal (A wondrous greeting, adventurer!...).
  • endConversation: Corresponde a la transición seleccionada en el intent Main invocation, que actualmente termina la conversación. (Obtendrás más información sobre las transiciones en la siguiente sección de este codelab).

Los registros de eventos proporcionan visibilidad sobre el funcionamiento de tu acción y, si tienes algún problema, son herramientas útiles para depurar la acción. A fin de ver los detalles de un evento, haz clic en la flecha junto al nombre, como se muestra en la siguiente captura de pantalla:

fcc389b59af5bef1.png

Ahora que definiste lo que ocurre cuando un usuario invoca tu acción, puedes compilar el resto de la conversación. Antes de continuar con este codelab, consulta los siguientes términos para comprender cómo funciona la conversación con tu acción:

Tu acción puede tener una o varias escenas, y debes activar cada una para poder ejecutarla. (La acción que compilarás en este codelab tiene una sola escena, titulada Start). La manera más común de activar una escena es configurar la acción de modo que, cuando un usuario asocia un intent de usuario dentro de una escena, ese intent activa la transición a otra escena para ejecutarla.

Por ejemplo, imagina que una acción hipotética proporciona al usuario datos sobre animales. Cuando el usuario invoca esta acción, se asocia el intent Main invocation y se activa la transición a una escena llamada Facts. Esta transición activa la escena Facts, que envía el siguiente mensaje al usuario: Would you like to hear a fact about cats or dogs?. Dentro de la escena Facts hay un intent del usuario llamado Cat, que incluye frases de entrenamiento que puede decir el usuario cuando quiere oír un dato sobre gatos, como "Quiero oír un dato sobre los gatos" o "gato". Cuando el usuario solicita oír un dato sobre gatos, se asocia el intent Cat y se activa una transición a la escena llamada Cat fact. La escena Cat fact activa y envía un mensaje al usuario que incluye un dato sobre gatos.

a78f549c90c3bff6.png

Figura 1: Flujo de una conversación típica en una acción compilada con Actions Builder

Juntos, los intents, las escenas y las transiciones conforman la lógica de tu conversación y definen los diferentes caminos que puede tomar el usuario durante la conversación de la acción. En la siguiente sección, crearás una escena y definirás cómo activarla después de que un usuario invoque tu acción.

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

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

A fin de 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 menú de navegación izquierdo.
  2. En la sección Transition, a la derecha, haz clic en el menú desplegable y escribe Start en el campo de texto.

29e12dff950a3bce.png

  1. 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.
  2. En el menú de navegación izquierdo, haz clic en Scenes para ver la lista de escenas.
  3. En Scenes, haz clic en Start para ver la escena Start.
  4. Haz clic en el signo + ubicado en la sección On enter de la escena Start.
  5. Selecciona Send prompts.
  6. Reemplaza la oración del campo speech (Enter the response that users will see or hear...) con una pregunta para el usuario: Before you continue on your quest, would you like your fortune told?.

3fc95466efd476f.png

  1. Haz clic en Save.

Asistente de Google le proporciona este mensaje (Before you continue on your quest...) al usuario cuando ingresa a la escena Start.

Cómo agregar chips de sugerencias

Estos chips 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 (Before you continue on your quest, would you like your fortune told?), a fin de brindar compatibilidad para usuarios que usan dispositivos con pantallas.

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

  1. En la escena Start, haz clic en la opción sugerencias que se muestra debajo del editor de código. Esta acción agrega un solo chip de sugerencias.
  2. En el campo title, reemplaza Suggested Response con 'Yes'.
  3. Usa el mismo formato para agregar de forma manual un chip de sugerencias denominado 'No'. El código debería verse como este fragmento:
    suggestions:
      - title: 'Yes'
      - title: 'No'
  1. Haz clic en Save.

2d13c2ada791ec26.png

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 preguntar al usuario si quiere conocer su fortuna. Los chips de sugerencias también deberían aparecer en la pantalla simulada.

A fin de 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. A fin de probar la acción en el simulador, escribe Talk to my test app en el campo Input.
  3. Presiona Intro. Tu acción debería responder con el mensaje Main invocation y el mensaje de la escena Start agregado: "Before you continue on your quest, would you like your fortune told?".

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

3c2013ebb2da886a.png

  1. Haz clic en el chip de sugerencias Yes o No a fin de responder el mensaje. (También puedes decir "Yes" o "No", o bien escribir Yes o No en el campo Input).

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?". Dado que aún no configuraste tu acción para que comprenda y responda a "Yes" o "No", la acción asocia tu entrada a un intent NO_MATCH.

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

Agrega los intents yes y no

Ahora que el usuario puede responder a la pregunta que le presenta tu acción, puedes configurarla para que comprenda las respuestas del usuario ("Yes" o "No"). En las siguientes secciones, crearás intents del usuario que coincidan cuando el usuario diga "Yes" o "No", y los agregarás a la escena Start.

Cómo crear el intent yes

Para crear el intent yes, sigue estos pasos:

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

98440276cb9e7de8.png

  1. Haz clic en Save.

Agrega el intent yes a la escena Start

Ahora, la acción puede comprender cuándo un usuario expresa un intent de afirmación. Puedes agregar el intent de usuario yes a la escena Start, dado que el usuario responde al mensaje Start ("Before you continue on your quest, would you like your fortune told?").

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 + (más), en la escena Start junto a User intent handling.
  3. En el panel desplegable del intent, selecciona yes.

681928e3d71abdbf.png

  1. Haz clic en Send prompts y actualiza el campo speech con este texto: Your future depends on the aid you choose to use for your quest. Choose wisely! Farewell, stranger.

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

 candidates:
  - first_simple:
      variants:
        - speech: >-
            Your future depends on the aid you choose to use for your quest. Choose
            wisely! Farewell, stranger.
  1. En la sección Transition, haz clic en el panel desplegable y selecciona End conversation.
  2. Haz clic en Save.

Cómo probar el intent yes en el simulador

Ahora, tu acción comprende cuando el usuario quiere oír su fortuna, y muestra una respuesta adecuada.

Para probar este intent en el simulador, completa los siguientes pasos:

  1. En la barra de navegación, haz clic en Test.
  2. Para probar la acción en el simulador, escribe Talk to my test app en el campo Input y presiona Intro.
  3. Escribe Yes en el campo Input y presiona Intro. De manera alternativa, puedes hacer clic en el chip de sugerencias Yes.

f131998710d8ffd8.png

Tu acción responde al usuario y le proporciona su fortuna según la opción que elija. Luego, la acción finaliza la sesión porque seleccionaste la transición End conversation para el intent yes.

Cómo crear el intent no

Ahora, debes crear el intent no para comprender cuando el usuario no quiera conocer su fortuna y responderle de forma adecuada. Para ello, sigue estos pasos:

  1. En el menú de navegación, haz clic en Develop.
  2. Luego, haz clic en Intents para abrir la lista de intents.
  3. Al final de la lista, haz clic en el signo + (más). 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 e ingresa las siguientes frases:
  • No
  • N
  • I don't want
  • nope

2e7b8fd57eac94c5.png

  1. Haz clic en Save.

Agrega el intent no a la escena Start

Ahora, la acción puede comprender cuando el usuario dice "no" o algo parecido a "no", como "nope". Debes agregar el intent de usuario no a la escena Start, dado que el usuario responde al mensaje Start ("Before you continue on your quest, would you like your fortune told?").

A fin de 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 + (más), en la escena Start junto a User intent handling.
  3. En la sección Intent, selecciona la opción no del menú desplegable.

4aa558abdecb3121.png

  1. Haz clic en Send prompts y actualiza el campo speech con este texto: I understand, stranger. Best of luck on your quest! Farewell.

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

 candidates:
  - first_simple:
      variants:
        - speech: >-
             I understand, stranger. Best of luck on your quest! Farewell.
  1. En la sección Transition, selecciona la opción End conversation del panel desplegable.
  2. Haz clic en Save.

Cómo probar el intent no en el simulador

Ahora, tu acción comprende cuando el usuario no quiere oír su fortuna, y le muestra una respuesta adecuada.

Para probar este intent en el simulador, completa los siguientes pasos:

  1. En la barra de navegación, haz clic en Test.
  2. Escribe Talk to my test app en el campo Input y presiona Enter.
  3. Escribe No en el campo Input y presiona Enter. De manera alternativa, puedes hacer clic en el chip de sugerencias No.

c0c8b04066577eb2.png

En lugar de proporcionar su fortuna al usuario, la acción le desea suerte en el viaje. Luego, la acción finaliza la sesión porque seleccionaste la transición End conversation para el intent no.

En este momento, las respuestas de tu acción son estáticas; es decir, cuando se activa una escena que contiene un mensaje, la acción envía el mismo mensaje siempre. En esta sección, implementarás una entrega que contiene la lógica para construir una respuesta conversacional dinámica.

La entrega identifica si el usuario es recurrente o nuevo y modifica el saludo correspondiente a la acción de usuarios recurrentes. Para este tipo de usuarios, el mensaje se acorta y hace referencia al regreso del usuario: "A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!".

En este codelab, puedes usar el editor de Cloud Functions en la Consola de Actions para editar e implementar tu código de entregas.

La acción puede activar webhooks que le notifiquen a tu entrega sobre un evento que tiene lugar durante una invocación o partes específicas de la ejecución de una escena. Cuando se activa un webhook, tu acción envía una solicitud con una carga útil de JSON a la entrega junto con el nombre del controlador que se usa para procesar el evento. Este controlador implementa una lógica y muestra una respuesta JSON correspondiente.

Cómo crear una entrega

Ya puedes modificar la entrega en el editor incorporado para generar mensajes diferentes según se trate de usuarios recurrentes o nuevos cuando invocan la acción.

Para agregar esta lógica a la entrega, sigue estos pasos:

  1. En el menú de navegación, haz clic en Develop.
  2. Haz clic en la pestaña Webhook del panel de navegación.
  3. Selecciona Inline Cloud Functions y haz clic en Confirm. Se agregará automáticamente código estándar para los archivos index.js y package.json.

d4702f1de6404285.png

  1. Reemplaza el contenido de index.js con el código que se muestra a continuación:

index.js

const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation({debug: true});

app.handle('greeting', conv => {
 let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Welcome to the mythical land of  Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
 }
 conv.add(message);
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);
  1. Haz clic en Save Fulfillment.
  2. Haz clic en Deploy Fulfillment.

Espera unos minutos a que Cloud Functions proporcione e implemente la entrega. Deberías ver un mensaje que diga Cloud Function deployment in progress… arriba del editor de código. Cuando se implemente correctamente el código, el mensaje cambiará a Your Cloud Function deployment is up to date.

Cómo comprender el código

Tu entrega, que usa la biblioteca de entregas de Actions on Google para Node.js, responde a las solicitudes HTTP de Asistente de Google.

En el fragmento de código anterior, definiste el controlador greeting, que verifica la propiedad lastSeenTime para comprobar si el usuario ya había visitado la acción. Si no se definió lastSeenTime, significa que el usuario es nuevo, por lo que el controlador greeting proporciona el mensaje correspondiente a ese tipo de usuario.

Cómo actualizar la invocación principal para activar un webhook

Ahora que definiste la función greeting, puedes configurar el controlador del evento greeting en el intent de la invocación principal para que tu acción sepa que debe llamar a esa función cuando el usuario invoque la acción.

Para configurar la acción a fin de que llame al nuevo controlador greeting, sigue estos pasos:

  1. Haz clic en Main invocation, en el menú de navegación.
  2. Desmarca la opción Send prompt y selecciona Call your webhook.
  3. Agrega greeting al cuadro de texto.

a803afe4f7375a97.png

  1. Haz clic en Save.

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

A fin de 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. A fin de probar la acción en el simulador, escribe Talk to my test app en el campo Input y presiona Enter.

Como ya probaste la acción más temprano en este codelab, no se te considera un usuario nuevo, por lo que recibirás este mensaje acortado: "A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!…".

¡Felicitaciones!

Ya aprendiste los conceptos básicos que te permiten crear acciones para Asistente de Google.

Temas que se abordaron

  • Cómo configurar un proyecto de Acciones con la Consola de Actions
  • Cómo agregar un mensaje a la invocación principal para que los usuarios puedan iniciar una conversación con tu acción
  • Cómo crear una interfaz de conversación con escenas, intents, transiciones, chips de sugerencias y entregas
  • Cómo probar tu acción con el simulador de acciones

Recursos de aprendizaje adicionales

Explora estos recursos para obtener más información sobre la compilación de Acciones para Asistente de Google:

Sigue a @ActionsOnGoogle en Twitter para estar al tanto de los anuncios más recientes y enviar tweets con #AoGDevs para compartir tu compilación.

Cómo limpiar tu proyecto (recomendado)

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

  1. Si quieres borrar el proyecto de la nube y los recursos, completa los pasos enumerados en la sección Cómo apagar (borrar) proyectos.
  1. Opcional: Para quitar un proyecto de la Consola de Actions de forma inmediata, completa los pasos enumerados en la sección Cómo borrar un proyecto. Si no sigues este paso, se quitará automáticamente el proyecto después de alrededor de 30 días.

Encuesta de opinión

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