Incorporamento Assistente Docs

Scopri come incorporare il widget Assistente Docs nelle tue pagine di documentazione.

Panoramica

L'Assistente Docs è un widget specializzato alimentato da IA progettato specificamente per le pagine di documentazione. Fornisce aiuto istantaneo ai tuoi utenti rispondendo alle domande sulla tua documentazione utilizzando un dialogo interattivo a schermo intero.

Provalo ora!

Clicca sul pulsante qui sotto per vedere l'Assistente Docs in azione su questa pagina.

Configurazione Base

Iniziare con il widget Assistente Docs è semplice. Segui semplicemente questi due passi:

Se la pagina dei documenti carica l'assistente all'interno di un iframe, assicurati che l'origine della pagina host sia inclusa nel valore consentiti_origins dell'applicazione OAuth. L'endpoint del token 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 un data-instance-id univoco a ogni 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>

Passo 2: Aggiungi un Pulsante di Attivazione

Crea un pulsante o elemento che chiami il metodo 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>

Esempi

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

Esempio 1: Integrazione HTML 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-client-id="your-client-id"    data-assistant-id="your-assistant-id"    data-config-id="your-config-id"    data-locale="en">  </script></body></html>

Esempio 2: Pulsante Personalizzato con Event Listener

Per più controllo, puoi aggiungere event listener ai tuoi pulsanti esistenti:

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

Esempio 3: Integrazione React/Next.js

In un'applicazione 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>  );}

Opzioni di Configurazione

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

Parametri Richiesti

data-client-id: Il tuo identificatore client univoco dal dashboard Companin
data-assistant-id: L'ID dell'assistente che vuoi utilizzare
data-config-id: ID configurazione per personalizzazione 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 modalità sviluppo (connette a localhost:3001)

API JavaScript

Una volta caricato, il widget espone una API globale per il controllo programmatico. Nelle configurazioni multi-widget, usa preferibilmente i registri per istanza (CompaninDocsWidgets.get(instanceId)) invece di affidarti solo al riferimento globale più recente:

open()

window.CompaninDocsWidget.open();

Apre il dialogo Assistente Docs in modalità schermo intero.

close()

window.CompaninDocsWidget.close();

Chiude il dialogo Assistente Docs e nasconde il widget.

Stile Personalizzato

Puoi dare stile ai tuoi pulsanti di attivazione come preferisci. Ecco un esempio di 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);}

Migliori Pratiche

Posiziona il pulsante di attivazione in una posizione prominente e facilmente accessibile (es. header, pulsante flottante)
Usa testo pulsante chiaro e orientato all'azione come 'Chiedi all'IA' 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 Problemi

Il widget non si carica?

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

Il dialogo non si apre?

Verifica di aver fornito correttamente tutti i parametri richiesti (client-id, assistant-id, config-id). Se sono presenti più widget, ogni script deve avere un data-instance-id univoco.

← Indietro Avanti: Panoramica →