Przewodniki instalacji

:::note Stan wersji Opublikowane npm SDK 0.1.4 z widget.js v15 obsługuje teardown po usunięciu wszystkich pasujących uchwytów przez remove(); window.ChattyBox.destroy() jest dostępne po inicjalizacji v15. Teardown anuluje oczekującą pracę, ale nie cofnie żądań już przetworzonych przez serwer. :::

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 zaimportuj źródło, przejrzyj zindeksowane strony i zweryfikuj reprezentatywne odpowiedzi w Przetestuj chatbota.

W części Instalacja → Instalacja na stronie przygotuj instalację dla swojej witryny lub zarządzaj kluczem bezpiecznym dla przeglądarki w Instalacja → Klucze i domeny. Sprawdź ograniczenia originów: klucz przygotowany dla domeny witryny może już być ograniczony do tego originu, a klucze utworzone bez ograniczeń działają z dowolnego originu. W Edytuj originy możesz opcjonalnie włączyć ograniczenia lub dodać dokładne dozwolone originy. Dopasowanie obejmuje schemat, nazwę hosta i port: https://example.com, https://preview.example.com i http://localhost:3000 to osobne wpisy. W Instalacja na stronie wpisz adres URL witryny HTTP(S). Lista oferuje niewygasłe klucze bez ograniczeń lub dozwolone dla originu tego adresu; aby wybrać ograniczony klucz, wpisz jego dozwolony origin. Wybierz odpowiedni klucz i skopiuj wygenerowany fragment. Jeśli formularz jest niedostępny, najpierw wykonaj wskazany w panelu krok konfiguracji. Fragment zawiera 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; zalecane przy wstrzykiwaniu skryptu z kodu aplikacji.
data-debug="true"	Nie	Włącza diagnostykę przeglądarki; domyślnie jest wyłączona.
data-color	Nie	Jawnie nadpisuje kolor akcentu po udanym pobraniu konfiguracji; użyj sześciocyfrowego koloru szesnastkowego. Preferuj panel.
data-position	Nie	Jawnie nadpisuje pozycję po udanym pobraniu konfiguracji: bottom-right, bottom-left, top-right lub top-left. Preferuj panel.

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 w Personalizacja → Wygląd.
• 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 w Instalacja → Klucze i domeny. Otwórz Edytuj originy, 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.

Adres URL API może być katalogiem głównym wdrożenia HTTP lub kończyć się na /chat; loader usuwa końcowe ukośniki i końcowe /chat. Nie zamienia adresu Convex .cloud na .site. Nie dodawaj parametrów zapytania ani fragmentów. Ograniczenie originu jest opcjonalne; weryfikacja używa Origin lub zapasowego originu Referer. Brak originu lub niedozwolony origin zwraca 401 Invalid API key. To ograniczenie nie jest uwierzytelnianiem odwiedzających.

Używaj tylko jednego loadera. SDK rozpoznaje powyższy atrybut, a nie każdy ręcznie dodany skrypt z tym samym src. Opublikowane SDK 0.1.4 zlicza odwołania tylko dla identycznych opcji montowania i odrzuca zmieniony klucz, endpoint, URL skryptu, locale lub ustawienie debugowania, dopóki nie zostaną usunięte wszystkie uchwyty. Widżet nie nasłuchuje zmian konfiguracji w panelu; aby pobrać zapisane ustawienia, zainicjuj go ponownie. W aktualnym źródłowym hostowanym widget.js v16 zmiana <html lang> lub data-locale może odświeżyć dostarczane przez widżet etykiety interfejsu, jeśli zmieni się rozstrzygnięta locale i pozwala na to polityka językowa projektu. Przed poleganiem na aktualizacji bez przeładowania sprawdź wersję wdrożonego loadera; to zachowanie jest niezależne od opublikowanego npm SDK. Własny tytuł i wiadomość powitalna ani wygenerowane odpowiedzi nie są automatycznie tłumaczone.

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

Podczas zwykłej nawigacji pozostaw loader w trwałej powłoce aplikacji. Jeśli chcesz go usuwać przy zmianie trasy lub cofnięciu zgody, usuń wszystkie uchwyty SDK 0.1.4: ostatni pasujący uchwyt sygnalizuje hostowanemu widget.js v15 zniszczenie własnego interfejsu i stylów oraz anulowanie oczekującej inicjalizacji, ponowień (do 10 prób w ciągu 30 sekund) i trwającego czatu. window.ChattyBox.destroy() jest dostępne po inicjalizacji v15. Teardown nie może cofnąć żądania już przetworzonego przez serwer. Hostowany widżet jest umieszczany pod document.body, a nie wewnątrz komponentu, który go ładuje.

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 załadowaniem loadera (jeśli projekt dopuszcza nadpisanie skryptem) albo wybierz Wykryj automatycznie, aby użyć wartości <html lang> strony. Tryb Stały korzysta z domyślnej locale projektu, chyba że dozwolone jest nadpisanie skryptem. Aktualny źródłowy hostowany widget.js v16 może odświeżyć dostarczane przez widżet etykiety interfejsu, gdy zmieni się rozstrzygnięta locale i pozwalają na to ustawienia językowe projektu; przed poleganiem na tej aktualizacji sprawdź wersję wdrożonego loadera. To zachowanie dotyczy hostowanego widżetu, a nie opublikowanego npm SDK 0.1.4. Własny tytuł, wiadomość powitalna ani wygenerowane odpowiedzi nie są automatycznie tłumaczone.

Loader powinien pozostać w trwałej powłoce aplikacji. Nie twórz go ponownie ani nie usuwaj podczas normalnych zmian tras po stronie klienta; gdy celowo potrzebujesz teardownu, użyj API usuwania hostowanego widżetu albo usuń wszystkie uchwyty montowania SDK, jeśli używasz SDK.

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.

1. Otwórz kontener GTM.
2. Utwórz nowy tag Custom HTML.
3. Wklej fragment ChattyBox.
4. Użyj wyzwalacza All Pages albo węższego wyzwalacza tylko dla stron, na których ma być widoczny widżet.
5. 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. Nie uruchamiaj ponownie loadera przy zmianach historii nawigacji.

Zasady Content Security Policy (CSP)

Dla domyślnego hostowanego loadera zezwól na https://chattybox.ai w script-src, a na origin API widżetu w connect-src. Widżet wstrzykuje arkusz stylów i atrybuty stylów inline; obecnie nie obsługuje nonce, więc polityka blokująca style inline uniemożliwi działanie części interfejsu. Jeśli polityka na to pozwala, zezwól na 'unsafe-inline' dla tych stylów albo użyj własnego interfejsu zgodnego z CSP. Załadowanie fontu Inter po otwarciu przycisku widżetu wymaga również https://fonts.googleapis.com w style-src oraz https://fonts.gstatic.com w font-src. W img-src zezwól na origin skonfigurowanego obrazu ikony. Przed poluzowaniem CSP uwzględnij wymagania dotyczące zgody i bezpieczeństwa.

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.

Nie jest to kontrola prywatności ani dostępu dla każdej strony frontendu. W razie potrzeby zaimplementuj i przetestuj wykluczenia stron płatności, konta, chronionych hasłem lub członkowskich za pomocą filtra wtyczki albo użyj ręcznej instalacji o odpowiednio ograniczonym zakresie.

Ustawienie adresu loadera we wtyczce nie zmienia wbudowanego produkcyjnego punktu końcowego API; w przypadku innego wdrożenia API użyj ręcznego fragmentu.

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, finalizacji zakupu, 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 Instalacja na stronie projektu i włącz chatbota. Moduł jest domyślnie wyłączony. Lokalnie sprawdzona wersja modułu ma punkt końcowy API zapisany na stałe. Porównaj go z fragmentem instalacyjnym; dla innego wdrożenia API użyj integracji ręcznej. Informacje o wykluczaniu tras, pamięci podręcznej i zgodzie znajdziesz w przewodniku po module chatbota Drupal.

Moduł pomija żądania administracyjne i niebędące HTML-em, ale nie całą prywatną treść frontendu. Zmiana adresu URL skryptu nie zmienia wbudowanego produkcyjnego punktu końcowego API. W przypadku innego wdrożenia API użyj ręcznego fragmentu widżetu zamiast modułu.

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. Sprawdź też ustawienia originów klucza: czy ograniczenie jest włączone i czy dozwolony jest origin wdrożenia. Klucz utworzony podczas przygotowywania instalacji może już być ograniczony.