Introduction
Ouvrez une connexion WebSocket en temps réel pour recevoir des mises à jour de contenu, de commandes et d'utilisateurs sans sondage.
Plus d'informations sur l'interface utilisateur du module https://doc.oneentry.cloud/docs/events/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 commandes, 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) :
// ❌ Bad - Polling every 5 seconds
setInterval(async () => {
const orders = await Orders.getOrders();
// Check if anything changed
// Wastes bandwidth, delays updates, server load
}, 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 :
// ✅ Good - Real-time WebSocket connection
const { WS } = defineOneEntry('https://your-site.oneentry.cloud', {
token: 'your-app-token'
});
// connect() returns a socket.io Socket (requires an authorized user)
const socket = await WS.connect();
// Listen for events with socket.on(...)
socket.on('my_event', (payload) => {
console.log('Update received!', payload);
// Instant notification, no polling!
});
Avantages :
- 🔋 Efficace - Une seule connexion persistante
- 📡 En temps réel - Mises à jour instantanées, sans délai
- ⏱️ Faible latence - Livraison de notifications en moins d'une seconde
- 🖥️ Charge réduite - Le serveur envoie des mises à jour 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 - Écoutez les événements avec
socket.on(...) - 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. Client opens a connection
(const socket = await WS.connect())
↓
2. Connection established
(socket.on('connect', ...) fires)
↓
3. Client listens for events
(socket.on('my_event', callback))
↓
4. Server sends events when they occur
(Instant delivery)
↓
5. Client receives event messages
(Callback function executes)
↓
6. Connection stays open
(No reconnection needed)
↓
7. Client disconnects when done
(socket.disconnect())
Quels événements arrivent par la connexion
Il n'y a pas de catalogue fixe de noms d'événements SDK. Les événements se déclenchent selon votre configuration du module Événements dans le panneau d'administration (l'événement doit avoir l'option WebSocket activée). Vous écoutez un événement par son marqueur avec socket.on('<event_marker>', callback).
La charge utile dépend de la source de l'événement. Champs de charge utile typiques (voir connect() pour des exemples complets) :
| Champ de Charge Utile | Arrive pour | Contient |
|---|---|---|
attributes | Chaque événement | Les propres attributs de l'événement |
product | Événements de catalogue (produit) | Attributs du produit plus title |
user | Événements de formulaire utilisateur | Champs du formulaire utilisateur |
order | Événements de commande | id de la commande et attributs |
email / code | Formulaires d'inscription / de code | Champs de formulaire supplémentaires |
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 envoie uniquement lorsque c'est nécessaire |
| Basé sur les Événements | Abonnez-vous à des événements spécifiques |
| Fonctionnalités en Direct | Activez le chat, les notifications, les tableaux de bord |
📋 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 retour exponentiel :
Meilleures pratiques :
- Utilisez un retour 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 des Événements
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 :
- Capturez 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 à haute fréquence
- 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 couper 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() | Connectez-vous au serveur WebSocket | Établir une connexion |
🔐
connect()nécessite un utilisateur autorisé — authentifiez-vous d'abord via AuthProvider. Après la connexion, attachez des gestionnaires d'événements avecsocket.on(...).
❓ Questions Fréquemment Posées (FAQ)
Comment puis-je me connecter au serveur WebSocket ?
Utilisez WS.connect() pour ouvrir une connexion — cela retourne un Socket socket.io. Cela nécessite un utilisateur autorisé, donc appelez d'abord AuthProvider.auth(...). Attendez l'événement connect avant de vous fier au socket, puis attachez des gestionnaires avec socket.on('<event_marker>', callback). La connexion est authentifiée avec le jeton d'accès de l'utilisateur plus votre jeton d'application de defineOneEntry().
Quels événements puis-je écouter ?
Il n'y a pas de liste fixe d'événements SDK. Les événements sont définis par votre configuration du module Événements dans le panneau d'administration (avec l'option WebSocket activée), et vous écoutez un événement par son marqueur avec socket.on('<event_marker>', callback). Voir connect() pour des exemples de charge utile (produit, utilisateur, commande, formulaire).
Comment gérer les coupures de connexion ?
Implémentez une reconnexion automatique avec un retour exponentiel. Écoutez les événements disconnect et connect_error de socket.io, 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 connect réussie. (socket.io se reconnecte également automatiquement par défaut.)
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-feux restrictifs, mode arrière-plan mobile).
Comment é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 retour exponentiel
- Désabonnez-vous lors du nettoyage - Détachez les gestionnaires (
socket.off) etsocket.disconnect()pour éviter les fuites de mémoire dans les SPA - Gérez les erreurs avec grâce - Capturez les erreurs dans les gestionnaires d'événements
- Limitez la fréquence des événements à haute fréquence - É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
Définition du module WS
Vous pouvez vous abonner à des événements via le 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