Aprende cómo incrustar el widget del Agente de Documentos en tus páginas de documentación.
El Agente de Documentos es un widget especializado impulsado por IA diseñado específicamente para páginas de documentación. Proporciona ayuda instantánea a tus usuarios respondiendo preguntas sobre tu documentación utilizando un diálogo interactivo de pantalla completa.
¡Pruébalo ahora!
Haz clic en el botón a continuación para ver el Agente de Documentos en acción en esta página.
Comenzar con el widget del Agente de Documentos es simple. Solo sigue estos dos pasos:
Si su página de documentos carga el agente dentro de un iframe, asegúrese de que el origen de la página host esté incluido en los allowed_origins de su aplicación OAuth. El punto final del token del widget valida este origen antes de emitir un token.
Agrega el script docs-widget.js a tu página HTML con la configuración requerida. Si cargas múltiples widgets de documentos, dale a cada script un data-instance-id único:
<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>Crea un botón o elemento que llame al método open() del 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>Aquí hay algunos ejemplos prácticos de cómo integrar el Agente de Documentos:
<!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>Para más control, puedes agregar listeners de eventos a tus botones 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(); });});En una aplicación React o 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> );}El widget del Agente de Documentos acepta varios parámetros de configuración. Usa data-instance-id para control determinista por instancia al incrustar múltiples widgets en una página:
data-widget-key: El ID de Widget de su widget de documentos: el único valor que la mayoría de las instalaciones necesitan. Resuelve su cliente, agente y configuración del lado del servidor.Alternativa avanzada a <code>data-widget-key</code>: pasa estos tres explícitamente solo para configuraciones de múltiples instancias:
data-client-id: Tu identificador único de cliente desde el tablero de Companindata-agent-id: El ID del agente que deseas usardata-config-id: ID de configuración para personalización del widgetdata-locale: Código de idioma (predeterminado: 'en'). Soporta: en, de, es, fr, it, nb, nl, pt, svdata-dev: Configúralo en 'true' para modo de desarrollo (se conecta a localhost:3001)Una vez cargado, el widget expone una API global para control programático. Para configuraciones de múltiples widgets, prefiere registros de instancia (CompaninDocsWidgets.get(instanceId)) sobre solo usar la última referencia global:
window.CompaninDocsWidget.open();Abre el diálogo del Agente de Documentos en modo de pantalla completa.
window.CompaninDocsWidget.close();Cierra el diálogo del Agente de Documentos y oculta el widget.
Puedes estilizar tus botones de activación como desees. Aquí hay un ejemplo de un botón de ayuda flotante:
.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);}Asegúrate de que el script se cargue antes de llamar a la API. Puedes verificar si el widget está disponible:
window.addEventListener('load', () => { console.log('Widget loaded:', !!window.CompaninDocsWidget);});Verifique que haya proporcionado una clave de widget válida (o, para la forma explícita, el client-id, agent-id y config-id) y que sea correcta. Si hay múltiples widgets presentes, asegúrese de que cada script tenga un data-instance-id único.