Avancerade funktioner, anpassningar och integrationer för kraftanvändare.
Widgeten exponerar ett globalt CompaninWidget-objekt för programmatisk kontroll. Detta gör att du kan integrera widgeten djupt i din applikations användarupplevelse, utlösa widgetåtgärder baserat på användarbeteende eller applikationstillstånd.
API:et laddas asynkront, så kontrollera alltid om det finns innan du anropar metoder. Du kan också lyssna efter en anpassad händelse när det är klart.
Dessa metoder ger dig full programmatisk kontroll över widgetens synlighet och beteende.
<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>Lyssna efter widgethändelser med hjälp av postMessage API. Detta är perfekt för att spåra användarengagemang, utlösa applikationslogik baserat på widgetinteraktioner eller synkronisera widgetens tillstånd med din applikation.
Vanliga användningsfall:
<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>Även om konfigurationsgränssnittet erbjuder omfattande stilalternativ kan du gå ännu längre med anpassad CSS för avancerade anpassningar. Detta är användbart när du behöver unika visuella effekter, animationer eller stilar som inte är tillgängliga i den standardkonfigurationen.
Viktiga överväganden:
!important sparsamt — endast när det är nödvändigt för att överskrida iframe-isoleringRikta in dig på widgetelement med hjälp av containerklassen. Lägg till din anpassade CSS antingen i widgetkonfigurationens fält för anpassad CSS eller i din webbplats globala stilmall:
/* 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; }Widgeten levereras med två paletter — Ljus och Mörk — konfigurerade i din instrumentpanel. Välj vilken som besökare ser med data-theme="light|dark|system" skriptattribut (system följer deras enhet), eller byt det vid körning med CompaninWidget.setTheme('dark'). CSS-variablerna nedan gäller fortfarande ovanpå den aktiva paletten för finjusterade överskrivningar.
Avancerad tematisering med CSS-anpassade egenskaper:
: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; } }Att förstå hur användare interagerar med din widget är avgörande för optimering. Genom att integrera med din analysplattform kan du spåra engagemangsmått, identifiera populära ämnen och mäta widgetens påverkan på användarupplevelsen och konverteringsgraden.
Nyckelmått att spåra:
Spåra widgetinteraktioner som anpassade händelser i Google Analytics. Detta integreras sömlöst med din befintliga analysuppsättning:
// 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; } });Obs: Utgående webhooks är på väg och ännu inte allmänt tillgängliga — det finns inget webhook-URL-fält i instrumentpanelen idag. Payloadformerna och händelsenamnen nedan beskriver den planerade designen. För realtids händelsehantering under tiden, använd in-page postMessage-händelser (t.ex. WIDGET_MESSAGE, WIDGET_RESPONSE) som visas i avsnittet Händelselyssning ovan, eller poll API:et.
Webhook-fördelar:
Konfigurera webhook-URL:er i din instrumentpanel för att ta emot HTTP POST-begärningar när specifika händelser inträffar. Varje webhook-payload inkluderar händelsedata och 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 - Användaren öppnade widgetenwidget_closed - Användaren stängde widgetenconversation_started - Ny konversation initieradmessage_received - Användaren skickade ett meddelandemessage_sent - Agenten skickade ett meddelandeflow_triggered - Konversationsflödet aktiveradessession_ended - Konversationssessionen avslutadesSäkerhet är avgörande när du bäddar in tredjepartsinnehåll på din webbplats. Även om widgeten följer säkerhetsbästa praxis finns det ytterligare steg du kan ta för att stärka din integration.
Innehållssäkerhetspolicyhuvuden hjälper till att förhindra XSS-attacker och andra kodinjektionssårbarheter. Konfigurera din CSP för att uttryckligen tillåta widgeten samtidigt som du upprätthåller strikt säkerhet på andra ställen:
# 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;Validera alltid och sanera användarinmatningar:
// 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; }Widgeten är optimerad för prestanda direkt ur lådan, men det finns strategier för att göra den ännu snabbare och mer effektiv, särskilt på högtrafikerade webbplatser eller långsammare anslutningar.
Istället för att ladda widgeten omedelbart när sidan laddas, skjuta upp den tills användaren behöver den eller efter att kritiskt innehåll har laddats. Detta förbättrar sidans initiala laddningstid och Core Web Vitals-poäng:
// 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); });Se till att dina färgval uppfyller WCAG-riktlinjer: