Widget da Web

O widget da Web é um cliente baseado na Web que pode ser usado em aplicativos da Web e para dispositivos móveis para que os usuários interajam com o aplicativo do agente usando chat ou voz. Este guia oferece uma visão geral e instruções de configuração.

Quando aberto, o widget pode ser exibido como uma janela de diálogo flutuante no canto inferior direito, como um painel ao lado do conteúdo principal ou em um modo de diálogo expandido para uma conversa focada.

diagrama de arquitetura

Limitações

No momento, as respostas de conteúdo avançado só estão disponíveis em inglês.

Configurar o widget da Web

Para incorporar o widget ao seu site:

  1. Clique em Implantar na parte de cima do criador de agentes.
  2. Clique em Criar canal ou Novo canal.
  3. Selecione o tipo de canal Widget da Web.
  4. Insira um nome para o canal.
  5. Selecione ou crie uma versão do aplicativo do agente.
  6. Configure outras preferências, como o tema de cores e o tipo de experiência (chat, ligação ou mista).
  7. Clique em Criar canal para gerar o código de implantação.
  8. Adicione o código de implantação ao HTML do seu site.
  9. Configure a autenticação para os usuários finais. O widget vai mostrar um aviso se você usar o código de incorporação não modificado sem configurar a autenticação. Para detalhes sobre opções e configuração, consulte a seção Configurar autenticação.

Incorporar o widget ao seu site

Para adicionar o widget ao seu site, inclua os snippets de HTML a seguir.

O snippet abaixo inclui um script necessário para o reCAPTCHA. Se o reCAPTCHA for usado no widget, um aviso será exibido na parte de baixo do widget indicando que o site está protegido pelo Google e que a Política de Privacidade do Google e os Termos de Serviço do Google se aplicam. Também é possível ocultar o selo reCAPTCHA.

Para oferecer suporte a layouts responsivos, também é possível carregar chat-messenger-layout.css. O arquivo chat-messenger-layout.css é usado para estilizar a responsividade e para deslizar o Messenger para dentro e para fora da visualização ao usar render-mode="slide-in" ou render-mode="slide-over". Como ele estiliza body, pode afetar seu site. Portanto, você pode optar por não carregar chat-messenger-layout.css ou copiar o conteúdo e integrá-lo ao seu próprio CSS.

Para ter o melhor desempenho e garantir layouts responsivos, siga estas posições:

Na seção <header>:

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

Na seção <body>:


<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 a conversa automaticamente

Por padrão, o widget de chat espera o usuário enviar a primeira mensagem. Para que o agente inicie a conversa automaticamente com uma saudação, defina enableWelcomeEvent: true na função chatSdk.prebuilts.ces.createContext.

Quando essa opção está ativada, o widget envia automaticamente um evento welcome ao agente quando a sessão de chat é inicializada. O agente responde a esse evento com a saudação configurada.

Considerações sobre segurança

Ao incorporar o widget como um elemento personalizado (<chat-messenger>) diretamente no seu site, ele é executado em um shadow DOM na página do host. Ele não aplica o sandbox estrito (como um iframe) por padrão.

Como o widget compartilha a origem da janela com seu aplicativo:

  • Acesso ao armazenamento compartilhado:todos os scripts em execução no componente personalizado do widget têm acesso a window.sessionStorage e window.localStorage da página host. Isso inclui tokens de autenticação ou dados de sessão sensíveis armazenados pelo próprio widget.
  • Scripting em vários sites (XSS): se o código do componente personalizado ou os payloads de conteúdo avançado contiverem entradas não limpas, eles poderão ser explorados para executar JavaScript arbitrário no contexto do aplicativo principal.

Para manter a segurança do aplicativo e dos dados dos usuários, você precisa:

  1. Limpar o código personalizado:verifique se todo o JavaScript e HTML personalizados usados em componentes ou payloads personalizados estão devidamente limpos.
  2. Validar entradas:trate todos os dados transmitidos ao widget de fontes externas (incluindo respostas do agente) como não confiáveis.
  3. Gerenciar o isolamento:se os requisitos de segurança exigirem um isolamento rigoroso entre o widget de chat e os dados do aplicativo, você precisará implementar seu próprio sandbox (por exemplo, encapsular o componente do widget em um contêiner que você controla e isola).

Configurar o encaminhamento para agente humano

Antes de configurar o widget, verifique se os recursos necessários foram criados e se a implantação do proxy do WebChat foi concluída.

  1. Configure o número de encaminhamento.
    1. Crie um recurso PhoneNumber para seu projeto.
      1. Use um perfil de conversa válido configurado para o aplicativo do agente.
      2. Associe o perfil de conversa ao PhoneNumber para permitir que o sistema lide com o encaminhamento para um atendente humano.
    2. Siga as instruções para configurar o proxy do WebChat.
  2. Configuração do cliente de webchat:

    1. Defina o atributo do proxy do WebChat para ativar o recurso de transferência em tempo real. Exemplo de snippet 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>
      

Personalização de HTML

É possível personalizar vários aspectos da aparência e do comportamento da caixa de diálogo do chat. Os elementos HTML chat-messenger e chat-messenger-container têm os seguintes atributos:

Atributo Atribuição de componentes Valor (opcional) Efeito
serviço chat-messenger O nome do serviço obrigatório para o serviço de back-end conectado.
url-allowlist chat-messenger * (lista separada por vírgulas de domínios de imagem
logging-level chat-messenger DEPURAR <OMIT>
enable-audio-input-only chat-messenger-container Modo somente voz
start-with-recording chat-messenger-container Requer o modo somente voz. O modo somente voz é iniciado no segundo em que o chat-messenger-container é renderizado
enable-audio-input chat-messenger-container Adiciona um botão para permitir o chat multimodal
enable-file-upload chat-messenger-container Ativa o upload de imagens
bot-writing-image chat-messenger-container string URL da imagem renderizada durante o "pensamento" do bot
chat-title-icon chat-messenger-container string URL da imagem renderizada na parte de cima do chat (imagem da marca)
chat-title chat-messenger-container string Texto do título da conversa
render-mode chat-messenger string ("slide-in" ou "slide-over") O modo de renderização da caixa de diálogo do chat em relação ao restante da página. As opções são "slide-over" ou "slide-in". Se não for especificado, o posicionamento poderá ser especificado pelo cliente. Os estilos são necessários para oferecer suporte ao modo de renderização. chat-messenger-layout.css pode ser usado como um valor de referência.

Personalização de CSS

A personalização da aparência do widget é feita por um sistema de tokens CSS. Ao modificar esses tokens, você garante que a interface do chat seja consistente com sua marca, mantendo a integridade e a acessibilidade do layout.

Tokens de cor

Esses tokens definem a paleta de cores para as superfícies do widget, elementos interativos, texto e estados.

Propriedade Descrição Tema claro padrão Tema escuro padrão
Contêineres / plataformas
--chat-messenger-color--surface A cor principal do plano de fundo do corpo do chat e da área do rodapé. #F8FAFD #1B1B1B
--chat-messenger-color--surface-container A cor de fundo dos contêineres de widgets (por exemplo, cards de produtos e carrosséis) aninhados no chat. #FFFFFF #131314
--chat-messenger-color--surface-container-high Um plano de fundo de alta ênfase para elementos em widgets (por exemplo, campos de entrada) #F0F4F9 #1E1F20
Marca / Destaque
--chat-messenger-color--primary Cor principal da marca usada para preenchimentos de alta ênfase e botões principais. #303030 #E3E3E3
--chat-messenger-color--primary-container Cor de fundo de destaque para componentes importantes, como balões de mensagens do usuário. #E9EEF6 #282A2C
--chat-messenger-color--secondary Cor para elementos interativos secundários, como o botão "Enviar" ou botões tonais. #DDE3EA #333537
Texto e ícones
--chat-messenger-color--on-surface Cor principal para texto e ícones exibidos em planos de fundo de superfície padrão. #1F1F1F #E3E3E3
--chat-messenger-color--on-surface-variant Cor de menor ênfase para texto secundário e ícones decorativos. #444746 #C4C7C5
--chat-messenger-color--on-primary Cor para texto e ícones colocados sobre os planos de fundo principais da marca. #F2F2F2 #303030
--chat-messenger-color--on-primary-container Cor para texto e ícones colocados sobre planos de fundo de contêineres primários. #1F1F1F #E3E3E3
--chat-messenger-color--on-secondary Cor para texto e ícones colocados sobre planos de fundo secundários da marca. #444746 #C4C7C5
Estados
--chat-messenger-color--state-layer-on-surface A sobreposição translúcida usada para indicar estados de passagem do cursor ou seleção em superfícies padrão. O preenchimento para componentes desativados. #1F1F1F 8% #E3E3E3 8%
--chat-messenger-color--state-layer-on-primary A sobreposição translúcida usada para estados de interação sobre elementos de cor primária. #FFFFFF 8% #062E6F 8%
--chat-messenger-color--state-layer-on-secondary A sobreposição translúcida usada para estados de interação sobre elementos de cor secundária. #1F1F1F 8% #E3E3E3 8%
--chat-messenger-color--state-on-surface-mute Cor para texto e ícones desativados. #444746 (38%) #C4C7C5 (38%)
Utilitários
--chat-messenger-color--outline Cor para bordas gerais, divisores e contornos decorativos. #C4C7C5 #444746
--chat-messenger-color--outline-variant Cor para bordas sutis (por exemplo, a moldura externa de widgets) #747775 com 16% #8E918F a 16%
--chat-messenger-color--outline-active Cor da borda dos campos de entrada e menus suspensos quando estão em foco ou ativos. #747775 #8E918F
--chat-messenger-color--error Cor que chama a atenção em relação à superfície para preenchimentos, ícones e texto, indicando urgência. #B3261E #F2B8B5
--chat-messenger-color--error-container Cor de preenchimento do plano de fundo para banners de erro ou contêineres de alerta interativos. #F9DEDC #8C1D18
--chat-messenger-color--on-error-container Texto e ícones colocados no plano de fundo do contêiner de erro. #8C1D18 #F9DEDC
--chat-messenger-color--link Cor usada para hiperlinks clicáveis em mensagens ou descrições. #0B57D0 #A8C7FA

Tokens de forma e elevação

Esses tokens controlam o raio do canto e a profundidade visual (sombras) dos componentes do chat.

Propriedade Descrição Padrão
--chat-messenger-shape--corner-value-small Raio de canto para pequenos elementos aninhados em widgets (por exemplo, miniaturas de imagens de produtos) 8px
--chat-messenger-shape--corner-value-medium Raio do canto para elementos aninhados em widgets (por exemplo, campos de entrada, imagens) 16px
--chat-messenger-shape--corner-value-large Raio do canto para contêineres aninhados em widgets (por exemplo, cards de carrossel, cards de ações rápidas) 20px
--chat-messenger-shape--corner-value-extra-large Raio do canto da janela de chat principal e dos contêineres de widget. 28 px
--chat-messenger-shape--corner-fully-rounded Usado para botões e elementos interativos em formato de pílula para garantir uma extremidade totalmente circular. 100 px
--chat-messenger-elevation A sombra de caixa aplicada aos elementos flutuantes e ao componente principal do chat. 0 1px 2px 0 rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15)

Tokens de tipografia

Esses tokens definem a família tipográfica e a escala específica (tamanho, peso, espaçamento) usada em toda a interface.

