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 scrapujte zdroj, zkontrolujte indexované stránky a ověřte reprezentativní odpovědi v Test Chat.

Poté vytvořte klíč bezpečný pro prohlížeč v části Public Keys. Ve výchozím nastavení funguje pro originy v produkci, náhledech/stagingu i na localhostu. Chcete-li volitelně zvýšit zabezpečení pomocí ochrany do hloubky, vyberte Edit origins, zapněte Restrict this key to specific origins a přidejte přesně povolené originy. Při zapnutí se shoda určuje podle schématu, názvu hostitele a portu: https://example.com, https://preview.example.com a http://localhost:3000 jsou samostatné položky. Vraťte se do Embed, vyberte klíč a zkopírujte vygenerovaný ú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 řídicího panelu. Hodnotu data-api-url ponechte přesně tak, jak je zobrazena v řídicím panelu. 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.

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ý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. Omezení zapnete v Public Keys > Edit origins 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ářů řídicího panelu. Veřejné klíče a povolené originy zůstávají přihlašovacími údaji nastavení projektu, nikoli hodnotami konfiguračního souboru.

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

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 loaderem jen při povoleném override, nebo použijte Auto a <html lang>. Fixed používá default a locale se při změně trasy SPA neaktualizuje.

Loader ponechte v trvalém shellu aplikace. Během běžných změn tras na straně klienta jej znovu nevytvářejte ani neodstraňujte.

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.

Vydané SDK 0.1.4 stejné mounty sdílí skript a každý handle drží referenci. remove() je idempotentní; teprve poslední handle signalizuje widget.js v15 zrušení čekající práce a odstranění UI, stylů, fontů, skriptu i globálního API. Jiné volby se odmítnou, dokud handly existují. Widget plave pod document.body.

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.

Otevřete kontejner GTM.
Vytvořte nový tag Custom HTML.
Vložte úryvek ChattyBox.
Použijte spouštěč All Pages nebo užší spouštěč pouze pro stránky, kde se má widget zobrazovat.
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.

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.

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 Embed projektu a povolte chatbot. Produkční koncový bod API se nastaví automaticky. Informace o vyloučení rout a ruční záložní variantě najdete v průvodci modulem chatbotu Drupal.

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 odpověď obsahuje citace zdrojů.
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. Originy kontrolujte pouze v případě, že jste pro klíč výslovně zapnuli omezení.

Než začnete s instalací​

Co patří do skriptu​

Obyčejné HTML​

Next.js / shell aplikace React​

Docusaurus​

Vlastní rozhraní​

Obecný CMS / vlastní HTML​

Google Tag Manager​

Průvodce pluginem WordPress​

Modul Drupal​

Ověření​

Nastavení soukromí