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, och 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 finns i den standardkonfigurationen.
Viktiga överväganden:
!important sparsamt - endast när det är nödvändigt för att överskrida iframe-isoleringRikta 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;}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 inverkan 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 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; }});Obs: Utgående webhooks finns på vägkartan och är ä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 om Händelselyssning ovan, eller poll API:et.
Webhook-fördelar:
Konfigurera webhook-URL:er i din instrumentpanel för att ta emot HTTP POST-förfrågningar när specifika händelser inträffar. Varje webhookpayload 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_öppnad - Användaren öppnade widgetenwidget_stängd - Användaren stängde widgetenkonversation_startad - Ny konversation initieradmeddelande_mottaget - Användaren skickade ett meddelandemeddelande_skickat - Agenten skickade ett meddelandeflöde_aktiverat - Konversationsflödet aktiveradessession_avslutad - 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.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;Validera och sanera alltid användarinmatningar:
// 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;}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 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);});Se till att dina färgval uppfyller WCAG-riktlinjer: