Przewodniki instalacji

:::note Stan wersji Opublikowane npm SDK 0.1.4 z widget.js v15 obsługuje teardown przez remove() lub window.ChattyBox.destroy() i anuluje oczekującą pracę. :::

Integracja hostowanego widget.js to ścieżka bez budowania, gdy chcesz, aby ChattyBox utrzymywał interfejs i transport. Jeśli aplikacja ma inicjalizować ten sam interfejs z kodu npm, użyj mountWidget(). Aby samodzielnie zarządzać interfejsem, użyj headless SDK.

Zanim rozpoczniesz instalację

Najpierw ukończ proces Pierwsze kroki: skonfiguruj i przeskanuj źródło, przejrzyj zindeksowane strony i zweryfikuj reprezentatywne odpowiedzi w Test Chat.

Następnie utwórz bezpieczny dla przeglądarki klucz w Public Keys. Domyślnie działa on w środowisku produkcyjnym, w wersjach podglądowych/stagingowych i na localhost. Aby opcjonalnie wzmocnić ochronę, wybierz Edit origins, włącz Restrict this key to specific origins i dodaj dokładne dozwolone originy. Po włączeniu ograniczenia dopasowanie obejmuje schemat, nazwę hosta i port: https://example.com, https://preview.example.com i http://localhost:3000 to osobne wpisy. Wróć do Embed, wybierz klucz, dokończ ewentualne dostosowanie hostowanego widżetu i skopiuj wygenerowany fragment. Zawiera on publiczny klucz oraz adres URL API projektu:

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

W przypadku platform ukierunkowanych na dokumentację zobacz przewodniki chatbot AI dla MkDocs, chatbot AI dla VitePress i chatbot AI dla GitBook.

Zastąp YOUR_API_KEY publicznym kluczem widżetu z panelu. Wartość data-api-url pozostaw dokładnie taką, jak pokazano w panelu. W środowisku produkcyjnym jest to stabilny adres https://...convex.site/chat publicznego API widżetu.

Co należy umieścić w skrypcie

Używaj atrybutów skryptu dla wartości, które muszą być dostępne przed uruchomieniem widżetu:

Atrybut	Wymagany	Zastosowanie
`src`	Tak	Ładowanie JavaScriptu widżetu ChattyBox.
`data-api-key`	Tak	Identyfikowanie publicznego klucza widżetu projektu.
`data-api-url`	Tak	Wysyłanie żądań widżetu do API ChattyBox.
`data-locale`	Nie	Żądanie języka UI przy inicjalizacji, tylko gdy projekt dopuszcza script override.
`data-chattybox-widget="true"`	Nie	Umożliwia dynamicznym loaderom i SDK znalezienie istniejącego skryptu.
`data-debug="true"`	Nie	Włącza diagnostykę przeglądarki.

Używaj ustawień panelu do wszystkiego, czym należy zarządzać bez ponownego wdrażania witryny:

Kolory, położenie, ikona, tytuł i wiadomość powitalna widżetu.
Domyślny tryb języka i informacja, czy dozwolone są zastąpienia data-locale.
Tworzenie i usuwanie kluczy publicznych oraz opcjonalne ograniczenia originów dla poszczególnych kluczy. Otwórz Public Keys > Edit origins, aby włączyć ograniczenie oraz dodać lub usunąć originy produkcyjne, stagingowe, podglądowe lub localhost.
Skanowanie, ponowne skanowanie, czat testowy, analityka i luki w treści.

Jeśli włączysz blokadę konfiguracji jako kodu, asystent, źródło, środowisko uruchomieniowe i obsługiwane ustawienia widżetu będą pochodzić z wdrożonej konfiguracji zamiast z formularzy panelu. Klucze publiczne i opcjonalne ograniczenia originów pozostają ustawieniami projektu, a nie wartościami pliku konfiguracyjnego.

API URL może być rootem wdrożenia HTTP lub kończyć się /chat; loader usuwa końcowy slash i /chat, ale nie zamienia Convex .cloud na .site. Nie dodawaj query ani fragmentu. Ograniczenie originu jest opcjonalne, używa Origin lub originu Referer i nie jest uwierzytelnianiem.

Zwykły HTML

Wklej fragment raz w pobliżu końca body, tuż przed </body>. Działa to w przypadku statycznego HTML, ręcznie kodowanych witryn i szablonów udostępniających globalną stopkę.

<!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 / powłoka aplikacji React

W witrynie Next.js App Router dodaj widżet do app/layout.tsx za pomocą next/script, aby ładował się raz dla całej aplikacji.

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

W aplikacji React typu single-page dodaj skrypt raz w powłoce aplikacji najwyższego poziomu lub szablonie HTML. Nie wstrzykuj go z każdego komponentu trasy.

W opublikowanym SDK 0.1.4 identyczne montaże współdzielą skrypt i referencję; remove() jest idempotentne i tylko ostatni handle sygnalizuje teardown v15, usuwający UI, style, fonty, skrypt i globalne API oraz anulujący oczekującą pracę. Różne opcje są odrzucane, dopóki istnieją handle. Hostowany widżet pływa pod document.body.

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

W Docusaurusie utwórz lub zaktualizuj src/theme/Root.tsx, aby widżet był dostępny na wszystkich stronach dokumentacji.

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

Jeśli witryna Docusaurus ma przetłumaczone trasy, ustaw data-locale przed loaderem tylko przy dozwolonym override albo użyj Auto i <html lang>. Fixed używa defaultu; locale jest rozstrzygane raz, więc zmiana trasy SPA nie aktualizuje UI.

Loader powinien pozostać w trwałej powłoce aplikacji. Nie twórz go ponownie ani nie usuwaj podczas normalnych zmian tras po stronie klienta.

Własny interfejs

Hostowany widżet jest opcjonalny. Jeśli chcesz mieć pełną kontrolę nad renderowaniem, stanem wiadomości i projektem interakcji, użyj JavaScript SDK z tym samym publicznym kluczem API i adresem URL API widżetu.

Ogólny CMS / niestandardowy HTML

Większość platform CMS ma obszar globalnego niestandardowego kodu, stopki lub szablonu motywu. Dodaj tam skrypt, aby każda publiczna strona mogła załadować widżet.

Użyj tej ścieżki dla Webflow, Framera, Squarespace, obszarów niestandardowego kodu Wix, motywów Shopify, szablonów HubSpot i niestandardowych platform CMS, które umożliwiają edycję globalnego HTML.

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

Przed publikacją sprawdź, czy CMS nie usuwa data-api-key, data-api-url ani async z niestandardowych skryptów.

Google Tag Manager

Użyj Google Tag Managera, jeśli Twój zespół już zarządza skryptami innych firm za pomocą GTM.

Otwórz kontener GTM.
Utwórz nowy tag Custom HTML.
Wklej fragment ChattyBox.
Użyj wyzwalacza All Pages albo węższego wyzwalacza tylko dla stron, na których ma być widoczny widżet.
Wyświetl podgląd kontenera, sprawdź, czy widżet się ładuje, a następnie opublikuj.

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

Jeśli witryna korzysta z trybu zgody lub zasad zgody dla tagów, upewnij się, że widżet może ładować się na stronach, na których odwiedzający potrzebują pomocy.

W SPA węższy trigger GTM zatrzyma pierwsze ładowanie wykluczonej trasy, ale nie usunie widżetu już załadowanego na innej trasie.

Przewodnik po wtyczce WordPress

W przypadku bezkodowej instalacji WordPress użyj wtyczki WordPress ChattyBox. Skorzystaj z przewodnika po wtyczce WordPress, aby ją zainstalować i skonfigurować, wykluczyć trasy oraz przeprowadzić weryfikację. Produkcyjny punkt końcowy API jest konfigurowany automatycznie.

Wtyczka ładuje hostowany widżet podczas żądań publicznego frontendu bez edytowania motywu. Celowo nie ładuje go w wp-admin, kanałach ani przy żądaniach REST i AJAX.

Jeśli wolisz instalację za pomocą skryptu, użyj jednej z lokalizacji skryptów obsługiwanych już przez Twoją konfigurację WordPress:

Ustawienia motywu udostępniające skrypty nagłówka lub stopki.
Motyw potomny kontrolujący szablon stopki.
Wtyczka skryptów nagłówka/stopki.
Google Tag Manager, jeśli witryna WordPress już go używa.

Wklej fragment w globalnej stopce, aby pojawiał się na opublikowanych stronach, wpisach, dokumentach i artykułach bazy wiedzy, na których chatbot powinien być dostępny.

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

Unikaj dodawania widżetu do stron wp-admin, koszyka, konta lub prywatnego członkostwa, chyba że strony te są celowo publiczne i obsługiwane.

Moduł Drupal

W przypadku Drupal 10 lub 11 zalecaną ścieżką instalacji jest Composer. Dodaj publiczne repozytorium VCS GitHub do głównego pliku composer.json używanego projektu Drupal:

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

Następnie zainstaluj oznaczoną wersję modułu i włącz ją:

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

Otwórz Configuration > Web services > ChattyBox, wklej publiczny klucz API widżetu z karty Embed projektu i włącz chatbota. Produkcyjny punkt końcowy API jest konfigurowany automatycznie. Informacje o wykluczaniu tras i ręcznej instalacji awaryjnej znajdziesz w przewodniku po module chatbota Drupal.

Weryfikacja

Po instalacji przejdź listę kontrolną przed uruchomieniem przed ogłoszeniem chatbota:

Otwórz publiczną stronę w oknie incognito.
Potwierdź, że pojawia się przycisk uruchamiający widżet.
Otwórz widżet i zadaj prawdziwe pytanie klienta.
Sprawdź cytowania wspieranej odpowiedzi oraz fallback dla pytania bez pokrycia (może nie mieć źródeł).
Sprawdź konsolę przeglądarki pod kątem braku data-api-key, braku data-api-url lub błędów klucza/originu.

Zanim rozpoczniesz instalację​

Co należy umieścić w skrypcie​

Zwykły HTML​

Next.js / powłoka aplikacji React​

Docusaurus​

Własny interfejs​

Ogólny CMS / niestandardowy HTML​

Google Tag Manager​

Przewodnik po wtyczce WordPress​

Moduł Drupal​

Weryfikacja​

Preferencje prywatności