Erweiterte Funktionen, Anpassungen und Integrationen für Power-User.
Das Widget stellt ein globales CompaninWidget-Objekt für die programmgesteuerte Steuerung zur Verfügung. Dies ermöglicht es Ihnen, das Widget tief in die Benutzererfahrung Ihrer Anwendung zu integrieren, indem Sie Widget-Aktionen basierend auf dem Benutzerverhalten oder dem Anwendungsstatus auslösen.
Die API wird asynchron geladen, daher sollten Sie immer überprüfen, ob sie existiert, bevor Sie Methoden aufrufen. Sie können auch auf ein benutzerdefiniertes Ereignis hören, wenn es bereit ist.
Diese Methoden geben Ihnen die volle programmgesteuerte Kontrolle über die Sichtbarkeit und das Verhalten des Widgets.
<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>Hören Sie auf Widget-Ereignisse mit der postMessage-API. Dies ist perfekt, um das Benutzerengagement zu verfolgen, Anwendungslogik basierend auf Widget-Interaktionen auszulösen oder den Widget-Zustand mit Ihrer Anwendung zu synchronisieren.
Häufige Anwendungsfälle:
<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>Während die Konfigurationsschnittstelle umfangreiche Styling-Optionen bietet, können Sie mit benutzerdefiniertem CSS für erweiterte Anpassungen noch weiter gehen. Dies ist nützlich, wenn Sie einzigartige visuelle Effekte, Animationen oder Stile benötigen, die in der Standardkonfiguration nicht verfügbar sind.
Wichtige Überlegungen:
!important sparsam — nur wenn nötig, um die Isolation des iFrames zu überschreibenZielen Sie Widget-Elemente mit der Container-Klasse an. Fügen Sie Ihr benutzerdefiniertes CSS entweder im benutzerdefinierten CSS-Feld der Widget-Konfiguration oder in Ihrem globalen Stylesheet hinzu:
/* 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; }Das Widget wird mit zwei Paletten — Hell und Dunkel — geliefert, die in Ihrem Dashboard konfiguriert sind. Wählen Sie, welche die Besucher mit dem data-theme="light|dark|system"-Skriptattribut sehen (System folgt ihrem Gerät), oder wechseln Sie zur Laufzeit mit CompaninWidget.setTheme('dark'). Die folgenden CSS-Variablen gelten weiterhin zusätzlich zur aktiven Palette für feinkörnige Überschreibungen.
Erweiterte Themen mit CSS-Benutzerdefinierten Eigenschaften:
: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; } }Zu verstehen, wie Benutzer mit Ihrem Widget interagieren, ist entscheidend für die Optimierung. Durch die Integration mit Ihrer Analyseplattform können Sie Engagementmetriken verfolgen, beliebte Themen identifizieren und die Auswirkungen des Widgets auf die Benutzererfahrung und die Konversionsraten messen.
Wichtige Metriken zur Verfolgung:
Verfolgen Sie Widget-Interaktionen als benutzerdefinierte Ereignisse in Google Analytics. Dies integriert sich nahtlos in Ihre bestehende Analyseeinrichtung:
// 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; } });Hinweis: Ausgehende Webhooks stehen auf der Roadmap und sind noch nicht allgemein verfügbar — es gibt heute kein Webhook-URL-Feld im Dashboard. Die unten beschriebenen Payload-Formate und Ereignisnamen beschreiben das geplante Design. Für die Echtzeit-Ereignisverarbeitung verwenden Sie in der Zwischenzeit die In-Page-postMessage-Ereignisse (z. B. WIDGET_MESSAGE, WIDGET_RESPONSE), die im Abschnitt Ereignisüberwachung oben gezeigt werden, oder poll die API.
Webhook-Vorteile:
Konfigurieren Sie Webhook-URLs in Ihrem Dashboard, um HTTP-POST-Anfragen zu erhalten, wenn bestimmte Ereignisse auftreten. Jede Webhook-Nutzlast enthält Ereignisdaten und Metadaten:
{ "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 - Benutzer hat das Widget geöffnetwidget_closed - Benutzer hat das Widget geschlossenconversation_started - Neue Konversation initiiertmessage_received - Benutzer hat eine Nachricht gesendetmessage_sent - Agent hat eine Nachricht gesendetflow_triggered - Konversationsfluss wurde aktiviertsession_ended - Konversationssitzung beendetSicherheit ist von größter Bedeutung, wenn Sie Inhalte von Drittanbietern auf Ihrer Website einbetten. Während das Widget die besten Sicherheitspraktiken befolgt, gibt es zusätzliche Schritte, die Sie unternehmen können, um Ihre Integration zu härten.
Content Security Policy-Header helfen, XSS-Angriffe und andere Code-Injektionsanfälligkeiten zu verhindern. Konfigurieren Sie Ihre CSP so, dass das Widget ausdrücklich erlaubt ist, während Sie an anderer Stelle strenge Sicherheit aufrechterhalten:
# 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;Validieren und bereinigen Sie immer Benutzereingaben:
// 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; }Das Widget ist von Haus aus für die Leistung optimiert, aber es gibt Strategien, um es noch schneller und effizienter zu machen, insbesondere auf stark frequentierten Websites oder langsameren Verbindungen.
Anstatt das Widget sofort beim Laden der Seite zu laden, verzögern Sie es, bis der Benutzer es benötigt oder nachdem kritische Inhalte geladen wurden. Dies verbessert die anfängliche Ladezeit Ihrer Seite und die Core Web Vitals-Werte:
// 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); });Stellen Sie sicher, dass Ihre Farbauswahl den WCAG-Richtlinien entspricht: