Installare il widget

Installare Webble richiede due pezzi: un piccolo endpoint per il token sul tuo backend e un tag script nelle tue pagine. La finestra Installa widget della dashboard li genera entrambi con i valori del tuo sito già compilati. Questa pagina spiega cosa fanno — scegli il tuo stack nelle schede qui sotto.

Perché un endpoint per il token?

Il widget non porta mai un segreto nel browser. Il tuo backend custodisce un API token di Webble e lo scambia con token di chat a breve scadenza, limitati al tuo sito. Il widget interroga il tuo endpoint e usa ciò che restituisce. Un token di chat trapelato scade da solo, e revocare l'API token ferma lo scambio.

1. Crea un API token

Crea un API token per il tuo sito nella dashboard e conservalo tra i segreti del backend come WEBBLE_API_TOKEN. Non deve mai comparire nel codice lato client. Un token può coprire più dei tuoi siti: il websiteId che invii nello scambio qui sotto indica per quale sito è il token di chat.

2. Aggiungi l'endpoint del token

Il tuo endpoint inoltra lo scambio a Webble e restituisce la risposta così com'è — codice di stato compreso, perché il widget interpreta un 403 (modalità test, tetto di spesa) come "nasconditi". Marca la risposta Cache-Control: no-store, altrimenti una risposta in cache continua a servire un token ormai scaduto.

Sostituisci ID_DEL_TUO_SITO con l'id del tuo sito, mostrato nella dashboard.

export async function GET() {
  const res = await fetch("https://webble.it/api/v1/widget-tokens", {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.WEBBLE_API_TOKEN}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({ websiteId: "ID_DEL_TUO_SITO" }),
    cache: "no-store",
  });
  return Response.json(await res.json(), {
    status: res.status,
    headers: { "cache-control": "no-store" },
  });
}

3. Aggiungi il tag script

data-wb-token-url punta all'endpoint del punto 2, sulla tua stessa origine. defer evita che il tag blocchi il rendering della pagina, così può stare sia in <head> sia in fondo al <body>.

<script
  defer
  src="https://webble.it/widget/webble.iife.js"
  data-wb-token-url="/api/webble-token"
></script>

• data-wb-token-url è l'endpoint del punto 2, sulla tua stessa origine.
• data-wb-lang è opzionale. Forza la lingua del widget invece di seguire il browser del visitatore.
• data-wb-pages è opzionale. Elenca le pagine in cui il widget deve comparire, come pattern di percorso separati da spazi o virgole; altrove resta spento, anche quando il sito naviga senza ricaricare. / è solo la homepage, /docs/* un livello sotto /docs, /docs/** /docs e tutto ciò che sta sotto, e un ! iniziale esclude: data-wb-pages="/** !/checkout/**" mostra il widget ovunque tranne che nel checkout. Senza l'attributo il widget è su ogni pagina in cui c'è lo script tag.

Il widget viene renderizzato in uno Shadow DOM, quindi il CSS del tuo sito e quello del widget non si toccano mai. Colori, stile del launcher e messaggio introduttivo si configurano per sito nello studio dell'aspetto della dashboard.

Visitatori autenticati

Se il tuo sito ha un proprio login, comunica a Webble chi sta chattando. Il tuo endpoint invia un visitorId nella richiesta che crea il token della chat: un identificativo stabile del visitatore autenticato, che non sia un segreto e non riveli chi è, per esempio un HMAC del suo id utente con una chiave tua, oppure null per un visitatore anonimo (al massimo 256 caratteri). Solo il tuo server può garantirlo, perché solo il tuo server vede la sessione del tuo login e custodisce il token API.

const session = await getSession(request);
const res = await fetch("https://webble.it/api/v1/widget-tokens", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.WEBBLE_API_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    websiteId: "YOUR_SITE_ID",
    visitorId: session ? hmac(session.userId) : null,
  }),
});
const body = await res.json();
return Response.json(
  {
    ...body,
    guestToken: session ? await mintGuestToken(session) : null,
  },
  { status: res.status, headers: { "cache-control": "no-store" } }
);

Webble registra il visitorId insieme al token della chat e non lo restituisce. Ogni messaggio inviato dal widget porta solo il token della chat e Webble ne ricava il visitatore, quindi una pagina non può cambiare l'identità con cui chatta.

Se i server MCP del sito devono agire per conto del visitatore, aggiungi anche un guestToken al JSON restituito dal tuo endpoint: una qualsiasi stringa che identifichi il visitatore autenticato presso la tua API, oppure null per un visitatore anonimo. Il widget lo invia con ogni messaggio e Webble lo inoltra a ogni server MCP abilitato per il sito nell'header X-Webble-Guest-Token. Webble non lo salva mai. Viene rinnovato insieme al token della chat, quindi l'accesso o l'uscita del visitatore vengono recepiti al rinnovo successivo. Il guest token deve restare valido per almeno 15 minuti, la durata di un token della chat.

Modalità test e live

Finché il sito è in modalità test, lo scambio del token rifiuta i widget installati, e solo l'anteprima della dashboard può chattare. Porta il sito in modalità live quando sei pronto per i visitatori.