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 offrono 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 monitorare il coinvolgimento degli utenti, attivare la logica dell'applicazione in base alle interazioni con il 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 personalizzati per personalizzazioni avanzate. Questo è utile quando hai bisogno di effetti visivi unici, animazioni o stili non 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 sia nel campo CSS personalizzato della configurazione del widget che 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; }Il widget viene fornito con due palette — Chiaro e Scuro — configurate nel tuo cruscotto. Scegli quale vedono i visitatori con l'attributo script data-theme="light|dark|system" (il sistema segue il loro dispositivo), oppure cambialo a runtime con CompaninWidget.setTheme('dark'). Le variabili CSS qui sotto si applicano comunque sopra la palette attiva per sovrascritture dettagliate.
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 di analytics, puoi monitorare le metriche di coinvolgimento, identificare argomenti popolari e misurare l'impatto del widget sull'esperienza utente e sui tassi di conversione.
Metriche chiave da monitorare:
Monitora le interazioni del widget come eventi personalizzati in Google Analytics. Questo si integra perfettamente con la tua configurazione di analisi esistente:
// 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; } });Nota: I webhook in uscita sono nella roadmap e non ancora generalmente disponibili — non c'è campo URL webhook nel cruscotto oggi. Le forme del payload e i nomi degli eventi qui sotto 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 nella tua dashboard per ricevere richieste HTTP POST quando si verificano eventi specifici. Ogni payload del webhook include dati e metadati dell'evento:
{ "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 - L'utente ha aperto il widgetwidget_closed - L'utente ha chiuso il widgetconversation_started - Nuova conversazione avviatamessage_received - L'utente ha inviato un messaggiomessage_sent - L'agente ha inviato un messaggioflow_triggered - Il flusso della conversazione è stato attivatosession_ended - 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 rigorosa sicurezza altrove:
# 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;Valida e sanitizza sempre gli input degli utenti:
// 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; }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 immediatamente il widget 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 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); });Assicurati che le tue scelte di colore soddisfino le linee guida WCAG: