Avanserte funksjoner, tilpasninger og integrasjoner for kraftbrukere.
Widgeten eksponerer et globalt CompaninWidget-objekt for programmatisk kontroll. Dette lar deg integrere widgeten dypt inn i brukeropplevelsen til applikasjonen din, og utløse widgethandlinger basert på brukerens atferd eller applikasjonsstatus.
API-en lastes asynkront, så sjekk alltid om den eksisterer før du kaller metoder. Du kan også lytte etter en tilpasset hendelse når den er klar.
Disse metodene gir deg full programmatisk kontroll over widgetens synlighet og atferd.
<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>Lytt etter widgethendelser ved hjelp av postMessage API. Dette er perfekt for å spore brukerengasjement, utløse applikasjonslogikk basert på widgetinteraksjoner, eller synkronisere widgetstatus med applikasjonen din.
Vanlige bruksområder:
<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>Mens konfigurasjonsgrensesnittet gir omfattende stylingalternativer, kan du gå enda lenger med tilpasset CSS for avanserte tilpasninger. Dette er nyttig når du trenger unike visuelle effekter, animasjoner eller stiler som ikke er tilgjengelige i standardkonfigurasjonen.
Viktige hensyn:
!important sparsommelig — bare når det er nødvendig for å overstyre iframe-isolasjonMål widgetelementer ved å bruke containerklassen. Legg til din tilpassede CSS enten i widgetkonfigurasjonens felt for tilpasset CSS eller i nettstedets globale stilark:
/* 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 leveres med to paletter — Lys og Mørk — konfigurert i dashbordet ditt. Velg hvilken en besøkende ser med data-theme="light|dark|system" skriptattributt (system følger enhetens innstillinger), eller bytt det i sanntid med CompaninWidget.setTheme('dark'). CSS-variablene nedenfor gjelder fortsatt i tillegg til den aktive paletten for finjustering.
Avansert tema med CSS-tilpassede 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; } }Å forstå hvordan brukere interagerer med widgeten din er avgjørende for optimalisering. Ved å integrere med analyseplattformen din kan du spore engasjementsmålinger, identifisere populære emner og måle widgetens innvirkning på brukeropplevelse og konverteringsrater.
Nøkkelmålinger å spore:
Spor widget-interaksjoner som tilpassede hendelser i Google Analytics. Dette integreres sømløst med din eksisterende analyseoppsett:
// 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; } });Merk: Utgående webhooks er på veikartet og ikke ennå generelt tilgjengelig — det er ikke noe webhook-URL-felt i dashbordet i dag. Payload-formene og hendelsesnavnene nedenfor beskriver den planlagte designen. For sanntidshåndtering av hendelser i mellomtiden, bruk de innebygde postMessage-hendelsene (f.eks. WIDGET_MESSAGE, WIDGET_RESPONSE) vist i avsnittet om Hendelseslytting ovenfor, eller spør API-en.
Webhook fordeler:
Konfigurer webhook-URL-er i dashbordet ditt for å motta HTTP POST-forespørsel når spesifikke hendelser skjer. Hver webhook-payload inkluderer hendelsesdata og 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 - Brukeren åpnet widgetenwidget_closed - Brukeren lukket widgetenconversation_started - Ny samtale initiertmessage_received - Brukeren sendte en meldingmessage_sent - Agenten sendte en meldingflow_triggered - Samtaleflyten ble aktivertsession_ended - Samtalesesjonen ble avsluttetSikkerhet er avgjørende når du integrerer tredjepartsinnhold på nettstedet ditt. Mens widgeten følger sikkerhetsbeste praksis, er det ytterligere trinn du kan ta for å styrke integrasjonen din.
Innholdssikkerhetspolicy-hoder bidrar til å forhindre XSS-angrep og andre kodeinjeksjons sårbarheter. Konfigurer CSP-en din for å eksplisitt tillate widgeten mens du opprettholder streng sikkerhet andre steder:
# 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;Valider alltid og sanitiser brukerinnspill:
// 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 er optimalisert for ytelse fra starten av, men det finnes strategier for å gjøre den enda raskere og mer effektiv, spesielt på nettsteder med høy trafikk eller tregere tilkoblinger.
I stedet for å laste widgeten umiddelbart når siden lastes, utsett den til brukeren trenger den eller etter at kritisk innhold har lastet. Dette forbedrer sidens innledende lastetid og Core Web Vitals-poeng:
// 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); });Sørg for at fargevalgene dine møter WCAG-retningslinjene: