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 sparsomt — bare når det er nødvendig for å overstyre iframe-isolasjonMål widgetelementer ved hjelp av 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;}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 engasjementsmetrikker, identifisere populære emner og måle widgetens innvirkning på brukeropplevelsen og konverteringsrater.
Nøkkelmetrikker å spore:
Spor widget-interaksjoner som tilpassede hendelser i Google Analytics. Dette integreres sømløst med din eksisterende analyseoppsett:
// 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; }});Merk: Utgående webhooks er på veikartet og ikke ennå generelt tilgjengelige — 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 - Bruker åpnet widgetenwidget_closed - Bruker lukket widgetenconversation_started - Ny samtale initiertmessage_received - Bruker sendte en meldingmessage_sent - Agent sendte en meldingflow_triggered - Samtaleflow ble aktivertsession_ended - Samtalesesjonen ble avsluttetSikkerhet er avgjørende når du integrerer tredjepartsinnhold på nettstedet ditt. Mens widgeten følger beste sikkerhetspraksis, 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.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;Valider og sanitiser alltid brukerinnganger:
// 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 er optimalisert for ytelse rett ut av boksen, 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 er lastet. Dette forbedrer sidens innledende lastetid og Core Web Vitals-poeng:
// 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);});Sørg for at fargevalgene dine oppfyller WCAG-retningslinjene: