:::note Status versi
Kode sumber loader ter-host saat ini yang tersimpan di repositori mengidentifikasi dirinya sebagai v16. Perilaku yang secara khusus ditandai sebagai perilaku kode sumber saat ini di bawah bukanlah klaim tentang versi loader yang telah di-deploy; verifikasi versi yang di-deploy sebelum mengandalkannya. SDK npm 0.1.4 yang dipublikasikan menggunakan handle mount dengan penghitungan referensi: hapus semua handle dengan opsi identik untuk memicu teardown akhir.
:::
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 Uji chatbot sebelum meluangkan waktu untuk tampilan. Lihat Memulai untuk urutan lengkapnya.
Konfigurasikan Widget Ter-host
- Buka Dasbor dan pilih proyek Anda.
- Buka Sesuaikan → Tampilan untuk mengedit tampilan, branding, dan pengaturan Bahasa Widget.
- Periksa status penyimpanan otomatis yang relevan. Perbaiki kesalahan validasi atau coba simpan lagi jika gagal sebelum menguji widget yang dipasang.
Kode instalasi dan kunci publik dikelola di bagian Pasang. Saat siap menginstal:
- Buka Pasang → Kunci & domain untuk memeriksa atau membuat kunci browser publik dan melihat pengaturan originnya.
- Di Pasang → Instalasi situs web, pilih kunci yang sesuai dan salin cuplikan yang dihasilkan. Kunci tanpa pembatasan berfungsi dari semua origin; kunci yang disiapkan untuk suatu situs mungkin sudah dibatasi ke origin situs tersebut. Periksa kunci yang dipilih sebelum menggunakan staging atau localhost.
- Anda dapat mengaktifkan pembatasan origin yang tepat sebagai pertahanan tambahan. Pembatasan ini tidak mengautentikasi pengunjung; kunci browser bersifat publik dan pengunjung tidak perlu login.
- 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>
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
-
Warna Aksen - Pilih warna utama merek Anda. Ini memengaruhi tombol pembuka, sorotan utama, dan pesan pengguna.
-
Posisi Widget - Pilih tempat widget muncul di layar.
-
Judul Header - Atur judul yang ditampilkan di bagian atas jendela chat.
-
Pesan Sambutan - Sesuaikan pesan pertama yang dilihat pengunjung saat membuka chat.
-
Tampilkan branding ChattyBox - Branding wajib ditampilkan pada paket Free. Paket Starter dan yang lebih tinggi dapat menyembunyikan footer “Dipersembahkan oleh ChattyBox”.
Editor juga menyediakan kontrol Latar Belakang Widget dan Warna Teks, serta ikon robot bawaan, emoji, URL gambar, atau gambar yang diunggah. Ikon unggahan maksimal 512 KiB dan harus memakai jenis MIME gambar yang diterima (PNG, JPEG, WebP, SVG, GIF, atau ICO). Kontrol ukuran iconSize di editor hanya tersedia untuk ikon URL gambar atau gambar yang diunggah. Loader ter-host v16 dalam kode sumber saat ini menggunakan iconSize untuk mengatur ukuran tombol pembuka dan ikon. Verifikasi loader yang di-deploy sebelum mengandalkan perilaku ini.
Pastikan status penyimpanan otomatis yang relevan, lalu muat ulang halaman yang dipasang untuk memverifikasi perubahan. Status antarmuka yang ditampilkan adalah Status penyimpanan tampilan, Status penyimpanan bahasa, dan Status penyimpanan merek; jika penyimpanan gagal, pilih Coba simpan lagi. Pratinjau dasbor adalah mock, bukan widget ter-host. Pada proyek yang dikunci konfigurasi, tampilan dan locale dikelola melalui config-as-code; proyek yang berhak tetap dapat menyimpan pengaturan branding secara terpisah.
Default Konfigurasi
Berikut adalah nilai default dalam respons widget-config publik yang berhasil ketika tidak ada nilai kustom:
| Field | Default |
|---|---|
enabled | true, kecuali dinonaktifkan pada proyek |
themeColor | #3b82f6 |
chatBgColor | #0f172a |
textColor | #f8fafc |
position | bottom-right; keempat sudut didukung |
iconType, iconSize | default, medium; kode sumber saat ini v16 menggunakan ukuran untuk tombol pembuka dan ikon. Kontrol ukuran hanya tersedia jika nilai iconType adalah url atau upload |
iconEmoji, iconUrl | emoji balon percakapan, null |
headerTitle | Chat with us (nilai default API) |
welcomeMessage | Hi! 👋 How can I help you today? (nilai default API) |
showBranding | true; dipaksa aktif pada proyek Free |
localeMode, defaultLocale, allowLocaleOverride | auto, en, true (nilai default) |
Jika pengambilan konfigurasi gagal atau respons tidak valid, loader kode sumber saat ini v16 membuat widget tidak tersedia dan tidak menampilkan UI fallback. Jika konfigurasi berhasil tetapi pengambilan terjemahan gagal, widget masih dapat muncul dengan label bawaan berbahasa Inggris. Respons berhasil dengan enabled: false juga mencegah widget dirender; API chat menolak permintaan widget yang dinonaktifkan dengan HTTP 403, termasuk permintaan SDK. Verifikasi versi loader yang di-deploy sebelum mengandalkan perilaku kode sumber saat ini.
Loader ter-host v16 dalam kode sumber saat ini meminta konfigurasi dengan header Authorization: Bearer dan mencoba sekali lagi menggunakan kunci pada parameter kueri hanya setelah HTTP 400. Loader juga mengulang permintaan GET konfigurasi dan terjemahan saat startup secara terpisah; ini berbeda dari retry pesan chat di bawah. SDK 0.1.4 yang dipublikasikan menerapkan fallback konfigurasi yang sama hanya jika halaman mengekspos window.ChattyboxSDK. Pembagian mount SDK hanya untuk opsi identik; kunci, endpoint, URL skrip, locale, atau pengaturan debug yang berubah akan ditolak sampai semua handle yang cocok dihapus. Verifikasi versi loader yang di-deploy sebelum mengandalkan perilaku kode sumbernya.
Opsi Lanjutan
Pengaturan Dasbor vs Atribut Skrip
Atur sebagian besar perilaku widget dari dasbor agar perubahan sederhana tidak mengharuskan Anda melakukan deployment ulang situs.
Gunakan dasbor untuk warna, posisi, ikon, judul header, pesan sambutan, bahasa default, pengelolaan kunci publik, scraping, dan analitik.
Pembatasan origin pada kunci publik bersifat opsional, sebagai pertahanan tambahan, bukan autentikasi pengunjung. Jika diaktifkan, sinkronkan origin persisnya dengan domain tempat widget dipasang.
Gunakan atribut skrip hanya untuk nilai yang diperlukan widget saat halaman dimuat:
data-api-keymengidentifikasi kunci widget publik.data-api-urlmemberi tahu widget ke mana harus mengirim permintaan. Dalam produksi, ini adalah URL stabilhttps://...convex.site/chatdari dasbor Anda.data-localememinta bahasa UI widget tertentu jika proyek mengizinkan override skrip. Loader kode sumber saat ini v16 juga mengamati perubahan berikutnya pada atribut ini.data-colordandata-positionmenggantikan warna aksen dan posisi tersimpan setelah pengambilan konfigurasi berhasil. Utamakan nilai dasbor; atribut ini dapat menutupi perubahan dasbor berikutnya.data-debug="true"mengaktifkan diagnostik konsol; nonaktif secara default.
Untuk setiap pesan baru, loader ter-host dalam kode sumber saat ini mencoba menyertakan origin dan path HTTP(S) halaman saat ini untuk analitik Pemicu Populer. Loader tidak memeriksa apakah halaman bersifat publik. Konteks yang tidak valid atau terlalu panjang dihilangkan; retry mempertahankan konteks permintaan awal. Query string, fragmen, dan kredensial dihapus, tetapi path dapat memuat pengenal sensitif. Jangan memuat widget pada rute sensitif hanya karena query string dihapus.
Konteks halaman diambil dari URL HTTP(S) saat ini, bukan dari pemeriksaan apakah halaman publik, dan tidak mengubah sumber terindeks yang diambil. Loader juga dapat mengirim error inisialisasi, konfigurasi, terjemahan, dan chat ke /widget-error melalui beacon atau fetch. Laporan dapat memuat detail error terbatas, locale, versi, serta origin/path halaman; mode debug tidak diperlukan. Widget dalam kode sumber saat ini juga menghormati prefers-reduced-motion, menyediakan kolom input pesan berlabel dan pengumuman live, serta menampilkan sitasi melalui panel Sumber yang dapat diakses dengan keyboard.
Chat menggunakan respons JSON lengkap, bukan streaming token. Loader ter-host v16 dalam kode sumber saat ini membuat kunci idempotensi per pesan dan melakukan maksimal 10 percobaan transport otomatis untuk error jaringan, pembacaan body respons sukses yang terputus, HTTP 429, HTTP 5xx, serta HTTP 409 dengan header Retry-After yang dapat dibaca. Loader tidak menjadwalkan percobaan lagi jika waktu tunggu akan melewati anggaran 30 detik; ini bukan batas waktu keras untuk permintaan yang sedang berlangsung. CORS browser dapat menyembunyikan Retry-After. Kunci idempotensi yang sama digunakan pada retry sehingga server dapat memutar ulang respons tersimpan alih-alih memproses pesan dua kali. Retry chat otomatis ini tidak tersedia pada sendMessage() headless di SDK; retry GET startup loader dan fallback config-400 SDK 0.1.4 merupakan perilaku terpisah yang terbatas. Status percakapan tersimpan dalam memori instance widget dan hilang saat reload atau inisialisasi ulang, meski pesan yang tersimpan di server dapat tetap ada. Sumber dideduplikasi dan dibatasi maksimal tiga entri yang ditampilkan; jawaban fallback mungkin tidak memiliki sumber. Verifikasi versi loader yang di-deploy sebelum mengandalkan perilaku kode sumber saat ini.
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
Untuk menyembunyikan widget secara visual, terapkan CSS berikut hanya di halaman tertentu (penerapan global akan menyembunyikannya di semua halaman):
.chattybox-widget {
display: none;
}
Penyembunyian CSS tidak menghentikan inisialisasi, permintaan API, atau pelaporan error dan bukan kontrol persetujuan maupun privasi. Loader tidak membuat keputusan persetujuan: tunda penyisipan skrip sampai persetujuan yang diwajibkan diberikan, dan cegah penyisipan ulang setelah persetujuan dicabut atau pada rute yang dikecualikan. Menghapus tag skrip saja tidak menghentikan widget yang sudah dimuat. Untuk transisi rute sisi klien atau pencabutan persetujuan, window.ChattyBox.destroy() tersedia pada widget.js v16 dalam kode sumber loader ter-host saat ini. Hapus semua handle mount SDK 0.1.4 dengan opsi identik untuk memicu teardown akhir. Pastikan loader yang di-deploy mendukung teardown. Teardown menghapus UI/gaya milik widget dan membatalkan pekerjaan tertunda, tetapi tidak dapat membatalkan permintaan yang sudah diproses server.
Kontrol Browser
Pada loader ter-host v16 dalam kode sumber saat ini, window.ChattyBox sudah tersedia saat startup dengan status: 'loading' dan destroy(). Memanggil destroy() saat itu membatalkan startup. open(), close(), toggle(), dan sendMessage(text) baru tersedia setelah inisialisasi berhasil; periksa window.ChattyBox?.status === 'ready' sebelum memanggilnya. Skrip yang sudah dimuat belum tentu berarti konfigurasi dan terjemahan sudah siap. destroy() menghapus elemen/gaya widget, membatalkan pekerjaannya, dan membersihkan global, tetapi tidak dapat membatalkan permintaan yang sudah diproses server. close() hanya menutup panel chat; tombol pembuka tetap ada. sendMessage(text) mengembalikan promise untuk operasi UI, bukan promise untuk jawaban; pengiriman saat pesan lain masih tertunda akan diabaikan. Global ini berbeda dari konstruktor SDK pada window.ChattyboxSDK. Verifikasi versi loader yang di-deploy sebelum mengandalkan perilaku ini.
Tema siang/malam yang dikendalikan situs (kode sumber saat ini)
Alur kerja config-as-code dalam kode sumber saat ini mendukung palet opsional widget.theme.light dan widget.theme.dark. Masing-masing dapat berisi primaryColor, backgroundColor, dan textColor dalam format warna hex enam digit; warna yang tidak dicantumkan mewarisi nilai dasar widget.theme. Konfigurasi tema tunggal yang sudah ada tetap berfungsi seperti sebelumnya. Ini memerlukan CLI/backend dalam kode sumber saat ini dan loader ter-host v16; CLI/config 0.3.1 yang dipublikasikan belum menerima kolom baru ini. Ini bukan klaim tentang versi loader yang di-deploy.
Atur data-theme="light" atau data-theme="dark" pada skrip loader sebelum dijalankan untuk memilih palet awal. Lalu hubungkan pengalih situs Anda ke API browser:
window.ChattyBox?.setTheme('light');
window.ChattyBox?.setTheme('dark');
window.ChattyBox?.setTheme(null); // Restore the configured base appearance.
Widget memperbarui gaya yang ada tanpa mengatur ulang pesan, sumber, teks draf, atau permintaan tertunda. Pemilihan tema tidak dapat menonaktifkan widget atau menghapus atribusi. Situs Anda bertanggung jawab menyimpan preferensi dan menangani tema OS; widget hanya memilih palet yang dikonfigurasi.
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 ter-host v16 dalam kode sumber saat ini menentukan locale UI berdasarkan mode Fixed atau Auto proyek. Widget mengamati perubahan <html lang> dan data-locale pada skrip loader, lalu memperbarui label tanpa mengatur ulang percakapan, draf, atau retry yang tertunda. Navigasi saja tidak memilih bahasa; perbarui salah satu atribut tersebut bila perlu. Perubahan pengaturan dasbor tetap memerlukan inisialisasi ulang. Ini menjelaskan kode sumber saat ini, bukan berarti loader yang di-deploy pasti memiliki perilaku tersebut.
Bahasa yang Didukung Secara Resmi
Widget memiliki katalog terjemahan untuk 14 bahasa. Semua katalog saat ini menggunakan tata letak kiri-ke-kanan. Katalog UI tidak menerjemahkan teks yang ditulis pemilik proyek atau jawaban yang dihasilkan AI.
| 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 Loader ter-host dalam kode sumber saat ini menyertakan locale UI yang telah ditentukan pada permintaan chat. Backend mendeteksi bahasa pertanyaan dan mencoba pengambilan serta pembuatan yang sadar bahasa. Untuk fallback milik produk, sinyal bahasa pertanyaan yang dikenali lebih diutamakan daripada locale UI; jika deteksi tidak meyakinkan atau hanya mengandalkan heuristik bahasa Inggris ASCII, locale UI dapat memilih bahasa fallback. Pesan fallback yang ditulis oleh pemilik proyek digunakan apa adanya, dan locale tidak menerjemahkannya atau mengubah keluaran AI. Bahasa dan kualitas jawaban bergantung pada konten yang diindeks dan model; katalog UI bukan jaminan kualitas jawaban. :::
Cara Kerja Deteksi Bahasa
Widget menggunakan sistem deteksi bertingkat:
- Override skrip yang diizinkan -
data-localeyang didukung akan menang jikaallowLocaleOverridebukanfalse, termasuk dalam mode Fixed. - Mode Fixed - Tanpa override yang diizinkan dan didukung, gunakan
defaultLocaledan abaikan bahasa halaman/browser. - Mode Auto - Coba berurutan
<html lang>halaman,navigator.language, setiap nilai dalamnavigator.languages,userLanguagelama, laludefaultLocale; pilih bahasa pertama yang didukung. - Normalisasi - Pencocokan tidak membedakan huruf besar/kecil dan nilai regional yang didukung seperti
fr-CAdinormalisasi ke bahasa dasar yang didukung. Kandidat yang tidak didukung dilewati; jika tidak ada yang cocok, gunakan bahasa Inggris.
Judul header dan pesan sambutan kustom ditampilkan apa adanya, tidak diterjemahkan otomatis. Kode sumber saat ini menggunakan label terlokalisasi untuk judul dan pesan sambutan default; jika terjemahan gagal dimuat, label bawaan bahasa Inggris digunakan.
Penggantian Bahasa Manual
Untuk meminta bahasa tertentu terlepas dari pengaturan browser, aktifkan Izinkan override skrip dan tambahkan atribut data-locale dengan kode bahasa yang didukung 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; loader ter-host v16 dalam kode sumber saat ini juga menerapkan perubahan atribut berikutnya. Perubahan rute saja tidak cukup untuk memilih bahasa.
:::
Pengaturan Bahasa Dasbor
Dasbor aplikasi memungkinkan Anda mengonfigurasi preferensi bahasa widget per proyek:
- Deteksi otomatis - Menggunakan bahasa halaman sebelum bahasa browser pengunjung
- Tetap - Menggunakan bahasa default yang dikonfigurasi kecuali
data-localeyang diizinkan menggantikannya - Izinkan override skrip - Mengaktifkan/menonaktifkan penggantian atribut
data-locale
Akses pengaturan ini di Dasbor → proyek → Sesuaikan → Tampilan → Bahasa Widget. Periksa Status penyimpanan bahasa, perbaiki error, atau pilih Coba simpan lagi sebelum menguji.
Pencocokan Bahasa Konten
Untuk pengalaman multibahasa yang berguna, indeks konten publik dalam bahasa pengunjung dan uji sumbernya; deteksi dan pengambilan tidak dijamin. Untuk melakukannya:
- Gunakan file
sitemap.xmluntuk menemukan versi bahasa dokumentasi Anda, lalu verifikasi halaman yang diindeks - Scraper mencoba mendeteksi bahasa halaman; periksa konten dan sitasinya
- 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. Jika pengambilan konfigurasi gagal, UI fallback tidak ditampilkan; jika konfigurasi berhasil tetapi pengambilan terjemahan gagal, label bawaan bahasa Inggris dapat digunakan.
- Periksa
data-locale- Pastikan atribut diatur dengan benar menggunakan kode bahasa yang didukung - Periksa mode proyek dan izin override - Mode Fixed mengabaikan bahasa halaman dan browser, tetapi
data-localeyang didukung tetap berlaku jika override diizinkan.data-localediabaikan jika override dinonaktifkan atau nilainya tidak didukung. - 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 dan permintaan yang didukung - Hanya 14 kode di atas yang memiliki katalog; label yang hilang dapat memakai label bawaan bahasa Inggris jika pengambilan konfigurasi berhasil.
Praktik Terbaik
- Tetapkan
<html lang>di halaman Anda - Membantu aksesibilitas dan deteksi widget - Uji dengan
data-localeselama pengembangan - Pastikan setiap bahasa dirender dengan benar dan override diizinkan - Scrape semua versi bahasa - Gunakan
sitemap.xmluntuk penemuan, lalu verifikasi halaman yang diindeks - Tinjau pertanyaan nyata - Periksa percakapan dan kesenjangan konten khusus bahasa; dasbor saat ini tidak menampilkan distribusi locale widget