Geavanceerde functies, aanpassingen en integraties voor power users.
De widget biedt een globaal CompaninWidget-object voor programmatic controle. Dit stelt je in staat om de widget diep in de gebruikerservaring van je applicatie te integreren, en widgetacties te activeren op basis van gebruikersgedrag of de status van de applicatie.
De API wordt asynchroon geladen, dus controleer altijd of deze bestaat voordat je methoden aanroept. Je kunt ook luisteren naar een aangepast evenement wanneer het klaar is.
Deze methoden geven je volledige programmatic controle over de zichtbaarheid en het gedrag van de 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>Luister naar widget-evenementen met behulp van de postMessage API. Dit is perfect voor het volgen van gebruikersbetrokkenheid, het activeren van applicatielogica op basis van widgetinteracties, of het synchroniseren van de widgetstatus met je applicatie.
Veelvoorkomende gebruiksscenario's:
<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>Hoewel de configuratie-interface uitgebreide stylingopties biedt, kun je nog verder gaan met aangepaste CSS voor geavanceerde aanpassingen. Dit is nuttig wanneer je unieke visuele effecten, animaties of stijlen nodig hebt die niet beschikbaar zijn in de standaardconfiguratie.
Belangrijke overwegingen:
!important spaarzaam — alleen wanneer nodig om iframe-isolatie te overschrijvenRicht je op widgetelementen met behulp van de containerklasse. Voeg je aangepaste CSS toe in het aangepaste CSS-veld van de widgetconfiguratie of in de globale stylesheet van je site:
/* 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; }De widget wordt geleverd met twee paletten — Licht en Donker — geconfigureerd in je dashboard. Kies welke bezoekers zien met het data-theme="light|dark|system" scriptattribuut (systeem volgt hun apparaat), of schakel het tijdens runtime met CompaninWidget.setTheme('dark'). De CSS-variabelen hieronder zijn nog steeds van toepassing bovenop de actieve palette voor fijne overschrijvingen.
Geavanceerde thematisering met CSS-aangepaste eigenschappen:
: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; } }Begrijpen hoe gebruikers met je widget omgaan is cruciaal voor optimalisatie. Door te integreren met je analytics-platform, kun je betrokkenheidsmetrics volgen, populaire onderwerpen identificeren en de impact van de widget op gebruikerservaring en conversieratio's meten.
Belangrijke metrics om te volgen:
Volg widgetinteracties als aangepaste evenementen in Google Analytics. Dit integreert naadloos met jouw bestaande analytics-instelling:
// 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; } });Opmerking: Uitgaande webhooks staan op de roadmap en zijn nog niet algemeen beschikbaar — er is momenteel geen webhook-URL-veld in het dashboard. De payloadvormen en evenementnamen hieronder beschrijven het geplande ontwerp. Voor realtime evenementverwerking in de tussentijd, gebruik de in-page postMessage-evenementen (bijv. WIDGET_MESSAGE, WIDGET_RESPONSE) die hierboven in de sectie Evenementluisteren worden weergegeven, of poll de API.
Webhook-voordelen:
Configureer webhook-URL's in jouw dashboard om HTTP POST-aanvragen te ontvangen wanneer specifieke evenementen zich voordoen. Elke webhook-payload bevat evenementgegevens en 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 - Gebruiker opende de widgetwidget_closed - Gebruiker sloot de widgetconversation_started - Nieuwe conversatie gestartmessage_received - Gebruiker stuurde een berichtmessage_sent - Agent stuurde een berichtflow_triggered - Conversatiestroom werd geactiveerdsession_ended - Conversatiesessie beëindigdBeveiliging is van het grootste belang bij het insluiten van inhoud van derden op je website. Hoewel de widget de beste beveiligingspraktijken volgt, zijn er aanvullende stappen die je kunt nemen om je integratie te versterken.
Content Security Policy-headers helpen XSS-aanvallen en andere code-injectievulnerabiliteiten te voorkomen. Configureer je CSP om de widget expliciet toe te staan terwijl je elders strikte beveiliging handhaaft:
# 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;Valideer en saniteer altijd gebruikersinvoer:
// 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; }De widget is geoptimaliseerd voor prestaties direct uit de doos, maar er zijn strategieën om het nog sneller en efficiënter te maken, vooral op drukbezochte sites of langzamere verbindingen.
In plaats van de widget onmiddellijk te laden wanneer de pagina laadt, stel je deze uit totdat de gebruiker deze nodig heeft of nadat kritieke inhoud is geladen. Dit verbetert de initiële laadtijd van je pagina en de Core Web Vitals-scores:
// 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); });Zorg ervoor dat je kleurkeuzes voldoen aan de WCAG-richtlijnen: