Vínculos de Asistente

Puedes generar una URL que se vincule directamente con un intent específico de tu acción. Se dirige a los usuarios que hacen clic en un vínculo de Asistente (antes llamados vínculos de acción) en un navegador web o dispositivo móvil a Asistente en su dispositivo, donde interactúan directamente con tu acción.

Los vínculos de Asistente son diferentes de los vínculos web de directorio, que envían a un usuario a la página de tu acción en el directorio de Asistente.

Estas son algunas situaciones en las que pueden ser útiles los vínculos de Asistente:

• Vincular a los usuarios a instrucciones guiadas por voz de un sitio web de instrucciones
• Vincular usuarios a una experiencia de asistencia al cliente desde una página de ayuda
• Vincular a los usuarios a un intent de actualización para que puedan aceptar recibir actualizaciones futuras

Genera un vínculo de Asistente

Puedes generar vínculos de Asistente desde tu proyecto en la Consola de Actions. Los vínculos de Asistente están disponibles en todos los canales de implementación (alfa, beta y producción). Por ejemplo, si el vínculo de Asistente está habilitado en la versión alfa de tu acción, el vínculo estará disponible para los verificadores alfa.

Si deseas generar una URL para una acción, sigue estos pasos:

1. En la Consola de Actions, navega a Deploy > Assistant links.
2. En Intent, selecciona el intent para el que deseas generar un vínculo.
3. Habilita la opción ¿Quieres habilitar la vinculación de intent_name?
4. (Opcional) En la sección Campaign parameters, ingresa la información que también quieras capturar en el vínculo como parámetros de URL.
5. (Opcional) Ingrese un Título del vínculo. Usa este título para describir lo que hace la acción. Por ejemplo, si tu acción lleva al usuario un flujo de transacción para comprar entradas de un concierto, el título del vínculo podría ser "comprar entradas de concierto".

Después de ingresar tu información, puedes ver y copiar la URL generada o el fragmento de código generado para el vínculo de Asistente. Usa el vínculo de Asistente donde quieras dirigir a los usuarios a esta acción específica.

Nota: Si habilitas un vínculo de Asistente después de implementar tu acción, debes volver a implementarla para que el vínculo se aplique.

Nota: Los usuarios de Dialogflow deben seguir los pasos que se indican en esta página.

Vínculos de Asistente de prueba

Puedes probar los vínculos de Asistente para cualquier intent (principal o personalizado, con o sin parámetros) a través del simulador o en un dispositivo.

Para probar el vínculo de Asistente en un dispositivo, sigue estos pasos:

1. Genera el vínculo de Asistente en la Consola de Actions.
2. Envíate el vínculo de Asistente como URL a ti mismo en un correo electrónico, mensaje de chat o algún otro formato.
3. En un dispositivo compatible con el Asistente, accede al Asistente con la misma cuenta que usaste para crear el proyecto de acciones.
4. En el mismo dispositivo, haz clic en el vínculo del Asistente que te enviaste.

Una vez que confirmes que la vinculación de Asistente funciona según lo esperado, debes volver a implementar la acción para que el vínculo esté disponible para tus usuarios.

Parámetros de vinculación de Asistente

De manera opcional, los vínculos de Asistente pueden contener un intent y parámetros en la URL. Usa la sección Campaign parameters para agregar parámetros de campaña.

Cuando un vínculo de Asistente no contiene parámetros adicionales, Asistente de Google se vincula al intent MAIN (actions.intent.MAIN) de tu acción con el siguiente comportamiento:

• Si no habilitaste explícitamente el intent MAIN en el vínculo de Asistente, Asistente hace coincidir el intent principal sin ningún parámetro, de manera similar al comportamiento de "Hablar con app_name".
• Si habilitaste de forma explícita el intent MAIN, Asistente pasa los parámetros a tus acciones.

A continuación, se muestra un ejemplo de una URL de vínculo de Asistente que usa el intent MAIN sin parámetros adicionales:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4

Especificación de URL del vínculo de Asistente

La sintaxis general de la URL de un vínculo de Asistente es la siguiente:

https://assistant.google.com/services/invoke[/$action_id][?intent=$intent&param.$param=$value][&$utm_param=$utm_value]

Los parámetros de URL que puedes establecer se describen en la siguiente tabla:

Parámetro de URL	Descripción
$action_id	Es el identificador numérico de la acción.
$intent	Es el nombre completo de un intent integrado o de usuario.
$param	Nombre completo de un parámetro de intent especificado en el paquete de acción.
$value	Valor codificado en formato URL de tipo declarado para $param en el paquete Action.
$utm_param	Lista de uno o más tipos de parámetros de UTM. Entre los valores válidos, se incluyen los siguientes: utm_source, utm_medium, utm_campaign, utm_term y utm_content.
$utm_value	Es el valor de string del parámetro UTM.

URLs de Asistente vinculadas con intents integrados

Si el vínculo de Asistente contiene un intent integrado (el intent comienza con actions.intent.), Asistente de Google intenta extraer los parámetros de intent integrados en la URL y pasarlos a tu acción. Se quitarán los parámetros que Asistente no comprenda como parámetros de intent integrados.

En el caso de las acciones de conversación, Asistente envía estos parámetros a la entrega como parte del mensaje AppRequest.

En el siguiente ejemplo, se muestra cómo podrías especificar una URL de vínculo de Asistente que incluya un intent integrado con un solo parámetro de intent:

https://assistant.google.com/services/invoke/uid/0000008ddd7eabec?intent=actions.intent.PLAY_GAME&param.name=%22ExampleGame%22

URLs de Asistente vinculadas con intents de usuario

Para los intents de usuario, Asistente de Google solo extrae los parámetros que define tu acción como parte del intent y descarta cualquier otro parámetro.

En el siguiente ejemplo, se muestra cómo podrías especificar una URL de vínculo de Asistente que incluya un intent de usuario:

https://assistant.google.com/services/invoke/uid/0000001f575305a0?intent=NEWS_UPDATE_DEEP_LINK&param.topic=sports

Para la URL de ejemplo anterior, en AppRequest, Asistente agrega un objeto JSON de la siguiente manera:

argument {
  name: 'topic',
  raw_text: 'sports',
  text_value: 'sports',
}

URLs de vinculación de Asistente con parámetros de UTM

Los parámetros de UTM son strings que Asistente de Google envía a tu acción cuando los usuarios hacen clic en un vínculo de Asistente. Puedes usar la información que contienen estas strings más adelante para las estadísticas.

Los parámetros de UTM que Asistente envía a tu acción incluyen los siguientes:

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content

En el siguiente ejemplo, se muestra cómo podrías especificar una URL de vínculo de Asistente que incluya parámetros de UTM:

https://assistant.google.com/services/invoke/uid/000000d139bbc4d4?utm_source=Google&utm_medium=email&utm_campaign=holiday+sale

Para la URL de ejemplo anterior, Asistente agrega los siguientes argumentos al mensaje AppRequest:

argument {
  name: 'utm_source',
  raw_text: 'Google',
  text_value: 'Google',
}
argument {
  name: 'utm_medium',
  raw_text: 'email',
  text_value: 'email',
}
argument {
  name: 'utm_campaign',
  raw_text: 'holiday sale',
  text_value: 'holiday sale',
}

Vínculos del Asistente

Los vínculos enriquecidos de Asistente te permiten aumentar el descubrimiento de acciones en tu sitio web mediante help.js. Los usuarios pueden probar tu acción y vincular su Cuenta de Google con tu servicio mediante la vinculación de cuentas.

Cuando un usuario visita tu sitio web, ve el botón "Probar con Asistente de Google", que activa el flujo de vínculos del Asistente.

Si habilitas la vinculación de cuentas para tu acción, los usuarios podrán acceder a ella en cualquiera de los dispositivos compatibles con Asistente. Además, los usuarios pueden vincular su cuenta con su servicio a su Cuenta de Google, lo que permite una experiencia más personalizada.

Cuando se usa con la vinculación de cuentas, las vinculaciones de Asistente de Rich usan tu URL de autorización, que se establece en tu proyecto en la Consola de Actions. Para obtener más información, consulte la documentación sobre la vinculación de cuentas.

Nota: Si el usuario no accedió a su Cuenta de Google, el vínculo de Asistente de Rich activa tu acción en Asistente en el dispositivo del usuario (si Asistente está disponible) o envía al usuario a la página del directorio de Asistente de tu acción.

Requisitos previos

Para usar vínculos del Asistente Rich, necesitas lo siguiente:

• Proyecto de acciones.
• Vínculo de Asistente habilitado para tu acción.
• (Opcional) Se habilitó la vinculación de las cuentas para tu acción.

Desarrollo local

Para incluir un vínculo enriquecido de Asistente en tu sitio web, completa los siguientes pasos:

1. Incluye la siguiente biblioteca de JavaScript en tu página y reemplaza <PROJECT_ID> por el ID de tu proyecto de acciones:

   <script async
   src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
   </script>
   

2. Agrega la siguiente etiqueta HTML a algún lugar de tu página. De esta manera, se carga el botón intercalado "Probar con Asistente de Google":

   <google-assistant-link-group>
     <!-- One or more <google-assistant-link> tags -->
     <google-assistant-link href="{ASSISTANT_LINK_1}">
     </google-assistant-link>
     <google-assistant-link href="{ASSISTANT_LINK_2}">
     </google-assistant-link>
   </google-assistant-link-group>
   

   Nota: Si un usuario del Asistente no accedió, el primer vínculo del Asistente activa el Asistente o lo redirecciona a la página del Directorio del Asistente para la acción.

Activación proactiva

Si quieres que el flujo de vínculos del Asistente enriquecido se inicie automáticamente cuando los usuarios visiten tu página por primera vez, usa la etiqueta <google-assistant-proactive-link>. Cuando aplica esta etiqueta, el vínculo se activa sin usuarios en su primera visita, sin que ellos seleccionen el botón intercalado.

Nota: Si bien la activación proactiva permanece activa durante un tiempo, los usuarios deben seleccionar ocasionalmente el botón intercalado para volver a activar el flujo de activación proactivo.

1. Agrega un id a tu etiqueta de grupo de vínculos de Asistente:

   <google-assistant-link-group id="my-group">
     <!-- One or more <google-assistant-link> tags -->
     <google-assistant-link href="{ASSISTANT_LINK_1}">
     </google-assistant-link>
     <google-assistant-link href="{ASSISTANT_LINK_2}">
     </google-assistant-link>
   </google-assistant-link-group>
   

2. Coloca una etiqueta <google-assistant-proactive-action-link> en tu página web y establece su atributo groupId en id:

   <google-assistant-link-group id="my-group">
     <!-- One or more <google-assistant-link> tags -->
     <google-assistant-link href="{ASSISTANT_LINK_1}">
     </google-assistant-link>
     <google-assistant-link href="{ASSISTANT_LINK_2}">
     </google-assistant-link>
   </google-assistant-link-group>
   
   <google-assistant-proactive-link
   groupId="my-group">
   </google-assistant-proactive-link>
   

Implementación

Los vínculos enriquecidos de Asistente solo funcionan para los dominios que posees y que verificaste con Google. Cuando se desarrolla de manera local, este requisito se omite mediante el acceso al proyecto de Actions, el acceso a tu Cuenta de Google y la configuración del parámetro de búsqueda dev=true en la etiqueta de la secuencia de comandos.

  <script async
    src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}&dev=true">
  </script>

Para implementar tu acción con vínculos enriquecidos de Asistente, haz lo siguiente:

1. Registra tu dominio público en la Consola de Actions, que está debajo de Deploy > Brand Verification > Connect Site.

2. Quita el parámetro de consulta dev=true de la secuencia de comandos:

   <script async
   src="https://actions.google.com/api/assist.js?projectId={PROJECT_ID}">
   </script>
   

Restricciones y prácticas recomendadas

Se aplican las siguientes restricciones y prácticas recomendadas para que la URL del vínculo de Asistente se pueda distribuir y hacer referencia fuera del directorio o de otros servicios de Google:

• Sigue admitiendo todos tus vínculos de Asistente. Si distribuyes un vínculo de Asistente que se interrumpe más tarde, es posible que tu proyecto de acciones se marque como en mal estado y se quite.

• La publicación de un vínculo significa que admites la activación desde fuentes no confiables. Para cualquier acción vinculada, debes confirmar explícitamente con el usuario antes de realizar cualquier acción en el mundo real. Por ejemplo, una acción que apaga un dispositivo de la casa inteligente debería pedirle al usuario que diga "¿Confirmas que quieres desactivar $applianceName?".

  En este contexto, una acción real es cualquier acción que afecta los servicios, los datos, los dispositivos, las redes, las computadoras o las APIs del usuario. Por ejemplo, enviar un correo electrónico, realizar una transacción, alterar el estado de un dispositivo de casa inteligente, crear una suscripción o actualizar contenido.