Ga naar de hoofdinhoud

:::note Versiestatus De gepubliceerde npm-SDK is 0.1.4; de huidige bronversie van de gehoste loader is widget.js v16. Dit zijn afzonderlijke versies: het SDK-pakket legt de loaderversie niet vast. Loader v16 ondersteunt teardown via remove() of window.ChattyBox.destroy(); controleer de uitgerolde versie voordat je hierop vertrouwt. Headless sendMessage() probeert niet automatisch opnieuw. :::

Integreren met een AI-codeerassistent

De aanbevolen integratie is het npm-pakket @openstaticfish/chattybox. Applicatiecode kan daarmee de openbare sleutel en API-URL configureren en de zwevende, onderhouden ChattyBox-widget vanuit een blijvende browsershell laden, of de headless client gebruiken voor een volledig aangepaste UI. De zwevende widget wordt niet in de component geplaatst die hem laadt.

Het zelfstandige script widget.js wordt als laatste beschreven als fallback zonder build voor sites waarop npm-pakketten niet kunnen worden geïnstalleerd.

Voordat je begint​

Rond de chatbotconfiguratie af voordat je een assistent vraagt je applicatie te bewerken:

  • Controleer representatieve antwoorden en citaten in Chatbot testen.
  • Bekijk of maak onder Installeren → Sleutels en domeinen een openbare browsersleutel aan en controleer de origininstellingen. Een sleutel die voor een website is voorbereid, kan al tot de origin van die site beperkt zijn; sleutels zonder beperkingen werken vanaf alle origins. Originbeperkingen zijn optionele extra beveiliging, geen bezoekersauthenticatie.
  • Selecteer in Installeren → Installatie op website een geschikte sleutel en kopieer het snippet. Gebruik de data-api-url als die aanwezig is; haal anders het juiste HTTP-eindpunt van de widget-API uit de deploymentconfiguratie.
  • Bepaal of een blijvende zwevende widget bij de applicatie past of dat je een aangepaste UI nodig hebt met plaatsing per route en teardown.

Dit zijn openbare browsergegevens. Voorkom toch dat je omgevingsspecifieke waarden commit; geef nooit een configuratiedeploymenttoken, beheerdersreferentie of niet-gerelateerd omgevingsbestand door.

Aanbevolen: de onderhouden UI vanuit npm mounten​

Dit is de standaardprompt voor React, Next.js, Vite en andere browserapplicaties die op pakketten zijn gebaseerd.

Opdracht
Het ChattyBox-npm-pakket integreren

Integreer ChattyBox in deze applicatie met het npm-pakket @openstaticfish/chattybox.

Openbare browserconfiguratie:
- API-sleutel: [PASTE PUBLIC WIDGET KEY]
- API-URL: [PASTE WIDGET API URL]

Controleer in het dashboard antwoorden via **Chatbot testen**, controleer de sleutel onder **Installeren → Sleutels en domeinen** en selecteer die onder **Installeren → Installatie op website** om het snippet te kopiëren.

Gebruik alleen de openbare widget-sleutel en de bijbehorende widget-API-URL. Een sleutel die voor een website is voorbereid, kan al tot de origin van die site beperkt zijn. Originbeperkingen zijn optionele extra beveiliging, geen bezoekersauthenticatie. Plaats geen beheerdersreferenties, deploymenttokens of andere geheimen in browsercode of prompts.

Inspecteer eerst het framework, het routingmodel, de pakketbeheerder, de conventies voor omgevingsvariabelen en de blijvende applicatielayout. Vertel me vóór het bewerken welke bestanden je van plan bent te wijzigen. Vraag het me als onduidelijk is op welke routes ChattyBox moet verschijnen.

