Lewati ke konten utama

Integrasikan dengan Asisten Coding AI

Integrasi kode aplikasi yang direkomendasikan adalah paket npm @openstaticfish/chattybox. Paket ini memungkinkan kode aplikasi mengonfigurasi kunci publik dan URL API, memuat widget mengambang terkelola ChattyBox dari layout browser yang persisten, atau menggunakan klien headless untuk UI yang sepenuhnya khusus.

Skrip mandiri widget.js didokumentasikan terakhir sebagai fallback tanpa build untuk situs yang tidak dapat memasang paket npm.

Sebelum Memulai​

Selesaikan penyiapan chatbot sebelum meminta asisten mengedit aplikasi Anda:

  • Verifikasi jawaban dan sitasi yang representatif di Uji chatbot.
  • Di Pasang → Kunci & domain, periksa atau buat kunci browser publik dan periksa pengaturan origin-nya. Kunci yang disiapkan untuk situs web mungkin sudah dibatasi; kunci tanpa pembatasan berfungsi dari semua origin. Pembatasan origin adalah penguatan keamanan opsional, bukan autentikasi pengunjung.
  • Di Pasang → Instalasi situs web, pilih kunci yang sesuai dan salin cuplikan kodenya. Gunakan data-api-url jika tersedia; jika tidak, dapatkan endpoint HTTP widget yang benar dari konfigurasi deployment sebelum integrasi.
  • Tentukan apakah widget mengambang persisten sesuai untuk aplikasi atau Anda memerlukan UI khusus dengan penempatan serta teardown per rute.

Ini adalah kredensial browser publik, tetapi Anda tetap harus menghindari commit nilai khusus lingkungan. Jangan pernah memberikan token deployment konfigurasi, kredensial admin, atau file lingkungan yang tidak terkait.

Direkomendasikan: Pasang UI Terkelola dari npm​

Ini adalah prompt default untuk React, Next.js, Vite, dan aplikasi browser berbasis paket lainnya.

Instruksi
Integrasikan paket npm ChattyBox

Integrasikan ChattyBox ke dalam aplikasi ini menggunakan paket npm @openstaticfish/chattybox.

Konfigurasi browser publik:
- Kunci API: [PASTE PUBLIC WIDGET KEY]
- URL API: [PASTE WIDGET API URL]

Gunakan label dashboard saat ini: **Uji chatbot**; **Pasang → Kunci & domain** untuk memeriksa atau membuat kunci dan pengaturan origin-nya; **Pasang → Instalasi situs web** untuk cuplikan instalasi. Pembatasan origin adalah penguatan keamanan opsional, bukan autentikasi pengunjung, dan kunci yang disiapkan untuk situs web mungkin sudah dibatasi. Jangan pernah memberikan token deployment konfigurasi, kredensial admin, atau file lingkungan privat.

Pertama, periksa framework, model routing, package manager, konvensi variabel lingkungan, dan layout aplikasi yang persisten. Beri tahu saya file yang akan Anda ubah sebelum mengedit. Tanyakan kepada saya jika rute tempat ChattyBox harus muncul tidak jelas.

