Widget web

El widget web es un cliente basado en la Web que puedes usar en tus aplicaciones web y para dispositivos móviles para que los usuarios interactúen con tu aplicación de agente a través de chat o voz. En esta guía, se proporciona una descripción general y las instrucciones de configuración.

Cuando se abre, el widget se puede mostrar como una ventana de diálogo flotante en la esquina inferior derecha, como un panel junto al contenido principal o en un modo de diálogo expandido para una conversación enfocada.

diagrama de arquitectura

Limitaciones

Actualmente, las respuestas de contenido enriquecido solo admiten el idioma inglés.

Configura el widget web

Para incorporar el widget en tu sitio web, sigue estos pasos:

  1. Haz clic en Implementar en la parte superior del compilador de agentes.
  2. Haz clic en Crear canal o Canal nuevo.
  3. Selecciona el tipo de canal Widget web.
  4. Ingresa un nombre para tu canal.
  5. Selecciona o crea una versión de la aplicación del agente.
  6. Configura otras preferencias, como el tema de color y el tipo de experiencia (chat, llamada o mixto).
  7. Haz clic en Crear canal para generar el código de implementación.
  8. Agrega el código de implementación al HTML de tu sitio web.
  9. Configura la autenticación para tus usuarios finales. El widget muestra una advertencia si usas el código de incorporación sin modificar sin configurar la autenticación. Para obtener detalles sobre las opciones y la configuración, consulta la sección Configura la autenticación.

Incorpora el widget en tu sitio web

Para agregar el widget a tu sitio web, debes agregar los siguientes fragmentos HTML.

El siguiente fragmento incluye una secuencia de comandos que se requiere para reCAPTCHA. Si se usa reCAPTCHA en el widget, se mostrará un aviso en la parte inferior del widget en el que se indica que el sitio está protegido por Google y que se aplican la Política de Privacidad de Google y las Condiciones del Servicio de Google. También puedes ocultar la insignia de reCAPTCHA.

Para admitir diseños responsivos, también puedes cargar chat-messenger-layout.css de forma opcional. El archivo chat-messenger-layout.css se usa para aplicar diseño responsivo y para deslizar el mensajero dentro y fuera de la vista cuando se usa render-mode="slide-in" o render-mode="slide-over". Como aplica diseño a body, puede afectar tu sitio web. Por lo tanto, puedes optar por no cargar chat-messenger-layout.css o copiar su contenido y, luego, integrarlo en tu propio CSS.

Para obtener el mejor rendimiento y garantizar diseños responsivos, sigue estas ubicaciones:

En la sección <header>, haz lo siguiente:

<header>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">

  <script defer src="https://www.gstatic.com/chat-messenger/sdk/prod/latest/chat-messenger.js"></script>

  <!-- Chat Messenger CSS -->
  <link rel="stylesheet" href="https://www.gstatic.com/chat-messenger/sdk/prod/latest/themes/chat-messenger-default.css">

  <!-- Optional responsive styling  -->
  <!-- <link rel="stylesheet" href="https://www.gstatic.com/chat-messenger/sdk/prod/latest/themes/chat-messenger-layout.css"> -->

  <!-- CSS customization -->
  <style>
    chat-messenger {
      z-index: 999;
      position: fixed;
      <!-- Your CSS customization goes here if needed -->
    }
  </style>
</header>

En la sección <body>, haz lo siguiente:


<body>
  <!-- Your website's main content goes here -->

  <script>
    window.addEventListener("chat-messenger-loaded", () => {
      chatSdk.registerContext(
        chatSdk.prebuilts.ces.createContext({
          deploymentName: "projects/YOUR_PROJECT_ID/locations/YOUR_REGION/apps/YOUR_APP_ID/deployments/YOUR_DEPLOYMENT_ID",
          tokenBroker: {
            enableTokenBroker: true,
            // If you enabled reCAPTCHA for the token broker, set enableRecaptcha to true.
            // enableRecaptcha: true,
          },
          // Automatically prompt the agent to start the conversation with a greeting.
          enableWelcomeEvent: true,
        }),
      );
    });
  </script>

  <!-- Messenger component -->
  <chat-messenger
    language-code="en"
    max-query-length="-1">
    <chat-messenger-chat-bubble
      chat-title="${your-chat-title}">
    </chat-messenger-chat-bubble>
  </chat-messenger>

  <!-- Page content continues -->
</body>

Iniciar la conversación automáticamente

De forma predeterminada, el widget de chat espera a que el usuario envíe el primer mensaje. Para que el agente inicie la conversación automáticamente con un saludo, configura enableWelcomeEvent: true en la función chatSdk.prebuilts.ces.createContext.

Cuando esta opción está habilitada, el widget envía automáticamente un evento welcome al agente cuando se inicializa la sesión de chat. El agente responde a este evento con su saludo configurado.

Consideraciones de seguridad

Cuando incorporas el widget como un elemento personalizado (<chat-messenger>) directamente en tu sitio web, el widget se ejecuta en un DOM de sombra en tu página de host. No aplica una zona de pruebas estricta (como un iframe) de forma predeterminada.

Debido a que el widget comparte el origen de la ventana con tu aplicación, se aplica lo siguiente:

  • Acceso al almacenamiento compartido: Cualquier secuencia de comandos que se ejecute dentro del componente personalizado del widget tiene acceso a window.sessionStorage y window.localStorage de la página host. Esto incluye tokens de autenticación o datos sensibles de la sesión que almacena el widget.
  • Secuencias de comandos entre sitios (XSS): Si el código de tu componente personalizado o las cargas útiles de contenido enriquecido contienen entradas no saneadas, se pueden aprovechar para ejecutar JavaScript arbitrario en el contexto de tu aplicación principal.

Para mantener la seguridad de tu aplicación y los datos de tus usuarios, debes hacer lo siguiente:

  1. Limpia el código personalizado: Asegúrate de que todo el código JavaScript y HTML personalizado que se use en los componentes o las cargas útiles personalizados se limpie de forma rigurosa.
  2. Valida las entradas: Trata todos los datos que se pasan al widget desde fuentes externas (incluidas las respuestas del agente) como no confiables.
  3. Controla el aislamiento: Si tus requisitos de seguridad exigen un aislamiento estricto entre el widget de chat y los datos de tu aplicación, debes implementar tu propio entorno de pruebas (por ejemplo, unir el componente del widget en un contenedor que controles y aisles).

Configura la transferencia a un agente humano

Antes de configurar el widget, asegúrate de que se hayan creado los recursos necesarios y de que se haya completado la implementación del proxy de WebChat.

  1. Configura el número de derivación.
    1. Crea un recurso PhoneNumber para tu proyecto.
      1. Usa un perfil de conversación válido configurado para la aplicación del agente.
      2. Asocia el perfil de conversación con el PhoneNumber para permitir que el sistema controle la derivación a un agente humano.
    2. Sigue las instrucciones para configurar el proxy de WebChat.
  2. Configuración del cliente de Webchat:

    1. Establece el atributo del proxy de WebChat para habilitar la función de transferencia en vivo. Ejemplo de fragmento de código:

      <chat-messenger service='{"name":"ces","deployment-id":"projects/YOUR_PROJECT_ID/locations/YOUR_REGION/apps/YOUR_APP_ID/deployments/YOUR_DEPLOYMENT_ID"}'
        liveHandoff="true"
      escalationNumber="projects/YOUR_PROJECT_ID/locations/global/phoneNumbers/YOUR_PHONE_NUMBER_ID"
        url-allowlist="*"
      >
        </chat-messenger>
      

Personalización de HTML

Puedes personalizar varios aspectos de cómo aparece y se comporta el diálogo de chat. Los elementos HTML chat-messenger y chat-messenger-container tienen los siguientes atributos:

Atributo Atribución de componentes Valor (opcional) Efecto
servicio chat-messenger Es el nombre del servicio obligatorio para el servicio de backend conectado.
url-allowlist chat-messenger * (lista de dominios de imágenes separados por comas)
logging-level chat-messenger DEPURAR <OMIT>
enable-audio-input-only chat-messenger-container Modo de solo voz
start-with-recording chat-messenger-container Requiere el modo Solo voz. El modo Solo voz se inicia en el momento en que se renderiza el contenedor de chat-messenger-container
enable-audio-input chat-messenger-container Agrega un botón para permitir el chat multimodal.
enable-file-upload chat-messenger-container Habilita la carga de imágenes
bot-writing-image chat-messenger-container cadena URL de la imagen que se renderiza mientras el bot "piensa"
chat-title-icon chat-messenger-container cadena URL de la imagen que se renderiza en la parte superior del chat (imagen de marca)
chat-title chat-messenger-container cadena Texto del título del chat
render-mode chat-messenger string ("slide-in" o "slide-over") Es el modo de renderizar el diálogo de chat en relación con el resto de la página. Las opciones son "slide-over" o "slide-in". Si no se especifica, el cliente puede especificar el posicionamiento. Los estilos son obligatorios para admitir el modo de renderización. chat-messenger-layout.css se puede usar como modelo de referencia.

Personalización de CSS

La personalización de la apariencia del widget se controla a través de un sistema de tokens de CSS. Si modificas estos tokens, puedes asegurarte de que la interfaz de chat sea coherente con tu marca y, al mismo tiempo, mantener la integridad y la accesibilidad del diseño.

Tokens de color

Estos tokens definen la paleta de colores para las superficies del widget, los elementos interactivos, el texto y los estados.

Propiedad Descripción Tema claro predeterminado Tema oscuro predeterminado
Contenedores y plataformas
--chat-messenger-color--surface Es el color de fondo principal del cuerpo del chat y del área del pie de página. #F8FAFD #1B1B1B
--chat-messenger-color--surface-container Es el color de fondo de los contenedores de widgets (por ejemplo, tarjetas de productos y carruseles) anidados en el chat. #FFFFFF #131314
--chat-messenger-color--surface-container-high Un fondo de énfasis alto para los elementos dentro de los widgets (por ejemplo, campos de entrada) #F0F4F9 #1E1F20
Marca / Acento
--chat-messenger-color--primary Es el color principal de la marca que se usa para los rellenos de énfasis alto y los botones principales. #303030 #E3E3E3
--chat-messenger-color--primary-container Es un color de fondo destacado para componentes clave, como las burbujas de mensajes de los usuarios. #E9EEF6 #282A2C
--chat-messenger-color--secondary Es el color de los elementos interactivos secundarios, como el botón "Enviar" o los botones tonales. #DDE3EA #333537
Texto e íconos
--chat-messenger-color--on-surface Es el color principal para el texto y los íconos que se muestran en los fondos de superficie estándar. #1F1F1F #E3E3E3
--chat-messenger-color--on-surface-variant Color de menor énfasis para el texto secundario y los íconos decorativos. #444746 #C4C7C5
--chat-messenger-color--on-primary Es el color del texto y los íconos que se colocan sobre los fondos de la marca principal. #F2F2F2 #303030
--chat-messenger-color--on-primary-container Es el color del texto y los íconos que se colocan sobre los fondos de contenedores principales. #1F1F1F #E3E3E3
--chat-messenger-color--on-secondary Es el color del texto y los íconos que se colocan sobre los fondos secundarios de la marca. #444746 #C4C7C5
Estados
--chat-messenger-color--state-layer-on-surface Es la superposición translúcida que se usa para indicar los estados de selección o de desplazamiento sobre las superficies estándar. Es el relleno de los componentes inhabilitados. #1F1F1F 8% #E3E3E3 8%
--chat-messenger-color--state-layer-on-primary Es la superposición translúcida que se usa para los estados de interacción sobre los elementos de color primario. #FFFFFF 8% #062E6F 8%
--chat-messenger-color--state-layer-on-secondary Es la superposición translúcida que se usa para los estados de interacción sobre los elementos de color secundario. #1F1F1F 8% #E3E3E3 8%
--chat-messenger-color--state-on-surface-mute Es el color del texto y los íconos inhabilitados. #444746 (38%) #C4C7C5 (38%)
Utilidad
--chat-messenger-color--outline Color para bordes generales, divisores y contornos decorativos. #C4C7C5 #444746
--chat-messenger-color--outline-variant Color para bordes sutiles (por ejemplo, el marco exterior de los widgets) #747775 al 16% #8E918F al 16%
--chat-messenger-color--outline-active Es el color del borde de los campos de entrada y los menús desplegables cuando están enfocados o activos. #747775 #8E918F
--chat-messenger-color--error Color llamativo contra la superficie para rellenos, íconos y texto, que indica urgencia. #B3261E #F2B8B5
--chat-messenger-color--error-container Es el color de relleno de fondo para los banners de error o los contenedores de alertas interactivos. #F9DEDC #8C1D18
--chat-messenger-color--on-error-container Texto e íconos colocados sobre el fondo del contenedor de errores. #8C1D18 #F9DEDC
--chat-messenger-color--link Es el color que se usa para los hipervínculos en los que se puede hacer clic en los mensajes o las descripciones. #0B57D0 #A8C7FA