Vereisten:
1. Installeer @openstaticfish/chattybox met de pakketbeheerder die deze repository al gebruikt.
2. Sla de openbare API-sleutel en API-URL op volgens de conventie van het framework voor omgevingsvariabelen die aan de browser worden blootgesteld. Voeg placeholdernamen toe aan een voorbeeldbestand voor omgevingsvariabelen, maar commit geen echte waarden.
3. Importeer Chattybox vanuit @openstaticfish/chattybox en maak één client met apiKey en baseUrl.
4. Roep client.mountWidget() alleen in browsercode aan nadat document.body bestaat, vanuit een blijvende applicatieshell. De widget zweeft onder document.body en wordt niet in de component geplaatst.
5. Houd de loader tijdens toegestane SPA-navigatie in stand. De gepubliceerde SDK 0.1.4 telt alleen mounts met identieke opties samen: roep remove() aan op elke teruggegeven handle; remove() is idempotent en alleen de laatste handle start de teardown. De huidige bronversie van de gehoste loader v16 verwerkt dit signaal, verwijdert de eigen UI en stijlen en annuleert de initialisatie, retries en lopende chat; window.ChattyBox.destroy() biedt dezelfde teardown via de loader. Laad de widget niet vóór de vereiste toestemming of op gevoelige/private routes; voer teardown uit wanneer een route wordt uitgesloten of toestemming wordt ingetrokken. Controleer of de uitgerolde loader teardown ondersteunt: de UI verbergen of alleen de script-tag verwijderen is niet voldoende. Teardown kan een al door de server verwerkte aanvraag niet ongedaan maken.
6. Injecteer widget.js niet handmatig, maak geen backendproxy en introduceer geen tweede loader. mountWidget weigert een gewijzigde sleutel, API-URL, script-URL, locale of debugoptie zolang er bestaande handles zijn; oude opties blijven niet stilzwijgend behouden.
7. Behoud bestaande navigatie, renderinggrenzen, lokalisatie, analytics, toestemming en styling. Een locale-optie voor de SDK volgt het script-overridebeleid van het project. De gepubliceerde SDK 0.1.4 heeft geen reactieve API voor locale-updates en geen ready-promise. De huidige bronversie van de gehoste widget v16 kan productlabels bijwerken wanneer de opgeloste locale verandert (bijvoorbeeld door een wijziging van <html lang> of data-locale), afhankelijk van het locale-beleid van het project; controleer de uitgerolde loader voordat je hierop vertrouwt. De gehoste widget v16 doet maximaal 10 chatpogingen binnen een retry-planningsvenster van 30 seconden; dit is geen harde timeout voor een aanvraag die al loopt. Headless sendMessage() probeert niet automatisch opnieuw; SDK 0.1.4 probeert getWidgetConfig() na HTTP 400 precies één keer opnieuw en de startup-GET-retries van de loader staan hier los van. SDK 0.1.4 valideert baseUrl en handelt onleesbare responsebody's af.
8. Breng alleen de kleinst mogelijke gerichte wijziging aan en deploy die niet.
9. Voer de build, lint, type-check en relevante tests van de repository uit.
10. Rapporteer gewijzigde bestanden, de omgevingsvariabelen die ik moet instellen, waar de UI wordt gemount en hoe ik die op de gedeployde site kan testen.

De volgende code is een voorbeeld van een browser-lifecyclecallback, geen aanroep op topniveau tijdens server rendering. Roep de functie aan vanuit een client-only effect in de blijvende shell, nadat document.body bestaat, en bewaar de 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();
}

// Bewaar de handle voor toegestane navigatie en bewuste teardown.

Bouw een aangepaste interface​

Kies dit wanneer je applicatie zelf de berichtenlijst, invoer, laadstatussen, fouten, citaten en plaatsing moet beheren in plaats van de onderhouden interface te mounten.

Opdracht
Een headless ChattyBox-interface bouwen

Bouw een aangepaste chatbotinterface met het npm-pakket @openstaticfish/chattybox en de headless client daarvan.

Openbare browserconfiguratie:
- API-sleutel: [PASTE PUBLIC WIDGET KEY]
- API-URL: [PASTE WIDGET API URL]

Controleer in het dashboard antwoorden via **Chatbot testen** en controleer de sleutel onder **Installeren → Sleutels en domeinen**; selecteer die onder **Installeren → Installatie op website** wanneer je het snippet ophaalt.