Propriedade Uso pretendido Padrão
--chat-messenger-font-family Família de fontes principal Google Sans
Título grande Cabeçalhos em destaque
--chat-messenger-typescale--title-large-font-size 18 px
--chat-messenger-typescale--title-large-font-weight 400
--chat-messenger-typescale--title-large-line-height 24px
--chat-messenger-typescale--title-large-letter-spacing 0
Título médio Cabeçalhos de seção em widgets.
--chat-messenger-typescale--title-medium-font-size 16px
--chat-messenger-typescale--title-medium-font-weight 500
--chat-messenger-typescale--title-medium-line-height 24px
--chat-messenger-typescale--title-medium-letter-spacing 0
Título pequeno
--chat-messenger-typescale--title-small-font-size Subtítulos ou títulos em cards menores. 14px
--chat-messenger-typescale--title-small-font-weight 500
--chat-messenger-typescale--title-small-line-height 20px
--chat-messenger-typescale--title-small-letter-spacing 0
Corpo grande Descrições longas.
--chat-messenger-typescale--body-large-font-size 16px
--chat-messenger-typescale--body-large-font-weight 400
--chat-messenger-typescale--body-large-line-height 24px
--chat-messenger-typescale--body-large-letter-spacing 0
Body medium Texto padrão da interface
--chat-messenger-typescale--body-medium-font-size 14px
--chat-messenger-typescale--body-medium-font-weight 400
--chat-messenger-typescale--body-medium-line-height 20px
--chat-messenger-typescale--body-medium-letter-spacing 0
Corpo pequeno Metadados e descrições secundários.
--chat-messenger-typescale--body-small-font-size 12px
--chat-messenger-typescale--body-small-font-weight 400
--chat-messenger-typescale--body-small-line-height 16px
--chat-messenger-typescale--body-small-letter-spacing 0,1
Rótulo grande Texto em botões e ícones de ação principal.
--chat-messenger-typescale--label-large-font-size 14px
--chat-messenger-typescale--label-large-font-weight 500
--chat-messenger-typescale--label-large-line-height 20px
--chat-messenger-typescale--label-large-letter-spacing 0
Rótulo médio Texto do botão secundário e rótulos de campo
--chat-messenger-typescale--label-medium-font-size 12px
--chat-messenger-typescale--label-medium-font-weight 500
--chat-messenger-typescale--label-medium-line-height 16px
--chat-messenger-typescale--label-medium-letter-spacing 0,1
Rótulo pequeno Microrrótulos e texto do selo
--chat-messenger-typescale--label-small-font-size 11px
--chat-messenger-typescale--label-small-font-weight 500
--chat-messenger-typescale--label-small-line-height 16px
--chat-messenger-typescale--label-small-letter-spacing 0,1

Tokens de espaçamento

Esses tokens mantêm uma densidade de layout consistente, definindo margens, preenchimentos e espaços entre os elementos.

Propriedade Padrão
--chat-messenger-spacing--half 4px
--chat-messenger-spacing--one 8px
--chat-messenger-spacing--one-and-half 12px
--chat-messenger-spacing--two 16px
--chat-messenger-spacing--two-and-half 20px
--chat-messenger-spacing--three 24px
--chat-messenger-spacing--three-and-half 28 px
--chat-messenger-spacing--four 32px

Eventos JavaScript

O Messenger aciona vários eventos para os quais você pode criar listeners de eventos. O destino desses eventos é o elemento chat-messenger.

Para adicionar um listener de eventos ao elemento chat-messenger, adicione o seguinte código JavaScript, em que event-type é um dos nomes de evento descritos nesta seção:


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

