Installationsguider

:::note Versionsstatus Det publicerade npm-SDK:t 0.1.4 med widget.js v15 stöder teardown via remove() eller window.ChattyBox.destroy() och avbryter väntande arbete. :::

Den hostade widget.js-integrationen är vägen utan bygge när du vill att ChattyBox ska underhålla gränssnitt och transport. Om appen ska initiera samma gränssnitt från npm-kod använder du mountWidget(). Om du vill äga gränssnittet använder du headless SDK.

Innan du installerar

Slutför först flödet Kom igång: konfigurera och skrapa källan, granska indexerade sidor och verifiera representativa svar i Test Chat.

Skapa sedan en webbläsarsäker nyckel i Public Keys. Den fungerar över origins för produktion, preview/staging och localhost som standard. Om du vill lägga till valfri defense-in-depth-härdning väljer du Edit origins, aktiverar Restrict this key to specific origins och lägger till de exakta tillåtna origins. När begränsningen är aktiverad matchas schema, värdnamn och port: https://example.com, https://preview.example.com och http://localhost:3000 är separata poster. Gå tillbaka till Embed, välj nyckeln, slutför eventuell anpassning av den hostade widgeten och kopiera det genererade kodfragmentet. Det innehåller projektets offentliga nyckel och API-URL:

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

För dokumentationsinriktade plattformar kan du läsa guiderna MkDocs AI-chattbot, VitePress AI-chattbot och GitBook AI-chattbot.

Ersätt YOUR_API_KEY med den offentliga widgetnyckeln från instrumentpanelen. Behåll värdet för data-api-url exakt som det visas i instrumentpanelen. I produktion är detta en stabil https://...convex.site/chat-URL för det offentliga widget-API:t.

Vad som ska finnas i skriptet

Använd skriptegenskaper för värden som måste finnas tillgängliga innan widgeten kan starta:

Attribut	Krävs	Använd det för
`src`	Ja	Laddar ChattyBox-widgetens JavaScript.
`data-api-key`	Ja	Identifierar projektets offentliga widgetnyckel.
`data-api-url`	Ja	Skickar widgetförfrågningar till ChattyBox API.
`data-locale`	Nej	Begär widgetens gränssnittsspråk vid initiering, endast när projektet tillåter script-override.

Använd inställningarna i instrumentpanelen för allt som ska hanteras utan att webbplatsen distribueras på nytt:

Widgetens färger, position, ikon, titel och välkomstmeddelande.
Standardläge för språk och om data-locale-åsidosättningar tillåts.
Skapande och borttagning av offentliga nycklar samt eventuella begränsningar av tillåtna origins för projektet.
Skrapning, omskrapning, testchatt, Analytics och innehållsluckor.

Om du aktiverar låset för konfiguration som kod kommer assistent, källa, runtime och stödda widgetinställningar från den distribuerade konfigurationen i stället för instrumentpanelens formulär. Offentliga nycklar och frivilliga originbegränsningar förblir projektinställningar och är inte värden i konfigurationsfilen.

Vanlig HTML

Klistra in fragmentet en gång nära slutet av body, precis före </body>. Det fungerar för statisk HTML, handkodade webbplatser och mallar som har en global sidfot.

<!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-applikationsskal

På en Next.js App Router-webbplats lägger du till widgeten i app/layout.tsx med next/script så att den laddas en gång för hela appen.

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

I en React-app med en sida lägger du till skriptet en gång i appens beständiga skal på högsta nivå eller i HTML-mallen. Injicera det inte från varje ruttkomponent. I det publicerade SDK:t 0.1.4 delar identiska mountar scriptet och en referens; remove() är idempotent och endast sista handtaget signalerar v15-teardown, som tar bort UI, stilar, fonter, script och global API samt avbryter väntande arbete. Olika optioner avvisas så länge handtag finns.

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

I Docusaurus skapar eller uppdaterar du src/theme/Root.tsx så att widgeten är tillgänglig på alla dokumentsidor.

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

Om Docusaurus-webbplatsen har översatta rutter anger du data-locale före laddning när override tillåts, eller använder Auto-läge och sidans <html lang>. Fixed-läge använder projektets standardspråk om ingen tillåten override finns. Widgeten avgör locale bara vid initiering, inte vid klientbaserade ruttändringar; en hel sidomladdning läser sidans nya språk.

Behåll laddaren i appens beständiga skal. Skapa inte om eller ta bort den under normala ruttändringar på klientsidan.

Anpassat gränssnitt

