Guide all'installazione

:::note Stato delle versioni L’SDK npm pubblicato 0.1.4 con widget.js v15 supporta il teardown con remove() o window.ChattyBox.destroy() e annulla il lavoro in attesa. :::

L'integrazione ospitata widget.js è la soluzione senza build quando vuoi che ChattyBox gestisca interfaccia e trasporto. Se l'app deve inizializzare la stessa UI dal codice npm, usa mountWidget(). Per gestire direttamente la UI, usa l'SDK headless.

Prima dell'installazione

Completa prima il flusso Per iniziare: configura e importa la fonte, verifica le pagine indicizzate e convalida risposte rappresentative in Prova il chatbot.

In Installa, prepara un’installazione per il tuo sito oppure gestisci una chiave browser sicura da Chiavi e domini. Controlla le impostazioni delle origini: una chiave preparata per il dominio di un sito potrebbe essere già limitata a quell’origine, mentre le chiavi create senza restrizioni funzionano su origini diverse. In Modifica origini puoi attivare restrizioni facoltative o aggiungere le origini di produzione, anteprima, staging e localhost necessarie. Se attivate, la corrispondenza richiede schema, hostname e porta: https://example.com, https://preview.example.com e http://localhost:3000 sono voci separate. È un rafforzamento facoltativo, non un metodo di autenticazione dei visitatori. In Installazione sul sito web, inserisci un URL HTTP(S): il selettore mostra le chiavi non scadute senza restrizioni o consentite per l’origine dell’URL. Per una chiave limitata inserisci un’origine consentita; usa Gestisci chiavi e domini consentiti per verificarla. Se il modulo non è disponibile, completa prima il passaggio di configurazione mostrato nella dashboard. Seleziona una chiave adatta e copia lo snippet generato, che include la chiave pubblica e l’URL API del progetto:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Per le piattaforme orientate alla documentazione, consulta le guide chatbot AI per MkDocs, chatbot AI per VitePress e chatbot AI per GitBook.

Sostituisci YOUR_API_KEY con la chiave pubblica del widget della dashboard. Mantieni il valore data-api-url esattamente come appare nella dashboard. In produzione è un URL stabile https://...convex.site/chat per l'API pubblica del widget.

Cosa deve contenere lo script

Usa gli attributi dello script per i valori che devono essere disponibili prima dell'avvio del widget:

Attributo	Obbligatorio	Utilizzo
src	Sì	Carica il JavaScript del widget ChattyBox.
data-api-key	Sì	Identifica la chiave pubblica del widget per il progetto.
data-api-url	Sì	Invia le richieste del widget all'API ChattyBox.
data-locale	No	Richiede lingua all’avvio, solo con override consentiti.
data-chattybox-widget="true"	No	Permette ai loader dinamici e all’SDK di trovare uno script esistente; è consigliato quando lo script viene inserito dal codice dell’applicazione.
data-debug="true"	No	Abilita la diagnostica nel browser; è disattivata per impostazione predefinita.
data-color	No	Sovrascrive il colore accento dopo il recupero riuscito della configurazione; usa un colore esadecimale a sei cifre. Preferisci la dashboard.
data-position	No	Sovrascrive la posizione dopo il recupero riuscito della configurazione: bottom-right, bottom-left, top-right o top-left. Preferisci la dashboard.

Usa le impostazioni della dashboard per tutto ciò che deve essere gestito senza ridistribuire il sito:

• Colori, posizione, icona, titolo e messaggio di benvenuto del widget.
• Modalità lingua predefinita e autorizzazione degli override data-locale.
• Creazione ed eliminazione delle chiavi pubbliche e restrizioni facoltative sulle origini per chiave. Apri Installa → Chiavi e domini e scegli Modifica origini per abilitare una restrizione e aggiungere o rimuovere origini di produzione, staging, anteprima o localhost.
• Scraping, nuovo scraping, chat di test, Analytics e lacune informative.

Se abiliti il blocco della configurazione come codice, che è irreversibile, le impostazioni supportate di assistente, fonte, runtime e widget provengono dalla configurazione distribuita anziché dai moduli della dashboard; il blocco impedisce anche le operazioni manuali sui contenuti. Le chiavi pubbliche e le restrizioni facoltative sulle origini restano impostazioni del progetto, non valori del file di configurazione.

L’URL API può essere la radice HTTP del deployment o terminare con /chat; il loader rimuove le barre finali e un eventuale /chat finale prima di ricavare gli endpoint. Non converte un URL Convex .cloud in .site. Non includere query string o frammenti. Installa un solo loader: l’SDK riconosce l’attributo di identificazione indicato sopra, non tutti gli script manuali con lo stesso src.

L’SDK pubblicato 0.1.4 condivide i mount solo se chiave, endpoint, URL dello script, lingua e debug coincidono; una modifica viene rifiutata finché non vengono rimossi tutti gli handle. Il widget non riceve in tempo reale le modifiche della dashboard: reinizializzalo per caricare le impostazioni salvate. Nel sorgente corrente del loader ospitato widget.js v16, le modifiche a <html lang> o data-locale possono aggiornare le etichette se cambia la lingua risolta, secondo la policy del progetto. Verifica la versione distribuita prima di affidarti agli aggiornamenti in tempo reale: questo comportamento è distinto dalla versione dell’SDK npm. Le restrizioni sulle origini, se attive, usano Origin o, in alternativa, l’origine di Referer; origini assenti o non consentite producono 401 Invalid API key. Non sono autenticazione.

HTML semplice

Incolla lo snippet una volta vicino alla fine di body, subito prima di </body>. Funziona con HTML statico, siti scritti a mano e template che espongono un footer globale.

<!doctype html>
<html lang="en">
  <head>
    <title>Example Site</title>
  </head>
  <body>
    <main>
      <!-- Page content -->
    </main>

    <script
      src="https://chattybox.ai/widget.js"
      data-api-key="YOUR_API_KEY"
      data-api-url="YOUR_WIDGET_API_URL"
      async
    ></script>
  </body>
</html>

Next.js / App shell React

Per un sito Next.js con App Router, aggiungi il widget a app/layout.tsx con next/script in modo che venga caricato una volta per tutta l'app.

import Script from "next/script";
import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://chattybox.ai/widget.js"
          data-api-key="YOUR_API_KEY"
          data-api-url="YOUR_WIDGET_API_URL"
          data-chattybox-widget="true"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Per una SPA React, aggiungi lo script una volta nell’app shell o nel template HTML principale, non in ogni componente di route. Mantieni il loader in una shell persistente durante la navigazione. Per rimuoverlo da una route o revocare il consenso, nell’SDK pubblicato 0.1.4 chiama remove() per ogni handle: solo l’ultimo segnala a widget.js v15 di rimuovere l’interfaccia e gli stili e annullare inizializzazione, retry in attesa e chat in corso. Il loader esegue al massimo 10 tentativi e non pianifica retry oltre il budget di 30 secondi, che non è un timeout rigido per una richiesta in corso. Dopo l’inizializzazione v15 è disponibile anche window.ChattyBox.destroy(). Il teardown non può annullare una richiesta già elaborata dal server. Il widget fluttua sotto document.body, non viene renderizzato dentro il componente che lo carica.

import { useEffect } from "react";

export function ChattyBoxWidget() {
  useEffect(() => {
    if (document.getElementById("chattybox-widget-script")) return;

    const script = document.createElement("script");
    script.id = "chattybox-widget-script";
    script.src = "https://chattybox.ai/widget.js";
    script.async = true;
    script.setAttribute("data-api-key", "YOUR_API_KEY");
    script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
    script.setAttribute("data-chattybox-widget", "true");
    document.body.appendChild(script);
  }, []);

  return null;
}

Docusaurus

In Docusaurus, crea o aggiorna src/theme/Root.tsx così il widget sarà disponibile in tutte le pagine della documentazione.

import React, { useEffect } from "react";

export default function Root({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    if (document.getElementById("chattybox-widget-script")) return;

    const script = document.createElement("script");
    script.id = "chattybox-widget-script";
    script.src = "https://chattybox.ai/widget.js";
    script.async = true;
    script.setAttribute("data-api-key", "YOUR_API_KEY");
    script.setAttribute("data-api-url", "YOUR_WIDGET_API_URL");
    script.setAttribute("data-chattybox-widget", "true");
    document.body.appendChild(script);
  }, []);

  return <>{children}</>;
}

Se il sito Docusaurus ha route tradotte, imposta data-locale prima del caricamento, se gli override sono consentiti, oppure usa la modalità automatica e il valore <html lang> della pagina. In modalità fissa si applica la lingua predefinita del progetto, salvo un override consentito. Nel codice sorgente attuale, il widget ospitato widget.js v16 può aggiornare le etichette gestite dal prodotto quando <html lang> o data-locale cambia la lingua risolta; verifica la versione del loader distribuita prima di fare affidamento sugli aggiornamenti in tempo reale. Questo comportamento non appartiene all’SDK npm pubblicato 0.1.4. Il titolo e il messaggio di benvenuto personalizzati, così come le risposte generate, non vengono tradotti automaticamente.

Mantieni il loader nell’app shell persistente durante la normale navigazione. Non ricrearlo a ogni cambio di route lato client; quando serve rimuoverlo intenzionalmente, usa l’API di distruzione del widget ospitato o rimuovi tutti gli handle di mount se hai usato l’SDK.

Interfaccia personalizzata

Il widget ospitato è facoltativo. Se vuoi il pieno controllo del rendering, dello stato dei messaggi e del design delle interazioni, usa l'SDK JavaScript con la stessa chiave API pubblica e lo stesso URL API del widget.

CMS generico/HTML personalizzato

La maggior parte delle piattaforme CMS dispone di un'area globale per il codice personalizzato, un footer o un template del tema. Aggiungi lì lo script, così ogni pagina pubblica potrà caricare il widget.

Usa questo percorso per Webflow, Framer, Squarespace, le aree di codice personalizzato di Wix, i temi Shopify, i template HubSpot e le piattaforme CMS personalizzate che consentono di modificare l'HTML globale.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Prima di pubblicare, verifica che il CMS non rimuova data-api-key, data-api-url o async dagli script personalizzati.

Google Tag Manager

Usa Google Tag Manager quando il team gestisce già gli script di terze parti tramite GTM.

1. Apri il contenitore GTM.
2. Crea un nuovo tag Custom HTML.
3. Incolla lo snippet ChattyBox.
4. Usa un trigger All Pages oppure un trigger più ristretto solo per le pagine in cui deve comparire il widget.
5. Visualizza il contenitore in anteprima, verifica che il widget venga caricato e poi pubblica.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Se il sito usa la modalità consenso o una policy di consenso dei tag, assicurati che il widget possa essere caricato nelle pagine in cui i visitatori hanno bisogno di aiuto.

Nelle SPA, un trigger GTM più ristretto evita il caricamento iniziale sulle route escluse, ma non rimuove un widget già caricato su un’altra route. Non attivare ripetutamente il loader ai cambiamenti della cronologia.

Content Security Policy

Per il loader ospitato predefinito, consenti https://chattybox.ai in script-src e l’origine dell’API del widget in connect-src. Il widget inserisce un foglio di stile e attributi di stile inline; al momento non dispone di un’opzione nonce, quindi una policy che vieta gli stili inline bloccherà parti dell’interfaccia. Se la tua policy lo consente, autorizza 'unsafe-inline' per questi stili oppure usa un’interfaccia personalizzata compatibile con la policy. Il caricamento del font Inter all’apertura del launcher richiede anche https://fonts.googleapis.com in style-src e https://fonts.gstatic.com in font-src. Consenti in img-src le origini delle immagini delle icone configurate. Valuta i requisiti di consenso e sicurezza prima di allentare la CSP.

Guida al plugin WordPress

Per un'installazione WordPress senza codice, usa il plugin WordPress ChattyBox. Segui la guida al plugin WordPress per installarlo, configurarlo, escludere route e verificarlo. L'endpoint API di produzione viene configurato automaticamente.

Il plugin carica il widget ospitato nelle richieste del frontend pubblico senza modificare il tema. Non viene caricato intenzionalmente in wp-admin, nei feed o nelle richieste REST o AJAX.

Questo non è un controllo della privacy o dell’accesso per ogni pagina frontend. Se serve, implementa e verifica l’esclusione di checkout, account, pagine protette da password o riservate agli iscritti tramite il filtro del plugin, oppure usa un’installazione manuale limitata alle pagine appropriate. L’impostazione dell’URL del loader del plugin non modifica l’endpoint API di produzione integrato: usa lo snippet manuale per un’installazione API diversa.

Se preferisci installare manualmente lo script, usa una delle posizioni per gli script già supportate dalla tua configurazione WordPress:

• Impostazioni del tema che forniscono script per header o footer.
• Un tema child che controlla il template del footer.
• Un plugin per script di header/footer.
• Google Tag Manager se il sito WordPress lo utilizza già.

Colloca lo snippet in una posizione globale del footer affinché compaia nelle pagine pubblicate, negli articoli, nei documenti e negli articoli della knowledge base in cui deve essere disponibile il chatbot.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="YOUR_WIDGET_API_URL"
  async
></script>

Evita di aggiungere il widget alle pagine wp-admin, checkout, account o membership private, a meno che tali pagine non siano intenzionalmente pubbliche e supportate.

Modulo Drupal

Per Drupal 10 o 11, Composer è il percorso di installazione consigliato. Aggiungi il repository VCS GitHub pubblico al composer.json principale del progetto Drupal che lo utilizza:

{
  "repositories": {
    "chattybox-drupal": {
      "type": "vcs",
      "url": "https://github.com/OpenStaticFish/chattybox-drupal.git"
    }
  }
}

Poi installa il modulo contrassegnato e abilitalo:

composer require openstaticfish/chattybox-drupal:^0.1
drush en chattybox

Apri Configuration > Web services > ChattyBox, incolla la chiave API pubblica del widget dallo snippet di Installa → Installazione sul sito web e abilita il chatbot. La versione del modulo verificata localmente usa un endpoint API codificato nel modulo: confrontalo con lo snippet e usa l’integrazione manuale per un deployment API diverso. Consulta la guida al modulo chatbot Drupal per esclusioni delle route, cache e consenso.

Il modulo parte disattivato ed esclude le richieste amministrative e non HTML, ma non tutti i contenuti frontend privati. Modificare l’URL dello script non cambia l’endpoint API di produzione integrato. Per usare un’installazione API diversa, usa uno snippet manuale.

Verifica

Dopo l'installazione, completa la checklist di lancio prima di annunciare il chatbot:

• Apri una pagina pubblica in una finestra in incognito.
• Conferma che compaia il launcher del widget.
• Apri il widget e poni una domanda reale di un cliente.
• Verifica che una risposta supportata includa citazioni delle fonti, quindi poni una domanda non supportata e controlla il fallback (che potrebbe non avere fonti).
• Controlla nella console del browser l’assenza di data-api-key, l’assenza di data-api-url o eventuali errori di chiave. Verifica se la chiave ha restrizioni di origine attive e, in tal caso, se l’origine desiderata è consentita.