Incrustación del Asistente de Docs

Aprenda cómo incrustar el widget del Asistente de Docs en sus páginas de documentación.

Resumen

El Asistente de Docs es un widget especializado impulsado por IA diseñado específicamente para páginas de documentación. Proporciona ayuda instantánea a sus usuarios respondiendo preguntas sobre su documentación usando un diálogo interactivo de pantalla completa.

¡Pruébalo ahora!

Haga clic en el botón a continuación para ver el Asistente de Docs en acción en esta página.

Configuración Básica

Comenzar con el widget del Asistente de Docs es simple. Solo siga estos dos pasos:

Si su página de documentos carga el asistente dentro de un iframe, asegúrese de que el origen de la página de host esté incluido en los orígenes_permitidos de su 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 varios widgets de documentación, asigna un data-instance-id único a cada script:

<script src="https://widget.companin.tech/docs-widget.js" data-client-id="YOUR_CLIENT_ID" data-assistant-id="YOUR_ASSISTANT_ID" data-config-id="YOUR_CONFIG_ID" data-instance-id="docs-help" data-locale="en"></script>

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

Cree un botón o elemento que llame al método open() del widget:

<button id="help-btn" type="button">Ask Documentation Assistant</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>

Ejemplos

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

Ejemplo 1: Integración Básica HTML

<!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-client-id="your-client-id"    data-assistant-id="your-assistant-id"    data-config-id="your-config-id"    data-locale="en">  </script></body></html>

Ejemplo 2: Botón Personalizado con Event Listener

Para más control, puede agregar event listeners a sus botones existentes:

// Wait for the widget to loadwindow.addEventListener('load', () => {  const unsubscribeResponse = window.CompaninDocsWidget?.on?.('response', (event) => {    console.log('Assistant 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 openDocsAssistant = () => {    if (window.CompaninDocsWidget) {      window.CompaninDocsWidget.open();    }  };  return (    <div>      <h1>API Documentation</h1>      <button        onClick={openDocsAssistant}        className="help-button"      >        Ask Customer Support AI Assistant      </button>    </div>  );}

Opciones de Configuración

El widget Docs Assistant acepta varios parámetros de configuración. Usa data-instance-id para un control determinístico por instancia cuando incrustes múltiples widgets en una misma página:

Parámetros Requeridos

data-client-id: Su identificador único de cliente del dashboard de Companin
data-assistant-id: El ID del asistente que desea usar
data-config-id: ID de configuración para 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: Establecer en 'true' para modo desarrollo (conecta a localhost:3001)

API JavaScript

Una vez cargado, el widget expone una API global para control programático. En configuraciones con múltiples widgets, usa preferentemente los registros por instancia (CompaninDocsWidgets.get(instanceId)) en lugar de depender solo de la referencia global más reciente:

open()

window.CompaninDocsWidget.open();

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

close()

window.CompaninDocsWidget.close();

Cierra el diálogo del Asistente de Docs y oculta el widget.

Estilo Personalizado

Puede dar estilo a sus botones de activación de cualquier manera que 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 una ubicación prominente y fácilmente accesible (ej. encabezado, botón flotante)
Use texto de botón claro y orientado a la acción como 'Preguntar a 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 código del lado del cliente

Solución de Problemas

¿Widget no se carga?

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 se abre?

Verifica que hayas proporcionado correctamente todos los parámetros requeridos (client-id, assistant-id, config-id). Si hay varios widgets, cada script debe tener un data-instance-id único.

← Atrás Siguiente: Resumen →