Panduan Instalasi

:::note Status versi SDK npm 0.1.4 yang dipublikasikan bersama widget.js v15 mendukung teardown lewat remove() atau window.ChattyBox.destroy() dan membatalkan pekerjaan tertunda. :::

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. Secara default, kunci ini berfungsi di origin produksi, pratinjau/staging, dan localhost. Untuk menambahkan hardening defense-in-depth opsional, pilih Edit origins, aktifkan Restrict this key to specific origins, dan tambahkan origin yang diizinkan secara tepat. Saat diaktifkan, pencocokan mencakup skema, hostname, dan port: https://example.com, https://preview.example.com, dan http://localhost:3000 adalah entri yang terpisah. Kembali ke Embed, pilih kunci tersebut, 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	Meminta bahasa UI saat inisialisasi, hanya jika proyek mengizinkan override skrip.
data-chattybox-widget="true"	Tidak	Memungkinkan loader dinamis dan SDK menemukan skrip yang sudah ada; direkomendasikan saat menyuntikkan dari kode aplikasi.
data-debug="true"	Tidak	Mengaktifkan diagnostik browser; nonaktif secara default.

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 opsional per kunci. Buka Public Keys > Edit origins untuk mengaktifkan pembatasan dan menambahkan atau menghapus origin produksi, staging, pratinjau, maupun localhost.
• Scraping, scraping ulang, chat pengujian, analitik, dan kesenjangan konten.

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

URL API dapat berupa root deployment HTTP atau diakhiri dengan /chat; loader menghapus garis miring akhir dan sufiks /chat untuk menurunkan endpoint. Jangan gunakan URL Convex .cloud, query string, atau fragmen.

Pasang satu loader saja. SDK hanya mengenali atribut penanda di atas, bukan setiap skrip manual dengan src yang sama. Widget memuat konfigurasi dan terjemahan sekali saat inisialisasi; widget tidak berlangganan perubahan dasbor atau perubahan bahasa halaman. Muat ulang halaman untuk mengambil pengaturan tersimpan. Jika pembatasan origin diaktifkan, pencocokan memakai Origin atau origin fallback dari Referer; origin yang tidak ada atau tidak diizinkan menghasilkan 401 Invalid API key. Pembatasan ini bukan autentikasi.

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"
          data-chattybox-widget="true"
          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. Dalam SDK 0.1.4 yang dipublikasikan, mount identik berbagi skrip dan referensi; remove() idempoten dan hanya handle terakhir yang memberi sinyal teardown v15, menghapus UI, gaya, font, skrip, dan API global serta membatalkan pekerjaan tertunda. Opsi berbeda ditolak selama masih ada handle.

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 sebelum memuat widget bila override diizinkan, atau gunakan mode otomatis dan <html lang> halaman. Mode Fixed memakai locale default proyek kecuali ada override skrip yang diizinkan. Locale diputuskan saat inisialisasi, bukan pada perubahan rute sisi klien; reload halaman penuh mengambil bahasa halaman baru.

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.

1. Buka container GTM Anda.
2. Buat tag Custom HTML baru.
3. Tempel cuplikan ChattyBox.
4. Gunakan pemicu All Pages, atau pemicu yang lebih sempit hanya untuk halaman yang seharusnya menampilkan widget.
5. 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.

Panduan plugin WordPress

Untuk instalasi WordPress tanpa kode, gunakan plugin WordPress ChattyBox. Ikuti panduan plugin WordPress untuk menginstal, mengonfigurasi, mengecualikan rute, dan memverifikasinya. Endpoint API produksi dikonfigurasi secara otomatis.

Plugin memuat widget ter-host pada permintaan frontend publik tanpa mengedit tema. Plugin sengaja tidak memuatnya di wp-admin, feed, permintaan REST, atau AJAX. Ini bukan pemeriksaan privasi untuk semua halaman frontend: kecualikan checkout, akun, halaman yang dilindungi sandi, atau keanggotaan secara eksplisit bila diperlukan. Mengubah URL loader plugin tidak mengubah endpoint API produksi bawaan; gunakan cuplikan manual untuk deployment API lain.

Jika Anda lebih memilih instalasi skrip manual, 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 pada halaman, postingan, docs, 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.

Modul Drupal

Untuk Drupal 10 atau 11, Composer adalah jalur instalasi yang direkomendasikan. Tambahkan repositori VCS GitHub publik ke composer.json root proyek Drupal yang menggunakannya:

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

Kemudian instal modul bertag dan aktifkan:

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

Buka Configuration > Web services > ChattyBox, tempel kunci API widget publik dari tab Embed proyek, lalu aktifkan chatbot. Endpoint API produksi dikonfigurasi secara otomatis. Lihat panduan modul chatbot Drupal untuk pengecualian rute dan fallback manual.

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 yang didukung menyertakan sitasi sumber yang relevan, lalu uji pertanyaan yang tidak didukung dan fallback-nya—yang dapat tidak memiliki sumber.
• Periksa konsol browser untuk data-api-key yang hilang, data-api-url yang hilang, atau kesalahan kunci. Periksa origin hanya jika Anda secara eksplisit mengaktifkan pembatasan untuk kunci tersebut.