Incorporamento dell'agente Docs

Panoramica

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.

Impostazione di Base

Iniziare con il widget dell'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.

Passo 1: Aggiungi lo Script

Aggiungi lo script docs-widget.js alla tua pagina HTML con la configurazione richiesta. Se carichi più widget docs, assegna a ciascun script un unico data-instance-id:

<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: Aggiungi un Pulsante di Attivazione

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>

Barra di ricerca inferiore

Fuori dalla scatola, il widget della documentazione non ha alcun lanciatore visibile: si apre solo quando la tua pagina chiama l'API. Dagli invece una barra di ricerca: un campo compatto fissato in fondo a ogni pagina, che apre il pannello completo quando un visitatore ci clicca sopra o inizia a digitare. Qualsiasi cosa già digitata viene portata nella casella di ricerca del pannello.

Attivalo nel tuo pannello di controllo sotto Widget → Contenuto → Testo del campo di ricerca. Il testo è memorizzato per lingua, quindi ogni locale ha la propria formulazione e i visitatori vedono la barra nella propria lingua.

Widget → Controlli del comportamento quando appare:

• Ritardo — millisecondi prima che la barra appaia. 0 la mostra immediatamente.
• Auto-nascondi dopo — millisecondi fino a quando la barra si nasconde da sola. 0 la mantiene finché il visitatore non la chiude.

La barra si nasconde mentre il pannello è aperto e torna quando il visitatore lo chiude, quindi funge sempre da via di ritorno. Ignorandola con la × la ritira solo per quella visualizzazione della pagina; ritorna al successivo caricamento della pagina.

Esempi

Ecco alcuni esempi pratici di come integrare l'agente Docs:

Esempio 1: Integrazione HTML di Base

<!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>

Esempio 2: Pulsante Personalizzato con Listener di Evento

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

Esempio 3: Integrazione React/Next.js

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

Opzioni di Configurazione

Il widget Docs Agent accetta diversi parametri di configurazione. Usa data-instance-id per un controllo deterministico per istanza quando incorpori più widget in una pagina:

Parametri richiesti

• data-widget-key: L'ID del widget del tuo documento — il valore singolo di cui la maggior parte delle installazioni ha bisogno. Risolve il tuo client, agente e configurazione lato server.

Alternativa avanzata a <code>data-widget-key</code> — passa esplicitamente questi tre solo per configurazioni multi-istanza:

• data-client-id: Il tuo identificatore cliente unico dal dashboard di Companin
• data-agent-id: L'ID dell'agente che desideri utilizzare
• data-config-id: ID di configurazione per la personalizzazione del widget

Parametri opzionali

• data-locale: Codice lingua (predefinito: 'en'). Supporta: en, de, es, fr, it, nb, nl, pt, sv
• data-dev: Imposta su 'true' per la modalità di sviluppo (si connette a localhost:3001)

API JavaScript

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 usare solo il riferimento globale più recente:

open()

window.CompaninDocsWidget.open();

Apre la finestra di dialogo del Docs Agent in modalità a schermo intero.

close()

window.CompaninDocsWidget.close();

Chiude la finestra di dialogo del Docs Agent e nasconde il widget.

Stile personalizzato

Puoi stilizzare i tuoi pulsanti di attivazione come preferisci. Ecco un esempio di un pulsante di aiuto galleggiante:

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

Migliori pratiche

• Posiziona il pulsante di attivazione in una posizione prominente e facilmente accessibile (ad es., intestazione, pulsante galleggiante)
• Usa un testo chiaro e orientato all'azione come 'Chiedi all'AI' o 'Hai bisogno di aiuto?'
• Assicurati che lo script del widget si carichi prima di provare a chiamare i suoi metodi API
• Mantieni le tue credenziali client sicure - non esporle mai nel codice lato client

Risoluzione dei problemi

Widget non caricato?

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

Dialogo non si apre?

Verifica di aver fornito un data-widget-key valido (o, per il modulo esplicito, il client-id, agent-id e config-id) e che sia corretto. Se sono presenti più widget, assicurati che ogni script abbia un data-instance-id unico.