:::note Status versi SDK npm 0.1.4 yang dipublikasikan bersama widget.js v15 mendukung teardown melalui remove() atau window.ChattyBox.destroy(): UI/gaya dihapus dan inisialisasi, percobaan ulang, serta chat yang tertunda dibatalkan. sendMessage() headless tidak mencoba ulang otomatis. :::

Kustomisasi Widget Ter-host

Sesuaikan antarmuka siap pakai yang dimuat oleh https://chattybox.ai/widget.js. Untuk contoh instalasi framework dan platform kanonis, lihat Panduan Instalasi.

Sebelum Menyesuaikan

Buat proyek, indeks kontennya, dan verifikasi jawaban representatif di Test Chat sebelum meluangkan waktu untuk presentasi. Lihat Memulai untuk urutan lengkapnya.

Konfigurasikan Widget Ter-host

1. Buka Dasbor dan pilih proyek Anda.
2. Buka tab Embed.
3. Pratinjau dan simpan tampilan serta perilaku bahasa widget.

Tab Embed mengatur presentasi dan membuat kode instalasi, tetapi kunci publik dikelola secara terpisah. Saat siap menginstal:

1. Buka Public Keys dan buat kunci browser.
2. Kembali ke Embed, pilih kuncinya, lalu salin cuplikan yang dibuat. Kunci bekerja pada produksi, pratinjau, staging, dan localhost secara default.
3. Secara opsional buka Public Keys > Edit origins dan aktifkan pembatasan origin tepat sebagai pertahanan tambahan.
4. Ikuti Panduan Instalasi untuk platform Anda.

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

tip

Perubahan presentasi yang disimpan di dasbor berlaku pada inisialisasi widget berikutnya tanpa mengganti cuplikan. Halaman yang sudah terbuka tidak diperbarui langsung; muat ulang untuk mengambil pengaturan tersimpan.

---

Kustomisasi Visual

Editor dasbor memungkinkan Anda menyesuaikan warna, penempatan, ikon, dan teks widget yang didukung tanpa mengedit kode situs. Verifikasi hasil pada widget ter-host karena pratinjau dan loader tidak identik.

Kontrol Dasbor

1. Accent Color - Pilih warna utama merek Anda. Ini memengaruhi peluncur, sorotan utama, dan pesan pengguna.

2. Position - Pilih tempat widget muncul di layar.

3. Header Title - Atur judul yang ditampilkan di bagian atas jendela chat.

4. Welcome Message - Sesuaikan pesan pertama yang dilihat pengunjung saat membuka chat.

5. ChattyBox Branding - Paket Starter dan lebih tinggi dapat mematikan footer “Powered by ChattyBox”. Branding tetap aktif di Free.

Editor juga menyediakan Widget Background, Text Color, serta ikon robot default, emoji, URL gambar, atau gambar yang diunggah. Ikon unggahan maksimal 512 KiB dan harus memakai jenis gambar yang diterima. Ukuran ikon tersimpan, tetapi loader ter-host saat ini tidak membaca iconSize; jangan mengharapkan small/medium/large mengubah ukurannya.

catatan

Simpan perubahan lalu muat ulang halaman yang dipasang untuk memverifikasinya. Pratinjau dasbor adalah mock, bukan widget ter-host. Pada proyek yang config-locked, tampilan dan locale dikelola konfigurasi sebagai kode; proyek yang berhak tetap dapat menyimpan branding secara terpisah.

Opsi Lanjutan

Pengaturan Dasbor vs Atribut Skrip

Sebagian besar perilaku widget sebaiknya dikelola dari dasbor agar Anda tidak perlu melakukan deployment ulang situs untuk perubahan sederhana.

Gunakan dasbor untuk warna, posisi, ikon, judul header, pesan sambutan, bahasa default, pengelolaan kunci publik, scraping, dan analitik.

Jika Anda secara eksplisit mengaktifkan pembatasan origin kunci publik, sinkronkan origin tepatnya dengan domain tempat widget dipasang. Origin adalah pertahanan tambahan opsional, bukan autentikasi.

Gunakan atribut skrip hanya untuk nilai yang diperlukan widget saat halaman dimuat:

• data-api-key mengidentifikasi kunci widget publik.
• data-api-url memberi tahu widget ke mana harus mengirim permintaan. Dalam produksi, ini adalah URL stabil https://...convex.site/chat dari dasbor Anda.
• data-locale meminta bahasa UI widget tertentu saat inisialisasi hanya jika proyek mengizinkan override skrip.
• data-color dan data-position menggantikan warna aksen dan posisi tersimpan setelah fetch konfigurasi berhasil. Pilih nilai dasbor bila memungkinkan.
• data-debug="true" mengaktifkan diagnostik konsol; nonaktif secara default.

Widget ter-host mengirim origin dan path halaman publik saat ini yang tervalidasi bersama setiap request chat untuk analitik Popular Triggers; query string, fragmen, dan kredensial dihapus. Konteks halaman tidak mengubah sumber terindeks yang diambil. Jangan memuat widget pada rute sensitif hanya karena query string dihapus.

Jika widget tidak muncul setelah instalasi, lihat Pemecahan Masalah.

Untuk contoh khusus platform, mulai dari Docusaurus, MkDocs, VitePress, WordPress, atau GitBook.

Menyembunyikan Widget di Halaman Tertentu

Jika perlu menyembunyikan widget di halaman tertentu, Anda dapat melakukannya dengan CSS:

.chattybox-widget {
  display: none;
}

Menyembunyikan CSS tidak menghentikan inisialisasi, request API, atau pelaporan error dan bukan kontrol persetujuan maupun privasi. Untuk mencegah pemuatan, kecualikan skrip pada request halaman tersebut. Untuk transisi rute sisi klien atau pencabutan persetujuan, widget.js v15 ter-host menyediakan window.ChattyBox.destroy() dan SDK npm 0.1.4 menyediakan remove() untuk teardown lengkap.

Integrasi Khusus

Memerlukan penyiapan yang lebih khusus daripada widget ter-host? Bangun antarmuka sendiri dengan SDK JavaScript, atau hubungi support@chattybox.ai untuk bantuan arsitektur.

Dukungan Multibahasa

Widget ChattyBox menentukan lokal UI saat inisialisasi berdasarkan mode Fixed atau Auto proyek; widget tidak memantau perubahan atribut atau rute sisi klien berikutnya.

Bahasa yang Didukung Secara Resmi

Widget memiliki katalog terjemahan untuk 14 bahasa. Keberadaan katalog tidak berarti setiap string yang terlihat atau dapat diakses diterjemahkan, dan tidak menjamin kualitas jawaban.

Bahasa	Kode
Inggris	en
Prancis	fr
Jerman	de
Spanyol	es
Italia	it
Belanda	nl
Portugis	pt
Polandia	pl
Swedia	sv
Indonesia	id
Estonia	et
Finlandia	fi
Wales	cy
Ceko	cs

:::note Bahasa UI dan jawaban Lokal UI tidak dikirim sebagai parameter bahasa chat. Backend mendeteksi bahasa pertanyaan dan mencoba pengambilan serta pembuatan yang sadar bahasa; bahasa dan kualitas jawaban bergantung pada konten yang diindeks dan model. :::

Cara Kerja Deteksi Bahasa

Widget menggunakan sistem deteksi bertingkat:

1. Override skrip yang diizinkan - data-locale yang tidak kosong hanya menang jika allowLocaleOverride bukan false, termasuk dalam mode Fixed.
2. Mode Fixed - Tanpa override yang diizinkan, gunakan defaultLocale.
3. Mode Auto - Gunakan nilai pertama yang tidak kosong dari <html lang> halaman, navigator.language browser (atau userLanguage lama), lalu defaultLocale.
4. Normalisasi - Nilai regional yang didukung seperti fr-CA diperkecil ke kode dasar; nilai yang tidak didukung langsung menjadi bahasa Inggris tanpa mencoba kandidat berikutnya.

Penggantian Bahasa Manual

Untuk meminta bahasa tertentu terlepas dari pengaturan browser, aktifkan Allow Script Override dan tambahkan atribut data-locale sebelum loader berjalan:

<script
  src="https://chattybox.ai/widget.js"
  data-api-key="YOUR_API_KEY"
  data-locale="de"
  data-api-url="https://adorable-woodpecker-629.convex.site/chat"
  async
></script>

:::tip Kasus Penggunaan Ini sangat berguna jika situs multibahasa memiliki URL sendiri untuk setiap versi bahasa (misalnya /de/, /fr/). Atur data-locale agar sesuai dengan bahasa setiap halaman, lalu periksa UI yang dirender. :::

Pengaturan Bahasa Dasbor

Dasbor aplikasi memungkinkan Anda mengonfigurasi preferensi bahasa widget per proyek:

• Auto-detect - Menggunakan bahasa halaman sebelum bahasa browser pengunjung
• Fixed Language - Menggunakan bahasa default yang dikonfigurasi kecuali data-locale yang diizinkan menggantikannya
• Allow Script Override - Mengaktifkan/menonaktifkan penggantian atribut data-locale

Akses pengaturan ini di Dasbor → Proyek → tab Embed → bagian Widget Language.

Pencocokan Bahasa Konten

Untuk pengalaman multibahasa yang berguna, indeks konten publik dalam bahasa pengunjung dan uji sumbernya; deteksi dan pengambilan tidak dijamin. Untuk melakukannya:

1. Scrape semua versi bahasa dokumentasi Anda menggunakan file sitemap.xml
2. Scraper mencoba mendeteksi bahasa halaman; periksa konten dan sitasinya
3. Pengambilan mencoba mengutamakan bahasa pertanyaan, tetapi dapat kembali ke konten terindeks lain

Penyiapan di Dasbor Aplikasi: Saat mengonfigurasi scraping, gunakan URL sitemap.xml (misalnya https://yourdocs.com/sitemap.xml) untuk menemukan versi bahasa, lalu verifikasi halaman yang diindeks. Sitemap tidak melewati batas crawl atau pengecualian.

Pemecahan Masalah

Widget Masih Menampilkan Bahasa Inggris

• Hard refresh sebagai diagnosis - Muat ulang dengan Ctrl+F5 atau Cmd+Shift+R, lalu periksa panel jaringan browser untuk permintaan widget dan terjemahan
• Periksa data-locale - Pastikan atribut diatur dengan benar menggunakan kode bahasa yang didukung
• Periksa mode proyek dan izin override - Mode Fixed dan override yang dinonaktifkan dapat dengan sengaja mengabaikan bahasa browser atau data-locale
• Verifikasi bahasa browser - Pastikan bahasa pilihan browser sudah diatur dengan benar
• Periksa HTML lang halaman - Pastikan halaman memiliki <html lang="de"> (atau kode yang sesuai)

Sumber Berada dalam Bahasa yang Salah

• Scrape ulang konten - Pastikan semua versi bahasa sudah diindeks
• Gunakan sitemap.xml - Konfirmasikan URL yang diinginkan benar-benar diindeks; batas crawl dan pengecualian dapat melewatkannya
• Periksa bahasa kueri - AI berusaha mencocokkan bahasa respons dengan bahasa kueri

Terjemahan Hilang

• Periksa bahasa yang didukung - Hanya 14 kode di atas yang memiliki katalog; label yang hilang dapat menggunakan fallback bahasa Inggris

Praktik Terbaik

1. Tetapkan <html lang> di halaman Anda - Membantu aksesibilitas dan deteksi widget
2. Uji dengan data-locale selama pengembangan - Pastikan setiap bahasa dirender dengan benar dan override diizinkan
3. Scrape semua versi bahasa - Gunakan sitemap.xml untuk penemuan, lalu verifikasi halaman yang diindeks
4. Tinjau pertanyaan nyata - Periksa percakapan dan kesenjangan konten khusus bahasa; dasbor saat ini tidak menampilkan distribusi locale widget