Fitur canggih, kustomisasi, dan integrasi untuk pengguna tingkat lanjut.
Widget ini mengekspos objek CompaninWidget global untuk kontrol programatik. Ini memungkinkan Anda untuk mengintegrasikan widget secara mendalam ke dalam pengalaman pengguna aplikasi Anda, memicu tindakan widget berdasarkan perilaku pengguna atau status aplikasi.
API dimuat secara asinkron, jadi selalu periksa apakah itu ada sebelum memanggil metode. Anda juga dapat mendengarkan acara kustom saat siap.
Metode ini memberi Anda kontrol programatik penuh atas visibilitas dan perilaku widget.
<script id="companin-widget-script-sales" src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-instance-id="sales-widget"></script> <script> // Ensure the widget has loaded before calling methods window.addEventListener('load', () => { const salesWidget = window.CompaninWidgets?.get('sales-widget') || window.CompaninWidget; if (salesWidget) { salesWidget.show(); salesWidget.sendMessage && salesWidget.sendMessage('Hello from page'); } }); </script>Dengarkan acara widget menggunakan API postMessage. Ini sempurna untuk melacak keterlibatan pengguna, memicu logika aplikasi berdasarkan interaksi widget, atau menyinkronkan status widget dengan aplikasi Anda.
Kasus penggunaan umum:
<script> window.addEventListener('message', (event) => { if (event.origin !== 'https://widget.companin.tech') return; const { type, data } = event.data || {}; switch (type) { case 'WIDGET_INIT_CONFIG': console.log('Widget is ready'); break; case 'WIDGET_SHOW': console.log('Widget was opened'); break; case 'WIDGET_MESSAGE': console.log('User sent message:', data?.message); break; } }); </script>Sementara antarmuka konfigurasi menyediakan opsi gaya yang luas, Anda dapat melangkah lebih jauh dengan CSS kustom untuk kustomisasi canggih. Ini berguna ketika Anda membutuhkan efek visual unik, animasi, atau gaya yang tidak tersedia dalam konfigurasi standar.
Pertimbangan penting:
!important dengan hemat — hanya saat diperlukan untuk menimpa isolasi iframeTarget elemen widget menggunakan kelas kontainer. Tambahkan CSS kustom Anda baik di bidang CSS kustom konfigurasi widget atau di stylesheet global situs Anda:
/* Target the widget container */ .companin-widget-container { /* Custom styles */ } /* Style the collapsed button */ .companin-widget-container button { border-radius: 50% !important; box-shadow: 0 0 20px rgba(0, 0, 0, 0.3) !important; } /* Custom message bubble styles */ .companin-widget-container .message-bubble { background: linear-gradient(45deg, #667eea 0%, #764ba2 100%) !important; } /* Hide the default close button */ .companin-widget-container .close-button { display: none !important; }Widget ini dilengkapi dengan dua palet — Terang dan Gelap — yang dikonfigurasi di dasbor Anda. Pilih mana yang dilihat pengunjung dengan atribut skrip data-theme="light|dark|system" (sistem mengikuti perangkat mereka), atau ganti saat runtime dengan CompaninWidget.setTheme('dark'). Variabel CSS di bawah ini tetap berlaku di atas palet aktif untuk override yang lebih halus.
Tema canggih dengan properti CSS kustom:
:root { /* Override widget theme variables */ --companin-primary: #ff6b6b; --companin-secondary: #4ecdc4; --companin-background: #2d3748; --companin-text: #e2e8f0; --companin-border-radius: 12px; } /* Dark theme variant */ @media (prefers-color-scheme: dark) { :root { --companin-background: #1a202c; --companin-text: #f7fafc; } }Memahami bagaimana pengguna berinteraksi dengan widget Anda sangat penting untuk optimasi. Dengan mengintegrasikan dengan platform analitik Anda, Anda dapat melacak metrik keterlibatan, mengidentifikasi topik populer, dan mengukur dampak widget terhadap pengalaman pengguna dan tingkat konversi.
Metrik kunci untuk dilacak:
Lacak interaksi widget sebagai acara kustom di Google Analytics. Ini terintegrasi dengan mulus dengan pengaturan analitik Anda yang ada:
// Track widget events window.addEventListener('message', (event) => { if (event.origin !== 'https://widget.companin.tech') return; const { type, data } = event.data; switch (type) { case 'WIDGET_SHOW': gtag('event', 'widget_opened', { event_category: 'engagement', event_label: 'chat_widget' }); break; case 'WIDGET_MESSAGE': gtag('event', 'message_sent', { event_category: 'engagement', event_label: data.messageLength > 50 ? 'long_message' : 'short_message' }); break; case 'WIDGET_RESPONSE': gtag('event', 'conversation_started', { event_category: 'engagement', event_label: 'chat_widget' }); break; } });// Custom analytics tracking const trackWidgetEvent = (eventName, properties = {}) => { fetch('/api/analytics/track', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ event: eventName, properties: { widget: 'companin', ...properties } }) }); }; window.addEventListener('message', (event) => { if (event.origin !== 'https://widget.companin.tech') return; const { type, data } = event.data; switch (type) { case 'WIDGET_SHOW': trackWidgetEvent('widget_opened'); break; case 'WIDGET_MESSAGE': trackWidgetEvent('message_sent', { length: data.message?.length || 0 }); break; } });Catatan: Webhook keluar ada di peta jalan dan belum tersedia secara umum — tidak ada bidang URL webhook di dasbor saat ini. Bentuk payload dan nama acara di bawah ini menggambarkan desain yang direncanakan. Untuk penanganan acara waktu nyata sementara, gunakan acara postMessage di halaman (misalnya WIDGET_MESSAGE, WIDGET_RESPONSE) yang ditunjukkan di bagian Mendengarkan Acara di atas, atau polling API.
Manfaat Webhook:
Konfigurasikan URL webhook di dasbor Anda untuk menerima permintaan HTTP POST ketika acara tertentu terjadi. Setiap payload webhook mencakup data acara dan metadata:
{ "event": "message_received", "timestamp": "2024-01-09T10:30:00Z", "data": { "session_id": "sess_123456", "message": { "id": "msg_789", "content": "Hello, I need help", "sender": "user", "timestamp": "2024-01-09T10:30:00Z" }, "metadata": { "user_agent": "Mozilla/5.0...", "ip_address": "192.168.1.1", "locale": "en" } } }widget_opened - Pengguna membuka widgetwidget_closed - Pengguna menutup widgetconversation_started - Percakapan baru dimulaimessage_received - Pengguna mengirim pesanmessage_sent - Agen mengirim pesanflow_triggered - Alur percakapan diaktifkansession_ended - Sesi percakapan berakhirKeamanan adalah hal yang utama saat menyematkan konten pihak ketiga di situs web Anda. Sementara widget mengikuti praktik terbaik keamanan, ada langkah tambahan yang dapat Anda ambil untuk memperkuat integrasi Anda.
Header Kebijakan Keamanan Konten membantu mencegah serangan XSS dan kerentanan injeksi kode lainnya. Konfigurasikan CSP Anda untuk secara eksplisit mengizinkan widget sambil mempertahankan keamanan yang ketat di tempat lain:
# nginx.conf add_header Content-Security-Policy " default-src 'self'; script-src 'self' https://widget.companin.tech; style-src 'self' 'unsafe-inline' https://widget.companin.tech; frame-src https://widget.companin.tech; connect-src 'self' https://app.companin.tech; " always;Selalu validasi dan sanitasi input pengguna:
// Validate message content function validateMessage(message) { if (message.length > 2000) { return { valid: false, error: 'Message too long' }; } const dangerousPatterns = [/<script/i, /javascript:/i, /onw+s*=/i]; for (const pattern of dangerousPatterns) { if (pattern.test(message)) { return { valid: false, error: 'Invalid content' }; } } return { valid: true }; } const validation = validateMessage(userInput); if (!validation.valid) { showError(validation.error); return; }Widget ini dioptimalkan untuk kinerja langsung dari kotak, tetapi ada strategi untuk membuatnya bahkan lebih cepat dan lebih efisien, terutama di situs dengan lalu lintas tinggi atau koneksi yang lebih lambat.
Alih-alih memuat widget segera saat halaman dimuat, tunda hingga pengguna membutuhkannya atau setelah konten kritis dimuat. Ini meningkatkan waktu muat awal halaman Anda dan skor Core Web Vitals:
// Load widget only when needed function loadWidget() { if (window.CompaninWidget) return; // Already loaded const script = document.createElement('script'); script.src = 'https://widget.companin.tech/widget.js'; script.setAttribute('data-widget-key', 'YOUR_WIDGET_KEY'); document.head.appendChild(script); } // Load on user interaction document.addEventListener('click', () => { loadWidget(); }, { once: true }); // Or load after page load window.addEventListener('load', () => { setTimeout(loadWidget, 2000); });Pastikan pilihan warna Anda memenuhi pedoman WCAG: