Geavanceerde functies, aanpassingen en integraties voor power users.
De widget exposeert een globale CompaninWidget object voor programmatic controle. Dit stelt je in staat om de widget diep in de gebruikerservaring van je applicatie te integreren, acties van de widget te triggeren op basis van gebruikersgedrag of applicatiestatus.
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 triggeren van applicatielogica op basis van widgetinteracties, of het synchroniseren van de widgetstatus met je applicatie.
Veelvoorkomende gebruiksgevallen:
<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 widget elementen 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;}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 betrokkenheidsstatistieken volgen, populaire onderwerpen identificeren en de impact van de widget op de gebruikerservaring en conversieratio's meten.
Belangrijke statistieken om te volgen:
Volg widget-interacties als aangepaste evenementen in Google Analytics. Dit integreert naadloos met uw bestaande analytics-instelling:
// 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; }});Opmerking: Uitgaande webhooks staan op de roadmap en zijn nog niet algemeen beschikbaar - er is vandaag 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-pagina postMessage evenementen (bijv. WIDGET_MESSAGE, WIDGET_RESPONSE) die hierboven in de Evenement Luisteren sectie worden getoond, of poll de API.
Webhook voordelen:
Configureer webhook-URL's in uw dashboard om HTTP POST-verzoeken 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_geopend - Gebruiker opende de widgetwidget_geclosed - Gebruiker sloot de widgetgesprek_geopend - Nieuwe conversatie gestartbericht_ontvangen - Gebruiker stuurde een berichtbericht_verzonden - Agent stuurde een berichtflow_geactiveerd - Conversatiestroom werd geactiveerdsessie_einde - 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-injectie kwetsbaarheden te voorkomen. Configureer je CSP om de widget expliciet toe te staan terwijl je strikte beveiliging elders handhaaft:
# 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;Valideer en saniteer altijd gebruikersinvoer:
// 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;}De widget is geoptimaliseerd voor prestaties 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 Core Web Vitals scores:
// 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);});Zorg ervoor dat je kleurkeuzes voldoen aan WCAG-richtlijnen: