Atrae la atención de los usuarios con tu Acción para el Asistente de Google

Atrae la atención de los usuarios con tu Acción para el Asistente de Google

Acerca de este codelab

Última actualización: jun 13, 2022

Escrito por Assistant Developer Relations

1. Descripción general

Advertencia: Las acciones de conversación quedarán obsoletas el 13 de junio de 2023. Para obtener más información, consulta Caducidad de las acciones de conversación.

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 completar tareas, como comprar alimentos o reservar un viaje. (Para obtener una lista completa de lo que puedes hacer, consulta el directorio de acciones). Como desarrollador, puedes usar Actions on Google a fin de crear y administrar fácilmente experiencias de conversación interesantes y eficaces entre los usuarios y tu servicio de terceros.

Este es un módulo de codelab avanzado, pensado para los lectores que ya tienen experiencia en la creación de acciones para Asistente de Google. Si no tienes experiencia previa en 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 por una serie de funciones que pueden ayudarte a expandir 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 la efectividad de la acción para lograr que vuelvan a interesarse después de la primera interacción. Para facilitar esta tarea, puedes implementar varias funciones en tu acción que les brinden a los usuarios rutas de regreso a tu conversación.

El codelab abarca las funciones de participación del usuario y las prácticas recomendadas para Actions on Google.

Qué crearás

Mejorarás una función que ya se creó habilitando lo siguiente:

• Envía a los usuarios una actualización diaria que puedan presionar para hablar sobre tu acción.
• Envía a los usuarios notificaciones push que se vinculen con 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 del usuario
• Qué funciones de participación del usuario usar en los diferentes tipos de acciones
• Cómo usar la API de Actions para enviar notificaciones a través del Asistente

Requisitos

Debes tener las siguientes herramientas:

• Un IDE o el editor de texto que prefieras, como WebStorm, Atom o Sublime
• Una terminal para ejecutar comandos 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)

Además, se recomienda familiarizarse con JavaScript (ES6), aunque no es obligatorio, para comprender el código de webhook.

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 compilada con anterioridad.

Términos clave:

• Participación del usuario: 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 mediante la cantidad de usuarios que regresan a tu acción, que es una métrica que se usa para determinar si se debe promover una acción. La alta participación de los usuarios 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 los usuarios regresen a tu acción cuando tengan más probabilidades de recuperar esa información.

Cómo interpretar la muestra

La muestra de este codelab es una acción simple para un gimnasio ficticio llamado &gtm, 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, ya que la lista rotativa de clases proporciona información útil diferente cada día.

En el siguiente diagrama, se muestra el flujo de conversación de muestra del Action Gym:

Se realizarán pequeñas modificaciones en el diálogo para que se adapten 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 tu agente

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

1. Abre la Consola de Actions.
2. Haz clic en Proyecto nuevo.
3. Ingresa un Project name, 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 Conversacional.
6. Haz clic en Build your Action para expandir las opciones y seleccionar Add Action(s).
7. Haz clic en Agrega tu primera acción.
8. En el diálogo Create action, seleccione Custom Intent y, luego, haga clic en Build para iniciar la consola de Dialogflow.
9. En la página de creación del agente en la consola de Dialogflow, haz clic en Create.
10. Haz clic en (ícono de ajustes) en la barra de navegación izquierda.
11. Haz clic en Export and Import y, 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. Haga clic en Listo.

Implementa tu entrega

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

Desde el directorio /user-engagement-codelab-nodejs/start/functions/ del clon 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 que se produjo un error inesperado desde la CLI, intenta ejecutar el comando firebase deploy nuevamente.

Después de unos minutos, deberías ver el mensaje sobre la implementación completa. Este mensaje indica que implementaste correctamente tu webhook en Firebase.

Recuperar la URL de implementación

Debe proporcionar a Dialogflow la URL de la Cloud Function. Para recuperar la URL, sigue estos pasos:

1. Abre Firebase console.
2. Selecciona tu proyecto de acciones en la lista de opciones.
3. Ve a Develop > Functions en la barra de navegación izquierda. Si se te solicita que elijas 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 Panel de control, deberías ver una entrada para la entrega y una URL en Activador. Guarda esta URL; deberás copiarla en Dialogflow en la próxima sección.

Configure la URL de webhook en Dialogflow

Ahora, debe actualizar su agente de Dialogflow a fin de usar su webhook para la entrega. Para ello, sigue estos pasos:

1. Abre la consola de Dialogflow (si quieres, puedes cerrar Firebase console).
2. En el panel de navegación izquierdo, haz clic en Fulfillment.
3. Habilita Webhook.
4. Pega la URL que copiaste del panel de Firebase si 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 el gimnasio, como una respuesta de texto hard-coded con el horario de atención y una respuesta de texto que detalle el programa de clases 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. Úsala como referencia 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 la barra de navegación izquierda de la consola de Dialogflow, haga clic en Integrations > Asistente de Google.
2. Asegúrate de que la opción Vista previa automática esté habilitada y haz clic en Probar para actualizar el proyecto de acciones.
3. El simulador de acciones 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ía ver una respuesta que le da la bienvenida al gimnasio de acción. Sigue las indicaciones para continuar la conversación y asegúrate de que la entrega tenga una respuesta para cada entrada.

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

3. Agrega suscripciones de actualización diaria

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

En este paso, aprenderás sobre las suscripciones de actualización diarias y las agregarás al intent Lista de clases de Acción. Después de seguir estas instrucciones, la conversación de la acción será similar al 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 actualización diaria son una manera sencilla de acceder a los usuarios de dispositivos móviles fuera de Asistente, siempre que la intención de enviar actualizaciones continúe proporcionando valor al usuario a diario.

Las actualizaciones diarias pueden ser una herramienta útil para generar participación, pero no necesariamente deben incorporarse en cada acción. Ten en cuenta estas sugerencias cuando decidas si deseas agregar suscripciones de actualización diarias a una acción:

• Asegúrate de que las actualizaciones diarias generen que el usuario vea información útil y diferente todos los días. Si el usuario presiona una actualización diaria cada vez que muestra el mismo mensaje, es probable que el usuario anule la suscripción después de un par de días.
• Asegúrate de que el diálogo tenga sentido para el usuario si salta directamente a tu intención de actualización diaria. El usuario no necesariamente comenzará desde el principio de la conversación, por lo que no se espera que tenga mucho contexto.
• Muéstrale al usuario el beneficio de tu acción antes de solicitarle que se suscriba a las actualizaciones diarias. Tu usuario debería pensar: "Quiero este contenido todos los días", cuando tiene la opción de suscribirse.
• No abrumes al usuario con sugerencias repetidas de que se suscriba. Ofrece una suscripción diaria a las actualizaciones justo después de mostrarle al usuario a qué se suscribió y evita molestarte en otro lugar.
• Mantén la conversación breve después de que se active el intent de actualización. La mayoría de las actualizaciones diarias solo deben incluir una única respuesta y, luego, cerrar sin requerir la intervención del usuario.

Sugerencia: Debido a que las actualizaciones diarias aparecerán como notificaciones en el dispositivo del usuario, deberás 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ñada para Asistente, pero se aplican los mismos principios para decidir si las actualizaciones diarias tienen sentido para tu intent o acción.

Cómo activar las actualizaciones diarias

Se pueden agregar suscripciones de actualización diaria al intent de bienvenida, que coloca al usuario al comienzo de la conversación, o un intent más específico para establecer un vínculo directo a alguna parte de la conversación. Para este codelab, el intent Lista de clases tiene más sentido porque el diálogo cambia todos los días, y a los usuarios puede resultarles útil recordar qué clases están disponibles.

Sigue estos pasos a fin de habilitar las actualizaciones diarias del intent Class List:

1. En la Consola de Actions, haz clic en la pestaña Develop y selecciona Actions en la barra de navegación izquierda.
2. Haz clic en Lista de clases en la lista Acciones.
3. En la sección Participación de los usuarios, activa la opción ¿Quieres ofrecer actualizaciones diarias a los usuarios?
4. Establece un Título de contenido descriptivo que describa la actualización diaria. El contexto será &"¿A qué hora quieres que envíe tu diario&quot? Asegúrate de que el título sea descriptivo y sea correcto cuando se hable en voz alta. Para este ejemplo, establece el Título del contenido en list of upcoming Action Gym classes.
5. Haga 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 diario de suscripciones de actualización:

Pídele al usuario que se suscriba

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

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

4. En la sección Fulfillment, activa o desactiva la opción Enable webhook call for this intent.
5. Haga clic en Guardar en la parte superior de la página.

Maneja la decisión del usuario

1. Configura un nuevo intent para procesar la respuesta del usuario a la solicitud de suscripción de actualizaciones diarias. Haz clic en el botón + junto a Intents en la barra de navegación izquierda para crear un intent nuevo.
2. Asigna el nombre Confirm Updates al nuevo intent.
3. En la sección Eventos, agrega actions_intent_REGISTER_UPDATE. Este evento de Dialogflow se activará cuando el usuario finalice el flujo diario de suscripciones de actualización, sin importar si finalizó la suscripción o no.
4. En la sección Fulfillment, activa o desactiva la opción Enable webhook call for this intent.
5. Haga clic en Guardar en la parte superior de la página.

Implementa la entrega

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

Cómo cargar 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');

Actualiza 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',
};

Cómo agregar la entrega para intents nuevos

Cuando el usuario indica que desea suscribirse, inicia el flujo de suscripción de actualizaciones diarias llamando al asistente de RegisterUpdate con el intent de la actualización (Lista de clases) y escribe (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 al usuario

Tu respuesta a la Lista de clases ofrecerá la suscripción de actualización diaria al final, pero esto presenta un problema. Dado que esa misma respuesta se activará cuando el usuario presione la notificación de actualización diaria, se le solicitará que se suscriba a las actualizaciones diarias, incluso si provienen de esta. ¿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 que el usuario inició la conversación. Puedes revisar los argumentos de conv para ver si contienen una sección UPDATES, que indica que el usuario comenzó 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 la conversación para cerrar el diálogo inmediatamente después de proporcionar la lista de clases, que sigue nuestra práctica recomendada de mantener la actualización diaria corta.

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]));
    };
  };
});

Cómo probar tus actualizaciones diarias

En la ventana de terminal, ejecuta el siguiente comando para implementar tu 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. Úsala como referencia si tienes algún problema con los pasos que se indican a continuación.

Para probar tu solicitud 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. Tu respuesta a la 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 deseas ver la actualización y presiona Intro. Para hacer pruebas, responde con 3 a 5 minutos más tarde que la hora actual.

Si recibes un error cuando intentas suscribirte a actualizaciones diarias en el paso 4, regresa a Build > Actions > Class List y desactiva las actualizaciones diarias. Haz clic en Save, vuelve a activar las actualizaciones diarias, haz clic en Save nuevamente y prueba nuevamente en el simulador.

En el dispositivo móvil, deberías recibir una notificación del Asistente aproximadamente a la hora que especificaste para las actualizaciones. Tenga en cuenta que esta notificación puede tardar unos minutos en aparecer. Presiona la notificación para que incluya un vínculo directo al intent Lista de clases en Asistente y te mostrará una lista de las próximas clases:

4. Cómo agregar notificaciones push

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

Términos clave:

• 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 y enviarle una notificación push con el contenido de la solicitud.

En este paso, aprenderás a implementar notificaciones push en tu acción agregando un intent Clase cancelada y enviando notificaciones a los usuarios que les notifican sobre la cancelación de una clase. También debes configurar los siguientes tres componentes necesarios para enviar notificaciones:

• Cuenta de la API de Actions: Para enviar notificaciones al usuario, debes enviar una solicitud de POST a una API, de modo que necesitarás configurar una cuenta de servicio y credenciales para interactuar con esta API.
• Asistente de permisos: Necesitas el permiso del usuario a fin de acceder al ID de usuario necesario para que pueda enviarle notificaciones push. En este ejemplo, usarás una función de biblioteca cliente para llamar al asistente de permisos y solicitar este ID.

Términos clave:

• Asistente: Un asistente es un intent que, cuando se completa, permite que Asistente se encargue de forma temporal de la conversación para solicitarle información específica al usuario. Si la solicitud se realiza correctamente, el asistente te muestra esa información.

• Almacenamiento: Para enviar notificaciones push a un usuario fuera de una conversación, debes almacenar los ID de usuario en algún lugar que se pueda recordar a voluntad. 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 la 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 manera flexible de acceder a los dispositivos móviles fuera del Asistente, siempre que los usuarios 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 recibirán varias notificaciones por día.

Las notificaciones push pueden ser una herramienta de participación útil, pero no necesariamente deben incorporarse en cada acción. Ten en cuenta estas sugerencias cuando decidas si deseas agregar notificaciones push a una acción:

• Planifica algunos programas de ejemplo para tus notificaciones push. Si planeas enviar solo una notificación push por día, considera usar las actualizaciones diarias.
• Asegúrate de que tus notificaciones push proporcionen información útil cada vez que las recibas. Las notificaciones también pueden incluir un vínculo directo a uno de tus intents de acción, por lo que debes asegurarte de que sea útil y relevante.
• Sé explícito cuando le pidas al usuario que se suscriba para recibir notificaciones push. Deberían comprender qué esperar con 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 estos mismos principios se aplican al decidir si se agrega notificación push para tu acción.

Habilita la API de Actions

1. Abra Google Cloud Console y seleccione el nombre de su proyecto de acciones en el menú desplegable.

2. En el menú de navegación (☰), ve a API y servicios > Biblioteca.
3. Busque la API de Actions y haga 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 a fin de crear e instalar una clave de cuenta de servicio para la API de Actions:

1. En el menú de navegación de Google Cloud Console (☰), ve a API y servicios > Credenciales.
2. Haga 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
• Función: Proyecto (propietario)
• ID de cuenta de servicio: service-account (siempre seguido de @<project_id>.iam.gserviceaccount.com)
• Tipo de clave: JSON

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

Habilitar Firestore

Para enviar notificaciones fuera de la conversación, necesitas una manera de almacenar los ID de usuario a los que se puede hacer referencia desde el código de notificaciones. En este ejemplo, se usa una base de datos de Firestore para almacenar los ID de usuario 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 la barra de navegación izquierda, ve a Develop > Database (Desarrollar base de datos) y haz clic en Crear base de datos (Create database).
3. Selecciona Comenzar en modo de prueba.
4. Haz clic en Habilitar.

Sugerencia: Solo usamos las reglas de seguridad del modo de prueba para realizar pruebas. Debes tener reglas de seguridad de los 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 notificaciones push:

Pídele al usuario que se suscriba

1. Configurar un nuevo intent para manejar el usuario que le solicita suscribirse a notificaciones push para las clases canceladas En la consola de Dialogflow, haga clic en el botón + junto a Intents en la barra de navegación izquierda para crear un intent nuevo.
2. Asigna el nombre Setup Push Notifications al nuevo intent.
3. En la sección Training phrases, agrega las siguientes expresiones de usuario:

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

4. En la sección Fulfillment, activa o desactiva la opción Enable webhook call for this intent.
5. Haga clic en Guardar en la parte superior de la página.

Maneja la decisión del usuario

1. Configurar un nuevo intent para manejar la respuesta del usuario a la solicitud de suscripción de notificaciones push Haz clic en el botón + junto a Intents en la barra de navegación izquierda para crear un intent nuevo.
2. Asigna el nombre Confirm Push Notifications al nuevo intent.
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 finalizó la suscripción o no.
4. En la sección Fulfillment, activa o desactiva la opción Enable webhook call for this intent.
5. Haga clic en Guardar en la parte superior de la página.

Cómo manejar las notificaciones push

Puedes vincular tus notificaciones push a un intent específico para que los usuarios que las presionen reciban un vínculo directo directamente a ese intent en tu acción. En este ejemplo, se agrega un nuevo intent para notificaciones push que proporciona detalles sobre las clases canceladas.

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

1. En la consola de Dialogflow, haga clic en el botón + junto a Intents en la barra de navegación izquierda para crear un intent nuevo.
2. Asigna el nombre Class Canceled al nuevo intent.
3. En la sección Training phrases, agrega Cancelations como expresión de usuario.
4. En la sección Fulfillment, activa o desactiva la opción Enable webhook call for this intent.
5. Haga clic en Guardar en la parte superior de la página.

Envía notificaciones de prueba en medio de la conversación

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

Para crear un intent a fin de probar las notificaciones push, sigue estos pasos:

1. Para fines de prueba y depuración, configura un nuevo intent que te permita enviar notificaciones push a usuarios suscritos. En la consola de Dialogflow, haga clic en el botón + junto a Intents en la barra de navegación izquierda para crear un intent nuevo.
2. Asigna el nombre Test Notification al nuevo intent.
3. En la sección Training phrases, agrega Test notification como expresión de usuario.
4. En la sección Fulfillment, activa o desactiva la opción Enable webhook call for this intent.
5. Haga clic en Guardar en la parte superior de la página.

Activar notificaciones de aplicación

Para habilitar las notificaciones push para el intent Clase cancelada, sigue estos pasos:

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 Class Canceled como un intent Invocación implícita. Este paso es necesario para que Dialogflow reconozca que los usuarios pueden iniciar tu conversación con el intent Clase cancelada (presionando una notificación push).
4. Haga 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 izquierda.
6. Haz clic en Clase cancelada en la lista Acciones.
7. En la sección Participación de los usuarios, activa o desactiva la opción ¿Quieres enviar notificaciones push?.
8. Configura un título de contenido descriptivo que describa la notificación push. El contexto será "Está bien si envío notificaciones push para \quot;por lo tanto, asegúrate de que tu título sea descriptivo y sea correcto cuando se hable en voz alta. Para este ejemplo, establece el Título del contenido en class cancelations.
9. Haga clic en Guardar en la parte superior de la página.

Implementa la entrega

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

Cómo cargar 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');

Actualiza 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',
};

Configura importaciones nuevas

A fin de conectarte a tu base de datos de Firestore, agrega el paquete firebase-admin y agrega constantes para los campos almacenados en la base de datos. Además, importa los paquetes google-auth-library y request para manejar 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 configurar 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]));
    };
  };
});

Cómo agregar la entrega para intents nuevos

Cuando el usuario diga que desea suscribirse a las notificaciones push, llama al ayudante UpdatePermission para solicitarle permiso. Si el resultado es satisfactorio, 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 del 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 string de marcador de posición; sin embargo, en una versión lista para producción de esta acción, tu secuencia de comandos de notificaciones proporcionará 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 y el intent de la notificación. En este ejemplo, la activación del intent de las notificaciones 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, se incluye el código que envía la notificación push en la entrega de tu webhook y se activa ese código mediante la invocación de un intent de prueba en la conversación. En las acciones que quieres publicar, tu código de 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 ventana de terminal, ejecuta el siguiente comando para implementar tu 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. Úsala como referencia 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 le otorgaste permiso a Action para que te envíe notificaciones push, escribe yes y presiona Intro.
6. Escribe yes y presiona Intro. Ahora, tu Cuenta de Google debe estar suscrita a las notificaciones push de esta acción.

Si recibes un error cuando intentas suscribirte a notificaciones push en el paso 4, regresa a Build > Actions > Class Canceled y desactiva las notificaciones push. Haz clic en Guardar, vuelve a activar las notificaciones push, haz clic en Guardar de nuevo y 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 conversación nueva.
9. Escribe Test notification y presiona Intro.

En cuestión de unos minutos, deberías recibir una notificación de prueba de gimnasio de acción de Asistente en tu dispositivo móvil. Si presionas esta notificación, se te dirigirá al intent Clase cancelada de tu acción.

Si tienes problemas para recibir la notificación, sigue las instrucciones de prueba de tu teléfono. Abre el Asistente en el teléfono y di "talk to my test app" y sigue las instrucciones de prueba del paso 3.

5. Crea un vínculo de Asistente

Hasta ahora, analizamos las funciones de participación que puedes implementar para que los usuarios vuelvan a la acción, pero que están previstos para que estos descubran y usen la acción.

Puedes crear un vínculo de Asistente que vincule a los usuarios de dispositivos móviles directamente a tu acción de Asistente. Dado que el vínculo de Asistente es un hipervínculo estándar, puedes agregarlo a un sitio web o a cualquier material de marketing web, como un blog o una publicación de redes sociales.

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

¿Cómo atraerá a los usuarios?

Atraer usuarios a tu acción por primera vez puede ser un desafío, especialmente cuando deben invocar de forma explícita tu acción en Asistente. Un vínculo de Asistente ayuda a los usuarios a vincular esta acción con el fin de aliviar esta fricción. Cuando un usuario sigue el vínculo de Asistente en un dispositivo compatible con Asistente, se lo dirige directamente a tu acción. Cuando un usuario abra el vínculo en un dispositivo que no sea móvil o en cualquier otro dispositivo que no sea compatible con Asistente, se lo dirigirá a la ficha del directorio de acciones (si está publicado), de modo que el vínculo aún pueda comercializar tu acción para esos usuarios.

Los vínculos de Asistente pueden ser una herramienta de participación útil; por lo tanto, debes crear una si tienes pensado publicar tu Acción en tu sitio web o redes sociales. Antes de crear y distribuir un vínculo de Asistente, ten en cuenta las siguientes sugerencias:

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

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

Activa los vínculos de Asistente

Siga estos pasos a fin de crear un vínculo de 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 izquierda.
2. Haz clic en actions.intent.MAIN en la lista de Actions.
3. En la sección Vínculos, activa o desactiva la opción ¿Quieres habilitar una URL para esta acción?
4. Establece un título de vínculo descriptivo que describa tu acción. Convierte tu título en un simple verbo o sustantivo que describa lo que el usuario puede lograr con tu acción. Para este ejemplo, establece el campo Título del vínculo en learn about Action Gym.
5. Copie el fragmento HTML de la parte inferior de esta página y guárdelo para más tarde.
6. Haga clic en Guardar en la parte superior de la página.

Implementa un sitio web de prueba

Para probar tu vínculo de Asistente, puedes usar las herramientas de Firebase a fin de implementar un sitio web de prueba junto con tu entrega. Ya hemos creado un sitio web de prueba sencillo para este ejemplo. Solo tienes que agregar tu vínculo de 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 de tu vínculo de Asistente en el elemento del cuerpo. Debería terminar con 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 Asistente

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

firebase deploy

Una vez que el comando de implementación termine de ejecutarse, tome nota de la URL de Hosting en el resultado.

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

También puedes intentar acceder 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 está publicada.

6. Próximos pasos

¡Felicitaciones!

Ahora conoces la importancia de la participación de los usuarios cuando se desarrolla una acción, las funciones de participación disponibles en la plataforma y cómo agregar cada función 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 de los usuarios y la documentación sobre los vínculos de Asistente: La documentación oficial de Actions on Google sobre las funciones que se analizan en este codelab y la participación general de los usuarios.
• Análisis de retención de usuarios: Documentación de la función de estadísticas en la Consola de Actions que muestra la retención de usuarios para tu acción publicada.
• Lineamientos de diseño de conversación: 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: La 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 contarnos cómo estamos.