Installatiehandleidingen

:::note Versiestatus Het gepubliceerde npm-pakket 0.1.4 met widget.js v15 ondersteunt teardown via remove() of window.ChattyBox.destroy() en annuleert wachtend werk. :::

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 scrape de bron, controleer de geïndexeerde pagina’s en verifieer representatieve antwoorden in Test Chat.

Maak daarna in Public Keys een browsersleutel aan. Deze werkt standaard voor productie-, preview/staging- en localhost-origins. Kies voor optionele extra beveiliging Edit origins, schakel Restrict this key to specific origins in en voeg de exact toegestane origins toe. Als deze optie is ingeschakeld, moeten schema, hostnaam en poort overeenkomen: https://example.com, https://preview.example.com en http://localhost:3000 zijn afzonderlijke vermeldingen. Ga terug naar Embed, selecteer de sleutel, rond eventuele aanpassingen van de gehoste widget af en kopieer het gegenereerde fragment. Het bevat de openbare sleutel en API-URL voor 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.

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 Public Keys > Edit origins om een beperking 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 het config-as-code-slot inschakelt, komen instellingen voor assistent, bron, runtime en ondersteunde widgetfuncties uit de gedeployde configuratie in plaats van uit dashboardformulieren. Openbare sleutels en toegestane origins blijven projectreferenties voor de setup en worden geen waarden in het configuratiebestand.

De API-URL mag de HTTP-deploymentroot of /chat zijn; loader en SDK normaliseren alleen die suffix, niet een Convex-.cloud-URL naar .site. Installeer slechts één loader. In de gepubliceerde SDK 0.1.4 delen alleen identieke mounts het script; elke handle is een referentie en pas de laatste remove() seint widget.js v15 voor volledige cleanup van UI, stijlen, fontlinks, initialisatie, retries, chat, script en globale API. Afwijkende opties worden geweigerd zolang er handles bestaan. De widget haalt configuratie en vertalingen één keer op en volgt geen dashboard- of paginataalwijzigingen.

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"
          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.

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 je data-locale vóór de loader alleen in bij een toegestane override, of gebruik je Auto-modus met <html lang>. In Fixed-modus geldt de standaardlocale van het project, behalve bij een toegestane override; client-side routewisselingen berekenen de locale niet opnieuw.

Houd de loader in je blijvende applicatieshell tijdens normale client-side routewijzigingen. Voor routegebonden verwijdering of intrekking van toestemming verwijder je elke gepubliceerde SDK 0.1.4-handle: alleen de laatste laat widget.js v15 UI, stijlen, fontlinks, lopend werk, script en globale API opruimen.

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.

Open je GTM-container.
Maak een nieuwe Custom HTML-tag.
Plak het ChattyBox-fragment.
Gebruik een trigger All Pages of een smallere trigger voor alleen de pagina’s waarop de widget moet worden weergegeven.
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.

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.

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 tabblad Embed van het project en schakel de chatbot in. Het productie-API-eindpunt wordt automatisch geconfigureerd. Raadpleeg de handleiding voor de Drupal-chatbotmodule voor het uitsluiten van routes en de handmatige fallback.

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 het antwoord bronvermeldingen bevat.
Controleer de browserconsole op ontbrekende data-api-key, ontbrekende data-api-url of sleutelfouten. Controleer origins alleen als je expliciet een beperking voor de sleutel hebt ingeschakeld.

Voordat je installeert​

Wat hoort er in het script?​

Plain HTML​

Next.js / React App Shell​

Docusaurus​

Aangepaste interface​

Algemene CMS/aangepaste HTML​

Google Tag Manager​

WordPress-plug-inhandleiding​

Drupal-module​

Verificatie​

Privacykeuzes