Persyaratan:
1. Instal @openstaticfish/chattybox dengan package manager yang sudah digunakan repositori ini.
2. Simpan kunci API publik dan URL API menggunakan konvensi variabel lingkungan yang diekspos ke browser oleh framework. Tambahkan nama placeholder ke file lingkungan contoh, tetapi jangan commit nilai nyata.
3. Impor Chattybox dari @openstaticfish/chattybox dan buat satu klien dengan apiKey dan baseUrl.
4. Panggil `client.mountWidget()` hanya dalam kode browser setelah `document.body` tersedia, dari shell aplikasi yang persisten. Widget mengambang dimuat di bawah `document.body`, bukan di dalam komponen.
5. Pertahankan loader selama navigasi SPA yang diizinkan. SDK `0.1.4` yang dipublikasikan hanya berbagi skrip milik SDK dengan opsi mount yang identik; `mountWidget()` menolak kunci, URL API, scriptUrl, locale, atau opsi debug yang berubah selama masih ada handle. Panggil `remove()` pada setiap handle yang dikembalikan untuk teardown yang disengaja. Dalam kode sumber saat ini, pada hosted `widget.js` v16, handle terakhir menghapus UI/gaya widget dan membatalkan inisialisasi tertunda, percobaan ulang, serta chat yang sedang berlangsung; `window.ChattyBox.destroy()` adalah cara setara untuk widget ter-host. Pastikan versi loader yang di-deploy mendukung teardown sebelum mengandalkannya; menyembunyikan UI atau hanya menghapus tag skrip tidak cukup. Jangan memuatnya sebelum persetujuan yang diwajibkan atau pada rute sensitif/privat; lakukan teardown aktif saat rute dikecualikan atau persetujuan dicabut. Pembersihan tidak dapat membatalkan permintaan yang sudah diproses server.
6. Jangan menyisipkan `widget.js` secara manual, membuat proxy backend, atau menambahkan loader kedua. `mountWidget()` hanya berbagi mount milik SDK dengan opsi identik; kunci, URL API, scriptUrl, locale, atau opsi debug yang berubah akan ditolak sampai semua handle yang ada dihapus. Opsi lama tidak pernah dipertahankan diam-diam.
7. Pertahankan navigasi, batas rendering, lokalisasi, analitik, persetujuan, dan styling yang ada. SDK tidak memiliki API locale reaktif atau ready promise; opsi locale SDK mengikuti kebijakan override skrip proyek. Widget ter-host dalam kode sumber saat ini, `widget.js` v16, dapat memperbarui label milik produk saat locale yang ditentukan berubah; pastikan versi loader yang di-deploy dan kebijakan locale proyek sebelum mengandalkan perilaku ini. Widget ter-host dalam kode sumber saat ini, `widget.js` v16, menjadwalkan paling banyak 10 percobaan chat dalam jendela penjadwalan retry 30 detik; ini bukan batas waktu keras untuk permintaan yang sedang berlangsung. Verifikasi versi loader yang di-deploy sebelum mengandalkan perilaku retry widget ini. `sendMessage()` headless tidak mencoba ulang otomatis; `getWidgetConfig()` SDK secara terpisah melakukan satu percobaan fallback setelah HTTP 400. Retry GET saat startup widget ter-host adalah mekanisme terpisah dari retry chat ini. SDK memvalidasi `baseUrl` dan menangani isi respons yang tidak dapat dibaca.
8. Buat perubahan terfokus sekecil mungkin dan jangan melakukan deployment.
9. Jalankan build, lint, type-check, dan tes yang relevan dari repositori.
10. Laporkan file yang diubah, variabel lingkungan yang harus saya atur, lokasi UI dipasang, dan cara mengujinya di situs yang di-deploy.

Berikut contoh callback siklus hidup browser, bukan pemanggilan tingkat atas saat server-side rendering. Panggil hanya setelah document.body tersedia dan simpan handle-nya untuk teardown yang disengaja:

import { Chattybox } from '@openstaticfish/chattybox';

const client = new Chattybox({
  apiKey: PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: PUBLIC_CHATTYBOX_API_URL,
});

function mountInBrowser() {
  if (typeof document === 'undefined' || !document.body) return;
  return client.mountWidget();
}

// Simpan handle yang dikembalikan untuk navigasi yang diizinkan dan teardown yang disengaja.

Bangun Antarmuka Khusus​

Pilih ini jika aplikasi Anda harus memiliki daftar pesan, input, state pemuatan, error, sitasi, dan penempatan sendiri alih-alih memasang antarmuka terkelola.

Instruksi
Bangun antarmuka ChattyBox headless

Bangun antarmuka chatbot khusus menggunakan paket npm @openstaticfish/chattybox dan klien headless-nya.

Konfigurasi browser publik:
- Kunci API: [PASTE PUBLIC WIDGET KEY]
- URL API: [PASTE WIDGET API URL]

Gunakan label dashboard saat ini: **Uji chatbot**; **Pasang → Kunci & domain** untuk memeriksa kunci dan pengaturan origin-nya; **Pasang → Instalasi situs web** untuk cuplikan instalasi. Pembatasan origin adalah penguatan keamanan opsional, bukan autentikasi pengunjung, dan kunci yang disiapkan untuk situs web mungkin sudah dibatasi. Jangan pernah memberikan token deployment konfigurasi, kredensial admin, atau file lingkungan privat.

Pertama, periksa framework aplikasi, sistem komponen, pola state, styling, konvensi aksesibilitas, dan penyiapan tes. Usulkan batas komponen dan file sebelum mengedit.

Persyaratan:
1. Instal @openstaticfish/chattybox dengan package manager yang sudah digunakan repositori.
2. Konfigurasikan satu klien Chattybox dengan apiKey dan baseUrl menggunakan variabel lingkungan yang diekspos ke browser; jangan commit nilai nyata.
3. Gunakan `sendMessage()` dan simpan `conversationId` dalam state yang terbatas pada pengunjung dan sesi; reset ID saat pengguna atau sesi berubah. Jangan pernah membagikan ID di antara pengunjung yang tidak berkaitan. Model menerima hingga 12 pesan terbaru yang tersimpan, masing-masing dipotong hingga 2.000 karakter, bukan seluruh transkrip atau memori permanen. Kunci publik, pembatasan origin, dan ID percakapan tidak mengautentikasi pengunjung atau melindungi percakapan privat. Hindari informasi sensitif: pesan dapat disimpan dan dilihat pemilik proyek; mengosongkan state lokal tidak menghapus catatan di server.
4. Render jawaban dengan aman sebagai teks atau Markdown yang disanitasi, serta render sumber HTTP(S) sebagai tautan yang aksesibel sambil mempertahankan urutannya. Jangan pernah menyisipkan HTML mentah yang tidak tepercaya atau skema tautan yang tidak aman.
5. Implementasikan state pending, kosong, error, dan retry. Jawaban fallback dapat memiliki sumber kosong; tidak ada flag umum `wasAnswered`. Jika backend memberikan `providerError`, persempit tipenya dengan aman sebagai field opsional dan tampilkan kegagalan provider generik, bukan jawaban normal. Jangan mengulang secara membabi buta respons berkunci yang sudah selesai. SDK `0.1.4` yang dipublikasikan mungkin tidak mengetik field respons dari kode sumber saat ini, jadi toleransi jika field tersebut tidak ada. `productFallback` dan `providerError` bersifat opsional; jangan mengarang field status fallback umum. Tangani ChattyboxError dan error jaringan yang tidak dibungkus; code bersifat opsional.
6. Tolak pesan yang kosong atau lebih dari 2.000 karakter setelah trim, cegah pengiriman duplikat, dan pastikan penggunaan keyboard serta pembaca layar tetap mudah. `sendMessage()` headless tidak mencoba ulang otomatis: gunakan satu `idempotencyKey` unik per pesan logis dan gunakan kembali input yang persis sama saat retry; jangan mencoba ulang secara membabi buta untuk setiap HTTP 409. SDK `0.1.4` secara terpisah hanya mencoba ulang `getWidgetConfig()` sekali setelah HTTP 400; retry GET saat startup widget ter-host adalah mekanisme terpisah.
7. Pasang antarmuka hanya pada rute atau layout yang saya tentukan.
8. Ikuti komponen dan gaya yang ada alih-alih menambahkan sistem desain baru.
9. Jangan memuat widget.js atau memanggil mountWidget().
10. Jalankan build, lint, type-check, dan tes yang relevan, lalu laporkan file yang diubah serta rencana verifikasi.

Catatan Framework​

Berikan satu kalimat tambahan kepada asisten bila diperlukan:

  • Next.js App Router: “Gunakan Client Component kecil dalam layout persisten dan panggil mountWidget() dari effect khusus browser, bukan saat rendering.”
  • React SPA: “Pasang dari app shell persisten. Jika komponen memiliki handle SDK, kembalikan remove() sebagai cleanup untuk setiap handle saat teardown yang disengaja; jika tidak, pertahankan loader bersama selama perubahan rute yang diizinkan.”
  • Docusaurus: “Inisialisasi dari src/theme/Root dalam kode browser dan pertahankan loader selama navigasi dokumentasi yang diizinkan. Verifikasi versi loader ter-host yang di-deploy serta perilaku locale sebelum mengandalkan pembaruan bahasa sisi klien; perubahan konfigurasi dashboard tetap memerlukan inisialisasi ulang.”
  • Vue, Nuxt, Svelte, atau framework lain: “Gunakan lifecycle pemasangan khusus klien dalam layout persisten; pilih UI headless jika memerlukan teardown yang sesuai.”

Tinjau Integrasi SDK yang Sudah Ada​

Instruksi
Tinjau integrasi SDK ChattyBox saya

Tinjau integrasi ChattyBox ini tanpa melakukan deployment atau mengubah kode yang tidak terkait.

Periksa bahwa:
1. @openstaticfish/chattybox terpasang dan diimpor, bukan perilakunya diduplikasi.
2. Satu klien Chattybox menerima kunci API publik dan URL API yang dimaksud.
3. Variabel lingkungan browser mengikuti aturan penamaan variabel publik framework ini tanpa mengekspos kredensial privat.
4. Widget ter-host menggunakan shell persisten dan melakukan teardown aktif dengan `remove()`/`window.ChattyBox.destroy()` saat rute SPA dikecualikan atau persetujuan dicabut; jangan memuatnya pada rute sensitif/privat atau sebelum persetujuan yang diwajibkan. Menyembunyikan UI atau hanya menghapus tag skrip tidak cukup, dan permintaan yang sudah diproses server tidak dapat dibatalkan. Antarmuka khusus memiliki cleanup komponen yang nyata.
5. Navigasi sisi klien dan remount saat pengembangan tidak membuat instance duplikat.
6. Batas rendering, lokalisasi, analitik, persetujuan, aksesibilitas, dan layout yang ada tetap utuh. Jalur dashboard saat ini adalah **Pasang → Kunci & domain** dan **Pasang → Instalasi situs web**. Pembatasan origin adalah penguatan keamanan opsional, bukan autentikasi pengunjung; kunci yang disiapkan untuk situs web mungkin sudah dibatasi. Kunci yang dibatasi memerlukan origin permintaan yang diizinkan, dan fetch Node tidak otomatis mengirim header Origin/Referer browser. Jangan pernah mengekspos rahasia admin atau token deployment konfigurasi.
7. Implementasi memiliki tes yang sesuai dan tidak ada refaktor yang tidak terkait.

Kembalikan temuan berdasarkan tingkat keparahan dengan jalur file dan referensi baris. Usulkan hanya perbaikan aman terkecil dan berikan perintah verifikasi yang tepat.

Tidak Ada npm atau Proses Build?​

Gunakan panduan instalasi widget.js hanya jika situs tidak dapat menggunakan paket npm—misalnya HTML biasa, kolom kode kustom CMS, atau Google Tag Manager.

Instruksi
Pasang skrip widget fallback

Pasang widget ChattyBox ter-host di situs ini menggunakan skrip persis yang dibuat oleh tampilan **Pasang → Instalasi situs web** ChattyBox. Periksa kunci browser publik dan pengaturan origin-nya di **Pasang → Kunci & domain**. Pembatasan origin adalah penguatan keamanan opsional, bukan autentikasi pengunjung, dan kunci yang disiapkan untuk situs web mungkin sudah dibatasi. Jangan pernah menyertakan token deployment konfigurasi, kredensial admin, atau file lingkungan privat:

[PASTE COMPLETE WIDGET SCRIPT]

Periksa situs terlebih dahulu dan identifikasi titik penyisipan paling aman untuk halaman publik. Muat skrip tanpa perubahan tepat satu kali dan hanya setelah persetujuan yang diwajibkan diberikan; kecualikan rute privat/admin/checkout. Saat rute SPA berubah atau persetujuan dicabut, lakukan teardown aktif pada widget yang sudah diinisialisasi sebelum memasuki status yang dikecualikan, dan inisialisasi ulang hanya jika diizinkan. Pastikan versi loader yang di-deploy mendukung teardown; menyembunyikan UI atau hanya menghapus tag skrip tidak cukup, dan teardown tidak dapat membatalkan permintaan yang sudah diproses. Pertahankan perilaku CSP, jangan mengekspos kredensial privat, rahasia admin, atau token deployment konfigurasi, jangan deploy perubahan, dan laporkan lokasi yang diubah beserta rencana pengujian browser.

Uji Hasilnya​

  1. Tinjau diff dan pastikan tidak ada kredensial nyata yang di-commit.
  2. Jalankan build, lint, type-check, dan tes normal proyek.
  3. Lakukan deployment melalui proses peninjauan normal.
  4. Verifikasi rute yang dituju di jendela browser privat, termasuk navigasi sisi klien.
  5. Ajukan pertanyaan yang didukung, ikuti sitasi, dan uji perilaku fallback.
  6. Periksa tata letak seluler, penggunaan keyboard, dan konsol browser.

Lanjutkan dengan referensi SDK dan daftar periksa peluncuran.