Lewati ke konten utama
ChattyBox Logo

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:

AtributWajibGunakan untuk
srcYaMemuat JavaScript widget ChattyBox.
data-api-keyYaMengidentifikasi kunci widget publik untuk proyek Anda.
data-api-urlYaMengirim permintaan widget ke ChattyBox API.
data-localeTidakMemaksa 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.

  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.

WordPress​

Untuk langkah-langkah terperinci tentang instalasi dan konfigurasi plugin, pengecualian rute, serta verifikasi, lihat panduan plugin WordPress.

Untuk sebagian besar situs WordPress, instal dan aktifkan plugin WordPress resmi ChattyBox:

  1. Di admin WordPress, instal dan aktifkan plugin ChattyBox AI Chatbot.
  2. Buka Settings > ChattyBox.
  3. Tempel hanya kunci API widget publik dari tab Embed. Endpoint API produksi dikonfigurasi secara otomatis.
  4. Aktifkan chatbot dan verifikasi di halaman publik.

Sebagai fallback manual, letakkan cuplikan di lokasi footer global menggunakan salah satu opsi berikut:

  • 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.
<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 menyertakan sitasi sumber.
  • Periksa konsol browser untuk data-api-key yang hilang, data-api-url yang hilang, atau kesalahan kunci/origin.

Privacy choices

We use optional analytics and tag-management tools to understand site use. Choose whether to allow PostHog and Google Tag Manager. Turning analytics off reloads this page so the change takes effect cleanly. Essential site functionality and error monitoring are not controlled by this choice. Read our privacy policy.