Fichas de forma y elevación

Estos tokens controlan el radio de las esquinas y la profundidad visual (sombras) de los componentes del chat.

Propiedad Descripción Predeterminado
--chat-messenger-shape--corner-value-small Radio de esquina para elementos anidados pequeños dentro de widgets (por ejemplo, miniaturas de imágenes de productos) 8 px
--chat-messenger-shape--corner-value-medium Radio de esquina para elementos anidados dentro de widgets (por ejemplo, campos de entrada, imágenes) 16 px
--chat-messenger-shape--corner-value-large Radio de esquina para contenedores anidados dentro de widgets (por ejemplo, tarjetas de carrusel, tarjetas de acciones rápidas) 20 px
--chat-messenger-shape--corner-value-extra-large Es el radio de la esquina de la ventana de chat principal y los contenedores de widgets. 28 px
--chat-messenger-shape--corner-fully-rounded Se usa para botones y elementos interactivos con forma de píldora para garantizar un extremo completamente circular. 100 px
--chat-messenger-elevation Es la sombra de cuadro que se aplica a los elementos flotantes y al componente principal del chat. 0 1px 2px 0 rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15)

Tokens de tipografía

Estos tokens definen el tipo de letra y la escala específica (tamaño, grosor y espaciado) que se usan en toda la interfaz.

