Erweiterte Funktionen, Anpassungen und Integrationen für Power-User.
Das Widget stellt ein globales CompaninWidget-Objekt zur programmgesteuerten Steuerung bereit. Dadurch können Sie das Widget tief in die Benutzererfahrung Ihrer Anwendung integrieren und Widget-Aktionen basierend auf dem Benutzerverhalten oder dem Anwendungsstatus auslösen.
Die API wird asynchron geladen. Überprüfen Sie daher immer, ob sie vorhanden ist, bevor Sie Methoden aufrufen. Sie können auch auf ein benutzerdefiniertes Ereignis warten, wenn es bereit ist.
Mit diesen Methoden erhalten Sie die vollständige 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>Lauschen Sie mithilfe der postMessage-API auf Widget-Ereignisse. Dies eignet sich perfekt zum Verfolgen des Benutzerengagements, zum Auslösen der Anwendungslogik basierend auf Widget-Interaktionen oder zum Synchronisieren des Widget-Status mit Ihrer Anwendung.
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 Konfigurationsoberfläche umfangreiche Gestaltungsoptionen 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 es nötig ist, um die Iframe-Isolation außer Kraft zu setzenZielen Sie mit der Containerklasse auf Widget-Elemente ab. Fügen Sie Ihr benutzerdefiniertes CSS entweder im benutzerdefinierten CSS-Feld der Widget-Konfiguration oder im globalen Stylesheet Ihrer Site 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;}Erweitertes Design mit benutzerdefinierten CSS-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; }}Für die Optimierung ist es entscheidend zu verstehen, wie Benutzer mit Ihrem Widget interagieren. Durch die Integration in Ihre Analyseplattform können Sie Engagement-Metriken verfolgen, beliebte Themen identifizieren und die Auswirkungen des Widgets auf Benutzererfahrung und Konversionsraten messen.
Wichtige zu verfolgende Kennzahlen:
Verfolgen Sie Widget-Interaktionen als benutzerdefinierte Ereignisse in Google Analytics. Dies integriert sich nahtlos in Ihre bestehende Analytics-Konfiguration:
// 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; }});Hinweis: Ausgehende Webhooks sind auf der Roadmap und noch nicht allgemein verfügbar – im Dashboard gibt es derzeit kein Webhook-URL-Feld. Die unten aufgeführten Nutzlastformen und Ereignisnamen beschreiben das geplante Design. Für die Ereignisverarbeitung in Echtzeit verwenden Sie in der Zwischenzeit die In-Page-PostMessage-Ereignisse (z. B. WIDGET_MESSAGE, WIDGET_RESPONSE), die oben im Abschnitt „Ereignisüberwachung“ gezeigt werden, oder fragen Sie die API ab.
Vorteile von Webhooks:
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_geöffnet - Der Benutzer hat das Widget geöffnet.widget_geschlossen - Der Benutzer hat das Widget geschlossen.Gespräch begonnen - Neue Unterhaltung gestartetnachricht_empfangen - Benutzer hat eine Nachricht gesendetnachricht_gesendet - Agent hat eine Nachricht gesendetfluss_ausgelöst - Das Gesprächsfluss wurde aktiviert.Sitzung_beendet - Gesprächssitzung beendetBei der Einbettung von Inhalten Dritter auf Ihrer Website steht die Sicherheit an erster Stelle. Während das Widget bewährte Sicherheitspraktiken befolgt, können Sie zusätzliche Schritte unternehmen, um Ihre Integration zu stärken.
Header der Inhaltssicherheitsrichtlinie tragen dazu bei, XSS-Angriffe und andere Sicherheitslücken durch Codeeinschleusung zu verhindern. Konfigurieren Sie Ihren CSP so, dass er das Widget explizit zulässt und an anderer Stelle strenge Sicherheit gewährleistet:
# 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;Überprüfen und bereinigen Sie Benutzereingaben stets:
// 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;}Das Widget ist standardmäßig auf Leistung optimiert, es gibt jedoch 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, verschieben 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-Ergebnisse:
// 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);});Stellen Sie sicher, dass Ihre Farbauswahl den WCAG-Richtlinien entspricht: