Utilisation avancée

API programmatique

Le widget expose un objet CompaninWidget global pour un 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.

Méthodes disponibles

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>

Écoute d'événements

É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 :

• Suivez l'engagement du widget dans votre plateforme d'analytique
• Afficher de l'aide contextuelle basée sur les conversations du widget
• Déclencher des actions d'application lorsque les conversations commencent
• Mettre à jour les éléments de l'interface utilisateur en fonction de l'état du widget
• Enregistrer les interactions de support client dans votre CRM

<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>

Style personnalisé

Bien que l'interface de configuration offre d'options de style étendues, 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 :

• Les styles personnalisés remplacent les paramètres de configuration
• Utilisez !important avec parcimonie — uniquement lorsque cela est nécessaire pour remplacer l'isolation iframe
• Testez soigneusement sur différents navigateurs car le CSS personnalisé peut se comporter différemment
• Les mises à jour du widget peuvent affecter vos styles personnalisés — passez en revue après chaque mise à jour

Surcharges CSS

Ciblez 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;    }

Personnalisation de thème

Le widget est livré avec deux palettes — Clair et Sombre — configurées dans votre tableau de bord. Choisissez celle que les visiteurs voient avec l'attribut de script data-theme="light|dark|system" (le système suit leur appareil), ou changez-la à l'exécution avec CompaninWidget.setTheme('dark'). Les variables CSS ci-dessous s'appliquent toujours en plus de la palette active pour des surcharges fines.

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;      }    }

Intégration d'analytique

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 :

• Taux d'ouverture/fermeture du widget
• Messages envoyés par session
• Durée moyenne de conversation
• Sujets de conversation populaires (à partir des flux)
• Temps jusqu'au premier message
• Taux de complétion des flux de conversation

Google Analytics

Suivez les interactions du widget comme des événements personnalisés dans Google Analytics. Cela s'intègre parfaitement à votre configuration d'analytique existante :

// 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;      }    });

Analytique personnalisée

// 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;      }    });

Intégration de webhook

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 :

• Synchronisation en temps réel avec vos systèmes
• Création automatique de tickets dans les systèmes de support
• Enrichissement des données clients dans le CRM
• Déclencheurs de flux de travail automatisés
• Conformité et journalisation des audits

Webhooks d'événements

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"        }      }    }

Événements disponibles

• widget_opened - L'utilisateur a ouvert le widget
• widget_closed - L'utilisateur a fermé le widget
• conversation_started - Nouvelle conversation initiée
• message_received - L'utilisateur a envoyé un message
• message_sent - L'agent a envoyé un message
• flow_triggered - Le flux de conversation a été activé
• session_ended - La session de conversation s'est terminée

Considérations de sécurité

La 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.

Politique de sécurité du contenu (CSP)

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.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;

Validation des entrées

Validez et assainissez toujours les entrées des utilisateurs :

// 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;    }

Optimisation des performances

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.

Chargement paresseux

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 Core Web Vitals :

// 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);    });

Minimiser le CSS personnalisé et les imagesUtiliser des schémas de couleurs efficacesLimiter l'historique des messages (configurer dans les paramètres du widget)Activer la compression sur votre serveurUtiliser un CDN pour les actifs statiques

• Minimiser le CSS personnalisé et les images
• Utiliser des schémas de couleurs efficaces
• Limiter l'historique des messages (configurer dans les paramètres du widget)
• Activer la compression sur votre serveur
• Utiliser un CDN pour les actifs statiques

Fonctionnalités d'accessibilité

Navigation au clavier

• Onglet - Naviguer entre les éléments
• Entrée / Espace - Activer les boutons
• Échapper - Fermer le widget
• Touches fléchées - Naviguer dans l'historique des messages

Support des lecteurs d'écran

• Tous les éléments interactifs ont des étiquettes ARIA appropriées
• Annonces de messages pour les lecteurs d'écran
• Gestion du focus lors de l'ouverture/fermeture
• Support du mode à contraste élevé

Contraste des couleurs

Assurez-vous que vos choix de couleurs respectent les directives WCAG :

• Texte principal : ratio de contraste minimum de 4.5:1
• Texte large : ratio de contraste minimum de 3:1
• Composants UI : ratio de contraste minimum de 3:1