Passa al contenuto principale

:::note Stato delle versioni Il pacchetto npm SDK pubblicato è 0.1.4; il sorgente corrente del loader ospitato è widget.js v16. Sono versioni separate: il pacchetto non fissa la versione del loader. Il loader v16 gestisce il teardown tramite remove() o window.ChattyBox.destroy(); verifica la versione distribuita prima di farci affidamento. Il client headless sendMessage() non ritenta automaticamente. :::

Integra con un assistente di programmazione IA

L’integrazione consigliata è il pacchetto npm @openstaticfish/chattybox. Permette al codice dell’applicazione di configurare la chiave pubblica e l’URL API, caricare l’interfaccia flottante gestita di ChattyBox da una shell browser persistente oppure usare il client headless per un’interfaccia completamente personalizzata. Il widget flottante non viene inserito nel componente che lo carica.

Lo script autonomo widget.js è documentato per ultimo come fallback senza build per i siti che non possono installare pacchetti npm.

Prima di iniziare​

Completa la configurazione del chatbot prima di chiedere a un assistente di modificare l’applicazione:

  • Verifica risposte rappresentative e citazioni in Prova il chatbot.
  • In Installa → Chiavi e domini, controlla o crea una chiave pubblica per il browser e verifica le impostazioni delle origini. Una chiave preparata per un sito può essere già limitata alla sua origine; le chiavi senza restrizioni funzionano da tutte le origini. Le restrizioni sono una protezione facoltativa, non autenticazione dei visitatori.
  • In Installa → Installazione sul sito web, seleziona una chiave adatta e copia lo snippet. Usa il suo data-api-url, se presente; altrimenti recupera la corretta URL HTTP dell’API widget dalla configurazione del deployment.
  • Decidi se un widget flottante persistente è adatto all’applicazione oppure se serve un’interfaccia personalizzata con posizionamento e teardown limitati alle route previste.

Sono credenziali pubbliche del browser. Evita comunque di inserire nei commit valori specifici dell’ambiente e non fornire mai un token di deployment della configurazione, credenziali amministrative o file di ambiente non pertinenti.

Consigliato: monta l’interfaccia gestita da npm​

Questo è il prompt predefinito per React, Next.js, Vite e altre applicazioni browser basate su pacchetti.

Istruzione
Integra il pacchetto npm ChattyBox

Integra ChattyBox in questa applicazione usando il pacchetto npm @openstaticfish/chattybox.

Configurazione pubblica del browser:
- Chiave API: [PASTE PUBLIC WIDGET KEY]
- URL API: [PASTE WIDGET API URL]

Nel dashboard, verifica le risposte in **Prova il chatbot**, controlla la chiave in **Installa → Chiavi e domini** e selezionala in **Installa → Installazione sul sito web** per copiare lo snippet.

Usa soltanto la chiave pubblica del widget e il relativo URL API: una chiave preparata per un sito può essere già limitata alla sua origine. Le restrizioni delle origini sono una protezione facoltativa, non autenticazione dei visitatori. Non inserire credenziali amministrative, token di deployment o segreti in codice eseguito nel browser né nei prompt.

Prima esamina il framework, il modello di routing, il gestore dei pacchetti, le convenzioni delle variabili d’ambiente e il layout persistente dell’applicazione. Dimmi quali file intendi modificare prima di apportare modifiche. Fammi una domanda se non sono chiare le route in cui deve comparire ChattyBox.

Requisiti:
1. Installa @openstaticfish/chattybox con il gestore dei pacchetti già usato da questo repository.
2. Memorizza la chiave API pubblica e l’URL API usando la convenzione del framework per le variabili d’ambiente esposte al browser. Aggiungi nomi segnaposto a un file di ambiente di esempio, ma non inserire nei commit valori reali.
3. Importa Chattybox da @openstaticfish/chattybox e crea un client con apiKey e baseUrl.
4. Chiama client.mountWidget() solo nel browser, dopo che document.body esiste, da una shell applicativa persistente. Carica un widget flottante sotto document.body, non dentro il componente.
5. Mantieni il loader durante la normale navigazione SPA consentita. L’SDK pubblicato 0.1.4 conta i riferimenti solo per mount con opzioni identiche: chiama remove() su ogni handle restituito; remove() è idempotente e solo l’ultimo handle avvia il teardown. Il loader ospitato v16 del sorgente corrente gestisce il segnale, rimuove l’interfaccia e gli stili di sua proprietà e annulla inizializzazione, tentativi di ripetizione e chat in corso; window.ChattyBox.destroy() è l’equivalente lato loader. Non caricare prima del consenso richiesto né su route sensibili/private; esegui il teardown quando una route viene esclusa o il consenso viene revocato. Verifica che il loader distribuito supporti il teardown: nascondere l’interfaccia o rimuovere soltanto il tag script non basta. Il teardown non può annullare una richiesta già elaborata dal server.
6. Non inserire manualmente widget.js, non creare un proxy backend e non introdurre un secondo loader. mountWidget rifiuta chiave, URL API, URL script, locale o opzioni debug diverse finché non sono stati rimossi tutti gli handle esistenti; non mantiene in silenzio le vecchie opzioni.
7. Mantieni navigazione, confini di rendering, localizzazione, Analytics, consenso e stili esistenti. La locale fornita a mountWidget segue la policy di override dello script del progetto. L’SDK pubblicato 0.1.4 non offre un’API reattiva per aggiornare la locale né una ready promise. Il widget ospitato v16 nel sorgente corrente può aggiornare le etichette di prodotto quando cambia la locale risolta (per esempio se cambia <html lang> o data-locale), nel rispetto della policy del progetto: verifica la versione distribuita prima di farci affidamento. Il widget ospitato v16 esegue al massimo 10 tentativi di chat nella finestra di pianificazione dei retry di 30 secondi; non è un timeout rigido per una richiesta già in corso. sendMessage() headless non ritenta automaticamente; l’SDK 0.1.4 ritenta getWidgetConfig() una sola volta dopo HTTP 400 e i retry delle richieste GET di avvio del loader sono separati. L’SDK 0.1.4 convalida baseUrl e gestisce i corpi di risposta illeggibili.
8. Apporta la modifica mirata più piccola possibile e non eseguire il deployment.
9. Esegui build, lint, controllo dei tipi e test pertinenti del repository.
10. Indica i file modificati, le variabili d’ambiente da impostare, dove viene montata l’interfaccia e come testarla sul sito sottoposto a deployment.

Il codice seguente è uno schema di callback del ciclo di vita nel browser, non una chiamata top-level durante il rendering lato server. Invocalo da un effetto solo client nella shell persistente, dopo che document.body esiste, e conserva l’handle:

import { Chattybox } from '@openstaticfish/chattybox';

const client = new Chattybox({
  apiKey: PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: PUBLIC_CHATTYBOX_API_URL,
});

function mountInBrowser() {
  if (typeof document === 'undefined' || !document.body) return;
  return client.mountWidget();
}

// Keep the returned handle for allowed navigation and intentional teardown.

Crea un’interfaccia personalizzata​

Scegli questa opzione quando l’applicazione deve gestire l’elenco dei messaggi, l’input, gli stati di caricamento, gli errori, le citazioni e il posizionamento invece di montare l’interfaccia gestita.

Istruzione
Crea un’interfaccia ChattyBox headless

Crea un’interfaccia chatbot personalizzata usando il pacchetto npm @openstaticfish/chattybox e il relativo client headless.

Configurazione pubblica del browser:
- Chiave API: [PASTE PUBLIC WIDGET KEY]
- URL API: [PASTE WIDGET API URL]

Nel dashboard, verifica le risposte in **Prova il chatbot** e controlla la chiave in **Installa → Chiavi e domini**; selezionala in **Installa → Installazione sul sito web** quando recuperi lo snippet.

Usa soltanto la chiave pubblica del widget e il relativo URL API. Le restrizioni delle origini sono facoltative e non autenticano i visitatori. Non inserire credenziali amministrative, token di deployment o segreti in codice eseguito nel browser né nei prompt.

Prima esamina il framework dell’applicazione, il sistema dei componenti, i modelli di stato, gli stili, le convenzioni di accessibilità e la configurazione dei test. Proponi i confini dei componenti e i file prima di modificare il codice.

Requisiti:
1. Installa @openstaticfish/chattybox con il gestore dei pacchetti già presente nel repository.
2. Configura un client Chattybox con apiKey e baseUrl usando variabili d’ambiente esposte al browser; non inserire nei commit valori reali.
3. Usa sendMessage() e conserva conversationId nello stato del visitatore; azzeralo quando cambia utente o sessione e non condividerlo tra visitatori non correlati. Chiave pubblica, restrizioni delle origini e ID di conversazione non autenticano i visitatori né proteggono conversazioni private. I messaggi possono essere salvati e restare visibili ai proprietari del progetto; cancellare lo stato locale non elimina i record salvati. Evita dati sensibili. Il modello riceve fino a 12 messaggi recenti salvati, ciascuno troncato a 2.000 caratteri, non l’intera trascrizione né una memoria permanente.
4. Visualizza le risposte come testo o Markdown sanitizzato e le fonti HTTP(S) come link accessibili, mantenendone l’ordine. Non inserire HTML non attendibile né usare schemi di link non sicuri.
5. Implementa gli stati di attesa, vuoto, errore e retry. Le risposte di fallback possono avere un array sources vuoto; non esiste un campo generale wasAnswered. Se il backend fornisce providerError, restringine in sicurezza il tipo come campo opzionale e mostra un errore generico del provider, non una risposta normale. Non ritentare alla cieca una risposta keyed già completata. L’SDK pubblicato 0.1.4 potrebbe non dichiarare i campi di risposta del sorgente corrente (per esempio providerError o productFallback): restringili in sicurezza e tollerane l’assenza. Gestisci sia ChattyboxError sia gli errori di rete non racchiusi; code è opzionale.
6. Rifiuta messaggi vuoti o con oltre 2.000 caratteri dopo il trim, impedisci invii duplicati e mantieni accessibili tastiera e screen reader. sendMessage() headless non ritenta automaticamente: usa un idempotencyKey univoco per ogni messaggio logico e riutilizza esattamente lo stesso input per i retry, incluso conversationId; non ritentare alla cieca ogni HTTP 409. L’SDK 0.1.4 ritenta getWidgetConfig() una sola volta dopo HTTP 400. Il widget ospitato v16 esegue al massimo 10 tentativi di chat nella finestra di pianificazione dei retry di 30 secondi, non un timeout rigido per una richiesta in corso; i retry GET di avvio del loader sono separati.
7. Monta l’interfaccia solo nelle route o nel layout indicati.
8. Segui componenti e stili esistenti invece di aggiungere un nuovo design system.
9. Non caricare widget.js e non chiamare mountWidget().
10. Esegui build, lint, controllo dei tipi e test pertinenti, poi indica i file modificati e un piano di verifica.

Note sui framework​

Quando serve, dai all’assistente una frase aggiuntiva:

  • Next.js App Router: “Mantieni il client Chattybox e la chiamata a mountWidget() all’interno di un piccolo Client Component renderizzato dal layout previsto.”
  • React SPA: “Monta dalla shell persistente dell’applicazione o dal layout della route specifica e occupati della pulizia nella funzione di ritorno dell’effetto.”
  • Docusaurus: “Crea un componente del tema solo client e renderizzalo da src/theme/Root; mantieni la navigazione della documentazione e i cambi di lingua.”
  • Vue, Nuxt, Svelte o un altro framework: “Usa il ciclo di vita di mounting solo client del framework e il relativo ciclo di pulizia.”

Esamina un’integrazione SDK esistente​

Istruzione
Esamina la mia integrazione dell’SDK ChattyBox

Esamina questa integrazione ChattyBox senza eseguire il deployment e senza modificare codice non correlato.

Verifica che:
1. @openstaticfish/chattybox sia installato e importato invece di duplicarne il comportamento.
2. Un solo client Chattybox riceva la chiave API pubblica e l’URL API previsti, selezionati in **Installa → Chiavi e domini** e **Installa → Installazione sul sito web**; verifica le risposte in **Prova il chatbot**.
3. Le variabili d’ambiente del browser seguano le regole di denominazione delle variabili pubbliche di questo framework senza esporre credenziali private.
4. mountWidget() o l’interfaccia personalizzata compaia solo nelle route previste e venga pulita correttamente. Non caricare il widget prima del consenso richiesto né su route sensibili/private; nelle transizioni SPA e alla revoca del consenso esegui il teardown reale, non limitarti a nascondere l’interfaccia o rimuovere il tag script. Verifica la versione distribuita del loader.
5. La navigazione lato client e i nuovi mounting in sviluppo non creino istanze duplicate.
6. I confini di rendering, la localizzazione, Analytics, il consenso, l’accessibilità e il layout esistenti rimangano intatti. Le restrizioni delle origini sono facoltative e non autenticano i visitatori; le chiavi limitate richiedono un’origine della richiesta consentita e fetch in Node non fornisce automaticamente gli header del browser.
7. L’implementazione abbia test appropriati e non includa refactoring non correlati.

Restituisci i risultati per gravità, con percorsi dei file e riferimenti alle righe. Proponi solo le correzioni sicure più piccole e fornisci i comandi esatti di verifica.

Niente npm o passaggio di build?​

Usa la guida all’installazione di widget.js solo quando il sito non può usare il pacchetto npm, ad esempio con HTML semplice, un campo di codice personalizzato di un CMS o Google Tag Manager.

Istruzione
Installa lo script widget di fallback

Installa il widget ChattyBox ospitato su questo sito usando lo script esatto generato in **Installa → Installazione sul sito web** nel dashboard di ChattyBox:

[PASTE COMPLETE WIDGET SCRIPT]

Esamina prima il sito e identifica il punto d’inserimento più sicuro per le pagine pubbliche. Usa soltanto lo script fornito e le credenziali pubbliche; non esporre credenziali private. Carica lo script invariato una sola volta e solo dopo il consenso richiesto; escludi le route private, amministrative, di checkout o altrimenti sensibili. Nelle transizioni SPA o alla revoca del consenso, esegui il teardown di un widget già avviato prima di entrare in uno stato escluso e reinizializzalo solo quando consentito. Verifica che la versione distribuita del loader supporti il teardown: nascondere l’interfaccia o rimuovere soltanto il tag script non basta. Il teardown non può annullare richieste già elaborate. Mantieni il comportamento CSP, non eseguire il deployment della modifica e indica la posizione modificata insieme a un piano di test nel browser.

Prova il risultato​

  1. Esamina il diff e conferma che non siano state inserite nei commit credenziali reali.
  2. Esegui build, lint, controllo dei tipi e i test normali del progetto.
  3. Esegui il deployment tramite il normale processo di revisione.
  4. Verifica le route previste in una finestra privata del browser, inclusa la navigazione lato client.
  5. Poni una domanda supportata, segui una citazione e prova il comportamento di fallback.
  6. Controlla il layout mobile, l’uso della tastiera e la console del browser.

Continua con la documentazione di riferimento dell’SDK e la checklist di lancio.