Présentation de Realtime
Realtime envoie des événements aux clients connectés via WebSockets. Votre serveur publie un événement sur un canal nommé, et les clients abonnés le reçoivent sans interrogation répétée.
Utilisez Realtime pour les changements dont un client a besoin sans effectuer une nouvelle requête : mises à jour de commandes, messages de chat, modifications de tableau de bord ou tâches en arrière-plan terminées.
Canaux, membres et connexions
Trois mots décrivent le modèle. Ils ne sont pas interchangeables.
Un canal est un espace nommé. Il existe tant qu'au moins une connexion est abonnée et disparaît quand la dernière se retire. Les noms de canaux acceptent jusqu'à 164 lettres, chiffres et ces caractères : _ - = @ , . ;.
Une connexion est un WebSocket ouvert. Elle reçoit un identifiant (26896.319537) lors de la connexion. L'autorisation signe cet identifiant, et une publication peut l'exclure de la distribution.
Un membre est une identité authentifiée sur un canal de présence. Un membre peut détenir plusieurs connexions, par exemple trois onglets de navigateur. Les événements de présence se déclenchent quand la première connexion du membre rejoint le canal et quand la dernière le quitte. Les onglets intermédiaires n'en produisent pas.
Les trois types de canaux
Le préfixe du nom de canal détermine le type de canal et son comportement d'autorisation.
| Nom | Qui peut s'abonner | A des membres |
|---|---|---|
| orders | toute personne disposant de la clé d'app | non |
| private-orders | uniquement les clients signés par votre backend | non |
| presence-lobby | uniquement les clients signés par votre backend | oui |
Un canal public est lisible par toute personne disposant de la clé d'app, qui est livrée dans le code client. Ne publiez que des données visibles par tous les visiteurs. Voir Canaux publics.
Un canal privé demande à votre backend d'approuver chaque abonnement. Le client envoie l'identifiant de connexion et le nom du canal à votre endpoint, qui renvoie une signature calculée avec le secret de l'app. Voir Canaux privés. Un canal private-encrypted-… chiffre également les payloads avec une clé détenue par vos serveurs. Voir Canaux chiffrés.
Un canal de présence ajoute une identité à l'autorisation de canal privé. Chaque abonné reçoit la liste des membres et ses modifications via member_id et l'optionnel member_info. Voir Canaux de présence.
Événements reçus par le client
Les événements applicatifs sont les vôtres : vous choisissez le nom au moment de la publication (order-updated, message.created) et vous y liez un handler. En parallèle, le client réémet les événements de cycle de vie sous le préfixe bird:, que vous liez exactement comme les vôtres :
- bird:subscription_succeeded se déclenche une fois par canal quand l'abonnement est actif. Sur un canal de présence, il contient la liste actuelle des membres, ce qui vous permet de rendre la salle avant tout mouvement.
- bird:member_added et bird:member_removed se déclenchent sur les canaux de présence quand des membres arrivent ou partent. member_added se déclenche quand la première connexion d'une personne s'abonne ; member_removed uniquement quand sa dernière connexion se retire. Un deuxième onglet qui s'ouvre puis se ferme ne produit aucun des deux.
- bird:connection_count indique combien de connexions sont abonnées au canal, si l'app a activé le comptage de connexions et les événements de compteur de connexions. Il compte les connexions : un membre avec trois onglets compte pour trois.
- bird:subscription_error se déclenche quand un abonnement est refusé, le plus souvent parce que l'autorisation a échoué.
Les noms commençant par client- sont réservés aux événements que les clients s'envoient directement entre eux, ce qui est un paramètre d'app distinct et n'est autorisé que sur les canaux privés et de présence.
Votre serveur peut aussi recevoir des événements, sous forme de webhooks, quand un canal devient occupé ou vacant et quand des membres rejoignent ou quittent. Ils arrivent en tant qu'événements realtime.* via les mêmes endpoints webhook que le reste de Bird.
Les clients
Trois clients reçoivent les événements via le même protocole. Utilisez @messagebird/realtime pour les navigateurs et Node.js, BirdRealtime pour iOS, macOS et Linux, ou com.messagebird:bird-realtime pour Android et la JVM serveur. Chacun prend en charge les abonnements, les bindings, la présence, signin() et les événements client.
Conservez le secret de l'app sur votre serveur. Les SDK serveur l'utilisent pour publier des événements, autoriser des canaux et déconnecter des membres.
Apps, clés et régions
Une app est un environnement isolé avec ses propres identifiants et son propre espace de noms de canaux. Deux apps ne voient jamais les canaux l'une de l'autre, ce qui fait de l'app la bonne frontière entre vos environnements de staging et de production.
Chaque app utilise une région immuable sélectionnée à la création. Utilisez Lister les régions Realtime pour récupérer les identifiants acceptés, et choisissez la région la plus proche de vos utilisateurs.
Chaque app possède trois valeurs aux usages distincts :
- L'app ID (rap_…) identifie l'app dans les appels Bird API et apparaît dans chaque chemin /v1/realtime/apps/….
- La clé est publique. Les navigateurs se connectent avec, et elle peut être livrée sans risque dans le code client.
- Le secret s'associe à la clé pour authentifier les appels côté serveur et signer l'autorisation de canal. Il n'est affiché qu'une seule fois, à la création. Quiconque le détient peut publier sur votre app et usurper des identités de présence.
Gérez vos apps et effectuez la rotation des clés sur la page Apps Realtime. Créez une seconde clé, déployez-la, puis révoquez l'ancienne.
Visibilité
La page Métriques Realtime affiche trois valeurs par app ou pour l'ensemble de l'espace de travail sur la fenêtre sélectionnée :
- Connexions max est le nombre le plus élevé de connexions ouvertes au même instant dans la fenêtre. Ce pic est la valeur à laquelle la limite de connexions s'applique.
- Connexions moyennes est la moyenne des pics journaliers. Elle ne moyenne pas chaque échantillon. Un espace de travail qui connaît un pic chaque après-midi et tourne au ralenti la nuit affiche une moyenne bien supérieure à ses heures creuses.
- Messages compte les distributions d'événements, une par canal : une publication désignant 50 canaux compte pour 50. Ce total inclut aussi les événements que le protocole envoie en votre nom, comme les arrivées de présence et les mises à jour du compteur de connexions, ce qui explique qu'il puisse dépasser les publications effectuées par votre code.
La consommation est agrégée par tranches d'une minute, de sorte que le trafic récent peut mettre plusieurs minutes à apparaître. Le API de consommation n'est disponible que dans le tableau de bord. Pour une visibilité programmatique, enregistrez les publications dans vos systèmes ou déduisez l'activité des webhooks realtime.*.
Plans et limites
Le plan gratuit couvre 100 connexions simultanées et 200 000 messages par jour, sur l'ensemble des apps d'un espace de travail. Créer plus d'apps n'augmente pas le plafond, car il s'applique à l'espace de travail.
Les plans payants commencent à 25 $ par mois pour 250 connexions simultanées et 500 000 messages par jour, et montent jusqu'à 30 000 connexions et 90 millions de messages par jour. Tarification Realtime liste chaque palier.
Des plafonds par requête s'appliquent sur tous les plans : une publication nomme au maximum 100 canaux, un batch contient au maximum 10 événements, et le payload d'un événement est limité à 10 Ko sérialisé.
Étapes suivantes
- Envoyer votre premier événement Realtime parcourt la boucle complète de bout en bout.
- Publier des événements couvre la publication depuis votre serveur, le batching et l'exclusion du client d'origine.
- Autoriser les canaux est le contrat que votre backend implémente pour les canaux privés et de présence.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.