Os seguintes tipos de evento são compatíveis:

  • chat-messenger-loaded: esse evento é acionado quando o elemento chat-messenger é totalmente carregado e inicializado.

  • chat-messenger-close

  • chat-messenger-error: esse evento ocorre quando o agente do CES envia um código de status de erro. A estrutura do evento é semelhante a esta:

    eventId= `chat-messenger-error-v2`
    event.details {
      message: string;
      code: number | undefined;
      status: number | string;
    }
    
  • df-update-cart-count: esse evento ocorre quando as ações "Adicionar ao carrinho", "Ajustar quantidade de itens" e "Excluir item" acontecem nos elementos de conteúdo avançado product_carousel, product_detail e product_comparison. A estrutura do evento é semelhante a esta:

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

Funções JavaScript

O elemento chat-messenger fornece funções que você pode chamar para afetar o comportamento dele.

renderCustomText

Essa função renderiza uma mensagem de texto, como se ela viesse do aplicativo do agente como uma resposta de texto.

Exemplo:

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

renderCustomCard

Essa função renderiza um card personalizado, como se viesse do aplicativo do agente como uma mensagem de resposta avançada. O formato da resposta do payload personalizado é definido na seção Mensagens de resposta avançada.

Exemplo:

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

Configurar a autenticação

Todas as solicitações de API feitas pelo widget da Web para os serviços de back-end do Google precisam ser autenticadas. Isso é feito usando um token de acesso do OAuth 2.0 de curta duração.

A identidade associada a esse token, seja um usuário final ou uma conta de serviço, precisa ter as permissões do IAM necessárias para interagir com o agente.

As subseções restantes descrevem as maneiras de configurar a autenticação.

Configurar um agente de token

Um agente de token é um serviço da Web executado no projeto do Google Cloud e gera um token de acesso em nome de uma conta de serviço que pertence a você. O widget da Web pode chamar automaticamente o URL do seu agente de token no início de uma conversa para receber um novo token que será usado na comunicação com a API CX Agent Studio.

É possível configurar um agente de token de duas maneiras: hospedado pelo Google ou auto-hospedado.

Hospedado pelo Google

Use o agente de token fornecido pelo Google para permitir o acesso público ao widget de chat:

  • Ao criar a implantação e a configuração do widget, ative o acesso público e, se quiser, as verificações de origem e do reCAPTCHA (recomendado para evitar spoofing e abuso).
  • O widget de chat vai solicitar um token de escopo de sessão do agente de token fornecido pelo Google e usá-lo para sessões de chat.

Auto-hospedado

Siga estas etapas para configurar um agente de token auto-hospedado:

  • Crie uma conta de serviço no seu projeto e conceda a ela o papel de cliente do Pacote de engajamento do cliente.
  • Implante uma função do Cloud Run functions com o exemplo de código do agente de token que fornecemos.

Confira instruções detalhadas no repositório de código aberto.

Configurar o OAuth2

Um cliente OAuth2 permite que o widget da Web inicie um fluxo de autenticação para o usuário final. Isso geralmente significa que uma janela de diálogo é aberta, em que o usuário faz login na Conta do Google (ou de outros provedores) e o widget da Web recebe um token para operar em nome do usuário.

Escolha essa opção para exigir que os usuários finais façam login antes de usar o agente, em que as credenciais do usuário são usadas para acessar o aplicativo do agente.

Confira as principais etapas que você precisa seguir:

  • No console do Google Cloud , acesse a Plataforma Google Auth e selecione "Clientes".
  • Clique em Criar cliente.
  • Selecione Aplicativo da Web como o tipo de cliente.
  • Insira um nome para o novo cliente.
  • Adicione o URL do seu site às origens JavaScript autorizadas e aos URIs de redirecionamento autorizados.
  • Clique em Criar e aguarde 5 minutos antes de continuar.

Depois de seguir as etapas, você vai receber um ID do cliente no formato:

123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com

Informe isso no atributo oauth-client-id do componente da Web chat-messenger.

Criar sua própria API de autenticação

Crie sua própria API para processar a autenticação e a autorização do usuário final, que retorna um token de acesso do Google ou um JWT assinado com permissão para chamar runSession no app.

Para informações sobre como usar a API CX Agent Studio, consulte Acesso à API.