Vínculos de Asistente

Puedes generar una URL que vincule directamente a un intent específico de tu Acción. A los usuarios que hacen clic en un vínculo de Asistente (anteriormente denominados vínculos de Acciones) en un navegador web o para dispositivos móviles se los dirige a Asistente en su dispositivo, donde interactúa directamente con tu acción

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

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

  • Vincular a los usuarios a instrucciones guiadas por voz desde un sitio web instructivo
  • Vincular 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 la opción las actualizaciones futuras.

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 del Asistente está habilitado en la versión alfa versión de tu acción, el vínculo estará disponible para los verificadores de las versiones alfa.

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

  1. En la Consola de Actions, navega a Implementar > Vínculos de Asistente.
  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 la información que deseas. capturar además 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. Para Por ejemplo, si tu Acción lleva al usuario a un flujo de transacción para comprar entradas a un concierto, el título del vínculo podría ser "comprar entradas para conciertos".

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

Puedes probar los vínculos de Asistente en busca de 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 tu Asistente en un dispositivo, sigue estos pasos:

  1. Genera el vínculo del Asistente en la Consola de Actions.
  2. Enviarte el vínculo del Asistente como una URL a ti mismo en un correo electrónico, mensaje de chat u otro de un conjunto de datos tengan un formato común.
  3. En un dispositivo compatible con el Asistente, accede con la misma cuenta que usaste para crear tu proyecto de Actions.
  4. En el mismo dispositivo, haz clic en el vínculo de Asistente que te enviaste.

Una vez que confirmes que la vinculación de Asistente funciona como se espera, deberás volver a realizar la implementación tu Acción para 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 el En la sección Campaign parameters, puedes agregar parámetros de campaña.

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

  • Si no habilitaste el intent MAIN en el vínculo del Asistente, haz lo siguiente: Asistente hace coincidir el intent principal sin ningún parámetro, de manera similar a lo siguiente: para "Hablar con app_name".
  • Si habilitaste explícitamente el intent MAIN, Asistente pasa los parámetros. a tus Acciones.

Aquí hay un ejemplo de una URL de vínculo de Asistente con el intent MAIN sin parámetros adicionales:

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

La sintaxis general para la URL de un vínculo del 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 Nombre completo de un intent integrado o del usuario.
$param Es el nombre completo de un parámetro de intent especificado en el paquete de acción.
$value Valor codificado de URL del tipo declarado para $param en el Paquete de acción.
$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 cadena del parámetro de UTM.

Si el vínculo del Asistente contiene un intent integrado (el intent comienza con actions.intent.), el Asistente de Google intentará extraer cualquier intent integrado. parámetros en la URL y los pasa a tu acción. Cualquier parámetro que Asistente no entiende que se quitan los parámetros de intents integrados.

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

El siguiente ejemplo muestra cómo especificar una URL del vínculo del Asistente que incluye 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

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

El siguiente ejemplo muestra cómo especificar una URL del vínculo del Asistente que Incluye 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 como sigue:

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

Los parámetros de UTM son cadenas que el Asistente de Google envía a tu Acción cuando los usuarios hacen clic en un vínculo de Asistente. Puedes utilizar la información incluida en estas cadenas para análisis.

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

El siguiente ejemplo muestra cómo especificar una URL del vínculo del Asistente que incluye 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 en el AppRequest mensaje:

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 del Asistente permiten aumentar el descubrimiento de tu acción tu sitio web, con help.js. Los usuarios pueden probar tu Acción y vincular sus Cuenta de Google a tu servicio mediante la vinculación de cuentas.

Cuando un usuario visita tu sitio web, ve el mensaje "Probar con Asistente de Google" que activa el flujo de vínculos de Rich Assistant.

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 brinda una experiencia más personalizada.

Cuando se usan con la vinculación de cuentas, los vínculos de Rich Assistant usan tu URL de autorización, que se configura en tu proyecto en la Consola de Actions. Si quieres obtener más información, consulta la documentación sobre la vinculación de cuentas.

Requisitos previos

Para usar vínculos de Rich Assistant, necesitas lo siguiente:

Desarrollo local

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

  1. Incluye la siguiente biblioteca de 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 la página. Se carga la línea "Pruébalo 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>
    

Activación proactiva

Si quieres que el flujo de vínculos enriquecido de Asistente 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 usuarios en su primera visita, sin que ellos seleccionen el botón intercalado.

  1. Agrega un id a tu etiqueta del grupo de vinculaciones del 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 de Asistente enriquecido solo funcionan para los dominios que posees y que verificaste con Google. Cuando se desarrolla de forma local, este requisito se omite cuando 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 Implementar > Verificación de marca > 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 la URL del vínculo del Asistente se puedan distribuir y se haga referencia a ellas fuera del directorio o de otros servicios servicios:

  • Sigue admitiendo todos tus vínculos de Asistente. Si distribuyes un Asistente que se interrumpe posteriormente, es posible que tu proyecto de acciones se marque como en mal estado y debilitado.
  • Si publicas un vínculo, podrás activar la activación desde fuentes no confiables. Para cualquiera acciones vinculadas, debes confirmar explícitamente con el usuario antes de realizar la acción en el mundo real. Por ejemplo, una Acción que desactiva una casa inteligente El dispositivo debe hacer que el usuario diga: "¿Confirmas que quieres desactivar $applianceName?".

    En este contexto, una acción real es cualquier acción que afecta la servicios, datos, dispositivos, redes, computadoras o APIs. Por ejemplo, enviar un correo electrónico, realizar una transacción, alterar el estado de una casa inteligente a través de un dispositivo móvil, la creación de una suscripción o la actualización de contenido.