Incorporação do Agente de Docs

Saiba como incorporar o widget do Agente de Docs em suas páginas de documentação.

Visão Geral

O Agente de 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.

Experimente agora!

Clique no botão abaixo para ver o Agente de Docs em ação nesta página.

Configuração Básica

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

Se sua página de docs carrega o agente dentro de um iframe, certifique-se de que a origem da página host está incluída nas allowed_origins do seu aplicativo OAuth. O endpoint 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 documentos, 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>

Exemplos

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

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 listeners 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 do Agente de Documentos 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 documentos — 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 estes três explicitamente apenas para configurações de várias instâncias:

data-client-id: Seu identificador de cliente exclusivo 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 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 Agente de Documentos em modo de tela cheia.

close()

window.CompaninDocsWidget.close();

Fecha o diálogo do Agente de Documentos e oculta o widget.

Estilo Personalizado

Você pode estilizar seus botões de gatilho da maneira que quiser. 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 à IA' ou 'Precisa de Ajuda?'
Certifique-se de que o script do widget carrega antes de tentar chamar seus métodos da API
Mantenha suas credenciais de cliente seguras - nunca as exponha em código do lado do cliente

Solução de Problemas

Widget não carregando?

Certifique-se de que o script está 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 uma chave de widget válida (ou, para a forma explícita, o client-id, agent-id e config-id) e se está correta. Se vários widgets estiverem presentes, certifique-se de que cada script tenha um data-instance-id único.

Voltar Próximo: Visão Geral