Quickstart

Ikhtisar Widget

Aplikasi widget dihosting di widget.companin.tech dan menyediakan cara mudah untuk menyematkan Agen AI Dukungan Pelanggan ke situs web Anda. Untuk memulai, Anda perlu membuat agen dan aplikasi OAuth.

Widget adalah aplikasi ringan, mandiri yang berjalan di iframe terisolasi di situs web Anda. Arsitektur ini memastikan bahwa widget tidak akan bertentangan dengan CSS atau JavaScript yang ada, sambil mempertahankan kinerja dan keamanan yang sangat baik.

1. Buat Agen

Pertama, buat Agen AI Dukungan Pelanggan di dasbor Anda:

Agen Anda adalah otak AI di balik widget. Ia memproses pesan pengguna, mempertahankan konteks percakapan, dan menghasilkan respons cerdas. Setiap agen dapat disesuaikan dengan instruksi spesifik, sifat kepribadian, dan basis pengetahuan untuk mencocokkan kasus penggunaan Anda.

1. Buka dasbor Anda dan navigasikan ke halaman "Sumber Data"
2. Klik tombol "Tambah" di bagian Agen
3. Isi detail agen (nama, deskripsi, nada, dll.)
4. Simpan agen dan catat ID-nya

Tip: Berikan agen Anda instruksi yang jelas dan spesifik tentang perannya dan batasannya. Misalnya: "Anda adalah agen dukungan pelanggan yang membantu untuk produk SaaS. Anda dapat menjawab pertanyaan tentang fitur, harga, dan manajemen akun. Untuk masalah teknis, arahkan pengguna untuk membuat tiket dukungan."

2. Buat Aplikasi OAuth

Buat aplikasi OAuth untuk mengautentikasi widget Anda:

1. Buka halaman "OAuth" di dasbor Anda
2. Klik "Buat Aplikasi"
3. Isi nama dan deskripsi aplikasi
4. Salin client_id dari aplikasi yang dibuat

3. Sematkan Widget melalui Iframe

Cara termudah untuk mengintegrasikan widget adalah dengan menyematkannya langsung menggunakan iframe. Metode ini tidak memerlukan inisialisasi JavaScript dan bekerja langsung. Untuk beberapa iframe di satu halaman, jaga agar setiap sematan terikat pada kontainer dan parameter masing-masing.

<iframe src="https://widget.companin.tech/embed/session?key=YOUR_WIDGET_KEY&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Agent Widget"></iframe>

Ganti YOUR_WIDGET_KEY dengan kunci instal widget Anda (nilai wgt_… — salin dari halaman Widget atau halaman Instal di dasbor). Parameter locale dapat diatur untuk mencocokkan bahasa situs Anda.

Lanjutan: Inisialisasi JavaScript

Metode integrasi yang disarankan adalah menggunakan pemuat widget JavaScript kami, yang menyediakan pengukuran otomatis, manajemen konfigurasi, dan perilaku responsif.

Integrasi Skrip

Tambahkan tag skrip berikut ke halaman HTML Anda:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-instance-id="support-widget"  data-locale="en"  data-theme="system"  async></script>

Atribut Skrip

Setiap atribut memiliki tujuan spesifik dalam mengonfigurasi widget Anda:

• data-widget-key: ID Widget widget Anda - Nilai tunggal yang paling banyak dibutuhkan untuk instalasi. Ini menyelesaikan klien, agen, dan konfigurasi Anda di sisi server, sehingga Anda tidak perlu menempelkannya secara terpisah.

Tiga atribut di bawah ini adalah alternatif lanjutan untuk data-widget-key - gunakan mereka untuk pengaturan multi-instance di mana Anda perlu menargetkan klien, agen, atau konfigurasi tertentu secara eksplisit:

• data-client-id: ID klien OAuth Anda - Ini mengautentikasi aplikasi Anda dengan API kami. Anggap ini sebagai kata sandi aplikasi Anda.
• data-agent-id: UUID agen Anda - Ini mengidentifikasi agen AI Dukungan Pelanggan mana yang menangani percakapan.
• data-config-id: UUID konfigurasi widget Anda - Ini menentukan bagaimana widget Anda terlihat dan berperilaku (warna, ukuran, posisi, dll.).
• data-instance-id: ID instance per-widget yang unik - Diperlukan saat menyematkan beberapa widget di halaman yang sama untuk menghindari tabrakan dan memungkinkan penargetan API per-instance.
• data-custom-css: Dihentikan. Mengatur atribut ini mencatat peringatan konsol dan tidak memiliki efek. Atur custom_css pada konfigurasi widget Anda di dasbor sebagai gantinya — itu dimuat dari konfigurasi dan disuntikkan ke iframe secara otomatis.
• data-locale: Kode bahasa (misalnya, "en", "es", "fr") - Mengatur bahasa tampilan widget. Agen akan tetap merespons dalam bahasa apa pun yang ditulis pengguna.
• data-theme: Mode tema - light, dark, atau system (mengikuti perangkat pengunjung). Memilih palet warna mana (yang dikonfigurasi di dasbor Anda) yang ditampilkan widget. Hilangkan untuk menggunakan default yang disimpan.
• data-dev: Atur ke "true" untuk mode pengembangan (localhost) - Gunakan ini saat menguji secara lokal. Hapus atau atur ke "false" untuk produksi.

Widget akan secara otomatis:

• Mengambil konfigurasi dari ID konfigurasi
• Menyesuaikan diri sesuai dengan dimensi widget dalam konfigurasi
• Menempatkan tombol yang terlipat berdasarkan pengaturan konfigurasi
• Mulai terbuka atau tertutup berdasarkan pengaturan start_open dari konfigurasi.

Catatan

• Widget secara otomatis mengelola ukurannya sendiri berdasarkan pengaturan konfigurasi Anda
• Posisi tombol yang terlipat dapat disesuaikan melalui konfigurasi widget
• Widget menghormati pengaturan start_open dari konfigurasi Anda
• Semua gaya (warna, font, dimensi) dikendalikan melalui konfigurasi widget
• Widget menggunakan komunikasi postMessage untuk perilaku responsif
• Mode pengembangan dapat diaktifkan dengan data-dev="true" untuk pengujian localhost
• Untuk pertukaran token sisi server, gunakan /api/v1/auth/widget-token dan simpan rahasia klien hanya di server Anda.
• Pastikan asal host Anda (misalnya http://localhost:3000) disertakan dalam allowed_origins OAuth saat menyematkan widget dalam iframe.