Przewodniki instalacji

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 i ogranicz jego dozwolone originy. Wróć do Embed, wybierz ten 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	Wymuszanie języka interfejsu widżetu na konkretnej stronie.

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 wszelkie ograniczenia dozwolonych originów skonfigurowane dla projektu.
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 dozwolone originy pozostają danymi uwierzytelniającymi konfiguracji projektu, a nie wartościami pliku konfiguracyjnego.

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.

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 na podstawie języka bieżącej strony lub polegaj na wartości <html lang> strony.

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.

WordPress

ChattyBox nie wymaga wtyczki WordPress. Użyj jednej z lokalizacji skryptu obsługiwanych już przez 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 ma 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.

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ź, czy odpowiedź zawiera cytowania ź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​

WordPress​

Weryfikacja​

Privacy choices