Güç kullanıcıları için gelişmiş özellikler, özelleştirmeler ve entegrasyonlar.
Widget, programatik kontrol için global CompaninWidget nesnesini açığa çıkarır. Bu, widget'ı uygulamanızın kullanıcı deneyimine derinlemesine entegre etmenizi sağlar ve kullanıcı davranışına veya uygulama durumuna dayalı olarak widget eylemlerini tetikler.
API asenkron olarak yüklenir, bu nedenle yöntemleri çağırmadan önce her zaman var olup olmadığını kontrol edin. Ayrıca, hazır olduğunda özel bir etkinlik dinlemek için de dinleyebilirsiniz.
Bu yöntemler, widget'ın görünürlüğü ve davranışı üzerinde tam programatik kontrol sağlar.
<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>Widget etkinliklerini postMessage API'sini kullanarak dinleyin. Bu, kullanıcı etkileşimini izlemek, widget etkileşimlerine dayalı uygulama mantığını tetiklemek veya widget durumunu uygulamanızla senkronize etmek için mükemmeldir.
Yaygın kullanım durumları:
<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>Yapılandırma arayüzü geniş stil seçenekleri sunsa da, gelişmiş özelleştirmeler için özel CSS ile daha da ileri gidebilirsiniz. Bu, standart yapılandırmada mevcut olmayan benzersiz görsel efektler, animasyonlar veya stillere ihtiyaç duyduğunuzda faydalıdır.
Önemli hususlar:
!important'ı yalnızca gerekli olduğunda kullanın — iframe izolasyonunu geçersiz kılmak içinKonteyner sınıfını kullanarak widget öğelerini hedefleyin. Özel CSS'inizi ya widget yapılandırmasının özel CSS alanında ya da sitenizin global stil sayfasında ekleyin:
/* 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, panonuzda yapılandırılmış iki paletle — Açık ve Koyu — birlikte gelir. Ziyaretçilerin hangi paleti göreceğini data-theme="light|dark|system" script niteliği ile seçin (sistem, cihazlarını takip eder) veya CompaninWidget.setTheme('dark') ile çalışma zamanında değiştirin. Aşağıdaki CSS değişkenleri, ince ayar geçersiz kılmaları için aktif paletin üzerine uygulanır.
CSS özel özellikleri ile gelişmiş tema oluşturma:
: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; } }Kullanıcıların widget'ınızla nasıl etkileşimde bulunduğunu anlamak optimizasyon için kritik öneme sahiptir. Analitik platformunuzla entegre olarak, etkileşim metriklerini izleyebilir, popüler konuları belirleyebilir ve widget'ın kullanıcı deneyimi ve dönüşüm oranları üzerindeki etkisini ölçebilirsiniz.
İzlenecek ana metrikler:
Widget etkileşimlerini Google Analytics'te özel olaylar olarak takip edin. Bu, mevcut analiz kurulumunuzla sorunsuz bir şekilde entegre olur:
// 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; } });Not: Dışa dönük webhook'lar yol haritasında ve henüz genel olarak mevcut değil — bugün panoda webhook URL alanı yok. Aşağıdaki yük şekilleri ve etkinlik adları planlanan tasarımı tanımlar. Bu arada gerçek zamanlı etkinlik işleme için, yukarıdaki Etkinlik Dinleme bölümünde gösterilen sayfa içi postMessage etkinliklerini (örneğin WIDGET_MESSAGE, WIDGET_RESPONSE) kullanın veya API'yi sorgulayın.
Webhook faydaları:
Belirli olaylar gerçekleştiğinde HTTP POST isteklerini almak için gösterge panelinizde webhook URL'lerini yapılandırın. Her webhook yükü, olay verilerini ve meta verileri içerir:
{ "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 - Kullanıcı widget'ı açtıwidget_closed - Kullanıcı widget'ı kapattıconversation_started - Yeni bir konuşma başlatıldımessage_received - Kullanıcı bir mesaj gönderdimessage_sent - Ajan bir mesaj gönderdiflow_triggered - Konuşma akışı etkinleştirildisession_ended - Konuşma oturumu sona erdiÜçüncü taraf içeriği web sitenize yerleştirirken güvenlik çok önemlidir. Widget güvenlik en iyi uygulamalarını takip etse de, entegrasyonunuzu güçlendirmek için alabileceğiniz ek adımlar vardır.
İçerik Güvenliği Politikası başlıkları, XSS saldırılarını ve diğer kod enjeksiyon zafiyetlerini önlemeye yardımcı olur. Widget'ı açıkça izin verecek şekilde CSP'nizi yapılandırın, diğer yerlerde sıkı güvenliği koruyarak:
# 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;Her zaman kullanıcı girdilerini doğrulayın ve temizleyin:
// 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, kutudan çıktığı gibi performans için optimize edilmiştir, ancak özellikle yüksek trafik alanlarında veya daha yavaş bağlantılarda daha hızlı ve daha verimli hale getirmek için stratejiler vardır.
Widget'ı sayfa yüklendiğinde hemen yüklemek yerine, kullanıcı ihtiyaç duyduğunda veya kritik içerik yüklendikten sonra erteleyin. Bu, sayfanızın başlangıç yükleme süresini ve Core Web Vitals puanlarını iyileştirir:
// 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); });Renk seçimlerinizin WCAG yönergelerine uygun olduğundan emin olun: