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

1. Descripción general

Advertencia: Las acciones de conversación dejaron de estar disponibles el 13 de junio de 2023. Para obtener más información, consulta Retiro 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 completar tareas, como comprar alimentos o reservar un viaje. (Para obtener una lista completa de lo que es posible, consulta el directorio de acciones). Como desarrollador, puedes usar Actions on Google para crear y administrar fácilmente experiencias de conversación interesantes y eficaces entre los usuarios y tu servicio externo.

Este es un módulo de codelab avanzado, diseñado para lectores que ya tienen algo de experiencia en la creació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 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 de los usuarios, es decir, la eficacia con la que la acción logra que los usuarios regresen después de su primera interacción. Para que sea más fácil, puedes implementar varias funciones en tu Acción que les permitan a los usuarios volver a tu conversación.

En el codelab, se abordan las funciones de participación del usuario y las prácticas recomendadas para las Acciones en Google.

Qué compilarás

Mejorarás una función que ya se creó habilitándola para que haga lo siguiente:

• Enviar a los usuarios una actualización diaria en la que pueden presionar para hablar con tu Action
• Envía a los usuarios notificaciones push que los dirijan a tu Action
• Crea un vínculo que lleve a los usuarios a tu Acción desde un navegador web para dispositivos móviles

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 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 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 Asistente (debes acceder a Asistente con la misma Cuenta de Google que usarás para compilar este proyecto)

También se recomienda tener conocimientos de JavaScript (ES6), aunque no es obligatorio, para comprender el código del webhook.

2. Configura tu proyecto

En esta sección, se muestra cómo agregar funciones de participación del usuario a una acción completa creada anteriormente.

Términos clave:

• Compromiso 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 por la cantidad de usuarios que regresan a tu Acción, que es una métrica que se usa para determinar si se debe promocionar 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 más adelante y formas para que el usuario vuelva a tu Acción cuando sea más probable que recupere esa información.

Comprende la muestra

La muestra de este codelab es una acción simple para un gimnasio ficticio llamado "Action Gym". 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 de clases rotativas brinda información útil diferente cada día.

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

Realizarás modificaciones menores 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 tu agente

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

1. Abre la Consola de Actions.
2. Haz clic en Proyecto nuevo.
3. En Project name, ingresa un nombre 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 selecciona Add Action(s).
7. Haz clic en Add Your First Action.
8. En el 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 (ícono de ajustes) en el panel de navegación izquierdo.
11. Haz clic en Importar y exportar y, luego, en Restaurar desde ZIP.
12. Sube el archivo agent.zip del 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 Actions y tu 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/ de la clonación de tus archivos base, ejecuta los siguientes comandos:

firebase use <PROJECT_ID>

Nota: Encuentra 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 dice "Se produjo un error inesperado en la CLI", vuelve a ejecutar el comando firebase deploy.

Después de unos minutos, deberías ver el mensaje que indica que se completó la implementación; es decir que el webhook se implementó correctamente en Firebase.

Recupera la URL de implementación

Debes proporcionar a Dialogflow la URL de la función de Cloud. Para recuperar esta 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 ignorar esta opción haciendo clic en Hacerlo más tarde.
4. En la pestaña Panel, deberías ver una entrada para "fulfillment" con una URL en Activador. Guarda esta URL, ya que deberás copiarla en Dialogflow en la siguiente sección.

Cómo establecer la URL del webhook en Dialogflow

Ahora debes actualizar tu agente de Dialogflow para que use 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 menú de navegación de la izquierda.
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 codificada con el horario de atención y una respuesta de texto que enumere el horario de clases para cada día de la semana.

Nota: Puedes encontrar la información más reciente sobre el uso del simulador de Actions en la guía del simulador de Actions. Úsala como referencia si tienes algún problema con los pasos que se mencionan a continuación.

Para probar tu acción en el simulador de Actions, sigue estos pasos:

1. En el menú de navegación de la izquierda de la consola de Dialogflow, haz clic en Integrations > Google Assistant.
2. Asegúrate de que la opción Vista previa automática de los cambios esté habilitada y haz clic en Probar para actualizar tu proyecto de Actions.
3. El simulador de Actions carga tu proyecto de Actions. Para probar la acción, escribe Talk to my test app en el campo Input y presiona Intro.
4. Deberías ver una respuesta que te da la bienvenida a Action Gym. Intenta seguir las instrucciones para continuar la conversación y asegúrate de que tu cumplimiento 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, intenta repetir los pasos de la sección Implementa tu cumplimiento.

3. Cómo agregar suscripciones a actualizaciones diarias

Una forma común de atraer a los usuarios es ofrecerles información cuando les resulta más útil. Para ello, se les ofrece a los usuarios la opción de suscribirse a las actualizaciones diarias de una intención, lo que les envía una notificación de Asistente que vincula directamente al cumplimiento de esa intención.

En este paso, aprenderás sobre las suscripciones a actualizaciones diarias y las agregarás a la intención Class List 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 conozcan las notificaciones push, que proporcionan información y actualizaciones específicas de las apps. Las suscripciones a actualizaciones diarias son una forma sencilla de acceder a los usuarios en dispositivos móviles fuera del Asistente, siempre que la intención para la que envías actualizaciones siga proporcionando valor al usuario a diario.

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

• Asegúrate de que las actualizaciones diarias hagan que el usuario vea información diferente y útil todos los días. Si al presionar una actualización diaria, se muestra el mismo mensaje cada vez, es probable que el usuario cancele la suscripción después de un par de días.
• Asegúrate de que el diálogo tenga sentido para el usuario si pasa directamente al intent de la actualización diaria. No es necesario que el usuario comience 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 pedirle que se suscriba a las actualizaciones diarias. El usuario debe pensar "Quiero este contenido todos los días" cuando se le dé la opción de suscribirse.
• No abrumes al usuario con sugerencias repetidas para que se suscriba. Ofrece una suscripción a actualizaciones diarias inmediatamente después de mostrarle al usuario a qué se suscribiría y evita insistirle sobre el tema en otros lugares.
• Mantén la conversación breve después de que se active la intención de actualización. La mayoría de las actualizaciones diarias solo deben consistir en una sola 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ía del contenido de la notificación de actualización diaria está prediseñado para Asistente, pero estos mismos principios se aplican cuando se decide si las actualizaciones diarias tienen sentido para tu intención o acción.

Activa las actualizaciones diarias

Las suscripciones a actualizaciones diarias se pueden agregar al intent de bienvenida, que coloca al usuario al inicio de la conversación, o a un intent más específico para vincularlo directamente a un punto dentro de la conversación. Para este codelab, la intención Class List es la más adecuada, ya que el diálogo cambiará todos los días y a los usuarios les puede resultar útil que se les recuerde qué clases están disponibles.

Sigue estos pasos para habilitar las actualizaciones diarias del intent Class List:

1. En la Consola de Actions, haz clic en la pestaña Develop y elige 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 Participación del usuario, activa la opción ¿Quieres 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 recibir tu actualización diaria de ", así que asegúrate de que el título sea descriptivo y suene correcto cuando se diga en voz alta. Para este ejemplo, configura 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 para crear intents para el flujo de suscripción a la actualización diaria:

Solicita al usuario que se suscriba

1. Configura una nueva intención para controlar la solicitud del usuario de suscribirse a las actualizaciones diarias. En la consola de Dialogflow, haz clic en el botón + que está junto a Intents en el menú de navegación de la izquierda 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 del usuario:

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

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

Cómo controlar la decisión del usuario

1. Configura un intent nuevo para controlar la respuesta del usuario a la solicitud de suscripción a las actualizaciones diarias. Haz clic en el botón + junto a Intents en la navegación de la izquierda 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 suscripción a las actualizaciones diarias, ya sea que se haya suscrito o no.
4. En la sección Entregas, activa la opción Habilitar llamada de webhook para este intent.
5. Haz 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:

Carga 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');

Chips de sugerencias de actualización

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 función de cumplimiento para intents nuevas

Cuando el usuario diga que quiere suscribirse, llama al asistente RegisterUpdate con la intención objetivo de la actualización (Class List) y el tipo (DAILY) para iniciar el flujo de suscripción a las actualizaciones diarias. Después de que finalice el flujo de suscripción, Asistente activará el evento actions_intent_REGISTER_UPDATE con un argumento status que describe si la suscripción se realizó correctamente o no. Se ofrecen mensajes de seguimiento al usuario que cambian 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 la clase ofrecerá la suscripción a la 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 pedirá que se suscriba a las actualizaciones diarias, aunque acabe de recibir 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 dónde el usuario inició la conversación. Puedes verificar los argumentos de 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 cambiar 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 la actualización diaria breve.

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 este:

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 actualizado del webhook en Firebase:

firebase deploy

Nota: Puedes encontrar la información más reciente sobre el uso del simulador de Actions en la guía del simulador de Actions. Úsala como referencia si tienes algún problema con los pasos que se mencionan a continuación.

Para probar tu mensaje personalizado en el simulador de Actions, 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 enviar recordatorios diarios.
4. Escribe Send daily reminders y presiona Intro.
5. Escribe la hora en la que quieres ver la actualización y presiona Intro. Para fines de prueba, 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 Build > Actions > Class List y desactiva las actualizaciones diarias. Haz clic en Save, vuelve a activar las actualizaciones diarias, haz clic en Save de nuevo y, luego, intenta realizar la prueba en el simulador otra vez.

En tu dispositivo móvil, deberías recibir una notificación del Asistente cerca 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 se debería vincular directamente con la intención de Lista de clases en el Asistente, lo que te dará una lista de las próximas clases:

4. Agrega notificaciones push

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

Términos clave:

• API de Actions: La API de Actions es una API de REST de Assistant 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íe una notificación push con el contenido de la solicitud.

En este paso, aprenderás a implementar notificaciones push en tu Acción agregando una nueva intención Clase cancelada y enviando notificaciones a los usuarios para informarles sobre la cancelación de una clase. También configurarás los siguientes tres componentes necesarios para enviar notificaciones:

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

Términos clave:

• Ayudante: Un ayudante es un intent que, cuando se cumple, permite que Asistente se haga cargo temporalmente de la conversación para solicitar información específica al usuario. Si la solicitud se realizó correctamente, el asistente te devolverá 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 donde se puedan recuperar 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 tu acción:

¿Cómo atraerá a los usuarios?

Es probable que los usuarios de smartphones conozcan las notificaciones push, que proporcionan información y actualizaciones específicas de las apps. Las notificaciones push son una forma flexible de acceder a los usuarios en dispositivos móviles fuera del Asistente, siempre y cuando se les proporcione un buen motivo para habilitarlas. Con las actualizaciones diarias, los usuarios ya saben que recibirán notificaciones todos los días. Sin embargo, con las notificaciones push, los usuarios no saben si habilitarán la recepción de notificaciones poco frecuentes o si recibirán varias notificaciones por día.

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

• Planifica algunos ejemplos de programaciones para tus notificaciones push. Si planeas enviar solo una notificación push por día, considera usar las actualizaciones diarias.
• Asegúrate de que las notificaciones push proporcionen información útil cada vez que se reciban. Tus notificaciones también pueden tener vínculos directos a uno de los intents de tu acción, así que asegúrate de que el intent sea útil y pertinente.
• Sé explícito cuando le pidas a un usuario que se suscriba a las notificaciones push. Deben comprender 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 el Asistente, pero estos mismos principios se aplican cuando decides si agregar una notificación push para tu Acción.

Habilita la API de Actions

1. Abre la consola de Google Cloud y selecciona el nombre de tu proyecto de Actions 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 el 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 para crear una base de datos de Firestore para tu acción:

1. En Firebase console, selecciona el nombre de tu proyecto de Actions.
2. En el menú de navegación de la izquierda, ve a Develop > Database y haz clic en Create database.
3. Selecciona Comenzar en modo de prueba.
4. Haz clic en Habilitar.

Nota: Solo usamos reglas de seguridad en modo de prueba con fines de prueba. Deberás tener reglas de seguridad de datos más sólidas antes de que se publique tu acción 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 aceptación de notificaciones push:

Solicita al usuario que se suscriba

1. Configura una nueva intención para controlar la solicitud del usuario de suscribirse a las notificaciones push de las clases canceladas. En la consola de Dialogflow, haz clic en el botón + que está junto a Intents en el menú de navegación de la izquierda para crear un intent nuevo.
2. Asigna el nombre Setup Push Notifications a este intent nuevo.
3. En la sección Frases de entrenamiento, agrega las siguientes expresiones del usuario:

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

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

Cómo controlar 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 la navegación de la izquierda 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, independientemente de si se suscribió o no.
4. En la sección Entregas, activa la opción Habilitar llamada de webhook para este intent.
5. Haz clic en Guardar en la parte superior de la página.

Cómo controlar la notificación push

Puedes vincular tus notificaciones push a un intent específico para que los usuarios que presionen la notificación push se vinculen directamente a ese intent en tu Acción a través de un vínculo directo. En este ejemplo, agrega una nueva intención para las notificaciones push que proporcione 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 + que está junto a Intents en el menú de navegación de la izquierda para crear un intent nuevo.
2. Asigna el nombre Class Canceled a este intent nuevo.
3. En la sección Frases de entrenamiento, agrega Cancelations como una expresión del usuario.
4. En la sección Entregas, activa la opción Habilitar llamada de webhook para este intent.
5. Haz clic en Guardar en la parte superior de la página.

Enviar notificaciones de prueba durante la conversación

En producción, debes tener una secuencia de comandos separada del código de cumplimiento de la acción que envíe 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 solo se usa para 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 una intent para probar las notificaciones push:

1. Para realizar pruebas y depuraciones, configura un intent nuevo que te permita enviar notificaciones push a los usuarios suscritos. En la consola de Dialogflow, haz clic en el botón + que está junto a Intents en el menú de navegación de la izquierda 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 del usuario.
4. En la sección Entregas, activa la opción Habilitar llamada 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 la intención Clase cancelada:

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 de invocación implícita. Este paso es necesario para que Dialogflow reconozca que los usuarios pueden iniciar tu conversación con la intención 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 elige Actions en la barra de navegación de la izquierda.
6. Haz clic en Clase cancelada en la lista Acciones.
7. En la sección Participación del usuario, activa la opción ¿Quieres enviar notificaciones push?.
8. Establece un título del contenido descriptivo que explique la notificación push. El contexto será "¿Te parece bien si te envío notificaciones push sobre ?", así que asegúrate de que el título sea descriptivo y suene bien cuando se pronuncie en voz alta. Para este ejemplo, configura el Título del contenido como class cancelations.
9. Haz 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:

Carga 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');

Chips de sugerencias de actualización

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

Para conectarte a tu 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');

Ofrecer la configuración de notificaciones de cancelación de clases

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 este:

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 función de cumplimiento para intents nuevas

Cuando el usuario diga que quiere suscribirse a las notificaciones push, llama al asistente UpdatePermission para solicitarle permiso. Si la operación se realiza correctamente, el argumento PERMISSION se agregará a los argumentos del objeto conv, que puedes verificar para cambiar el enfoque de 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 la intención Class Canceled que se activa cuando se presiona 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 información más dinámica sobre qué clase 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 de destino. En este ejemplo, activar el intent de Test Notification iterará en tu base de datos de Firestore y enviará notificaciones push a cada usuario que se haya suscrito a las notificaciones.

Recuerda que, en este ejemplo, incluyes el código que envía la notificación push en la respuesta del webhook y activas ese código invocando una intención de prueba en tu conversación. En las acciones que deseas publicar, el código de la notificación push debe existir en un lenguaje de secuencias de comandos independiente de tu cumplimiento.

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 actualizado del webhook en Firebase:

firebase deploy

Nota: Puedes encontrar la información más reciente sobre el uso del simulador de Actions en la guía del simulador de Actions. Úsala como referencia si tienes algún problema con los pasos que se mencionan a continuación.

Para probar las notificaciones en el simulador de Actions, 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 tu Acción para enviarte notificaciones push, escribe yes y presiona Intro.
6. Escribe yes y presiona Intro. Tu Cuenta de Google ahora debería estar suscrita a las notificaciones push de esta acción.

Si recibes un error cuando intentas suscribirte a las notificaciones push en el paso 4, vuelve a Build > Actions > Class Canceled y desactiva las notificaciones push. Haz clic en Save, vuelve a activar las notificaciones push, haz clic en Save de nuevo y, luego, intenta realizar la prueba en el simulador otra vez.

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 unos minutos, deberías recibir una notificación push del Asistente en tu dispositivo móvil que diga "Notificación de prueba de Action Gym". Si presionas esta notificación, se te vinculará directamente con la intención Class Canceled de tu acción.

Si tienes problemas para que aparezca la notificación, sigue las instrucciones de prueba en tu teléfono. Abre Asistente en tu teléfono y di "talk to my test app". Luego, sigue las instrucciones de prueba anteriores desde el 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 tu Acción, pero estas se basan en tener usuarios que descubran y usen tu Acción.

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

En este paso, aprenderás qué es un vínculo del Asistente, cómo crear uno para la intención 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 un desafío, especialmente cuando deben invocar tu Acción de forma explícita en Asistente. Un vínculo de Asistente alivia esta fricción, ya que les brinda a los usuarios un vínculo directo a tu Acción. Cuando un usuario sigue tu vínculo de Asistente en un dispositivo compatible con 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 dispositivo que no admita el Asistente, se lo dirigirá a la ficha de tu directorio de Actions (si se publicó) para que el vínculo pueda seguir promocionando tu Action entre esos usuarios.

Los vínculos del Asistente pueden ser una herramienta de participación útil, por lo que debes crear uno si planeas anunciar tu Acción a través de tu sitio web o redes sociales. Solo 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 tu Acción. Mientras tu proyecto esté en estado de borrador, el vínculo solo funcionará en tus propios dispositivos. Las demás personas serán redireccionadas a una página de error 404 en el directorio de Actions.
• Puedes permitir que los usuarios prueben un vínculo de Asistente antes de publicarlo lanzando tu Acción en un entorno alfa o beta. Ten en cuenta que solo los usuarios que participen en tu versión alfa o beta podrán probar el vínculo de Assistant.
• Asegúrate de que la intención de destino de tu vínculo de Asistente cause una buena primera impresión en los usuarios nuevos. Tu intent de bienvenida es el destino predeterminado para un vínculo de Assistant porque ya debería hacer un buen trabajo presentando tu Acción.

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

Activa los vínculos del Asistente

Sigue estos pasos para crear un vínculo de Assistant para la intención de bienvenida:

1. En la Consola de Actions, haz clic en la pestaña Develop y elige 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 ¿Quieres habilitar una URL para esta acción?.
4. Establece un título del vínculo descriptivo que describa tu acción. Crea un título que sea un par simple de verbo y sustantivo que describa lo que el usuario puede lograr con tu acción. En este ejemplo, establece el título del vínculo como learn about Action Gym.
5. Copia el fragmento de código HTML que se encuentra en la parte inferior de esta página y guárdalo para usarlo más adelante.
6. Haz clic en Guardar en la parte superior de la página.

Implementa un sitio web de prueba

Para probar tu vínculo de Assistant, 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 debes agregar tu vínculo de Asistente.

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

En el archivo index.html, pega el fragmento de código HTML de tu vínculo de Asistente en el elemento body. El archivo debería verse 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 tu vínculo del Asistente

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

firebase deploy

Cuando termine de ejecutarse el comando de implementación, anota la URL de Hosting en el resultado.

Ve a esta URL en el navegador web de tu dispositivo móvil y deberías ver el vínculo del Asistente en tu sitio web de prueba. Si haces clic en este vínculo en tu dispositivo móvil, deberías acceder a la intención de bienvenida de tu Acción en Asistente.

También puedes intentar ir a la URL de Hosting en un navegador para computadoras, que debería llevarte a una página 404 en el directorio de Assistant, ya que tu Acción no está publicada.

6. Próximos pasos

¡Felicitaciones!

Ahora ya sabes la importancia de la participación del usuario cuando desarrollas una Acción, qué funciones de participación del usuario está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 del usuario y Documentos de vínculos de Asistente: Documentación oficial de Actions on Google sobre las funciones que se analizan en este codelab y la participación del usuario en general.
• Análisis de retención de usuarios: Documentación sobre la función de análisis de la consola de Actions que muestra la retención de usuarios de tu acción publicada.
• Lineamientos sobre el diseño de conversaciones: Prácticas recomendadas y lineamientos para diseñar funciones de participación del usuario
• Repositorio de GitHub de Actions on Google: Código de muestra y bibliotecas
• r/GoogleAssistantDev: Es 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 lo estamos haciendo.