Propiedad Uso previsto Predeterminado
--chat-messenger-font-family Familia de fuentes principal Google Sans
Título grande Encabezados destacados
--chat-messenger-typescale--title-large-font-size 18 px
--chat-messenger-typescale--title-large-font-weight 400
--chat-messenger-typescale--title-large-line-height 24 px
--chat-messenger-typescale--title-large-letter-spacing 0
Título mediano Encabezados de sección dentro de los widgets
--chat-messenger-typescale--title-medium-font-size 16 px
--chat-messenger-typescale--title-medium-font-weight 500
--chat-messenger-typescale--title-medium-line-height 24 px
--chat-messenger-typescale--title-medium-letter-spacing 0
Título pequeño
--chat-messenger-typescale--title-small-font-size Subencabezados o títulos dentro de tarjetas más pequeñas 14px
--chat-messenger-typescale--title-small-font-weight 500
--chat-messenger-typescale--title-small-line-height 20 px
--chat-messenger-typescale--title-small-letter-spacing 0
Body large Descripciones largas.
--chat-messenger-typescale--body-large-font-size 16 px
--chat-messenger-typescale--body-large-font-weight 400
--chat-messenger-typescale--body-large-line-height 24 px
--chat-messenger-typescale--body-large-letter-spacing 0
Body medium Texto de la IU estándar
--chat-messenger-typescale--body-medium-font-size 14px
--chat-messenger-typescale--body-medium-font-weight 400
--chat-messenger-typescale--body-medium-line-height 20 px
--chat-messenger-typescale--body-medium-letter-spacing 0
Texto de cuerpo pequeño Metadatos y descripciones secundarios
--chat-messenger-typescale--body-small-font-size 12 px
--chat-messenger-typescale--body-small-font-weight 400
--chat-messenger-typescale--body-small-line-height 16 px
--chat-messenger-typescale--body-small-letter-spacing 0.1
Etiqueta grande Texto dentro de los botones y los chips de acción principales
--chat-messenger-typescale--label-large-font-size 14px
--chat-messenger-typescale--label-large-font-weight 500
--chat-messenger-typescale--label-large-line-height 20 px
--chat-messenger-typescale--label-large-letter-spacing 0
Label medium Texto del botón secundario y etiquetas de campo
--chat-messenger-typescale--label-medium-font-size 12 px
--chat-messenger-typescale--label-medium-font-weight 500
--chat-messenger-typescale--label-medium-line-height 16 px
--chat-messenger-typescale--label-medium-letter-spacing 0.1
Etiqueta pequeña Microetiquetas y texto de insignias
--chat-messenger-typescale--label-small-font-size 11 px
--chat-messenger-typescale--label-small-font-weight 500
--chat-messenger-typescale--label-small-line-height 16 px
--chat-messenger-typescale--label-small-letter-spacing 0.1

Tokens de espaciado

Estos tokens mantienen una densidad de diseño coherente, ya que definen los márgenes, los rellenos y los espacios entre los elementos.

Propiedad Predeterminado
--chat-messenger-spacing--half 4 px
--chat-messenger-spacing--one 8 px
--chat-messenger-spacing--one-and-half 12 px
--chat-messenger-spacing--two 16 px
--chat-messenger-spacing--two-and-half 20 px
--chat-messenger-spacing--three 24 px
--chat-messenger-spacing--three-and-half 28 px
--chat-messenger-spacing--four 32 px

Eventos de JavaScript

Messenger activa una variedad de eventos para los que puedes crear objetos de escucha de eventos. El destino de estos eventos es el elemento chat-messenger.

Para agregar un objeto de escucha de eventos para el elemento chat-messenger, agrega el siguiente código de JavaScript, en el que event-type es uno de los nombres de eventos que se describen en esta sección:


const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.addEventListener('event-type', function (event) {
  // Handle event
  ...
});

Se admiten los siguientes tipos de eventos:

  • chat-messenger-loaded: Este evento se activa cuando el elemento chat-messenger se carga y se inicializa por completo.

  • chat-messenger-close

  • chat-messenger-error: Este evento se produce cuando el agente de CES envía un código de estado de error. La estructura del evento se ve de la siguiente manera:

    eventId= `chat-messenger-error-v2`
    event.details {
      message: string;
      code: number | undefined;
      status: number | string;
    }
    
  • df-update-cart-count: Este evento ocurre cuando se realizan las acciones "Agregar al carrito", "Ajustar la cantidad de artículos" o "Borrar artículo" en los elementos de contenido enriquecido product_carousel, product_detail o product_comparison. La estructura del evento se ve de la siguiente manera:

    {
      "detail": {
        "count": <cart_item_count>,
      }
    }
    

Funciones de JavaScript

El elemento chat-messenger proporciona funciones a las que puedes llamar para modificar su comportamiento.

renderCustomText

Esta función renderiza un mensaje de texto, como si proviniera de la aplicación del agente como una respuesta de texto.

Por ejemplo:

const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.renderCustomText('Custom text');

renderCustomCard

Esta función renderiza una tarjeta personalizada, como si proviniera de la aplicación del agente como un mensaje de respuesta enriquecida. El formato de la respuesta de carga útil personalizada se define en la sección Mensajes de respuesta enriquecida.

Por ejemplo:

const chatMessenger = document.querySelector('chat-messenger');
const payload = [
  {
    "type": "info",
    "title": "Info item title",
    "subtitle": "Info item subtitle",
    "image": {
      "src": {
        "rawUrl": "https://example.com/images/logo.png"
      }
    },
    "actionLink": "https://example.com"
  }];
chatMessenger.renderCustomCard(payload);

Configura la autenticación

Todas las solicitudes a la API que realiza el widget web a los servicios de backend de Google deben autenticarse. Esto se logra con un token de acceso de OAuth 2.0 de corta duración.

La identidad asociada con este token, ya sea un usuario final o una cuenta de servicio, debe tener los permisos de IAM necesarios para interactuar con el agente.

En los apartados restantes, se describen las formas en que puedes configurar la autenticación.

Configura un agente de tokens

Un agente de tokens es un servicio web que se ejecuta en tu proyecto de Google Cloud y genera un token de acceso en nombre de una cuenta de servicio de tu propiedad. El widget web puede llamar automáticamente a la URL de tu agente de tokens al comienzo de una conversación para obtener un token nuevo que se usará cuando se comunique con la API de CX Agent Studio.

Puedes configurar un agente de tokens de dos maneras: alojado en Google o alojado de forma independiente.

Alojado en Google

Usa el agente de tokens que proporciona Google para permitir el acceso público a tu widget de chat:

  • Cuando crees la configuración de la implementación y del widget, habilita el acceso público y, de manera opcional, habilita las verificaciones de origen y de reCAPTCHA (se recomienda para evitar la falsificación de identidad y el abuso).
  • El widget de chat solicitará un token de alcance de sesión al agente de tokens proporcionado por Google y lo usará para las sesiones de chat.

Autoalojado

Sigue estos pasos para configurar un agente de tokens autoalojado:

  • Crea una cuenta de servicio en tu proyecto y otórgale el rol de cliente de Paquete de interacción con los clientes.
  • Implementa una función de Cloud Run Functions con el código de muestra del agente de tokens que proporcionamos.

Consulta las instrucciones detalladas paso a paso en el repositorio de código abierto.

Configura OAuth2

Un cliente de OAuth2 permite que el widget web inicie un flujo de autenticación para el usuario final. Por lo general, esto significa que se abre una ventana de diálogo en la que el usuario accede a su Cuenta de Google (o a otros proveedores) y el widget web recibe un token para operar en nombre del usuario.

Elige esta opción para exigir que los usuarios finales accedan antes de usar el agente, en el que se usan las credenciales de usuario para acceder a la aplicación del agente.

Estos son los pasos principales que debes seguir:

  • En la consola de Google Cloud , ve a Google Auth Platform y selecciona Clientes.
  • Haz clic en Crear cliente.
  • Selecciona Aplicación web como el tipo de cliente.
  • Ingresa un nombre para tu cliente nuevo.
  • Agrega la URL de tu sitio web a los Orígenes autorizados de JavaScript y a los URI de redireccionamiento autorizados.
  • Haz clic en Crear y espera 5 minutos antes de continuar.

Después de seguir los pasos, obtendrás un ID de cliente con el siguiente formato:

123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com

Proporciona este valor en el atributo oauth-client-id del componente web chat-messenger.

Compila tu propia API de autenticación

Compila tu propia API para controlar la autenticación y autorización del usuario final, que devuelve un token de acceso de Google o un JWT firmado que tiene permiso para llamar a runSession en tu app.

Para obtener información sobre cómo usar la API de CX Agent Studio, consulta Acceso a la API.