Den hostade widgeten är valfri. Om du vill ha full kontroll över rendering, meddelandetillstånd och interaktionsdesign använder du JavaScript SDK med samma offentliga widget-API-nyckel och widget-API-URL.

Generisk CMS / anpassad HTML

De flesta CMS-plattformar har ett område för global anpassad kod, sidfot eller temamall. Lägg till skriptet där så att varje offentlig sida kan ladda widgeten.

Använd den här vägen för Webflow, Framer, Squarespace, Wix områden för anpassad kod, Shopify-teman, HubSpot-mallar och anpassade CMS-plattformar som låter dig redigera global HTML.

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

Kontrollera före publicering att CMS:et inte tar bort data-api-key, data-api-url eller async från anpassade skript.

Google Tag Manager

Använd Google Tag Manager om teamet redan hanterar tredjepartsskript via GTM.

Öppna din GTM-container.
Skapa en ny Custom HTML-tagg.
Klistra in ChattyBox-fragmentet.
Använd en All Pages-utlösare eller en snävare utlösare för endast de sidor där widgeten ska visas.
Förhandsgranska containern, verifiera att widgeten laddas och publicera sedan.

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

Om webbplatsen använder samtyckesläge eller en policy för taggsamtycke ska du se till att widgeten får laddas på de sidor där besökare behöver hjälp.

WordPress – guide till tillägget

För en kodfri WordPress-installation använder du ChattyBox WordPress-tillägg. Följ WordPress-guiden för tillägget för att installera, konfigurera, utesluta rutter och verifiera det. Produktions-API-slutpunkten konfigureras automatiskt.

Tillägget distribueras som en versionslåst ZIP-fil från GitHub, inte via WordPress.org Plugin Directory. Ladda ner den versionslåsta ZIP-filen för ChattyBox WordPress-pluginet 0.2.0, öppna Plugins > Add New > Upload Plugin, ladda upp ZIP-filen och följ guiden för att aktivera tillägget.

Tillägget läser in den hostade widgeten vid offentliga frontendförfrågningar utan att du behöver redigera temat. Det läser avsiktligt inte in widgeten i wp-admin, feeds, REST-förfrågningar eller AJAX-förfrågningar.

Som manuell fallback placerar du fragmentet på en global sidfotsplats med något av dessa alternativ:

Temainställningar som tillhandahåller skript för sidhuvud eller sidfot.
Ett barntema som styr sidfotsmallen.
Ett tillägg för skript i sidhuvud/sidfot.
Google Tag Manager om WordPress-webbplatsen redan använder det.

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

Undvik att lägga till widgeten på wp-admin-, kassasidor, kontosidor eller privata medlemssidor om sidorna inte avsiktligt är offentliga och stöds.

Drupal-modul

För Drupal 10 eller 11 är Composer den rekommenderade installationsvägen. Lägg till det offentliga GitHub VCS-repositoryt i rotens composer.json i det Drupal-projekt som använder det:

Modulen finns ännu inte på Drupal.org eller Packagist, så VCS-repositoriet måste anges innan Composer kan hitta paketet.

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

Installera sedan den taggade modulen och aktivera den:

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

Öppna Configuration > Web services > ChattyBox, klistra in widgetens offentliga API-nyckel från projektets flik Embed och aktivera chattboten. Produktions-API-slutpunkten konfigureras automatiskt. Läs installationsguiden för Drupal-chattbotmodulen om ruttundantag och manuell reservlösning.

Verifiering

Kör lanseringschecklistan efter installationen och innan du tillkännager chattboten:

Öppna en offentlig sida i ett inkognitofönster.
Bekräfta att widgetens startknapp visas.
Öppna widgeten och ställ en verklig kundfråga.
Kontrollera att ett svar som stöds innehåller relevanta källhänvisningar och att en fråga som inte stöds får reservsvaret, som kan sakna källor.
Kontrollera webbläsarkonsolen efter saknad data-api-key, saknad data-api-url eller nyckel-/originfel.

Ladda bara en loader per sida. Den hostade widgeten läser konfiguration och översättningar vid initiering och följer inte sparade instrumentpanelsändringar eller ändringar av sidans språk live; ladda om sidan för att hämta sparade inställningar. Origins är öppna som standard; exakt kontroll av schema, värd och port används först när du frivilligt aktiverar en begränsning.

Innan du installerar​

Vad som ska finnas i skriptet​

Vanlig HTML​

Next.js / React-applikationsskal​

Docusaurus​

Anpassat gränssnitt​

Generisk CMS / anpassad HTML​

Google Tag Manager​

WordPress – guide till tillägget​

Drupal-modul​

Verifiering​

Integritetsval