Installationsguider

:::note Versionsstatus Det publicerade npm-SDK:t 0.1.4 räknar referenser till identiska mountar. När det sista matchande handtaget tas bort kan den hostade widget.js v15 riva ned sitt gränssnitt och avbryta väntande arbete; window.ChattyBox.destroy() är tillgängligt efter initiering av v15. :::

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 Testa chatbot.

Förbered sedan en installation för webbplatsen eller hantera en webbläsarsäker nyckel under Installera → Nycklar & domäner. Kontrollera nyckelns origin-inställningar: en nyckel som förberetts för en webbplats kan redan vara begränsad till den origin:en, medan nycklar utan begränsningar fungerar från olika origins. Under Redigera origins kan du aktivera valfria begränsningar eller lägga till de produktions-, förhandsgransknings-, staging- och localhost-origins du behöver. När begränsningen är aktiverad matchas schema, värdnamn och port exakt: https://example.com, https://preview.example.com och http://localhost:3000 är separata poster. Under Installation på webbplatsen väljer du nyckeln och kopierar 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>

Under Installera → Installation på webbplatsen anger du först en HTTP(S)-webbadress. Väljaren visar bara nycklar som inte har gått ut och som är obegränsade eller tillåtna för adressens origin. För en begränsad nyckel anger du en tillåten origin; granska begränsningarna via Hantera nycklar och tillåtna domäner. Om formuläret inte är tillgängligt slutför du först det förberedelsesteg som visas i instrumentpanelen.

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.
data-chattybox-widget="true"	Nej	Hjälper dynamiska laddare och SDK:t att hitta ett befintligt skript; rekommenderas när det infogas från applikationskod.
data-debug="true"	Nej	Aktiverar webbläsardiagnostik; av som standard.
data-color	Nej	Uttrycklig åsidosättning av accentfärgen efter en lyckad konfigurationshämtning; använd ett sexsiffrigt hexvärde. Föredra inställningen i instrumentpanelen.
data-position	Nej	Uttrycklig positionsåsidosättning efter en lyckad konfigurationshämtning: bottom-right, bottom-left, top-right eller top-left. Föredra inställningen i instrumentpanelen.

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 valfria originbegränsningar per nyckel. Öppna Installera → Nycklar & domäner och Redigera origins för att aktivera begränsningar och lägga till eller ta bort origins för produktion, staging, förhandsgranskning eller localhost.
• Skrapning, omskrapning, testchatt, Analys 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 valfria originbegränsningar förblir projektinställningar och är inte värden i konfigurationsfilen.

Installera bara en loader. SDK:t hittar den markerade skripttaggen ovan, inte alla manuella skript med samma src. Det publicerade SDK:t 0.1.4 referensräknar endast identiska mount-alternativ och avvisar ändrad nyckel, endpoint, skript-URL, locale eller debug-inställning tills alla handtag har tagits bort. Widgeten prenumererar inte på ändringar i instrumentpanelens konfiguration; initiera om den för att hämta sparade inställningar. I den aktuella källversionen av den hostade widget.js v16 kan ändringar i <html lang> eller loaderns data-locale uppdatera widgetens etiketter när den lösta lokalen ändras, med förbehåll för projektets språkpolicy. Kontrollera loader-versionen som faktiskt distribuerats innan du förlitar dig på liveuppdateringar; detta beteende är separat från den publicerade npm-SDK-versionen. När originbegränsningar är aktiverade används Origin eller en reserv-origin från Referer; origin som saknas eller inte tillåts ger 401 Invalid API key. Begränsningarna är inte autentisering.

API-URL:en kan vara HTTP-tjänstens rot-URL eller sluta på /chat; loadern tar bort avslutande snedstreck och ett avslutande /chat innan den räknar fram slutpunkterna. Den konverterar inte Convex-URL:er med ändelsen .cloud till .site. Ta inte med frågesträngar eller fragment i värdet.

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"
          data-chattybox-widget="true"
          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.

Behåll loadern i ett beständigt skal vid vanlig navigering. Vid ruttbaserad borttagning eller återkallat samtycke tar du bort alla SDK 0.1.4-handtag: det sista matchande handtaget signalerar till den hostade widget.js v15 att avveckla sitt gränssnitt och sina stilar samt avbryta väntande initiering, återförsök och pågående chatt. Loadern gör högst 10 försök och schemalägger inga automatiska återförsök efter 30 sekunder; det är ingen hård tidsgräns för en pågående begäran. window.ChattyBox.destroy() finns efter initiering av v15. Avvecklingen kan inte ångra en begäran som servern redan har behandlat. Den hostade widgeten flyter under document.body och renderas inte i komponenten som laddar den.

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>. Fast-läget använder projektets standardspråk om ingen tillåten override finns. I den aktuella källversionen av den hostade widget.js v16 kan etiketter uppdateras när någon av dessa attribut ändrar den lösta lokalen; verifiera den distribuerade loader-versionen innan du förlitar dig på beteendet. Egen titel- och välkomsttext samt genererade svar översätts inte automatiskt.

Behåll laddaren i appens beständiga skal. Skapa inte om den under normala ruttändringar på klientsidan; använd den hostade widgetens avvecklings-API när du avsiktligt behöver ta bort den, eller ta bort alla SDK-mount-handtag om du använde SDK:t.

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.

1. Öppna din GTM-container.
2. Skapa en ny Custom HTML-tagg.
3. Klistra in ChattyBox-fragmentet.
4. Använd en All Pages-utlösare eller en snävare utlösare för endast de sidor där widgeten ska visas.
5. 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.

I en SPA förhindrar en snävare GTM-utlösare den första laddningen på uteslutna rutter, men tar inte bort en widget som redan laddats på en annan rutt. Aktivera inte loadern upprepade gånger vid historikändringar.

Content Security Policy

För standardloadern som hostas tillåter du https://chattybox.ai i script-src och widgetens API-origin i connect-src. Widgeten injicerar ett formatmallselement och inline-stilattribut; den har för närvarande inget nonce-alternativ, så en policy som förbjuder inline-stilar blockerar delar av gränssnittet. Om policyn tillåter det kan du tillåta 'unsafe-inline' för dessa stilar eller använda ett eget gränssnitt som följer policyn. Om Inter läses in när startknappen används krävs också https://fonts.googleapis.com i style-src och https://fonts.gstatic.com i font-src. Tillåt den konfigurerade ikonens bildorigin i img-src. Granska samtyckes- och säkerhetskrav innan du lättar på CSP.

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.

Detta är inte en sekretess- eller åtkomstkontroll för varje frontend-sida. Vid behov implementerar och testar du undantag för kassa-, konto-, lösenordsskyddade eller medlemssidor med tilläggets filter, eller använder en manuellt avgränsad installation. Tilläggets inställning för loader-URL ändrar inte dess inbyggda produktions-API-endpoint; använd det manuella kodfragmentet för en annan API-distribution.

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 kodfragmentet under Installation på webbplatsen och aktivera chattboten. Den lokalt granskade modulversionen använder en hårdkodad API-slutpunkt. Jämför den med kodfragmentet och använd manuell integration för en annan API-distribution. Läs installationsguiden för Drupal-chattbotmodulen om ruttundantag, cachelagring, samtycke och manuell reservlösning.

Modulen är inaktiverad från början. Den hoppar över administrativa förfrågningar och förfrågningar som inte är HTML, inte allt privat innehåll på frontend. Om du ändrar skript-URL:en ändras inte den inbyggda produktions-API-endpointen. Använd ett manuellt widgetkodfragment i stället för modulen om du behöver en annan API-distribution.

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 följer inte sparade ändringar i instrumentpanelen; initiera om den för att hämta sparade inställningar. Den aktuella källversionen av den hostade widget.js v16 kan uppdatera produktägda etiketter vid lokaländring enligt beskrivningen ovan, men kontrollera den distribuerade versionen innan du förlitar dig på det. Egen titel- och välkomsttext samt genererade svar översätts inte automatiskt. Vid verifiering kontrollerar du nyckelns origin-inställningar: om en begränsning är aktiverad och om testorigin:en är tillåten. En nyckel som förberetts för en installation kan redan vara begränsad. Originbegränsningar matchar schema, värd och port exakt och är inte autentisering.