Fonctionnalités avancées, personnalisations et intégrations pour les utilisateurs avancés.
Le widget expose un objet CompaninWidget global pour le contrôle programmatique. Cela vous permet d'intégrer le widget profondément dans l'expérience utilisateur de votre application, en déclenchant des actions de widget en fonction du comportement de l'utilisateur ou de l'état de l'application.
L'API est chargée de manière asynchrone, donc vérifiez toujours si elle existe avant d'appeler des méthodes. Vous pouvez également écouter un événement personnalisé lorsqu'il est prêt.
Ces méthodes vous donnent un contrôle programmatique total sur la visibilité et le comportement du widget.
<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>Écoutez les événements du widget en utilisant l'API postMessage. C'est parfait pour suivre l'engagement des utilisateurs, déclencher la logique de l'application en fonction des interactions avec le widget, ou synchroniser l'état du widget avec votre application.
Cas d'utilisation courants :
<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>Bien que l'interface de configuration offre d'amples options de style, vous pouvez aller encore plus loin avec du CSS personnalisé pour des personnalisations avancées. Cela est utile lorsque vous avez besoin d'effets visuels uniques, d'animations ou de styles qui ne sont pas disponibles dans la configuration standard.
Considérations importantes :
!important avec parcimonie — uniquement lorsque nécessaire pour remplacer l'isolation iframeCiblez les éléments du widget en utilisant la classe conteneur. Ajoutez votre CSS personnalisé soit dans le champ CSS personnalisé de la configuration du widget, soit dans la feuille de style globale de votre site :
/* 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;}Thématisation avancée avec des propriétés CSS personnalisées :
: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; }}Comprendre comment les utilisateurs interagissent avec votre widget est crucial pour l'optimisation. En intégrant votre plateforme d'analytique, vous pouvez suivre les métriques d'engagement, identifier les sujets populaires et mesurer l'impact du widget sur l'expérience utilisateur et les taux de conversion.
Métriques clés à suivre :
Suivez les interactions du widget en tant qu'événements personnalisés dans Google Analytics. Cela s'intègre parfaitement à votre configuration d'analyse existante :
// 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; }});Remarque : Les webhooks sortants sont sur la feuille de route et ne sont pas encore généralement disponibles — il n'y a pas de champ d'URL de webhook dans le tableau de bord aujourd'hui. Les formes de charge utile et les noms d'événements ci-dessous décrivent le design prévu. Pour le traitement des événements en temps réel en attendant, utilisez les événements postMessage en page (par exemple, WIDGET_MESSAGE, WIDGET_RESPONSE) montrés dans la section Écoute d'événements ci-dessus, ou interrogez l'API.
Avantages des webhooks :
Configurez les URL de webhook dans votre tableau de bord pour recevoir des requêtes HTTP POST lorsque des événements spécifiques se produisent. Chaque charge utile de webhook comprend des données d'événements et des métadonnées :
{ "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_ouvert - L'utilisateur a ouvert le widgetwidget_fermé - L'utilisateur a fermé le widgetconversation_démarrée - Nouvelle conversation initiéemessage_reçu - L'utilisateur a envoyé un messagemessage_envoyé - L'agent a envoyé un messageflux_déclenché - Le flux de conversation a été activésession_terminée - La session de conversation est terminéeLa sécurité est primordiale lors de l'intégration de contenu tiers sur votre site web. Bien que le widget suive les meilleures pratiques de sécurité, il existe des étapes supplémentaires que vous pouvez prendre pour renforcer votre intégration.
Les en-têtes de politique de sécurité du contenu aident à prévenir les attaques XSS et d'autres vulnérabilités d'injection de code. Configurez votre CSP pour autoriser explicitement le widget tout en maintenant une sécurité stricte ailleurs :
# 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;Validez et assainissez toujours les entrées utilisateur :
// 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;}Le widget est optimisé pour la performance dès le départ, mais il existe des stratégies pour le rendre encore plus rapide et plus efficace, surtout sur des sites à fort trafic ou des connexions plus lentes.
Au lieu de charger le widget immédiatement lorsque la page se charge, différer son chargement jusqu'à ce que l'utilisateur en ait besoin ou après que le contenu critique a été chargé. Cela améliore le temps de chargement initial de votre page et les scores des Core Web Vitals :
// 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);});Assurez-vous que vos choix de couleurs respectent les directives WCAG :