Průvodci instalací

:::note Stav verzí Vydané npm SDK 0.1.4 s widget.js v15 podporuje teardown přes remove() nebo window.ChattyBox.destroy() a ruší čekající práci. :::

Hostovaná integrace widget.js je cesta bez sestavení, pokud chcete, aby ChattyBox spravoval rozhraní i přenos dat. Pokud má vaše aplikace inicializovat stejné rozhraní z kódu npm, použijte mountWidget(). Chcete-li vlastnit rozhraní, použijte headless SDK.

Než začnete s instalací

Nejprve dokončete postup Začínáme: nakonfigurujte a importujte zdroj, zkontrolujte indexované stránky a ověřte reprezentativní odpovědi v Otestovat chatbota.

V části Instalace → Instalace na web připravte instalaci pro svůj web nebo spravujte klíč bezpečný pro prohlížeč v části Instalace → Klíče a domény. Zkontrolujte nastavení originů: klíč připravený pro doménu webu už může být omezen na tento origin, zatímco klíče vytvořené bez omezení fungují ze všech originů. V části Upravit originy můžete volitelně zapnout omezení nebo přidat produkční, náhledové, stagingové a localhost originy. Při zapnutém omezení se shoda určuje přesně podle schématu, názvu hostitele a portu: https://example.com, https://preview.example.com a http://localhost:3000 jsou samostatné položky. V části Instalace na web zadejte HTTP(S) URL webu. Výběr nabízí neexpirované klíče bez omezení nebo povolené pro origin této URL; pro omezený klíč zadejte jeho povolený origin. Vyberte vhodný klíč a zkopírujte vygenerovaný úryvek. Není-li formulář dostupný, nejprve dokončete krok nastavení uvedený v dashboardu. Úryvek obsahuje veřejný klíč a URL API vašeho projektu:

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

Pro platformy zaměřené na dokumentaci použijte průvodce AI chatbot pro MkDocs, AI chatbot pro VitePress a AI chatbot pro GitBook.

Nahraďte YOUR_API_KEY veřejným klíčem widgetu z dashboardu. Hodnotu data-api-url ponechte přesně tak, jak je zobrazena v dashboardu. V produkci jde o stabilní URL https://...convex.site/chat pro veřejné API widgetu.

Co patří do skriptu

Atributy skriptu používejte pro hodnoty, které musejí být dostupné ještě před spuštěním widgetu:

Atribut	Povinné	Použijte jej pro
src	Ano	Načtení JavaScriptu widgetu ChattyBox.
data-api-key	Ano	Identifikaci veřejného klíče widgetu vašeho projektu.
data-api-url	Ano	Odesílání požadavků widgetu do API ChattyBox.
data-locale	Ne	Požadavek na jazyk UI při inicializaci, jen pokud projekt povoluje přepsání skriptem.
data-chattybox-widget="true"	Ne	Umožní dynamickému loaderu a SDK najít existující skript; doporučeno při vkládání skriptu z kódu aplikace.
data-debug="true"	Ne	Zapne diagnostiku prohlížeče; ve výchozím stavu je vypnutá.
data-color	Ne	Výslovně přepíše barvu zvýraznění po úspěšném načtení konfigurace; použijte šestimístnou hexadecimální barvu. Upřednostněte dashboard.
data-position	Ne	Výslovně přepíše pozici po úspěšném načtení konfigurace: bottom-right, bottom-left, top-right nebo top-left. Upřednostněte dashboard.

Nastavení v řídicím panelu používejte pro vše, co má být spravováno bez opětovného nasazení webu:

• Barvy, pozice, ikona, název a uvítací zpráva widgetu v části Přizpůsobení → Vzhled.
• Výchozí režim jazyka a to, zda je povoleno přepsání pomocí data-locale.
• Vytváření, mazání a volitelná omezení originů pro jednotlivé veřejné klíče v části Instalace → Klíče a domény. Omezení zapnete přes Upravit originy a přidáte nebo odeberete produkční, stagingové, náhledové nebo localhost originy.
• Scraping, opětovný scraping, testovací chat, analytika a mezery v obsahu.

Pokud povolíte zámek konfigurace jako kódu, asistent, zdroj, runtime a podporovaná nastavení widgetu budou pocházet z nasazené konfigurace místo z formulářů dashboardu. Veřejné klíče a povolené originy zůstávají nastavením projektu, nikoli hodnotami konfiguračního souboru.

URL API může být kořenem HTTP deploymentu nebo končit /chat; loader odstraňuje koncová lomítka a koncové /chat. URL Convex .cloud nepřevádí na .site. Nepřidávejte query string ani fragment. Pokud je omezení originu zapnuté, ověřuje se podle Origin nebo záložního originu Referer; chybějící či nepovolený origin vede k odpovědi 401 Invalid API key. Nejde o ověřování totožnosti návštěvníka.

Použijte pouze jeden loader. SDK rozpoznává výše uvedený marker, nikoli každý ručně vložený skript se stejným src. Vydané SDK 0.1.4 sdílí počet referencí pouze při shodných volbách mountWidget() a odmítne změněný klíč, endpoint, URL skriptu, locale nebo nastavení ladění, dokud nebudou odstraněny všechny handly. Widget nesleduje změny konfigurace v dashboardu; pro načtení uložených nastavení jej znovu inicializujte. V aktuálním zdrojovém hostovaném widget.js v16 může změna <html lang> nebo data-locale obnovit systémové popisky widgetu, pokud se změní výsledná locale a pravidla projektu ji povolují. Než se na živém webu spolehnete na aktualizaci bez opětovné inicializace, ověřte nasazenou verzi loaderu; toto chování je oddělené od vydaného npm SDK. Uživatelsky zadaný název, uvítací text ani vygenerované odpovědi se automaticky nepřekládají.

Obyčejné HTML

Vložte úryvek jednou poblíž konce body, těsně před </body>. Funguje to pro statické HTML, ručně kódované weby a šablony s globálním zápatím.

<!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 / shell aplikace React

U webu Next.js App Router přidejte widget do app/layout.tsx pomocí next/script, aby se načetl jednou pro celou aplikaci.

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

V jednostránkové aplikaci React přidejte skript jednou do shellu aplikace nejvyšší úrovně nebo do šablony HTML. Nevkládejte jej z komponenty každé trasy.

Při běžné navigaci ponechte loader v trvalém shellu aplikace. Pokud jej potřebujete odebrat při změně trasy nebo odvolání souhlasu, odeberte všechny handly SDK 0.1.4: poslední odpovídající handle signalizuje hostovanému widget.js v15 zničení vlastního rozhraní a stylů a zrušení čekající inicializace, opakovaných pokusů (až 10 pokusů během 30 sekund) a probíhajícího chatu. window.ChattyBox.destroy() je dostupné po inicializaci v15. Teardown nemůže vrátit požadavek, který už zpracoval server. Hostovaný widget se vkládá pod document.body, nikoli dovnitř komponenty, která jej načítá.

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

V Docusauru vytvořte nebo aktualizujte src/theme/Root.tsx, aby byl widget dostupný na všech stránkách dokumentace.

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

Pokud má Docusaurus přeložené trasy, nastavte data-locale před načtením loaderu (pokud projekt povoluje přepsání skriptem), nebo zvolte Automatická detekce a použijte hodnotu <html lang> stránky. Volba Pevné používá výchozí locale projektu, pokud není povoleno přepsání skriptem. Aktuální zdrojový hostovaný widget.js v16 může při změně výsledné locale obnovit systémové popisky widgetu, pokud to politika locale projektu dovoluje; před spoléháním na tuto aktualizaci ověřte nasazenou verzi loaderu. Toto chování se týká hostovaného widgetu, nikoli vydaného npm SDK 0.1.4. Vlastní název, uvítací text ani vygenerované odpovědi se automaticky nepřekládají.

Loader ponechte v trvalém shellu aplikace. Během běžných změn tras na straně klienta jej znovu nevytvářejte. Při záměrném odstranění použijte API hostovaného widgetu pro teardown nebo, pokud používáte SDK, odeberte všechny mount handly.

Vlastní rozhraní

Hostovaný widget je volitelný. Pokud chcete plnou kontrolu nad vykreslováním, stavem zpráv a návrhem interakcí, použijte JavaScript SDK se stejným veřejným klíčem API widgetu a URL API widgetu.

Obecný CMS / vlastní HTML

Většina platforem CMS má globální vlastní kód, zápatí nebo oblast šablony motivu. Přidejte skript tam, aby widget mohla načíst každá veřejná stránka.

Tuto cestu použijte pro Webflow, Framer, Squarespace, vlastní kód Wix, motivy Shopify, šablony HubSpot a vlastní platformy CMS, které umožňují upravovat globální HTML.

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

Před zveřejněním ověřte, že CMS z vlastních skriptů neodstraňuje data-api-key, data-api-url ani async.

Google Tag Manager

Google Tag Manager použijte, pokud váš tým už spravuje skripty třetích stran prostřednictvím GTM.

1. Otevřete kontejner GTM.
2. Vytvořte nový tag Custom HTML.
3. Vložte úryvek ChattyBox.
4. Použijte spouštěč All Pages nebo užší spouštěč pouze pro stránky, kde se má widget zobrazovat.
5. Prohlédněte si náhled kontejneru, ověřte načtení widgetu a poté publikujte.

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

Pokud web používá režim souhlasu nebo zásady souhlasu pro tagy, zajistěte, aby se widget mohl načíst na stránkách, kde návštěvníci potřebují pomoc.

V SPA užší spouštěč GTM zabrání prvotnímu načtení widgetu na vyloučených trasách, ale neodstraní widget, který už byl načten na jiné trase. Nespouštějte loader opakovaně při změnách historie.

Zásady zabezpečení obsahu (CSP)

Pro výchozí hostovaný loader povolte https://chattybox.ai v script-src a origin API widgetu v connect-src. Widget vkládá šablonu stylů a atributy s vloženými styly; v současnosti nenabízí možnost nonce, takže zásady zakazující vložené styly zablokují části rozhraní. Pokud to vaše zásady dovolují, povolte pro tyto styly 'unsafe-inline', nebo použijte vlastní rozhraní kompatibilní s CSP. Načtení fontu Inter při otevření launcheru také vyžaduje https://fonts.googleapis.com v style-src a https://fonts.gstatic.com v font-src. V img-src povolte případný nakonfigurovaný origin obrázku ikony. Před zmírněním CSP zohledněte požadavky na souhlas a zabezpečení.

Průvodce pluginem WordPress

Pro instalaci pluginu do WordPressu bez kódu použijte plugin ChattyBox pro WordPress. Podle průvodce pluginem pro WordPress jej nainstalujte, nakonfigurujte, vylučte trasy a ověřte. Produkční koncový bod API se nastaví automaticky.

Plugin načítá hostovaný widget při požadavcích na veřejný frontend bez úprav šablony. Záměrně se nenačítá ve wp-admin, kanálech, požadavcích REST ani AJAX.

Tím se ale nekontroluje soukromí ani přístup na každé stránce frontendu. Podle potřeby implementujte a otestujte vyloučení pokladny, účtu, stránek chráněných heslem nebo členských stránek pomocí filtru pluginu, případně použijte ruční instalaci s vhodně omezeným rozsahem.

Nastavení URL loaderu v pluginu nemění vestavěný produkční koncový bod API; pro jiné nasazení API použijte ruční úryvek.

Pokud dáváte přednost ruční instalaci skriptu, použijte jedno z umístění skriptů, která vaše nastavení WordPressu již podporuje:

• Nastavení motivu poskytující skripty záhlaví nebo zápatí.
• Odvozený motiv, který ovládá šablonu zápatí.
• Plugin pro skripty záhlaví/zápatí.
• Google Tag Manager, pokud jej váš web WordPress již používá.

Vložte úryvek do globálního zápatí, aby se zobrazil na publikovaných stránkách, příspěvcích, dokumentech a článcích znalostní báze, kde má být chatbot dostupný.

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

Widget nepřidávejte na stránky wp-admin, pokladny, účtu nebo soukromého členství, pokud tyto stránky nejsou záměrně veřejné a podporované.

Modul Drupal

Pro Drupal 10 nebo 11 je Composer doporučeným způsobem instalace. Přidejte veřejný GitHub VCS repozitář do kořenového composer.json používaného projektu Drupal:

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

Poté nainstalujte označený modul a povolte jej:

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

Otevřete Configuration > Web services > ChattyBox, vložte veřejný API klíč widgetu z karty Instalace na web projektu a povolte chatbota. Modul je při instalaci zakázán. Lokálně prověřená verze modulu má koncový bod API pevně zadaný. Porovnejte jej se svým úryvkem; pro jiné nasazení API použijte ruční integraci. Informace o vyloučení tras, ukládání do cache a souhlasu najdete v průvodci modulem chatbotu Drupal.

Modul přeskakuje administrativní požadavky a požadavky, jejichž formát Drupal neurčí jako HTML; nekontroluje výslednou hlavičku Content-Type ani veškerý soukromý obsah frontendu. Změna adresy skriptu nezmění vestavěný produkční koncový bod API. Pro jiné nasazení API použijte místo modulu ruční úryvek widgetu.

Ověření

Po instalaci před oznámením chatbota proveďte kontrolní seznam před spuštěním:

• Otevřete veřejnou stránku v anonymním okně.
• Ověřte, že se zobrazí spouštěč widgetu.
• Otevřete widget a položte skutečnou otázku zákazníka.
• Ověřte, že podporovaná odpověď obsahuje relevantní citace zdrojů, poté položte nepodporovanou otázku a zkontrolujte záložní odpověď (která nemusí mít zdroje).
• Zkontrolujte konzoli prohlížeče kvůli chybějícímu data-api-key, chybějícímu data-api-url nebo chybám klíče. Zkontrolujte také nastavení originů klíče: zda je omezení zapnuté a zda je povolen očekávaný origin nasazení. Klíč vytvořený při přípravě instalace už může být omezený.