Panduan Instalasi

Integrasi widget.js ter-host adalah jalur tanpa build jika Anda ingin ChattyBox memelihara antarmuka dan transport. Jika aplikasi Anda harus menginisialisasi UI yang sama dari kode npm, gunakan mountWidget(). Untuk memiliki kendali atas UI, gunakan SDK headless.

Sebelum Menginstal

Selesaikan alur Memulai terlebih dahulu: konfigurasikan dan scrape sumber, tinjau halaman yang diindeks, dan verifikasi jawaban representatif di Test Chat.

Kemudian buat kunci yang aman untuk browser di Public Keys dan batasi origin yang diizinkan. Kembali ke Embed, pilih kunci tersebut, selesaikan kustomisasi widget ter-host jika ada, lalu salin cuplikan yang dibuat. Cuplikan ini berisi kunci publik dan URL API untuk proyek Anda:

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

Untuk platform yang berfokus pada dokumentasi, lihat panduan chatbot AI MkDocs, chatbot AI VitePress, dan chatbot AI GitBook.

Ganti YOUR_API_KEY dengan kunci widget publik dari dasbor Anda. Pertahankan nilai data-api-url persis seperti yang ditampilkan di dasbor. Dalam produksi, ini adalah URL stabil https://...convex.site/chat untuk API widget publik.

Apa yang Termasuk dalam Skrip

Gunakan atribut skrip untuk nilai yang harus tersedia sebelum widget dapat dimulai:

Atribut	Wajib	Gunakan untuk
`src`	Ya	Memuat JavaScript widget ChattyBox.
`data-api-key`	Ya	Mengidentifikasi kunci widget publik untuk proyek Anda.
`data-api-url`	Ya	Mengirim permintaan widget ke ChattyBox API.
`data-locale`	Tidak	Memaksa bahasa UI widget pada halaman tertentu.

Gunakan pengaturan dasbor untuk semua hal yang perlu dikelola tanpa melakukan deployment ulang situs:

Warna, posisi, ikon, judul, dan pesan sambutan widget.
Mode bahasa default dan apakah penggantian data-locale diizinkan.
Pembuatan dan penghapusan kunci publik serta pembatasan origin yang diizinkan untuk proyek.
Scraping, scraping ulang, chat pengujian, analitik, dan kesenjangan konten.

Jika Anda mengaktifkan kunci config-as-code, pengaturan asisten, sumber, runtime, dan widget yang didukung berasal dari konfigurasi yang di-deploy, bukan formulir dasbor. Kunci publik dan origin yang diizinkan tetap menjadi kredensial penyiapan proyek, bukan nilai dalam file konfigurasi.

HTML Biasa

Tempelkan cuplikan sekali di dekat akhir body, tepat sebelum </body>. Ini berfungsi untuk HTML statis, situs yang dikodekan manual, dan templat yang menyediakan footer global.

<!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 / React App Shell

Untuk situs Next.js App Router, tambahkan widget ke app/layout.tsx dengan next/script agar dimuat sekali untuk seluruh aplikasi.

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

Untuk aplikasi React satu halaman, tambahkan skrip sekali di app shell tingkat atas atau templat HTML. Jangan menyuntikkannya dari setiap komponen rute.

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

Untuk Docusaurus, buat atau perbarui src/theme/Root.tsx agar widget tersedia di seluruh halaman dokumentasi.

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

Jika situs Docusaurus Anda memiliki rute terjemahan, atur data-locale dari bahasa halaman saat ini atau andalkan nilai <html lang> halaman.

Pertahankan loader di app shell yang persisten. Jangan membuat ulang atau menghapusnya selama perubahan rute sisi klien yang normal.

Antarmuka Khusus

Widget ter-host bersifat opsional. Jika Anda menginginkan kendali penuh atas rendering, state pesan, dan desain interaksi, gunakan SDK JavaScript dengan kunci API widget publik dan URL API widget yang sama.

CMS Umum/HTML Khusus

Sebagian besar platform CMS memiliki area kode kustom global, footer, atau templat tema. Tambahkan skrip di sana agar setiap halaman publik dapat memuat widget.

Gunakan jalur ini untuk area kode kustom Webflow, Framer, Squarespace, Wix, tema Shopify, templat HubSpot, dan platform CMS khusus yang memungkinkan Anda mengedit HTML global.

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

Sebelum menerbitkan, pastikan CMS tidak menghapus data-api-key, data-api-url, atau async dari skrip kustom.

Google Tag Manager

Gunakan Google Tag Manager ketika tim Anda sudah mengelola skrip pihak ketiga melalui GTM.

Buka container GTM Anda.
Buat tag Custom HTML baru.
Tempel cuplikan ChattyBox.
Gunakan pemicu All Pages, atau pemicu yang lebih sempit hanya untuk halaman yang seharusnya menampilkan widget.
Pratinjau container, verifikasi widget dimuat, lalu terbitkan.

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

Jika situs menggunakan mode persetujuan atau kebijakan persetujuan tag, pastikan widget diizinkan dimuat pada halaman tempat pengunjung memerlukan bantuan.

WordPress

ChattyBox tidak memerlukan plugin WordPress. Gunakan salah satu lokasi skrip yang sudah didukung oleh penyiapan WordPress Anda:

Pengaturan tema yang menyediakan skrip header atau footer.
Tema anak yang mengontrol templat footer.
Plugin skrip header/footer.
Google Tag Manager jika situs WordPress Anda sudah menggunakannya.

Tempel cuplikan di lokasi footer global agar muncul di halaman, postingan, dokumen, dan artikel basis pengetahuan yang diterbitkan tempat chatbot harus tersedia.

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

Hindari menambahkan widget ke halaman wp-admin, checkout, akun, atau keanggotaan privat kecuali halaman tersebut memang sengaja dibuat publik dan didukung.

Verifikasi

Setelah memasang, jalankan daftar periksa peluncuran sebelum mengumumkan chatbot:

Buka halaman publik di jendela penyamaran.
Pastikan peluncur widget muncul.
Buka widget dan ajukan pertanyaan pelanggan yang nyata.
Pastikan jawaban menyertakan sitasi sumber.
Periksa konsol browser untuk data-api-key yang hilang, data-api-url yang hilang, atau kesalahan kunci/origin.

Sebelum Menginstal​

Apa yang Termasuk dalam Skrip​

HTML Biasa​

Next.js / React App Shell​

Docusaurus​

Antarmuka Khusus​

CMS Umum/HTML Khusus​

Google Tag Manager​

WordPress​

Verifikasi​

Privacy choices