Aller au contenu principal

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 - via une connexion persistante, de sorte que le serveur vous envoie les mises à jour instantanément au lieu que vous les sondiez. Cela permet des fonctionnalités en direct comme les notifications, le chat en direct et les tableaux de bord en temps réel.

La méthode unique, connect(), ouvre la connexion et renvoie un Socket de socket.io. Elle est synchronisée et nécessite un utilisateur autorisé, donc authentifiez-vous d'abord.

🚀 Démarrage rapide​

Initialisez le module depuis defineOneEntry :


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

connect() est synchrone et renvoie un Socket de socket.io (pas d'await). Attachez des gestionnaires d'événements avec socket.on(...) :

// connect() requires an authorized user — authenticate first via AuthProvider.
const socket = WS.connect();

socket.on('connect', () => {
  console.log('WebSocket connected');
});

// Listen for an event by its marker (configured in the Events module).
socket.on('my_event', (payload) => {
  console.log('Update received!', payload);
});

✨ 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éWebSocketSondage HTTP
ConnexionPersistante (reste ouverte)Connexions répétées
LatenceMoins d'une secondeDépend de l'intervalle (2-30s)
EfficacitéTrès efficaceGaspillage (de nombreuses réponses vides)
Charge serveurFaible (événements uniquement)Élevée (demandes constantes)
Cas d'utilisationMises à jour en temps réelAcceptable pour des mises à jour non critiques

Cycle de vie de la connexion​

1. Authenticate the user (AuthProvider.auth)
   ↓
2. Open the connection: const socket = WS.connect()
   ↓
3. Wait for the 'connect' event: socket.on('connect', ...)
   ↓
4. Listen for events: socket.on('<event_marker>', callback)
   ↓
5. Server pushes events as they occur
   ↓
6. Disconnect 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 Events 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 utileArrive pourContient
attributesChaque événementLes propres attributs de l'événement
productÉvénements de catalogue (produit)Attributs du produit plus title
userÉvénements de formulaire utilisateurChamps du formulaire utilisateur
orderÉvénements de commandeid de la commande et attributs
email / codeFormulaires d'inscription / de codeChamps supplémentaires du formulaire

📋 Ce que vous devez savoir​

L'autorisation est requise​

connect() nécessite un utilisateur autorisé — appelez AuthProvider.auth(...) avant de vous connecter. La connexion est authentifiée avec le jeton d'accès de l'utilisateur plus votre jeton d'application de defineOneEntry(). Si aucun utilisateur n'est autorisé, le SDK enregistre une erreur.

connect() est synchrone​

connect() renvoie immédiatement un Socket de socket.io — ne l'attendez pas. Attendez l'événement connect avant de vous fier au socket, puis attachez des gestionnaires avec socket.on(...).

socket.io est chargé à la demande​

socket.io-client (~41 kB) est importé la première fois que connect() est appelé, donc les projets qui n'ouvrent jamais de socket ne l'incluent pas — voir Taille du bundle & Formats de module.

La signature reste inchangée et l'utilisation normale n'est pas affectée : jusqu'à ce que le morceau soit résolu, l'objet renvoyé met en file d'attente tout ce que vous faites avec (on, emit, disconnect) et le rejoue sur le vrai socket dans le même tick où il est créé — avant que la connexion puisse livrer quoi que ce soit — donc aucun événement n'est perdu. Lire l'état tôt est également précis : un socket fraîchement créé n'est pas connecté non plus, donc id est undefined et connected est false.

La seule différence : une méthode qui doit retourner une valeur (par exemple listeners()) ne peut pas répondre avant que le morceau arrive, et les objets imbriqués tels que socket.io ne sont accessibles qu'une fois qu'il est chargé.

Abonnez-vous après l'ouverture de la connexion, nettoyez lorsque c'est fait​

Attachez des gestionnaires d'événements après que l'événement connect se soit déclenché, et détachez-les (socket.off) plus appelez socket.disconnect() lorsque la connexion n'est plus nécessaire (par exemple lors du démontage du composant ou de la déconnexion de l'utilisateur) pour éviter les fuites de mémoire dans les SPA.

Reconnexion​

socket.io se reconnecte automatiquement par défaut. Pour personnaliser, écoutez les événements disconnect et connect_error et reconnectez-vous avec un retour exponentiel, en réinitialisant le délai lors d'une connect réussie.

📊 Tableau de référence rapide​

MéthodeDescriptionCas d'utilisation
connect() 🔐Connectez-vous au serveur WebSocketÉtablir la connexion

🔐 connect() nécessite un utilisateur autorisé — authentifiez-vous d'abord via AuthProvider. Après la connexion, attachez des gestionnaires d'événements avec socket.on(...).

❓ Questions fréquentes (FAQ)​

Comment puis-je me connecter au serveur WebSocket ?​

Utilisez WS.connect() pour ouvrir une connexion — elle est synchrone et renvoie un Socket de socket.io. Elle 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).

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

Il n'y a pas de liste fixe d'événements SDK. Les événements sont définis par votre configuration du module Events 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 interruptions de connexion ?​

socket.io se reconnecte automatiquement par défaut. Pour personnaliser, écoutez les événements disconnect et connect_error et reconnectez-vous avec un retour exponentiel (par exemple, 1s, 2s, 4s, 8s, jusqu'à un maximum), en réinitialisant le compteur de délai lors d'une connect réussie.

Comment éviter les fuites de mémoire avec les abonnements WebSocket ?​

Détachez les gestionnaires d'événements (socket.off) et appelez socket.disconnect() lorsque les composants se démontent ou que la connexion n'est plus nécessaire. Dans React, faites cela dans le nettoyage de useEffect ; dans Vue, dans beforeUnmount.

🎓 Meilleures pratiques​

  • Authentifiez-vous d'abord - connect() nécessite un utilisateur autorisé.
  • N'attendez pas connect() - C'est synchrone et renvoie un Socket.
  • Abonnez-vous après l'ouverture de la connexion - Attachez des gestionnaires après que l'événement connect se soit déclenché.
  • Nettoyez - Détachez les gestionnaires (socket.off) et socket.disconnect() pour éviter les fuites de mémoire dans les SPA.
  • Gérez la reconnexion - socket.io se reconnecte automatiquement ; personnalisez avec disconnect / connect_error et retour si nécessaire.
  • Validez les charges utiles des événements - La forme de la charge utile dépend de la source de l'événement ; vérifiez les champs avant de les utiliser.

🔗 Documentation connexe​