Vínculos de Asistente

Puedes generar una URL que se vincule directamente a un intent específico de tu Acción. Los usuarios que hacen clic en un vínculo de Asistente (antes denominado vínculos de acciones) en un navegador web o para dispositivos móviles se dirigen al Asistente en su dispositivo, donde interactúan directamente con tu acción.

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

A continuación, se detallan algunas situaciones en las que los vínculos de Asistente pueden resultar útiles:

  • Vinculación de usuarios a instrucciones guiadas por voz desde un sitio web de instructivos.
  • Vinculación de usuarios a una experiencia de asistencia al cliente desde una página de ayuda.
  • Vincular usuarios a un intent de actualización para que puedan habilitar las actualizaciones futuras

Puedes generar vínculos del 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.

Para generar una URL para una Acción, sigue estos pasos:

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

Después de ingresar la información, podrás 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.

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 del Asistente en un dispositivo, sigue estos pasos:

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

Una vez que confirmes las funciones de vinculación de Asistente como se esperaba, debes volver a implementar tu Acción a fin de que el vínculo esté disponible para tus usuarios.

De manera opcional, los vínculos de Asistente pueden contener un intent y parámetros en la URL. Usa la sección Parámetros de la campaña para agregar parámetros de la 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 buscará coincidencias en el intent principal sin ningún parámetro, de manera similar al comportamiento de "Hablar con app_name".
  • Si habilitaste el intent MAIN de forma explícita, Asistente pasará 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

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 configurar 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 del usuario.
$param Nombre completo de un parámetro de intent especificado en el paquete de acciones.
$value Valor codificado como URL del tipo declarado para $param en el paquete de acciones.
$utm_param Lista de uno o más tipos de parámetros de UTM. Los valores válidos son utm_source, utm_medium, utm_campaign, utm_term y utm_content.
$utm_value El valor de string del parámetro de UTM.

Si el vínculo de Asistente contiene un intent integrado (el intent comienza con actions.intent.), Asistente de Google intentará extraer los parámetros de intent integrados en la URL y los pasará a la 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 tu 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

En el caso de los intents de usuario, Asistente de Google extrae solo los parámetros definidos por tu Acción como parte del intent y descarta cualquier otro parámetro.

En el siguiente ejemplo, se muestra cómo especificar una URL de vínculo de Asistente que incluya un intent del 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',
}

Los parámetros de UTM son cadenas que Asistente de Google envía a tu acción cuando los usuarios hacen clic en un vínculo de Asistente. Más adelante, puedes usar la información contenida en estas strings para obtener estadísticas.

Entre los parámetros de UTM que envía Asistente a tu acción, se 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 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 en el 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',
}

Los vínculos enriquecidos de Asistente te brindan una manera de aumentar el descubrimiento de tu Acción a través de tu sitio web mediante asistencia.js. Los usuarios pueden probar tu acción y vincular su Cuenta de Google a 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 de Asistente enriquecido.

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

Cuando se usan con la vinculación de cuentas, los vínculos de Asistente enriquecido utilizan tu URL de autorización, que se establece en tu proyecto en la Consola de Actions. Para obtener más información, consulta la documentación de vinculación de cuentas.

Requisitos previos

Para usar vínculos de Asistente enriquecido, necesitarás lo siguiente:

Desarrollo local

Para incluir un vínculo enriquecido de Asistente en tu sitio web, sigue estos pasos:

  1. Incluye la siguiente biblioteca JavaScript en tu página y reemplaza <PROJECT_ID> por el ID del 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 en alguna parte de tu página. Se cargará el botón intercalado "Probar con el 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>
    

Activación proactiva

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

  1. Agrega un id a tu etiqueta del grupo de vinculaciones 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 del Asistente enriquecido solo funcionan para los dominios que te pertenecen y que verificaste con Google. Cuando realizas desarrollos locales, este requisito se omite si se tiene acceso al proyecto de Acciones, se accede a tu Cuenta de Google y se configura el parámetro de consulta 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 los vínculos enriquecidos de Asistente, haz lo siguiente:

  1. Registra tu dominio público en la Consola de Actions, en 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 distribuir la URL del vínculo de Asistente y hacer referencia a ella fuera del directorio o de otros servicios de Google:

  • Sigue admitiendo todos los vínculos de Asistente. Si distribuyes un vínculo de Asistente que luego se interrumpe, es posible que tu proyecto de acciones se marque en mal estado y se quite.
  • Publicar un vínculo significa que admites la activación de fuentes no confiables. Para las acciones vinculadas, debes confirmar explícitamente con el usuario antes de realizar cualquier acción en el mundo real. Por ejemplo, una acción que desactiva un dispositivo de 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 un contenido.