Scopri come incorporare il widget dell'Agente Docs nelle tue pagine di documentazione.
L'Agente Docs è un widget specializzato alimentato da AI progettato specificamente per le pagine di documentazione. Fornisce ai tuoi utenti aiuto immediato rispondendo a domande sulla tua documentazione utilizzando un dialogo interattivo a schermo intero.
Provalo ora!
Clicca il pulsante qui sotto per vedere l'Agente Docs in azione su questa pagina.
Iniziare con il widget Agente Docs è semplice. Segui semplicemente questi due passaggi:
Se la tua pagina documenti carica l'agente all'interno di un iframe, assicurati che l'origine della pagina host sia inclusa negli allowed_origins della tua applicazione OAuth. L'endpoint del token del widget convalida questa origine prima di emettere un token.
Aggiungi lo script docs-widget.js alla tua pagina HTML con la configurazione richiesta. Se carichi più widget docs, assegna a ciascun script un data-instance-id unico:
<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 pulsante o un elemento che chiama il metodo 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>Ecco alcuni esempi pratici di come integrare l'Agente Docs:
<!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>Per un maggiore controllo, puoi aggiungere listener di eventi ai tuoi pulsanti esistenti:
// 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(); });});In un'applicazione 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> );}Il widget Agente Docs accetta diversi parametri di configurazione. Usa data-instance-id per un controllo deterministico per istanza quando incorpori più widget su una pagina:
data-widget-key: L'ID del widget dei tuoi documenti — il singolo valore di cui la maggior parte delle installazioni ha bisogno. Risolve il tuo client, agente e server di configurazione lato server.Alternativa avanzata a <code>data-widget-key</code> — passa questi tre esplicitamente solo per configurazioni multi-istanza:
data-client-id: Il tuo identificatore client unico dal dashboard Companindata-agent-id: L'ID dell'agente che desideri utilizzaredata-config-id: ID di configurazione per la personalizzazione del widgetdata-locale: Codice lingua (predefinito: 'en'). Supporta: en, de, es, fr, it, nb, nl, pt, svdata-dev: Imposta su 'true' per la modalità di sviluppo (si collega a localhost:3001)Una volta caricato, il widget espone un'API globale per il controllo programmatico. Per configurazioni multi-widget, preferisci i registri delle istanze (CompaninDocsWidgets.get(instanceId)) piuttosto che utilizzare solo il riferimento globale più recente:
window.CompaninDocsWidget.open();Apre il dialogo dell'Agente Docs in modalità a schermo intero.
window.CompaninDocsWidget.close();Chiude il dialogo dell'Agente Docs e nasconde il widget.
Puoi stilizzare i tuoi pulsanti di attivazione come preferisci. Ecco un esempio di un pulsante di aiuto flottante:
.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);}Assicurati che lo script sia caricato prima di chiamare l'API. Puoi controllare se il widget è disponibile:
window.addEventListener('load', () => { console.log('Widget loaded:', !!window.CompaninDocsWidget);});Verifica di aver fornito una chiave valida per data-widget-key (o, per la forma esplicita, il client-id, l'agent-id e il config-id) e che sia corretta. Se sono presenti più widget, assicurati che ogni script abbia un data-instance-id univoco.