Funzionalità avanzate, personalizzazioni e integrazioni per utenti esperti.
Il widget espone un oggetto CompaninWidget globale per il controllo programmatico. Questo ti consente di integrare profondamente il widget nell'esperienza utente della tua applicazione, attivando azioni del widget in base al comportamento dell'utente o allo stato dell'applicazione.
L'API viene caricata in modo asincrono, quindi controlla sempre se esiste prima di chiamare i metodi. Puoi anche ascoltare un evento personalizzato quando è pronto.
Questi metodi ti danno il pieno controllo programmatico sulla visibilità e sul comportamento del 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>Ascolta gli eventi del widget utilizzando l'API postMessage. Questo è perfetto per tracciare il coinvolgimento degli utenti, attivare la logica dell'applicazione in base alle interazioni del widget o sincronizzare lo stato del widget con la tua applicazione.
Casi d'uso comuni:
<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>Sebbene l'interfaccia di configurazione fornisca ampie opzioni di stile, puoi andare ancora oltre con CSS personalizzato per personalizzazioni avanzate. Questo è utile quando hai bisogno di effetti visivi unici, animazioni o stili che non sono disponibili nella configurazione standard.
Considerazioni importanti:
!important con parsimonia—solo quando necessario per sovrascrivere l'isolamento dell'iframeTargetizza gli elementi del widget utilizzando la classe contenitore. Aggiungi il tuo CSS personalizzato nel campo CSS personalizzato della configurazione del widget o nel foglio di stile globale del tuo sito:
/* 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;}Tematizzazione avanzata con proprietà CSS personalizzate:
: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; }}Comprendere come gli utenti interagiscono con il tuo widget è fondamentale per l'ottimizzazione. Integrando con la tua piattaforma analitica, puoi tracciare metriche di coinvolgimento, identificare argomenti popolari e misurare l'impatto del widget sull'esperienza utente e sui tassi di conversione.
Metriche chiave da tracciare:
Traccia le interazioni del widget come eventi personalizzati in Google Analytics. Questo si integra perfettamente con la tua configurazione di analisi esistente:
// Track widget eventswindow.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 trackingconst 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; }});Nota: I webhook in uscita sono nella roadmap e non sono ancora generalmente disponibili — non c'è campo URL webhook nel dashboard oggi. Le forme del payload e i nomi degli eventi di seguito descrivono il design pianificato. Per la gestione degli eventi in tempo reale nel frattempo, utilizza gli eventi postMessage in pagina (ad es. WIDGET_MESSAGE, WIDGET_RESPONSE) mostrati nella sezione Ascolto degli eventi sopra, o interroga l'API.
Vantaggi dei webhook:
Configura gli URL dei webhook nel tuo dashboard per ricevere richieste HTTP POST quando si verificano eventi specifici. Ogni payload del webhook include dati sugli eventi e metadati:
{ "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_aperto - L'utente ha aperto il widgetwidget_chiuso - L'utente ha chiuso il widgetconversazione_iniziata - Nuova conversazione avviatamessaggio_ricevuto - L'utente ha inviato un messaggiomessaggio_inviato - L'agente ha inviato un messaggioflusso_attivato - Il flusso di conversazione è stato attivatosessione_terminata - La sessione di conversazione è terminataLa sicurezza è fondamentale quando si incorpora contenuti di terze parti sul tuo sito web. Sebbene il widget segua le migliori pratiche di sicurezza, ci sono ulteriori passaggi che puoi intraprendere per rafforzare la tua integrazione.
Le intestazioni della Politica di sicurezza dei contenuti aiutano a prevenire attacchi XSS e altre vulnerabilità di iniezione di codice. Configura la tua CSP per consentire esplicitamente il widget mantenendo una sicurezza rigorosa altrove:
# nginx.confadd_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;Valida e sanitizza sempre gli input degli utenti:
// Validate message contentfunction 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;}Il widget è ottimizzato per le prestazioni fin da subito, ma ci sono strategie per renderlo ancora più veloce ed efficiente, specialmente su siti ad alto traffico o connessioni più lente.
Invece di caricare il widget immediatamente quando la pagina si carica, rimandalo fino a quando l'utente ne ha bisogno o dopo che il contenuto critico è stato caricato. Questo migliora il tempo di caricamento iniziale della tua pagina e i punteggi Core Web Vitals:
// Load widget only when neededfunction 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 interactiondocument.addEventListener('click', () => { loadWidget();}, { once: true });// Or load after page loadwindow.addEventListener('load', () => { setTimeout(loadWidget, 2000);});Assicurati che le tue scelte di colore soddisfino le linee guida WCAG: