Introduction

🎯 Que fait ce module ?

Le module WS (WebSocket) vous permet de recevoir des notifications en temps réel - mises à jour de contenu, changements de commande, actions des utilisateurs - en établissant des connexions persistantes pour obtenir des mises à jour instantanées sans sondage, permettant des fonctionnalités en direct comme des notifications, un chat en direct et des tableaux de bord en temps réel.

Considérez-le comme votre système de notification en temps réel - au lieu de demander sans cesse "y a-t-il quelque chose de nouveau ?" (sondage), WebSocket maintient une connexion ouverte et le serveur vous envoie instantanément des mises à jour lorsque des événements se produisent.

---

📖 Explication Simple

Chaque application moderne a besoin de mises à jour en temps réel :

• 🔔 Notifications en Direct - Alertes instantanées lorsque quelque chose se produit
• 💬 Chat en Direct - Messagerie en temps réel entre utilisateurs
• 📊 Tableaux de Bord en Direct - Statistiques et métriques se mettant à jour automatiquement
• 🛒 Mises à Jour de Commandes - Changements de statut de commande instantanés
• 📝 Mises à Jour de Contenu - Changements de contenu en direct et publication
• 👥 Activité des Utilisateurs - Présence et actions des utilisateurs en temps réel
• 🔄 Synchronisation des Données - Synchronisation automatique entre appareils

Le problème avec le sondage (demandes répétées) :

// ❌ Mauvais - Sondage toutes les 5 secondes
setInterval(async () => {
  const orders = await Orders.getOrders();
  // Vérifiez si quelque chose a changé
  // Gaspille de la bande passante, retarde les mises à jour, charge du serveur
}, 5000);

Problèmes :

• 🔋 Consommation de batterie - Les demandes constantes gaspillent de l'énergie
• 📡 Gaspillage de réseau - La plupart des demandes retournent "aucun changement"
• ⏱️ Mises à jour retardées - Délai allant jusqu'à 5 secondes
• 🖥️ Charge du serveur - Demandes inutiles toutes les quelques secondes

La solution WebSocket :

// ✅ Bon - Connexion WebSocket en temps réel
const { WS } = defineOneEntry('https://your-site.oneentry.cloud', {
  token: 'your-app-token'
});

// S'abonner aux événements
WS.subscribe('order.created', (order) => {
  console.log('Nouvelle commande reçue !', order);
  // Notification instantanée, pas de sondage !
});

WS.subscribe('content.updated', (content) => {
  console.log('Contenu mis à jour !', content);
  // Mettre à jour l'interface utilisateur immédiatement
});

Avantages :

• 🔋 Efficace - Une seule connexion persistante
• 📡 En temps réel - Mises à jour instantanées, pas de délai
• ⏱️ Faible latence - Livraison de notifications en moins d'une seconde
• 🖥️ Charge réduite - Le serveur pousse uniquement lorsque c'est nécessaire

---

✨ Concepts Clés

Qu'est-ce que WebSocket ?

WebSocket est une connexion bidirectionnelle persistante entre le client et le serveur :

• Connexion Persistante - Reste ouverte, pas de poignées de main répétées
• Bidirectionnelle - Le client et le serveur peuvent envoyer des messages
• En Temps Réel - Livraison instantanée des messages
• Basé sur les Événements - S'abonner à des événements spécifiques
• Efficace - Faible surcharge par rapport au sondage HTTP

WebSocket vs Sondage HTTP

Fonctionnalité	WebSocket	Sondage HTTP
Connexion	Persistante (reste ouverte)	Connexions répétées
Latence	Moins d'une seconde	Dépend de l'intervalle (2-30s)
Efficacité	Très efficace	Gaspillage (de nombreuses réponses vides)
Charge du Serveur	Faible (événements uniquement)	Élevée (demandes constantes)
Utilisation de la Batterie	Faible	Élevée (appareils mobiles)
Cas d'Utilisation	Mises à jour en temps réel	Acceptable pour des mises à jour non critiques

Cycle de Vie de la Connexion WebSocket

1. Le client se connecte au serveur WebSocket
   (WS.connect())
   ↓
2. Connexion établie
   (l'événement onOpen se déclenche)
   ↓
3. Le client s'abonne aux événements
   (WS.subscribe('event.name', callback))
   ↓
4. Le serveur envoie des événements lorsqu'ils se produisent
   (Livraison instantanée)
   ↓
5. Le client reçoit des messages d'événements
   (La fonction de rappel s'exécute)
   ↓
6. La connexion reste ouverte
   (Pas besoin de reconnexion)
   ↓
7. Le client se déconnecte lorsqu'il a terminé
   (WS.disconnect())

Événements WebSocket Courants

Type d'Événement	Description	Cas d'Utilisation
order.created	Nouvelle commande passée	Afficher la notification "Nouvelle Commande !"
order.updated	Changement de statut de commande	Mettre à jour le statut de la commande dans l'interface utilisateur
content.published	Nouveau contenu publié	Rafraîchir la liste de contenu
content.updated	Contenu édité	Mettre à jour le contenu affiché
user.registered	Nouvel utilisateur inscrit	Afficher le nouvel utilisateur dans le tableau de bord admin
payment.completed	Paiement traité	Mettre à jour le statut de la commande à "Payé"
product.outOfStock	Produit en rupture de stock	Afficher le badge "Rupture de Stock"

Pourquoi Utiliser le Module WebSocket ?

Avantage	Description
Mises à Jour en Temps Réel	Notifications instantanées, pas de délai de sondage
Efficace	Une seule connexion, faible surcharge
Amical pour la Batterie	Pas de sondage constant sur mobile
Scalable	Le serveur pousse uniquement lorsque c'est nécessaire
Basé sur les Événements	S'abonner à des événements spécifiques
Fonctionnalités en Direct	Activer le chat, les notifications, les tableaux de bord

---

🚀 Exemple Rapide

---

📋 Ce Que Vous Devez Savoir

Gestion de la Connexion WebSocket

Les connexions WebSocket doivent être gérées avec soin :

Meilleures pratiques :

• Vérifiez l'état de la connexion avant de vous abonner
• Implémentez une logique de reconnexion
• Gérez les erreurs de connexion avec grâce
• Déconnectez-vous lorsque l'utilisateur se déconnecte

Gestion de l'Abonnement aux Événements

Abonnez-vous aux événements uniquement après que la connexion soit établie

Meilleures pratiques :

• Utilisez des fonctions de rappel nommées pour faciliter la désinscription
• Abonnez-vous après que la connexion soit ouverte
• Désabonnez-vous lorsque le composant se démonte
• Ne vous abonnez pas au même événement plusieurs fois

Désinscription des Événements

Désabonnez-vous toujours lorsque vous avez terminé pour éviter les fuites de mémoire :

Meilleures pratiques :

• Désabonnez-vous dans les fonctions de nettoyage
• Déconnectez WebSocket lorsqu'il n'est pas nécessaire
• Évitez les fuites de mémoire dans les SPA

Stratégie de Reconnexion

Implémentez une reconnexion automatique avec un backoff exponentiel :

Meilleures pratiques :

• Utilisez un backoff exponentiel pour la reconnexion
• Limitez le nombre maximum de tentatives de reconnexion
• Réinitialisez les compteurs lors d'une connexion réussie
• Autorisez une déconnexion manuelle sans reconnexion

Structure de la Charge Utile de l'Événement

Les charges utiles des événements suivent une structure cohérente :

Meilleures pratiques :

• Validez la structure de la charge utile de l'événement
• Gérez les champs manquants avec grâce
• Vérifiez le type de la charge utile en TypeScript

Gestion des Erreurs

Implémentez une gestion des erreurs complète :

Meilleures pratiques :

• Attrapez les erreurs dans les gestionnaires d'événements
• Enregistrez les erreurs pour le débogage
• Affichez des messages d'erreur conviviaux
• Ne laissez pas les erreurs faire planter l'application

Optimisation des Performances

Optimisez les performances de WebSocket :

Meilleures pratiques :

• Limitez la fréquence des événements
• Regroupez plusieurs mises à jour ensemble
• Débounsez les mises à jour de l'interface utilisateur
• Évitez les opérations coûteuses dans les gestionnaires

---

💡 Notes Importantes

⚠️ Gestion de l'État de Connexion

Vérifiez toujours l'état de la connexion avant de vous abonner

🔄 Gestion de la Reconnexion

Les connexions WebSocket peuvent se déconnecter de manière inattendue :

• Changements de réseau (WiFi à cellulaire)
• Redémarrages du serveur
• Délai d'inactivité

Implémentez toujours une logique de reconnexion

🧹 Prévention des Fuites de Mémoire

Désabonnez-vous lorsque vous avez terminé pour éviter les fuites de mémoire

🔒 Sécurité

Les connexions WebSocket sont authentifiées :

• Authentification par jeton (comme pour l'API REST)
• Protocole WebSocket sécurisé (WSS)
• Pas besoin d'envoyer le jeton avec chaque message

Meilleures pratiques :

• Utilisez WSS (WebSocket sécurisé) en production
• Ne pas exposer de données sensibles dans les gestionnaires d'événements
• Validez les charges utiles des événements avant de les traiter

📱 Considérations Mobiles

WebSocket sur les appareils mobiles :

• Utilisation de la batterie (efficace, mais connexion persistante)
• Les connexions en arrière-plan peuvent être interrompues
• Les changements de réseau nécessitent une reconnexion

Meilleures pratiques :

• Reconnectez-vous lorsque l'application revient au premier plan
• Gérez les changements d'état du réseau
• Envisagez le sondage pour des mises à jour non critiques sur mobile

---

📊 Tableau de Référence Rapide

Méthode	Description	Cas d'Utilisation
connect()	Se connecter au serveur WebSocket	Établir la connexion

❓ Questions Fréquemment Posées (FAQ)

Comment puis-je me connecter au serveur WebSocket ?

Utilisez WS.connect() pour établir une connexion. Attendez que la connexion s'ouvre (écoutez l'événement onOpen) avant de vous abonner aux événements. La connexion est authentifiée à l'aide de votre jeton d'application de defineOneEntry().

---

À quels événements puis-je m'abonner ?

Abonnez-vous à des événements comme order.created, order.updated, content.published, payment.completed, user.registered, etc. Les événements disponibles dépendent de votre configuration OneEntry et de la configuration du module Events dans le panneau d'administration.

---

Comment gérer les déconnexions ?

Implémentez une reconnexion automatique avec un backoff exponentiel. Écoutez les événements onClose et onError, puis essayez de vous reconnecter après un délai (par exemple, 1s, 2s, 4s, 8s, jusqu'à un maximum de 30s). Réinitialisez le compteur de délai lors d'une connexion réussie.

---

Dois-je utiliser WebSocket ou le sondage pour mon application ?

Utilisez WebSocket pour des fonctionnalités en temps réel (chat en direct, notifications, tableaux de bord) où les mises à jour instantanées sont importantes. Utilisez le sondage pour des mises à jour non critiques ou lorsque les connexions WebSocket posent problème (pare-feu restrictifs, mode arrière-plan mobile).

---

Comment puis-je éviter les fuites de mémoire avec les abonnements WebSocket ?

Désabonnez-vous toujours des événements lorsque les composants se démontent ou lorsque la connexion n'est plus nécessaire. Dans React, utilisez des fonctions de nettoyage dans useEffect. Dans Vue, utilisez le hook de cycle de vie beforeUnmount.

---

Puis-je utiliser WebSocket sur des appareils mobiles ?

Oui, mais soyez conscient que les systèmes d'exploitation mobiles peuvent interrompre les connexions WebSocket en arrière-plan. Reconnectez-vous lorsque l'application revient au premier plan. Considérez l'impact sur la batterie des connexions persistantes sur les appareils mobiles.

---

🎓 Meilleures Pratiques

• Vérifiez l'état de la connexion - Abonnez-vous uniquement après l'ouverture de la connexion
• Implémentez la reconnexion - Reconnexion automatique en cas de déconnexion avec un backoff exponentiel
• Désabonnez-vous lors du nettoyage - Évitez les fuites de mémoire dans les SPA
• Gérez les erreurs avec grâce - Attrapez les erreurs dans les gestionnaires d'événements
• Limitez la fréquence des événements - Évitez de submerger l'interface utilisateur avec des mises à jour
• Validez les charges utiles des événements - Vérifiez la structure des données avant de les traiter
• Utilisez des rappels nommés - Plus facile à désabonner et à déboguer
• Enregistrez l'état de la connexion - Suivez les événements d'ouverture/fermeture/erreur pour le débogage

---

Plus d'informations sur l'interface utilisateur du module https://doc.oneentry.cloud/docs/events/introduction

---

Définition du module WS

Vous pouvez vous abonner à des événements via WebSocket pour recevoir des notifications

const { WS } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

---

🔗 Documentation Connexe

• Module Commandes - Événements de commande pour le suivi des commandes en temps réel
• Module Utilisateurs - Événements d'utilisateur pour les notifications d'inscription
• Module Paiements - Événements de paiement pour les mises à jour de transaction
• API WebSocket

---