Guida Rapida

Incorpora il widget e ottieni un token widget dal server.

L'app widget è ospitata su widget.companin.tech e fornisce un modo semplice per incorporare un assistente IA nel tuo sito web. Per iniziare, dovrai creare un assistente e un'applicazione OAuth.

Il widget è un'applicazione leggera e autonoma che viene eseguita in un iframe isolato sul tuo sito web. Questa architettura garantisce che il widget non entri in conflitto con il CSS o JavaScript esistente, pur mantenendo prestazioni e sicurezza eccellenti.

⚡ Distribuzione rapida

La maggior parte degli sviluppatori esegue il widget sul proprio sito entro 10 minuti. Il processo di installazione prevede solo tre passaggi: creazione di credenziali, configurazione dell'aspetto e aggiunta di un singolo tag script al tuo HTML.

1. Creare un Assistente

Innanzitutto, crea un assistente IA nella tua dashboard:

Il tuo assistente è il cervello dell'intelligenza artificiale dietro il widget. Elabora i messaggi degli utenti, mantiene il contesto della conversazione e genera risposte intelligenti. Ogni assistente può essere personalizzato con istruzioni specifiche, tratti della personalità e basi di conoscenza per adattarsi al tuo caso d'uso.

Vai alla tua dashboard e naviga alla pagina "Data Sources"
Clicca il pulsante "Add" nella sezione Assistants
Compila i dettagli dell'assistente (nome, descrizione, tono, etc.)
Salva l'assistente e annota il suo ID

Mancia: Dai al tuo assistente istruzioni chiare e specifiche sul suo ruolo e sui suoi limiti. Ad esempio: "Sei un utile assistente dell'assistenza clienti per un prodotto SaaS. Puoi rispondere a domande su funzionalità, prezzi e gestione dell'account. Per problemi tecnici, indirizza gli utenti a creare un ticket di supporto".

2. Creare un'Applicazione OAuth

Crea un'applicazione OAuth per autenticare il tuo widget:

Vai alla pagina "OAuth" nella tua dashboard
Clicca "Create Application"
Compila il nome e la descrizione dell'applicazione
Copia il client_id dall'applicazione creata

3. Incorporare il Widget tramite Iframe

Il modo più semplice per integrare il widget è incorporarlo direttamente tramite iframe. Questo metodo non richiede inizializzazione JavaScript e funziona subito. Se usi più iframe nella stessa pagina, mantieni ogni integrazione separata con il proprio contenitore e i propri parametri.

<iframe src="https://widget.companin.tech/embed/session?clientId=YOUR_CLIENT_ID&assistantId=YOUR_ASSISTANT_ID&configId=YOUR_CONFIG_ID&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Assistant Widget"></iframe>

Sostituisci YOUR_CLIENT_ID e YOUR_ASSISTANT_ID con i tuoi valori effettivi. Il parametro locale può essere impostato per corrispondere alla lingua del tuo sito.

Avanzato: Inizializzazione JavaScript

Il metodo di integrazione consigliato è l'utilizzo del nostro caricatore di widget JavaScript, che fornisce dimensionamento automatico, gestione della configurazione e comportamento reattivo.

Integrazione della sceneggiatura

Aggiungi il seguente tag script alla tua pagina HTML:

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

Attributi della sceneggiatura

Ogni attributo ha uno scopo specifico nella configurazione del widget:

data-client-id: il tuo ID client OAuth: autentica la tua applicazione con la nostra API. Considerala come la password della tua app.
data-assistant-id: l'UUID del tuo assistente: identifica quale assistente AI dell'assistenza clienti gestisce le conversazioni.
data-config-id: l'UUID della configurazione del tuo widget: determina l'aspetto e il comportamento del tuo widget (colori, dimensioni, posizione, ecc.).
data-instance-id: ID istanza univoco per widget: obbligatorio quando si incorporano più widget nella stessa pagina per evitare collisioni e abilitare il targeting API per istanza.
data-custom-css: (facoltativo) regole CSS in linea che verranno inserite nel <head> dell'iframe prima del rendering dell'app. Usalo per sovrascrivere gli stili senza modificare la configurazione. La codifica URL viene gestita automaticamente.
data-locale: codice della lingua (ad esempio, "en", "es", "fr") - Imposta la lingua di visualizzazione del widget. L'assistente risponderà comunque nella lingua in cui gli utenti scrivono.
data-dev: imposta su "true" per la modalità di sviluppo (localhost): utilizzalo durante i test locali. Rimuovere o impostare su "false" per la produzione.

Il widget automaticamente:

Recupera la configurazione dall'ID di configurazione
Dimensionarsi in base alle dimensioni del widget nel file config
Posiziona il pulsante compresso in base alle impostazioni di configurazione
Inizia aperto o chiuso in base all'impostazione start_open della configurazione

Note

Il widget gestisce automaticamente il proprio dimensionamento in base alle impostazioni di configurazione
La posizione del pulsante compresso può essere personalizzata tramite la configurazione del widget
Il widget rispetta l'impostazione start_open della tua configurazione
Tutti gli stili (colori, caratteri, dimensioni) sono controllati tramite la configurazione del widget
Il widget utilizza la comunicazione postMessage per un comportamento reattivo
La modalità di sviluppo può essere abilitata con data-dev="true" per il test dell'host locale
Per lo scambio di token lato server, utilizza /api/v1/auth/widget-token e mantieni il client segreto solo sul tuo server.
Assicurati che l'origine del tuo host (ad esempio http://localhost:3000) sia inclusa in OAuth aware_origins quando incorpori il widget in un iframe.

← Indietro Avanti: Riferimento API →