Gebruik alleen de openbare widget-sleutel en de bijbehorende widget-API-URL. Originbeperkingen zijn optioneel en authenticeren bezoekers niet. Plaats geen beheerdersreferenties, deploymenttokens of andere geheimen in browsercode of prompts.

Inspecteer eerst het framework, componentsysteem, de statepatronen, styling, toegankelijkheidsconventies en testopstelling van de applicatie. Stel de componentgrenzen en bestanden voor voordat je bewerkt.

Vereisten:
1. Installeer @openstaticfish/chattybox met de bestaande pakketbeheerder van de repository.
2. Configureer één Chattybox-client met apiKey en baseUrl via browser-exposed omgevingsvariabelen; commit geen echte waarden.
3. Gebruik sendMessage() en bewaar conversationId in bezoekersgebonden state; wis deze ID wanneer de gebruiker of sessie verandert en deel hem nooit tussen niet-gerelateerde bezoekers. Een openbare sleutel, originbeperkingen en conversationId authenticeren bezoekers niet en beschermen privégesprekken niet. Berichten kunnen worden opgeslagen en zichtbaar blijven voor projecteigenaren; lokale state wissen verwijdert geen opgeslagen records. Vermijd gevoelige gegevens. Met dezelfde conversationId ontvangt het model maximaal 12 recente opgeslagen berichten, elk afgekapt op 2.000 tekens; het krijgt niet het volledige transcript of een permanent geheugen.
4. Geef antwoorden veilig weer als tekst of gesanitiseerde Markdown en geef HTTP(S)-bronnen weer als toegankelijke links, in dezelfde volgorde. Voeg nooit niet-vertrouwde ruwe HTML of onveilige linkprotocollen in.
5. Implementeer pending-, lege, fout- en retrystatussen. Fallbackantwoorden kunnen lege sources hebben; er is geen algemene wasAnswered-vlag. Als de backend providerError levert, baken die optionele waarde veilig af en toon een generieke providerfout, geen normaal antwoord. Herhaal een voltooide keyed response niet blind. De gepubliceerde SDK 0.1.4 declareert current-source responsevelden zoals providerError of productFallback mogelijk niet; baken zulke velden veilig af en verdraag dat ze ontbreken. Behandel zowel ChattyboxError als ongewikkelde netwerkfouten; code is optioneel.
6. Wijs lege berichten en berichten van meer dan 2.000 tekens na trim af, voorkom dubbele verzendingen en houd toetsenbord- en schermlezergebruik toegankelijk. Headless sendMessage() probeert niet automatisch opnieuw: gebruik één unieke idempotencyKey per logisch bericht en hergebruik voor retries exact dezelfde input, inclusief conversationId; probeer niet elke HTTP 409 blind opnieuw. SDK 0.1.4 probeert getWidgetConfig() na HTTP 400 precies één keer opnieuw. De gehoste widget v16 doet maximaal 10 chatpogingen binnen een retry-planningsvenster van 30 seconden; dit is geen harde timeout voor een lopende aanvraag. De startup-GET-retries van de loader staan hier los van.
7. Mount de interface alleen op de routes of layout die ik aangeef.
8. Volg bestaande componenten en stijlen in plaats van een nieuw designsysteem toe te voegen.
9. Laad widget.js niet en roep mountWidget() niet aan.
10. Voer build, lint, type-check en relevante tests uit en rapporteer daarna de gewijzigde bestanden en een verificatieplan.

Frameworknotities​

Geef de assistent indien nodig één extra zin:

  • Next.js App Router: “Houd de Chattybox-client en de aanroep van mountWidget() binnen een kleine Client Component die door de bedoelde layout wordt gerenderd.”
  • React SPA: “Mount vanuit de blijvende app-shell of de specifieke routelayout en ruim op in de returnfunctie van het effect.”
  • Docusaurus: “Maak een client-only themacomponent en render die vanuit src/theme/Root; behoud docs-navigatie en locale-wijzigingen.”
  • Vue, Nuxt, Svelte of een ander framework: “Gebruik de client-only mount-lifecycle van het framework en de bijbehorende cleanup-lifecycle.”

Een bestaande SDK-integratie controleren​

Opdracht
Mijn ChattyBox-SDK-integratie controleren

Controleer deze ChattyBox-integratie zonder te deployen of niet-gerelateerde code te wijzigen.

Controleer of:
1. @openstaticfish/chattybox is geïnstalleerd en geïmporteerd in plaats van dat het gedrag wordt gedupliceerd.
2. Eén Chattybox-client de bedoelde openbare API-sleutel en API-URL ontvangt, geselecteerd onder **Installeren → Sleutels en domeinen** en **Installeren → Installatie op website**; controleer antwoorden via **Chatbot testen**.
3. Browseromgevingsvariabelen de regels van dit framework voor namen van openbare variabelen volgen zonder privéreferenties bloot te leggen.
4. mountWidget() of de aangepaste interface alleen op de bedoelde routes verschijnt en correct opruimt. Laad de widget niet vóór de vereiste toestemming of op gevoelige/private routes; voer bij SPA-routewissels en intrekking van toestemming echte teardown uit in plaats van alleen de UI te verbergen of de script-tag te verwijderen. Controleer de uitgerolde loaderversie.
5. Client-side navigatie en remounts tijdens development geen dubbele instanties maken.
6. Bestaande renderinggrenzen, lokalisatie, analytics, toestemming, toegankelijkheid en layout intact blijven. Originbeperkingen zijn optioneel en geen bezoekersauthenticatie; beperkte sleutels vereisen een toegestane request-origin en Node-fetch verstuurt browserheaders niet automatisch.
7. De implementatie passende tests heeft en geen niet-gerelateerde refactor bevat.

Geef bevindingen terug per ernstniveau, met bestandspaden en regelnummers. Stel alleen de kleinst mogelijke veilige oplossingen voor en geef me exacte verificatieopdrachten.

Geen npm of buildstap?​

Gebruik de installatiehandleiding voor widget.js alleen wanneer de site het npm-pakket niet kan gebruiken—bijvoorbeeld gewone HTML, een CMS-veld voor aangepaste code of Google Tag Manager.

Opdracht
Het fallback-widgetscript installeren

Installeer de gehoste ChattyBox-widget op deze site met het exacte script dat is gegenereerd onder **Installeren → Installatie op website** in mijn ChattyBox-project:

[PASTE COMPLETE WIDGET SCRIPT]

Inspecteer de site eerst en bepaal het veiligste invoegpunt voor openbare pagina’s. Gebruik alleen het meegeleverde script en openbare credentials; stel geen private credentials bloot. Laad het ongewijzigde script precies één keer en alleen nadat de vereiste toestemming is verkregen; sluit private, beheer-, checkout- en andere gevoelige routes uit. Voer bij SPA-routewissels of intrekking van toestemming teardown uit voor een al geïnitialiseerde widget voordat de site naar een uitgesloten toestand gaat, en initialiseer opnieuw zodra dat weer is toegestaan. Controleer of de uitgerolde loader teardown ondersteunt: de UI verbergen of alleen de script-tag verwijderen is niet voldoende. Teardown kan al verwerkte aanvragen niet ongedaan maken. Behoud CSP-gedrag, deploy de wijziging niet en rapporteer de gewijzigde locatie plus een browsertestplan.

Het resultaat testen​

  1. Controleer de diff en bevestig dat er geen echte referenties zijn gecommit.
  2. Voer de normale build, lint, type-check en tests van het project uit.
  3. Deploy via je normale beoordelingsproces.
  4. Controleer de bedoelde routes in een privébrowservenster, inclusief client-side navigatie.
  5. Stel een ondersteunde vraag, volg een citaat en test het fallbackgedrag.
  6. Controleer de mobiele layout, het toetsenbordgebruik en de browserconsole.

Ga verder met de SDK-referentie en de launchchecklist.