Atrae a los usuarios con tu acción para Asistente de Google

1. Descripción general

Advertencia: Las acciones de conversación dejarán de estar disponibles el 13 de junio de 2023. Para obtener más información, consulta el artículo Retirada de las acciones conversacionales.

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

Este es un módulo de codelab avanzado, dirigido a lectores que ya tienen algo de experiencia en la compilación de Acciones para Asistente de Google. Si no tienes experiencia previa de desarrollo con Actions on Google, te recomendamos que sigas nuestros codelabs introductorios ( nivel 1, nivel 2 y nivel 3) para familiarizarte con la plataforma. Estos módulos avanzados te guiarán a través de una serie de funciones que pueden ayudarte a ampliar la funcionalidad de tu acción y aumentar tu público.

Una forma importante de medir el éxito de una Acción es la participación del usuario o qué tan eficaz es la Acción para volver a atraer a los usuarios después de su primera interacción. Para que esto sea más fácil, puedes implementar varias funciones en tu Action que les den a los usuarios rutas de regreso a tu conversación.

En el codelab, se abordan funciones para la participación de los usuarios y prácticas recomendadas para Actions on Google.

Qué compilarás

Para mejorar una función que ya se creó, habilita las siguientes funciones:

• Envía a los usuarios una actualización diaria que puedan presionar para hablar con tu acción
• Envía a los usuarios notificaciones push con vínculos a tu Acción
• Crea un vínculo que lleve a los usuarios a tu acción desde un navegador web móvil

Qué aprenderás

• Qué es la participación del usuario y por qué es importante para el éxito de una Acción
• Cómo modificar una acción para aumentar la participación de los usuarios
• Qué funciones de participación de los usuarios usar en diferentes tipos de Acciones
• Cómo usar la API de Actions para enviar notificaciones por medio del Asistente

Requisitos

Debes tener las siguientes herramientas:

• Un IDE o editor de texto que prefieras, como WebStorm, Atom o Sublime
• Una terminal para ejecutar comandos de shell con Node.js, npm y git instalados
• Un navegador web, como Google Chrome
• Un entorno de desarrollo local con la interfaz de línea de comandos de Firebase
• Un dispositivo móvil (Android o iOS) con el Asistente (debes acceder a Asistente con la misma Cuenta de Google que usarás para crear este proyecto)

Se recomienda estar familiarizado con JavaScript (ES6), aunque no es obligatorio, para comprender el código de los webhooks.

2. Configura tu proyecto

En esta sección, se muestra cómo agregar funciones de participación de los usuarios a una acción completa ya creada.

Términos clave:

• Participación de los usuarios: Es la métrica que se usa para medir si los usuarios encuentran valor en un producto o servicio. La participación se puede representar por la cantidad de usuarios que regresan a tu Acción, que es una métrica que se usa para determinar si se promueve una Acción. La alta participación del usuario proviene de dos componentes de una acción: información útil que los usuarios querrán ver en una fecha posterior y formas para que el usuario vuelva a tu acción cuando sea más probable que recupere esa información.

Comprende la muestra

El ejemplo de este codelab es una acción simple para un gimnasio ficticio llamado "Gimnasio de acción". La acción proporciona información sobre el gimnasio, incluida una lista de clases que rotan cada día. Una acción informativa como esta es una buena candidata para todas las funciones de participación del usuario porque la lista de clases rotativa brinda información útil diferente cada día.

En el siguiente diagrama, se muestra el flujo conversacional de la muestra de Action Gym:

Realizarás pequeñas modificaciones en el diálogo para que se adapte mejor a las funciones de participación que agregues. Sin embargo, el diseño general de la conversación no cambiará mucho.

Descarga los archivos de base

Ejecuta el siguiente comando para clonar el repositorio de GitHub del codelab:

git clone https://github.com/actions-on-google/user-engagement-codelab-nodejs

Configura tu proyecto y agente

Para configurar tu proyecto de acciones y agente de Dialogflow, completa los siguientes pasos:

1. Abre la Consola de Actions.
2. Haz clic en Proyecto nuevo.
3. En Project name, escribe un nombre de proyecto, como engagement-codelab.
4. Haz clic en Crear proyecto.
5. En lugar de elegir una categoría, desplázate hacia abajo hasta la sección Más opciones y haz clic en la tarjeta Conversación.
6. Haz clic en Build your Action para expandir las opciones y selecciona Add Action(s).
7. Haz clic en Add Your First Action.
8. En el cuadro de diálogo Create Action, selecciona Custom Intent y, luego, haz clic en Build para iniciar la consola de Dialogflow.
9. En la página de creación del agente de la consola de Dialogflow, haz clic en Crear.
10. Haz clic en el (ícono de ajustes) en el panel de navegación izquierdo.
11. Haz clic en Export and Import, luego, en Restore From Zip.
12. Sube el archivo agent.zip desde el directorio /user-engagement-codelab-nodejs/start/ que descargaste antes.
13. Escribe RESTORE y haz clic en Restablecer.
14. Haz clic en Listo.

Implementa tu entrega

Ahora que tu proyecto de acciones y el agente de Dialogflow están listos, implementa tu archivo local index.js con la CLI de Firebase Functions.

Desde el directorio /user-engagement-codelab-nodejs/start/functions/ de la clonación de tus archivos base, ejecuta los siguientes comandos:

firebase use <PROJECT_ID>

Sugerencia: Busca el ID del proyecto de tu Acción en la Consola de Actions en Descripción general > (ícono de ajustes) > Configuración del proyecto:

npm install

firebase deploy

Si ves un mensaje de error que indica “Se produjo un error inesperado desde la CLI”, vuelve a ejecutar el comando firebase deploy.

Después de unos minutos, deberías ver el mensaje “Deploy complete!”, que indica que implementaste correctamente tu webhook en Firebase.

Recupera la URL de implementación

Debes proporcionarle a Dialogflow la URL de la Cloud Function. Para recuperar esta URL, sigue estos pasos:

1. Abre Firebase console.
2. Selecciona tu proyecto de acciones en la lista de opciones.
3. Dirígete a Develop > Functions en la barra de navegación izquierda. Si aparece el mensaje "Elegir la configuración de uso compartido de datos", puedes hacer clic en Realizar esta acción más adelante para ignorar esta opción.
4. En la pestaña Dashboard, deberías ver una entrada para “entregas”. con una URL en Activador. Guarda esta URL. deberás copiarlo en Dialogflow en la siguiente sección.

Configura la URL de webhook en Dialogflow

Ahora debes actualizar tu agente de Dialogflow a fin de usar tu webhook para la entrega. Para hacerlo, sigue estos pasos:

1. Abre la consola de Dialogflow (puedes cerrar Firebase console si lo deseas).
2. Haz clic en Fulfillment en el panel de navegación izquierdo.
3. Habilita Webhook.
4. Pega la URL que copiaste del panel de Firebase si aún no aparece.
5. Haz clic en Guardar.

Verifica que tu proyecto esté configurado correctamente

Los usuarios deben poder invocar tu acción para obtener información sobre Action Gym, incluida una respuesta de texto hard-coded con el horario de atención y una respuesta de texto que enumere el programa de la clase para cada día de la semana.

Sugerencia: Puedes encontrar la información más reciente sobre el uso del simulador de acciones en la guía del simulador de acciones. Consúltala si tienes algún problema con los pasos que se indican a continuación.

Para probar tu acción en el simulador de acciones, haz lo siguiente:

1. En el menú de navegación izquierdo de la consola de Dialogflow, haz clic en Integraciones > Asistente de Google
2. Asegúrate de que la opción Cambios de vista previa automática esté habilitada y haz clic en Probar para actualizar tu proyecto de acciones.
3. El simulador de Actions carga tu proyecto de acciones. Para probar la acción, escribe Talk to my test app en el campo Input y presiona Intro.
4. Deberías ver una respuesta dándote la bienvenida a Action Gym. Intenta seguir las indicaciones para continuar la conversación y asegurarte de que tu entrega tenga una respuesta para cada entrada.

Si no ves estas respuestas, es probable que se deba a un problema con la configuración de Firebase. En este caso, intenta repetir los pasos de la sección Implementa tu entrega.

3. Agregar suscripciones de actualizaciones diarias

Una forma habitual de atraer a los usuarios es ofrecerles información cuando sea más útil. Para ello, se ofrece a los usuarios la opción de suscribirse a las actualizaciones diarias de un intent, lo que les envía una notificación de Asistente que vincula directamente a la entrega de ese intent.

En este paso, aprenderás sobre las suscripciones de actualización diarias y las agregarás al intent Lista de clases de tu acción. Después de seguir estas instrucciones, la conversación de tu acción se verá como el siguiente diagrama:

¿Cómo atraerá a los usuarios?

Es probable que los usuarios de smartphones estén familiarizados con las notificaciones push, que proporcionan información y actualizaciones específicas de la app. Las suscripciones de actualizaciones diarias son una forma sencilla de acceder a los usuarios en dispositivos móviles fuera de Asistente, siempre que el intent para el que envías actualizaciones siga proporcionando valor a los usuarios a diario.

Las actualizaciones diarias pueden ser una herramienta de participación útil, pero no necesariamente deben incorporarse en todas las Acción. Ten en cuenta estas sugerencias para decidir si quieres agregar suscripciones de actualización diarias a una acción:

• Asegúrate de que las actualizaciones diarias hagan que el usuario vea información útil y diferente todos los días. Si, cuando presiona una actualización diaria, aparece el mismo mensaje cada vez, es probable que el usuario anule la suscripción después de un par de días.
• Asegúrate de que tu diálogo tenga sentido para el usuario si salta directamente al intent de tu actualización diaria. Tu usuario no necesariamente comenzará desde el principio de la conversación, por lo que no se debe esperar que tenga mucho contexto.
• Muéstrale al usuario el beneficio de tu acción antes de pedirle que se suscriba a las actualizaciones diarias. El usuario debe pensar: “Quiero este contenido todos los días”. cuando se les da la opción de suscribirse.
• No abrumes al usuario con sugerencias repetidas para suscribirse. Ofrece una suscripción de actualización diaria justo después de mostrarle al usuario a qué contenido se suscribiría y evita molestarlo por alguna otra parte.
• Procura que la conversación sea breve después de que se active el intent de actualización. La mayoría de las actualizaciones diarias solo deben consistir en una única respuesta y, luego, cerrarse sin requerir la entrada del usuario.

Nota: Dado que las actualizaciones diarias aparecerán como notificaciones en el dispositivo del usuario, debes revisar nuestras prácticas recomendadas para diseñar notificaciones útiles. La mayor parte del contenido de la notificación de actualización diaria está prediseñado para Asistente, pero estos mismos principios se aplican a la hora de decidir si las actualizaciones diarias se relacionan con tu intención o Acción.

Activar las actualizaciones diarias

Las suscripciones de actualizaciones diarias se pueden agregar al intent de bienvenida, que coloca al usuario al comienzo de la conversación, o a un intent más específico con el fin de vincularlos directamente a algún lugar de la conversación. Para este codelab, el intent Class List tiene más sentido, ya que el diálogo cambiará todos los días, y puede resultarles útil a los usuarios que les recuerden qué clases están disponibles.

Sigue estos pasos para habilitar las actualizaciones diarias del intent Lista de clases:

1. En la Consola de Actions, haz clic en la pestaña Develop y selecciona Actions en la barra de navegación de la izquierda.
2. Haz clic en Lista de clases en la lista Acciones.
3. En la sección User engagement, activa la opción ¿Te gustaría ofrecer actualizaciones diarias a los usuarios?
4. Establece un Título del contenido descriptivo que describa la actualización diaria. El contexto será "¿A qué hora quieres que te envíe el <título del contenido>" diario, así que asegúrate de que el título sea descriptivo y suene correcto cuando se pronuncie en voz alta. En este ejemplo, establece el Título del contenido como list of upcoming Action Gym classes.
5. Haz clic en Guardar en la parte superior de la página.

Configura Dialogflow

Sigue estos pasos en la consola de Dialogflow a fin de crear intents para el flujo de suscripción de actualización diaria:

Pídele al usuario que se suscriba

1. Configura un intent nuevo para controlar al usuario que solicita suscribirse a las actualizaciones diarias. En la consola de Dialogflow, haz clic en el botón + junto a Intents, en el panel de navegación izquierdo, para crear un intent nuevo.
2. Asigna el nombre Setup Updates a este intent nuevo.
3. En la sección Frases de entrenamiento, agrega las siguientes expresiones de usuario:

• Send daily reminders
• Reminder
• Remind me
• Updates
• Upcoming classes

4. En la sección Entrega, activa o desactiva la opción Habilitar llamadas de webhook para este intent.
5. Haz clic en Guardar en la parte superior de la página.

Maneja la decisión del usuario

1. Configura un intent nuevo para controlar la respuesta del usuario a la solicitud de suscripción de actualizaciones diarias. Haz clic en el botón + junto a Intents, en el panel de navegación izquierdo, para crear un intent nuevo.
2. Asigna el nombre Confirm Updates a este intent nuevo.
3. En la sección Eventos, agrega actions_intent_REGISTER_UPDATE. Este evento de Dialogflow se activará cuando el usuario finalice el flujo de actualización diaria de la suscripción, sin importar si se suscribió o no.
4. En la sección Entrega, activa o desactiva la opción Habilitar llamadas de webhook para este intent.
5. Haz clic en Guardar en la parte superior de la página.

Cómo implementar la entrega

Para implementar la entrega en tu webhook, completa los siguientes pasos:

Carga de dependencias

En el archivo index.js, actualiza la función require() para agregar el paquete RegisterUpdate del paquete actions-on-google, de modo que tus importaciones se vean de la siguiente manera:

index.js

const {
  dialogflow,
  Suggestions,
  RegisterUpdate,
} = require('actions-on-google');

Cómo actualizar los chips de sugerencias

En el archivo index.js, agrega una entrada DAILY a la lista de títulos de chips de sugerencias para que tu definición de Suggestion se vea de la siguiente manera:

index.js

// Suggestion chip titles
const Suggestion = {
  HOURS: 'Ask about hours',
  CLASSES: 'Learn about classes',
  DAILY: 'Send daily reminders',
};

Agrega entregas para intents nuevos

Cuando el usuario diga que quiere suscribirse, inicia el flujo de suscripción a las actualizaciones diarias llamando al ayudante RegisterUpdate con el intent de destino de la actualización (Lista de clases) y el tipo (DAILY). Una vez que finaliza el flujo de suscripción, Asistente activa el evento actions_intent_REGISTER_UPDATE con un argumento status que describe si la suscripción se realizó correctamente o no. Ofrece mensajes de seguimiento al usuario que cambien según el estado de la suscripción.

En el archivo index.js, agrega el siguiente código:

index.js

// Start opt-in flow for daily updates
app.intent('Setup Updates', (conv) => {
  conv.ask(new RegisterUpdate({
    intent: 'Class List',
    frequency: 'DAILY',
  }));
});

// Confirm outcome of opt-in for daily updates
app.intent('Confirm Updates', (conv, params, registered) => {
  if (registered && registered.status === 'OK') {
     conv.ask(`Gotcha, I'll send you an update everyday with the ` +
     'list of classes. Can I help you with anything else?');
  } else {
    conv.ask(` I won't send you daily reminders. Can I help you with anything else?`);
  }
  if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.HOURS, Suggestion.CLASSES]));
  }
});

Ofrece mensajes alternativos para el usuario

Tu respuesta de Lista de clases ofrecerá la suscripción de actualización diaria al final, pero esto presenta un problema. Dado que esta misma respuesta se activará cuando el usuario presione la notificación de actualización diaria, se le seguirá pidiendo que se suscriba a las actualizaciones diarias, aunque solo provenga de una. ¿Cómo puedes evitar que el usuario piense que debe volver a suscribirse?

Afortunadamente, los argumentos de tu objeto conv incluyen información sobre el punto en el que el usuario inició la conversación. Puedes verificar los argumentos conv para ver si contienen una sección UPDATES, que indica que el usuario inició la conversación desde una notificación de actualización diaria, y cambia la respuesta según corresponda. También puedes usar esta rama de conversación para cerrar el diálogo inmediatamente después de proporcionar la lista de clases, lo que sigue nuestra práctica recomendada de mantener breve la actualización diaria.

En el archivo index.js, reemplaza el siguiente código:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  const classesMessage =
  `On ${day} we offer the following classes: ${classes}. ` +
  `Can I help you with anything else?`;
  conv.ask(classesMessage);
  if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.HOURS]));
  }
});

con esto:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
    };
  };
});

Prueba tus actualizaciones diarias

En la terminal, ejecuta el siguiente comando para implementar el código de webhook actualizado en Firebase:

firebase deploy

Sugerencia: Puedes encontrar la información más reciente sobre el uso del simulador de acciones en la guía del simulador de acciones. Consúltala si tienes algún problema con los pasos que se indican a continuación.

Para probar tu nueva instrucción personalizada en el simulador de acciones, sigue estos pasos:

1. En la Consola de Actions, navega a Test.
2. Escribe Talk to my test app en el campo Input y presiona Intro.
3. Escribe Learn about classes y presiona Intro. La respuesta de tu acción ahora debería ofrecer el envío de recordatorios diarios.
4. Escribe Send daily reminders y presiona Intro.
5. Ingresa la hora en la que te gustaría ver la actualización y presiona Intro. Para realizar pruebas, intenta responder entre 3 y 5 minutos después de la hora actual.

Si recibes un error cuando intentas suscribirte a las actualizaciones diarias en el paso 4, vuelve a Compilación > Acciones > Class List y desactiva las actualizaciones diarias. Haz clic en Guardar, vuelve a activar las actualizaciones diarias y, luego, vuelve a hacer clic en Guardar. Luego, intenta realizar nuevamente la prueba en el simulador.

En tu dispositivo móvil, deberías recibir una notificación del Asistente alrededor de la hora que especificaste para las actualizaciones. Ten en cuenta que esta notificación puede tardar unos minutos en aparecer. Presiona la notificación y debería establecer un vínculo directo al intent Class List en el Asistente, lo que te dará una lista de las próximas clases:

4. Agrega notificaciones push

Como otra opción para atraer a los usuarios fuera de tu Acción, puedes llamar a la API de Actions para enviarles notificaciones push a los usuarios. A diferencia de las actualizaciones diarias, Asistente no programa automáticamente esas notificaciones, por lo que puedes enviarlas cuando quieras.

Términos clave:

• API de Actions: La API de Actions es una API de REST de Asistente que se usa para enviar notificaciones a los usuarios. Con el permiso del usuario, puedes enviar una solicitud POST al extremo de la API de Actions que le envía una notificación push con el contenido de la solicitud.

En este paso, aprenderás a implementar notificaciones push en tu acción. Para ello, agregarás un nuevo intent Class Canceled y enviarás notificaciones a los usuarios para informarles sobre una cancelación de la clase. También configurarás los siguientes tres componentes necesarios para enviar notificaciones:

• Cuenta de la API de Actions: Envías notificaciones al usuario mediante el envío de una solicitud POST a una API, por lo que tendrás que configurar una cuenta de servicio y credenciales para interactuar con esta API.
• Asistente de permisos: Necesitas el permiso del usuario para acceder al ID del usuario que se necesita para enviarle notificaciones push. En este ejemplo, usarás una función de biblioteca cliente para llamar al auxiliar de permisos y solicitar este ID.

Términos clave:

• Asistente: Un asistente es un intent que, cuando se completa, permite que Asistente se haga cargo temporalmente de la conversación para solicitarle información específica al usuario. Si la solicitud se realizó correctamente, el ayudante te mostrará esa información.

• Almacenamiento: Para enviar notificaciones push a un usuario fuera de una conversación, debes almacenar los IDs de usuario en algún lugar que se pueda recuperar si lo deseas. En este ejemplo, configurarás una base de datos de Firestore para almacenar información de cada usuario.

Después de seguir estas instrucciones, agregarás el siguiente diálogo a la conversación de tu acción:

¿Cómo atraerá a los usuarios?

Es probable que los usuarios de smartphones estén familiarizados con las notificaciones push, que proporcionan información y actualizaciones específicas de la app. Las notificaciones push son una forma flexible de acceder a los usuarios que usan dispositivos móviles fuera del Asistente, siempre que tengan un buen motivo para habilitarlas. Con las actualizaciones diarias, los usuarios ya saben que recibirán una notificación a diario. Sin embargo, con las notificaciones push, los usuarios no saben si aceptan recibir notificaciones poco frecuentes o se sentirán ansiosos por recibir varias notificaciones por día.

Las notificaciones push pueden ser una herramienta de participación útil, pero no deberían incorporarse necesariamente en todas las Acción. Ten en cuenta estas sugerencias para decidir si agregar notificaciones push a una acción:

• Planifica algunos ejemplos de programas para tus notificaciones push. Si planeas enviar solo una notificación push por día, considera usar actualizaciones diarias.
• Asegúrate de que tus notificaciones push proporcionen información útil cada vez que se reciban. Las notificaciones también pueden incluir un vínculo directo a uno de los intents de tu Acción, así que asegúrate de que el intent sea útil y relevante.
• Debes ser explícito cuando le pidas a un usuario que se suscriba a notificaciones push. Debería saber qué esperar de cada notificación push y tener una idea de la frecuencia con la que se envían.

Sugerencia: Revisa nuestras prácticas recomendadas para diseñar notificaciones útiles. El logotipo y la prioridad de la notificación están predeterminados para Asistente, pero se aplican estos mismos principios cuando decides agregar notificaciones push a tu Acción.

Habilita la API de Actions

1. Abre la consola de Google Cloud y selecciona el nombre de tu proyecto de acciones en el menú desplegable.

2. En el menú de navegación (☰), ve a APIs y Servicios > Biblioteca.
3. Busca la API de Actions y haz clic en Habilitar.

Crea una cuenta de servicio

La API de Actions requiere autenticación, por lo que debes crear una cuenta de servicio para enviar solicitudes. Sigue estos pasos para crear e instalar una clave de cuenta de servicio para la API de Actions:

1. En el menú de navegación de la consola de Google Cloud (☰), ve a APIs y Servicios > Credenciales.
2. Haz clic en Crear credenciales > Clave de cuenta de servicio.
3. En el menú desplegable Cuenta de servicio, selecciona Nueva cuenta de servicio.
4. Completa la siguiente información:

• Nombre de la cuenta de servicio (Service account name): service-account
• Rol: Proyecto > Propietario
• ID de la cuenta de servicio: service-account (siempre seguido de @<project_id>.iam.gserviceaccount.com)
• Tipo de clave: JSON

5. Haz clic en Crear.
6. Mueve el archivo JSON descargado al directorio /user-engagement-codelab/start/functions/ de tu proyecto.
7. Cambia el nombre del archivo JSON a service-account.json.

Habilita Firestore

Para enviar notificaciones fuera de la conversación, necesitas una forma de almacenar los IDs de usuario a los que se puede hacer referencia desde tu código de notificación. En este ejemplo, usamos una base de datos de Firestore para almacenar los IDs de los usuarios suscritos.

Sigue estos pasos a fin de crear una base de datos de Firestore para tu acción:

1. En Firebase console, selecciona el nombre de tu proyecto de acciones.
2. En el panel de navegación de la izquierda, ve a Develop > Base de datos y haz clic en Crear base de datos.
3. Selecciona Comenzar en modo de prueba.
4. Haz clic en Habilitar.

Nota: Solo usamos las reglas de seguridad del modo de prueba con fines de prueba. Debes implementar reglas de seguridad de datos más sólidas antes de que tu acción se publique en producción. Obtén más información sobre las reglas de seguridad de Cloud Firestore en la documentación de Firestore.

Configura Dialogflow

Sigue estos pasos en la consola de Dialogflow para crear el flujo de habilitación de las notificaciones push:

Pídele al usuario que se suscriba

1. Configurar un intent nuevo para controlar al usuario que solicita suscribirse a notificaciones push de clases canceladas En la consola de Dialogflow, haz clic en el botón + junto a Intents, en el panel de navegación izquierdo, para crear un intent nuevo.
2. Asígnale el nombre Setup Push Notificationsa este intent nuevo.
3. En la sección Frases de entrenamiento, agrega las siguientes expresiones de usuario:

• Subscribe to notifications
• Send notification
• Notify me
• Send class notifications
• Cancelled notifications

4. En la sección Entrega, activa o desactiva la opción Habilitar llamadas de webhook para este intent.
5. Haz clic en Guardar en la parte superior de la página.

Maneja la decisión del usuario

1. Configura un intent nuevo para controlar la respuesta del usuario a la solicitud de suscripción a las notificaciones push. Haz clic en el botón + junto a Intents, en el panel de navegación izquierdo, para crear un intent nuevo.
2. Asigna el nombre Confirm Push Notifications a este intent nuevo.
3. En la sección Eventos, agrega actions_intent_PERMISSION. Este evento de Dialogflow se activará cuando el usuario finalice el flujo de suscripción a las notificaciones push, sin importar si se suscribió o no.
4. En la sección Entrega, activa o desactiva la opción Habilitar llamadas de webhook para este intent.
5. Haz clic en Guardar en la parte superior de la página.

Cómo controlar las notificaciones push

Puedes vincular tus notificaciones push con un intent específico para que los usuarios que presionen la notificación de aplicación tengan vínculos directos a ese intent en tu acción. En este ejemplo, se agrega un intent nuevo para las notificaciones push que proporciona detalles sobre las clases canceladas.

Sigue estos pasos para agregar un intent que se active cuando el usuario presione una notificación push:

1. En la consola de Dialogflow, haz clic en el botón + junto a Intents, en el panel de navegación izquierdo, para crear un intent nuevo.
2. Asígnale el nombre Class Canceleda este intent nuevo.
3. En la sección Frases de entrenamiento, agrega Cancelations como una expresión de usuario.
4. En la sección Entrega, activa o desactiva la opción Habilitar llamadas de webhook para este intent.
5. Haz clic en Guardar en la parte superior de la página.

Envía notificaciones de prueba durante la conversación

En producción, debes tener una secuencia de comandos separada de tu código de entrega de Actions que envía notificaciones push. Para este ejemplo, crea un intent que puedas invocar para enviar una notificación push mientras hablas con tu acción. Este intent es solo con fines de depuración. En la práctica, tu entrega no debería controlar las notificaciones push ni activarse como parte de la conversación de tu acción.

Sigue estos pasos para crear un intent que pruebe las notificaciones push:

1. Con fines de prueba y depuración, configura un nuevo intent que te permita enviar notificaciones push a los usuarios suscritos. En la consola de Dialogflow, haz clic en el botón + junto a Intents, en el panel de navegación izquierdo, para crear un intent nuevo.
2. Asigna el nombre Test Notification a este intent nuevo.
3. En la sección Frases de entrenamiento, agrega Test notification como una expresión de usuario.
4. En la sección Entrega, activa o desactiva la opción Habilitar llamadas de webhook para este intent.
5. Haz clic en Guardar en la parte superior de la página.

Activar notificaciones push

Sigue estos pasos para habilitar las notificaciones push para el intent Class Canceled:

1. En la consola de Dialogflow, ve a Integraciones en la barra de navegación.
2. En la tarjeta Asistente de Google, haz clic en Configuración de integración.
3. Agrega Clase cancelada como un intent de invocación implícita. Este paso es necesario para que Dialogflow reconozca que los usuarios pueden iniciar tu conversación con el intent Class Canceled (presionando una notificación push).
4. Haz clic en Cerrar.

5. En la Consola de Actions, haz clic en la pestaña Develop y selecciona Actions en la barra de navegación de la izquierda.
6. Haz clic en Class Canceled en la lista Actions.
7. En la sección User engagement, activa la opción ¿Deseas enviar notificaciones push?
8. Establece un Título del contenido descriptivo que describa la notificación push. El contexto será “¿Está bien si envío notificaciones push sobre <título del contenido>?”, así que asegúrate de que el título sea descriptivo y suene correcto cuando se pronuncie en voz alta. En este ejemplo, establece el Título del contenido como class cancelations.
9. Haz clic en Guardar en la parte superior de la página.

Cómo implementar la entrega

Para implementar la entrega en tu webhook, completa los siguientes pasos:

Carga de dependencias

En el archivo index.js, actualiza la función require() para agregar el paquete UpdatePermission del paquete actions-on-google, de modo que tus importaciones se vean de la siguiente manera:

index.js

const {
  dialogflow,
  Suggestions,
  RegisterUpdate,
  UpdatePermission,
} = require('actions-on-google');

Cómo actualizar los chips de sugerencias

En el archivo index.js, agrega una entrada NOTIFICATIONS a la lista de títulos de chips de sugerencias para que tu definición de Suggestion se vea de la siguiente manera:

index.js

// Suggestion chip titles
const Suggestion = {
  HOURS: 'Ask about hours',
  CLASSES: 'Learn about classes',
  DAILY: 'Send daily reminders',
  NOTIFICATIONS: 'Get notifications',
};

Cómo configurar importaciones nuevas

Si quieres conectarte a la base de datos de Firestore, agrega el paquete firebase-admin y constantes para los campos almacenados en la base de datos. Además, importa los paquetes google-auth-library y request para controlar la autenticación y las solicitudes a la API de Actions.

En el archivo index.js, agrega el siguiente código a tus importaciones:

index.js

// Firebase admin import
const admin = require('firebase-admin');

// Initialize Firestore
admin.initializeApp();
const db = admin.firestore();

// Firestore constants
const FirestoreNames = {
 INTENT: 'intent',
 USER_ID: 'userId',
 USERS: 'users',
};

// Actions API authentication imports
const {auth} = require('google-auth-library');
const request = require('request');

Ofrece la opción de configurar las notificaciones de cancelación de la clase

En el archivo index.js, reemplaza el siguiente código:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like me to send you daily reminders of upcoming classes, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.HOURS]));
    };
  };
});

con esto:

index.js

// Class list intent handler
app.intent('Class List', (conv, {day}) => {
  if (!day) {
    day = DAYS[new Date().getDay()];
  }
  const classes =
  [...new Set(schedule.days[day].map((d) => `${d.name} at ${d.startTime}`))]
  .join(', ');
  let classesMessage = `On ${day} we offer the following classes: ${classes}. `;
  // If the user started the conversation from the context of a daily update,
  // the conv's arguments will contain an 'UPDATES' section.
  let engagement = conv.arguments.get('UPDATES');
  // Check the conv arguments to tailor the conversation based on the context.
  if (engagement) {
    classesMessage += `Hope to see you soon at Action Gym!`;
    conv.close(classesMessage);
  } else {
    classesMessage += `Would you like to receive daily reminders of upcoming classes, subscribe to notifications about cancelations, or can I help you with anything else?`;
    conv.ask(classesMessage);
    if (conv.screen) {
      conv.ask(new Suggestions([Suggestion.DAILY, Suggestion.NOTIFICATIONS,
Suggestion.HOURS]));
    };
  };
});

Agrega entregas para intents nuevos

Cuando el usuario diga que quiere suscribirse a las notificaciones push, llama al asistente de UpdatePermission para solicitarle permiso. Si se ejecuta correctamente, se agregará el argumento PERMISSION a los argumentos del objeto conv, que puedes verificar para reorientar la conversación.

Una vez que tengas el permiso del usuario, toma el ID de usuario de los argumentos del objeto conv y guárdalo en tu base de datos. Más adelante, enviarás este ID de usuario a la API de Actions, que es la forma en que Asistente determina quién recibe la notificación.

Por último, agrega la entrega para el intent Class Canceled que se activa presionando la notificación push. En este ejemplo, tu respuesta es una cadena de marcador de posición, aunque, en una versión lista para producción de esta Acción, tu secuencia de comandos de notificación proporcionaría más información dinámica sobre la clase que se canceló.

En el archivo index.js, agrega el siguiente código:

index.js

// Call the User Information helper for permission to send push notifications
app.intent('Setup Push Notifications', (conv) => {
 conv.ask('Update permission for setting up push notifications');
 conv.ask(new UpdatePermission({intent: 'Class Canceled'}));
});

// Handle opt-in or rejection of push notifications
app.intent('Confirm Push Notifications', (conv) => {
 if (conv.arguments.get('PERMISSION')) {
   let userId = conv.arguments.get('UPDATES_USER_ID');
   if (!userId) {
     userId = conv.request.conversation.conversationId;
   }
   // Add the current conversation ID and the notification's
   // target intent to the Firestore database.
   return db.collection(FirestoreNames.USERS)
   .add({
     [FirestoreNames.INTENT]: 'Class Canceled',
     [FirestoreNames.USER_ID]: userId,
   })
   .then(() => {
     conv.ask(`Great, I'll notify you whenever there's a class cancelation. ` +
     'Can I help you with anything else?');
   });
 } else {
   conv.ask(`Okay, I won't send you notifications about class cancelations. ` +
     'Can I help you with anything else?');
 }
 if (conv.screen) {
    conv.ask(new Suggestions([Suggestion.CLASSES, Suggestion.HOURS]));
  }
});

// Intent triggered by tapping the push notification
app.intent('Class Canceled', (conv) => {
 conv.ask('Classname at classtime has been canceled.');
});

Cómo agregar notificaciones de prueba

Para enviar una notificación push a un usuario, envía una solicitud POST a la API de Actions con el ID del usuario, el título de la notificación y el intent objetivo. En este ejemplo, activar el intent de notificación de prueba iterará a través de tu base de datos de Firestore y enviará notificaciones push a todos los usuarios suscritos a notificaciones.

Recuerda que, en este ejemplo, incluirás el código que envía la notificación push en la entrega de tu webhook y activarás ese código invocando un intent de prueba en tu conversación. En las acciones que quieras publicar, el código de tu notificación push debe existir en una secuencia de comandos independiente de tu entrega.

En el archivo index.js, agrega el siguiente código:

index.js

// Debug intent to trigger a test push notification
app.intent('Test Notification', (conv) => {
 // Use the Actions API to send a Google Assistant push notification.
 let client = auth.fromJSON(require('./service-account.json'));
 client.scopes = ['https://www.googleapis.com/auth/actions.fulfillment.conversation'];
 let notification = {
   userNotification: {
     title: 'Test Notification from Action Gym',
   },
   target: {},
 };
 client.authorize((err, tokens) => {
   if (err) {
     throw new Error(`Auth error: ${err}`);
   }
   // Iterate through Firestore and send push notifications to every user
   // who's currently opted in to canceled class notifications.
   db.collection(FirestoreNames.USERS)
       .where(FirestoreNames.INTENT, '==', 'Class Canceled')
       .get()
       .then((querySnapshot) => {
         querySnapshot.forEach((user) => {
           notification.target = {
             userId: user.get(FirestoreNames.USER_ID),
             intent: user.get(FirestoreNames.INTENT),
           };
           request.post('https://actions.googleapis.com/v2/conversations:send', {
             'auth': {
               'bearer': tokens.access_token,
             },
             'json': true,
             'body': {'customPushMessage': notification, 'isInSandbox': true},
           }, (err, httpResponse, body) => {
             if (err) {
               throw new Error(`API request error: ${err}`);
             }
             console.log(`${httpResponse.statusCode}: ` +
               `${httpResponse.statusMessage}`);
             console.log(JSON.stringify(body));
           });
         });
       })
       .catch((error) => {
         throw new Error(`Firestore query error: ${error}`);
       });
 });
 conv.ask('A notification has been sent to all subscribed users.');
});

Prueba tus notificaciones push

En la terminal, ejecuta el siguiente comando para implementar el código de webhook actualizado en Firebase:

firebase deploy

Sugerencia: Puedes encontrar la información más reciente sobre el uso del simulador de acciones en la guía del simulador de acciones. Consúltala si tienes algún problema con los pasos que se indican a continuación.

Para probar las notificaciones en el simulador de acciones, sigue estos pasos:

1. En la Consola de Actions, ve a la pestaña Test.
2. Escribe Talk to my test app en el campo Input y presiona Intro.
3. Escribe Learn about classes y presiona Intro.
4. Escribe Get notifications y presiona Intro.
5. Si aún no otorgaste permiso de acción para enviarte notificaciones push, escribe yes y presiona Intro.
6. Escribe yes y presiona Intro. Tu Cuenta de Google debería estar suscrita para recibir notificaciones push sobre esta acción.

Si ves un error cuando intentas suscribirte a las notificaciones push en el paso 4, vuelve a Compilación > Acciones > Se canceló la clase y desactiva las notificaciones push. Haz clic en Guardar, vuelve a activar las notificaciones push y, luego, vuelve a hacer clic en Guardar. Luego, prueba nuevamente en el simulador.

7. Escribe no y presiona Intro para salir.
8. Escribe Talk to my test app y presiona Intro para iniciar una nueva conversación.
9. Escribe Test notification y presiona Intro.

En unos minutos, deberías recibir una "Notificación de prueba de Action Gym" Notificaciones push de Asistente en tu dispositivo móvil. Si presionas esta notificación, se te proporcionará un vínculo directo al intent Class Canceled de tu acción.

Si tienes problemas para que aparezca la notificación, sigue las instrucciones de prueba en el teléfono. Abre Asistente en tu teléfono y di "talk to my test app"; luego, sigue las instrucciones de la prueba que se mencionaron anteriormente en el paso 3.

5. Crea un vínculo de Asistente

Hasta ahora, hablamos sobre las funciones de participación que puedes implementar para que los usuarios regresen a tu acción, pero se basan en que los usuarios descubran y usen tu acción.

Puedes crear un vínculo del Asistente que vincule a los usuarios de dispositivos móviles directamente a tu Action on Assistant. Dado que un vínculo del Asistente es un hipervínculo estándar, puede agregarlo a un sitio web o a cualquier material de marketing web, como un blog o una entrada de redes sociales.

En este paso, aprenderás qué es un vínculo del Asistente, cómo crear uno para el intent de bienvenida de tu acción y cómo agregarlo a un sitio web simple para realizar pruebas.

¿Cómo atraerá a los usuarios?

Atraer usuarios a tu acción por primera vez puede ser desafiante, en especial cuando necesitan invocar explícitamente tu acción en Asistente. Los vínculos del Asistente alivian esta fricción, ya que les brindan a los usuarios un vínculo directo a tu Acción. Cuando un usuario sigue el vínculo de tu Asistente en un dispositivo compatible con el Asistente, se lo dirige directamente a tu Acción. Cuando un usuario abra tu vínculo en un dispositivo que no sea móvil o en cualquier otro que no admita Asistente, se lo dirigirá a la ficha del directorio de acciones (si se publicó) para que pueda promocionar tu Acción para esos usuarios.

Los vínculos del Asistente pueden ser una herramienta de participación útil, por lo que te recomendamos crear uno si tienes previsto promocionar la Acción en tu sitio web o redes sociales. Ten en cuenta las siguientes sugerencias antes de crear y distribuir un vínculo del Asistente:

• Los vínculos de Asistente solo funcionan una vez que se publica la acción. Mientras el proyecto esté en estado de borrador, el vínculo solo funcionará en tus propios dispositivos. Se redireccionará a las demás personas a una página 404 del directorio Actions.
• Puedes permitir que los usuarios prueben un vínculo del Asistente antes de publicar tu Acción en un entorno Alfa o Beta. Ten en cuenta que solo los usuarios que participen en las versiones alfa o beta podrán probar el vínculo de tu Asistente.
• Asegúrate de que el intent de destino de tu vínculo de Asistente cause una buena primera impresión a los usuarios nuevos. Tu intent de bienvenida es el destino predeterminado de un vínculo del Asistente porque ya debería presentar la acción correctamente.

Sugerencia: En este ejemplo, solo crearás un vínculo simple al Asistente que dirija a los usuarios al intent de bienvenida, pero puedes hacer mucho más para personalizar un vínculo del Asistente. Puedes agregar parámetros de URL a tu vínculo que envíen a los usuarios a intents específicos y hasta incluir parámetros de intents para personalizar la respuesta que reciben los usuarios cuando siguen tu vínculo. Si bien no abarcamos estas opciones avanzadas en este codelab, puedes obtener más información en la documentación para desarrolladores.

Cómo activar los vínculos de Asistente

Sigue estos pasos para crear un vínculo del Asistente para el intent de bienvenida:

1. En la Consola de Actions, haz clic en la pestaña Develop y selecciona Actions en la barra de navegación de la izquierda.
2. Haz clic en actions.intent.MAIN en la lista Actions.
3. En la sección Vínculos, activa la opción ¿Te gustaría habilitar una URL para esta acción?
4. Establece un Título del vínculo descriptivo que describa tu Acción. Haz que el título sea un par simple de verbo y sustantivo que describa lo que el usuario puede lograr con tu acción. Para este ejemplo, establece el Título del vínculo como learn about Action Gym.
5. Copia el fragmento HTML de la parte inferior de esta página y guárdalo para más adelante.
6. Haz clic en Guardar en la parte superior de la página.

Implementa un sitio web de prueba

Para probar el vínculo de tu Asistente, puedes usar las herramientas de Firebase para implementar un sitio web de prueba junto con tu entrega. Ya creamos un sitio web de prueba simple para este ejemplo, solo tienes que agregar tu vínculo del Asistente.

Ve al directorio /user-engagement-codelab-nodejs/start/public/ de tu entrega y abre el archivo index.html en un editor de texto.

En el archivo index.html, pega el fragmento HTML del vínculo del Asistente en el elemento del cuerpo. El archivo debería terminar luciendo como el siguiente fragmento:

index.html

<body>
    <p>
     <a href="https://assistant.google.com/services/invoke/uid/000000efb5f2fd97">🅖 Ask my test app to learn about Action Gym
     </a>
    </p>
</body>

Prueba el vínculo de tu Asistente

En la terminal, ejecuta el siguiente comando para implementar tu sitio web de prueba en Firebase:

firebase deploy

Cuando el comando de implementación termine de ejecutarse, toma nota de la URL de Hosting que aparece en el resultado.

Visita esta URL en el navegador web de tu dispositivo móvil. Deberías ver el vínculo del Asistente en el sitio web de prueba. Si haces clic en este vínculo en tu dispositivo móvil, se te debería redireccionar al intent de bienvenida de tu acción en el Asistente.

También puedes intentar ir a la URL de Hosting en un navegador de escritorio, lo que debería llevarte a una página 404 en el directorio de Asistente, ya que tu acción no se publica.

6. Próximos pasos

¡Felicitaciones!

Ya aprendiste sobre la importancia de la participación del usuario al desarrollar una acción, qué funciones de participación del usuario están disponibles en la plataforma y cómo agregar cada una a una acción.

Recursos de aprendizaje adicionales

Explora estos recursos para obtener más información sobre la participación de los usuarios en tu acción:

• Participación del usuario y Documentos de vínculos de Asistente: Es la documentación oficial de Actions on Google sobre las funciones que se analizan en este codelab y la participación de los usuarios en general.
• Estadísticas de retención de usuarios: Es la documentación de la función de estadísticas de la Consola de Actions que muestra la retención de usuarios de tu acción publicada.
• Lineamientos de diseño conversacional: Son prácticas recomendadas y lineamientos para diseñar funciones de participación de los usuarios.
• Repositorio de GitHub de Actions on Google: Código de muestra y bibliotecas
• r/GoogleAssistantDev (comunidad oficial de Reddit para desarrolladores que trabajan con Asistente)

Síguenos en Twitter (@ActionsOnGoogle) para mantenerte al tanto de los anuncios más recientes y enviar tuits con #AoGDevs para compartir tu compilación.

Encuesta de opinión

Antes de irte, completa este formulario para darnos tu opinión.