Incrustación del Agente Docs

Descripción general

El Agente Docs 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.

Configuración Básica

Comenzar con el widget del Agente Docs es simple. Solo sigue estos dos pasos:

Si tu página de documentos carga el agente dentro de un iframe, asegúrate de que el origen de la página host esté incluido en los allowed_origins de tu aplicación OAuth. El punto final del token del widget valida este origen antes de emitir un token.

Paso 1: Agregar el Script

Agrega el script docs-widget.js a tu página HTML con la configuración requerida. Si cargas múltiples widgets de docs, 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>

Paso 2: Agregar un Botón de Activación

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>

Barra de búsqueda inferior

Fuera de la caja, el widget de docs no tiene un lanzador visible; solo se abre cuando tu página llama a la API. Dale en su lugar una barra de búsqueda: un campo compacto fijado en la parte inferior de cada página, que abre el panel completo cuando un visitante hace clic en él o comienza a escribir. Cualquier cosa ya escrita se lleva al cuadro de búsqueda del panel.

Actívalo en tu panel bajo Widget → Contenido → Texto del campo de búsqueda. El texto se almacena por idioma, por lo que cada localidad tiene su propia redacción y los visitantes ven la barra en su propio idioma.

Widget → Controles de comportamiento cuando aparece:

• Retraso — milisegundos antes de que aparezca la barra. 0 la muestra inmediatamente.
• Ocultar automáticamente después de — milisegundos hasta que la barra se oculte por sí misma. 0 la mantiene hasta que el visitante la descarta.

La barra se oculta mientras el panel está abierto y vuelve cuando el visitante lo cierra, por lo que siempre sirve como el camino de regreso. Descartarlo con el × lo retira solo para esa vista de página; vuelve en la siguiente carga de página.

Ejemplos

Aquí hay algunos ejemplos prácticos de cómo integrar el Agente Docs:

Ejemplo 1: Integración 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>

Ejemplo 2: Botón Personalizado con Listener de Eventos

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

Ejemplo 3: Integración React/Next.js

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

Opciones de Configuración

El widget Docs Agent acepta varios parámetros de configuración. Utilice data-instance-id para un control determinista por instancia al incrustar múltiples widgets en una página:

Parámetros Requeridos

• data-widget-key: El ID del Widget de su widget de docs — 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> — pase estos tres explícitamente solo para configuraciones de múltiples instancias:

• data-client-id: Su identificador único de cliente del panel de Companin
• data-agent-id: El ID del agente que desea usar
• data-config-id: ID de configuración para la personalización del widget

Parámetros Opcionales

• data-locale: Código de idioma (predeterminado: 'en'). Soporta: en, de, es, fr, it, nb, nl, pt, sv
• data-dev: Establezca en 'true' para el modo de desarrollo (se conecta a localhost:3001)

API de JavaScript

Una vez cargado, el widget expone una API global para control programático. Para configuraciones de múltiples widgets, prefiera registros de instancia (CompaninDocsWidgets.get(instanceId)) sobre solo usar la última referencia global:

open()

window.CompaninDocsWidget.open();

Abre el diálogo del Docs Agent en modo de pantalla completa.

close()

window.CompaninDocsWidget.close();

Cierra el diálogo del Docs Agent y oculta el widget.

Estilo Personalizado

Puede estilizar sus botones de activación como desee. 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);}

Mejores Prácticas

• Coloque el botón de activación en un lugar prominente y de fácil acceso (por ejemplo, encabezado, botón flotante)
• Utilice texto de botón claro y orientado a la acción como 'Preguntar a la IA' o '¿Necesita ayuda?'
• Asegúrese de que el script del widget se cargue antes de intentar llamar a sus métodos API
• Mantenga sus credenciales de cliente seguras - nunca las exponga en el código del lado del cliente

Solución de Problemas

¿Widget no cargando?

Asegúrese de que el script esté cargado antes de llamar a la API. Puede verificar si el widget está disponible:

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

¿Diálogo no abriendo?

Verifique que haya proporcionado un data-widget-key válido (o, para el formulario explícito, el client-id, agent-id y config-id) y que sea correcto. Si hay múltiples widgets presentes, asegúrese de que cada script tenga un data-instance-id único.