Installatiehandleidingen

:::note Versiestatus De gepubliceerde npm-SDK 0.1.4 ondersteunt samen met de gehoste widget.js v15 teardown via remove() of window.ChattyBox.destroy() en annuleert wachtend werk. Controleer welke loader je site daadwerkelijk gebruikt. :::

De gehoste widget.js-integratie is de optie zonder build wanneer je wilt dat ChattyBox de interface en het transport onderhoudt. Als je app dezelfde UI vanuit npm-code moet initialiseren, gebruik dan mountWidget(). Gebruik de headless SDK als je de UI zelf wilt beheren.

Voordat je installeert

Voltooi eerst de flow Aan de slag: configureer en importeer de bron, controleer de geïndexeerde pagina’s en verifieer representatieve antwoorden in Chatbot testen.

Bereid in Installeren een installatie voor je website voor of beheer een browsersleutel via Sleutels en domeinen. Controleer de origininstellingen van de sleutel: een sleutel die voor het domein van een website is voorbereid, kan al tot die origin zijn beperkt; sleutels die zonder beperkingen zijn aangemaakt, werken op meerdere origins. Via Origins bewerken kun je optionele beperkingen inschakelen of de benodigde origins voor productie, preview, staging en localhost toevoegen. Wanneer beperkingen zijn ingeschakeld, moeten schema, hostnaam en poort exact overeenkomen: https://example.com, https://preview.example.com en http://localhost:3000 zijn afzonderlijke vermeldingen. Voer bij Installeren → Installatie op website een HTTP(S)-website-URL in. De kiezer toont niet-verlopen sleutels die onbeperkt zijn of voor de origin van die URL zijn toegestaan. Voer voor een beperkte sleutel een toegestane origin in en bekijk de beperkingen via Sleutels en toegestane domeinen beheren. Is het formulier niet beschikbaar, voltooi dan eerst de getoonde installatiestap in het dashboard. Kies een geschikte sleutel en kopieer het gegenereerde fragment met de openbare sleutel en API-URL van je project:

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

Bekijk voor documentatieplatforms de handleidingen voor de MkDocs AI-chatbot, VitePress AI-chatbot en GitBook AI-chatbot.

Vervang YOUR_API_KEY door de openbare widgetsleutel uit je dashboard. Behoud de waarde van data-api-url exact zoals die in het dashboard wordt getoond. In productie is dit een stabiele https://...convex.site/chat-URL voor de openbare widget-API.

Wat hoort er in het script?

Gebruik scriptattributen voor waarden die beschikbaar moeten zijn voordat de widget kan starten:

Attribuut	Vereist	Gebruik het voor
src	Ja	De JavaScript van de ChattyBox-widget laden.
data-api-key	Ja	De openbare widgetsleutel voor je project identificeren.
data-api-url	Ja	Widgetverzoeken naar de ChattyBox-API sturen.
data-locale	Nee	Een UI-taal bij initialisatie aanvragen, alleen wanneer script-overschrijving in het project is toegestaan.
data-chattybox-widget="true"	Nee	Hiermee kunnen dynamische loaders en de SDK een bestaand script vinden; aanbevolen wanneer je het vanuit applicatiecode injecteert.
data-debug="true"	Nee	Browserdiagnostiek inschakelen; standaard uitgeschakeld.
data-color	Nee	Accentkleur expliciet overschrijven na een geslaagde configuratieophaling; gebruik een hexkleur van zes cijfers. Gebruik bij voorkeur het dashboard.
data-position	Nee	Positie expliciet overschrijven na een geslaagde configuratieophaling: bottom-right, bottom-left, top-right of top-left. Gebruik bij voorkeur het dashboard.

Gebruik dashboardinstellingen voor alles wat je wilt beheren zonder je site opnieuw te deployen:

• Widgetkleuren, positie, pictogram, titel en welkomstbericht.
• Standaardtaalmodus en of overschrijven via data-locale is toegestaan.
• Openbare sleutels aanmaken en verwijderen, plus optionele originbeperkingen per sleutel. Open Installeren → Sleutels en domeinen en kies Origins bewerken om beperkingen in te schakelen en productie-, staging-, preview- of localhost-origins toe te voegen of te verwijderen.
• Scraping, opnieuw scrapen, testchat, analytics en contentgaten.

Als je de config-as-code-vergrendeling inschakelt, die onomkeerbaar is, komen instellingen voor assistent, bron, runtime en ondersteunde widgetfuncties uit de gedeployde configuratie in plaats van uit dashboardformulieren; ook handmatige contentbewerkingen worden geblokkeerd. Openbare sleutels en toegestane origins blijven projectinstellingen en worden geen waarden in het configuratiebestand.

Installeer slechts één loader. De SDK herkent het markeringsattribuut hierboven, niet elk handmatig script met dezelfde src. De gepubliceerde SDK 0.1.4 deelt het script alleen tussen mounts met identieke opties en weigert een andere sleutel, endpoint, script-URL, locale of debuginstelling zolang er handles bestaan. Verwijder alle SDK-handles wanneer je de mount wilt opruimen; alleen de laatste handle geeft de gehoste widget.js v15 de opdracht om de eigen UI en stijlen te vernietigen en de initialisatie, retries en actieve chat te annuleren. De widget volgt wijzigingen in de dashboardconfiguratie niet: initialiseer hem opnieuw om opgeslagen instellingen op te halen. In de huidige broncode kan de gehoste widget.js v16 productlabels vernieuwen wanneer een wijziging van <html lang> of data-locale de opgeloste locale verandert, afhankelijk van het locale-beleid van het project. Controleer de gedeployde loaderversie voordat je op live updates vertrouwt; dit gedrag staat los van de gepubliceerde npm SDK-versie. Origins worden, wanneer beperkingen zijn ingeschakeld, gecontroleerd via Origin of een fallback-origin uit Referer; ontbrekende of niet-toegestane origins geven 401 Invalid API key. Dit is geen authenticatie.

De API-URL mag de HTTP-deploymentroot zijn of eindigen op /chat; de loader verwijdert afsluitende slashes en een afsluitend /chat voordat hij de endpoints afleidt. Hij zet een Convex-.cloud-URL niet om naar .site. Laat querystrings en fragmenten weg. De retries zijn beperkt tot maximaal 10 pogingen binnen 30 seconden. Na initialisatie van v15 is ook window.ChattyBox.destroy() beschikbaar. Opruimen kan een al door de server verwerkte aanvraag niet ongedaan maken.

Plain HTML

Plak het fragment één keer vlak voor het einde van body, net vóór </body>. Dit werkt voor statische HTML, handmatig gecodeerde sites en templates met een algemene footer.

<!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 / React App Shell

Voeg de widget voor een Next.js App Router-site toe aan app/layout.tsx met next/script, zodat hij één keer voor de hele app wordt geladen.

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>
  );
}

Voeg het script voor een React-singlepageapp één keer toe aan je app-shell op het hoogste niveau of aan je HTML-template. Injecteer het niet vanuit elke routecomponent.

Houd de loader tijdens normale navigatie in een blijvende shell. De gehoste widget zweeft onder document.body en wordt niet weergegeven binnen de component die hem laadt. Gebruik voor bewuste teardown de vernietigings-API van de ondersteunde gehoste loader of verwijder alle SDK-handles; zie ook de versie- en opruimbeperkingen hierboven.

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

Maak of wijzig voor Docusaurus src/theme/Root.tsx, zodat de widget op alle documentatiepagina’s beschikbaar is.

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}</>;
}

Als je Docusaurus-site vertaalde routes heeft, stel data-locale dan vóór het laden in als scriptoverschrijvingen zijn toegestaan, of gebruik de automatische modus met <html lang>. In de vaste modus wordt de standaardlocale van het project gebruikt, tenzij een toegestane scriptoverschrijving aanwezig is. In de huidige broncode kan de gehoste widget.js v16 productlabels vernieuwen wanneer <html lang> of data-locale de opgeloste locale verandert. Controleer de gedeployde loaderversie voordat je op updates tijdens runtime vertrouwt. Dit gedrag hoort niet bij de gepubliceerde npm SDK 0.1.4. Aangepaste titels en welkomstberichten en gegenereerde antwoorden worden niet automatisch vertaald.

Houd de loader in je blijvende applicatieshell tijdens normale client-side routewijzigingen. De widget abonneert zich niet op wijzigingen in de dashboardconfiguratie; initialiseer hem opnieuw om opgeslagen instellingen op te halen. Verwijder bij routegebonden verwijdering of intrekking van toestemming elke SDK 0.1.4-handle: alleen de laatste geeft widget.js v15 opdracht om de UI en stijlen op te ruimen en lopend werk te annuleren.

Aangepaste interface

De gehoste widget is optioneel. Wil je volledige controle over rendering, berichtstatus en interactieontwerp, gebruik dan de JavaScript-SDK met dezelfde openbare widget-API-sleutel en widget-API-URL.

Algemene CMS/aangepaste HTML

De meeste CMS-platforms hebben een algemeen gebied voor aangepaste code, footer of themasjabloon. Voeg het script daar toe, zodat elke openbare pagina de widget kan laden.

Gebruik dit pad voor Webflow, Framer, Squarespace, aangepaste Wix-codegebieden, Shopify-thema’s, HubSpot-templates en aangepaste CMS-platforms waarmee je globale HTML kunt bewerken.

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

Controleer vóór publicatie of het CMS data-api-key, data-api-url of async niet uit aangepaste scripts verwijdert.

Google Tag Manager

Gebruik Google Tag Manager wanneer je team scripts van derden al via GTM beheert.

1. Open je GTM-container.
2. Maak een nieuwe Custom HTML-tag.
3. Plak het ChattyBox-fragment.
4. Gebruik een trigger All Pages of een smallere trigger voor alleen de pagina’s waarop de widget moet worden weergegeven.
5. Bekijk een voorbeeld van de container, controleer of de widget wordt geladen en publiceer vervolgens.

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

Als je site de toestemmingsmodus of een toestemmingsbeleid voor tags gebruikt, zorg er dan voor dat de widget mag laden op pagina’s waar bezoekers hulp nodig hebben.

Bij SPA’s voorkomt een smallere GTM-trigger de eerste keer laden op uitgesloten routes, maar verwijdert die geen widget die al op een andere route is geladen. Activeer de loader niet herhaaldelijk bij geschiedeniswijzigingen.

Content Security Policy

Sta voor de standaard gehoste loader https://chattybox.ai toe in script-src en de origin van je widget-API in connect-src. De widget voegt een stylesheet en inline style-attributen toe; er is momenteel geen nonce-optie, dus een policy die inline stijlen verbiedt, blokkeert delen van de UI. Als je policy dit toestaat, sta dan 'unsafe-inline' toe voor deze stijlen of gebruik een aangepaste UI die bij je policy past. Voor het laden van Inter wanneer de launcher wordt geopend, zijn ook https://fonts.googleapis.com in style-src en https://fonts.gstatic.com in font-src nodig. Sta in img-src alle geconfigureerde afbeeldingsorigins van pictogrammen toe. Controleer de vereisten voor toestemming en beveiliging voordat je de CSP versoepelt.

WordPress-plug-inhandleiding

Gebruik voor een codeloze WordPress-installatie de ChattyBox WordPress-plug-in. Volg de WordPress-plug-inhandleiding om de plug-in te installeren, configureren, routes uit te sluiten en te verifiëren. Het productie-API-eindpunt wordt automatisch geconfigureerd.

De plug-in laadt de gehoste widget bij openbare frontendverzoeken zonder je thema te bewerken. Hij wordt bewust niet geladen in wp-admin, feeds, REST-verzoeken of AJAX-verzoeken.

Dit is geen privacy- of toegangscontrole voor elke frontendpagina. Stel waar nodig uitsluitingen voor checkout-, account-, wachtwoordbeveiligde of ledenpagina’s in met het filter van de plug-in en test ze, of gebruik een handmatige installatie met een passende scope. De URL-instelling voor de loader van de plug-in verandert het ingebouwde productie-API-eindpunt niet; gebruik een handmatig fragment voor een andere API-deployment.

Als je liever een handmatige scriptinstallatie gebruikt, kies dan een van deze opties om het fragment in een algemene footerlocatie te plaatsen:

• Thema-instellingen die header- of footerscripts bieden.
• Een child-thema dat de footertemplate beheert.
• Een header-/footerscriptplug-in.
• Google Tag Manager als je WordPress-site dit al gebruikt.

Plak het fragment op een algemene footerlocatie, zodat het verschijnt op gepubliceerde pagina's, berichten, docs en kennisbankartikelen waar de chatbot beschikbaar moet zijn.

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

Voeg de widget niet toe aan wp-admin-, checkout-, account- of privélidmaatschapspagina’s, tenzij die pagina’s bewust openbaar en ondersteund zijn.

Drupal-module

Voor Drupal 10 of 11 is Composer de aanbevolen installatieroute. Voeg de openbare GitHub VCS-repository toe aan de composer.json in de hoofdmap van het Drupal-project dat de module gebruikt:

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

Installeer daarna de getagde module en schakel deze in:

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

Open Configuration > Web services > ChattyBox, plak de openbare widget-API-sleutel uit het fragment bij Installeren → Installatie op website en schakel de chatbot in. De lokaal gecontroleerde moduleversie gebruikt een vast in de code opgenomen API-eindpunt. Vergelijk dit met je fragment en gebruik de handmatige integratie voor een andere API-deployment. Raadpleeg de handleiding voor de Drupal-chatbotmodule voor route-uitsluitingen, caching en toestemming.

De module is aanvankelijk uitgeschakeld en slaat beheerverzoeken en niet-HTML-verzoeken over, maar niet alle privé-inhoud op de frontend. Een wijziging van de script-URL verandert het ingebouwde productie-API-eindpunt niet. Gebruik een handmatig widgetsnippet als je een andere API-deployment nodig hebt.

Verificatie

Voer na de installatie de launchchecklist uit voordat je de chatbot aankondigt:

• Open een openbare pagina in een incognitovenster.
• Controleer of de widgetlauncher verschijnt.
• Open de widget en stel een echte klantvraag.
• Controleer of een ondersteund antwoord relevante bronvermeldingen bevat en stel daarna een niet-ondersteunde vraag om de fallback te controleren (die mogelijk geen bronnen heeft).
• Controleer de browserconsole op ontbrekende data-api-key, ontbrekende data-api-url of sleutelfouten. Controleer of originbeperkingen voor de sleutel zijn ingeschakeld en, zo ja, of de gewenste origin is toegestaan.