Incorporação do Agente Docs

Visão Geral

O Agente Docs é um widget especializado alimentado por IA projetado especificamente para páginas de documentação. Ele fornece ajuda instantânea aos seus usuários respondendo perguntas sobre sua documentação usando um diálogo interativo em tela cheia.

Configuração Básica

Começar com o widget do Agente Docs é simples. Basta seguir estas duas etapas:

Se sua página de documentos carrega o agente dentro de um iframe, certifique-se de que a origem da página host esteja incluída nas allowed_origins do seu aplicativo OAuth. O ponto de extremidade do token do widget valida essa origem antes de emitir um token.

Passo 1: Adicione o Script

Adicione o script docs-widget.js à sua página HTML com a configuração necessária. Se você carregar vários widgets de docs, dê a cada script um data-instance-id exclusivo:

<script  src="https://widget.companin.tech/docs-widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-instance-id="docs-help"  data-locale="en"  async></script>

Passo 2: Adicione um Botão de Gatilho

Crie um botão ou elemento que chama o método open() do widget:

<button id="help-btn" type="button">Ask Documentation Agent</button><script>  const handleOpen = (event) => {    console.log('Docs widget opened', event?.context);  };  // Generic event API (returns unsubscribe function)  const unsubscribeOpen = window.CompaninDocsWidget?.on?.('open', handleOpen);  document.getElementById('help-btn')?.addEventListener('click', () => {    window.CompaninDocsWidget?.open();  });  // Cleanup on page unload or SPA route change  window.addEventListener('beforeunload', () => {    if (typeof unsubscribeOpen === 'function') unsubscribeOpen();  });</script>

Barra de pesquisa inferior

Fora da caixa, o widget de docs não tem lançador visível — ele só abre quando sua página chama a API. Dê a ele uma barra de pesquisa em vez disso: um campo compacto fixado na parte inferior de cada página, que abre o painel completo quando um visitante clica nele ou começa a digitar. Qualquer coisa já digitada é levada para a caixa de pesquisa do painel.

Ative-o no seu painel em Widget → Conteúdo → Texto do campo de pesquisa. O texto é armazenado por idioma, então cada localidade recebe sua própria redação e os visitantes veem a barra em seu próprio idioma.

Widget → Controles de comportamento quando ele aparece:

• Atraso — milissegundos antes da barra aparecer. 0 a mostra imediatamente.
• Ocultar automaticamente após — milissegundos até que a barra se esconda sozinha. 0 mantém até que o visitante a descarte.

A barra se oculta enquanto o painel está aberto e volta quando o visitante o fecha, então sempre serve como o caminho de volta. Descartá-la com o × a retira apenas para essa visualização de página; ela retorna na próxima carga de página.

Exemplos

Aqui estão alguns exemplos práticos de como integrar o Agente Docs:

Exemplo 1: Integração HTML Básica

<!DOCTYPE html><html lang="en"><head>  <meta charset="UTF-8">  <meta name="viewport" content="width=device-width, initial-scale=1.0">  <title>My Documentation</title></head><body>  <header>    <h1>Product Documentation</h1>    <button onclick="window.CompaninDocsWidget.open()">      Need Help?    </button>  </header>  <main>    <!-- Your documentation content -->  </main>  <script    src="https://widget.companin.tech/docs-widget.js"    data-widget-key="your-widget-key"    data-locale="en">  </script></body></html>

Exemplo 2: Botão Personalizado com Listener de Evento

Para mais controle, você pode adicionar ouvintes de eventos aos seus botões existentes:

// Wait for the widget to loadwindow.addEventListener('load', () => {  const unsubscribeResponse = window.CompaninDocsWidget?.on?.('response', (event) => {    console.log('Agent response:', event?.data);  });  document.getElementById('help-btn').addEventListener('click', () => {    if (window.CompaninDocsWidget) {      window.CompaninDocsWidget.open();    }  });  window.addEventListener('beforeunload', () => {    if (typeof unsubscribeResponse === 'function') unsubscribeResponse();  });});

Exemplo 3: Integração React/Next.js

Em uma aplicação React ou Next.js:

import React from 'react';export default function Documentation() {  const openDocsAgent = () => {    if (window.CompaninDocsWidget) {      window.CompaninDocsWidget.open();    }  };  return (    <div>      <h1>API Documentation</h1>      <button        onClick={openDocsAgent}        className="help-button"      >        Ask Customer Support AI Agent      </button>    </div>  );}

Opções de Configuração

O widget Docs Agent aceita vários parâmetros de configuração. Use data-instance-id para controle determinístico por instância ao incorporar vários widgets em uma página:

Parâmetros Obrigatórios

• data-widget-key: O ID do Widget do seu widget de docs — o único valor que a maioria das instalações precisa. Ele resolve seu cliente, agente e configuração no lado do servidor.

Alternativa avançada para <code>data-widget-key</code> — passe esses três explicitamente apenas para configurações de múltiplas instâncias:

• data-client-id: Seu identificador único de cliente do painel Companin
• data-agent-id: O ID do agente que você deseja usar
• data-config-id: ID de configuração para personalização do widget

Parâmetros Opcionais

• data-locale: Código de idioma (padrão: 'en'). Suporta: en, de, es, fr, it, nb, nl, pt, sv
• data-dev: Defina como 'true' para o modo de desenvolvimento (conecta-se a localhost:3001)

API JavaScript

Uma vez carregado, o widget expõe uma API global para controle programático. Para configurações de múltiplos widgets, prefira registros de instância (CompaninDocsWidgets.get(instanceId)) em vez de usar apenas a referência global mais recente:

open()

window.CompaninDocsWidget.open();

Abre o diálogo do Docs Agent em modo de tela cheia.

close()

window.CompaninDocsWidget.close();

Fecha o diálogo do Docs Agent e oculta o widget.

Estilo Personalizado

Você pode estilizar seus botões de gatilho da maneira que desejar. Aqui está um exemplo de um botão de ajuda flutuante:

.my-help-button {  position: fixed;  bottom: 20px;  right: 20px;  padding: 12px 24px;  background: #2563eb;  color: white;  border: none;  border-radius: 8px;  font-weight: 600;  cursor: pointer;  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);  transition: all 0.2s;}.my-help-button:hover {  background: #1d4ed8;  transform: translateY(-2px);  box-shadow: 0 6px 8px rgba(0, 0, 0, 0.15);}

Melhores Práticas

• Coloque o botão de gatilho em um local proeminente e de fácil acesso (por exemplo, cabeçalho, botão flutuante)
• Use texto de botão claro e orientado para ação, como 'Pergunte ao AI' ou 'Precisa de Ajuda?'
• Certifique-se de que o script do widget seja carregado antes de tentar chamar seus métodos de API
• Mantenha suas credenciais de cliente seguras - nunca as exponha no código do lado do cliente

Solução de Problemas

Widget não carregando?

Certifique-se de que o script esteja carregado antes de chamar a API. Você pode verificar se o widget está disponível:

window.addEventListener('load', () => {  console.log('Widget loaded:', !!window.CompaninDocsWidget);});

Diálogo não abrindo?

Verifique se você forneceu um data-widget-key válido (ou, para o formulário explícito, o client-id, agent-id e config-id) e se está correto. Se vários widgets estiverem presentes, certifique-se de que cada script tenha um data-instance-id exclusivo.