Un canal existe dès qu'un abonné s'y connecte et disparaît quand la dernière connexion le quitte. Son nom détermine le type : public pour tout ce qu'un visiteur peut lire, privé pour tout ce qui est limité à un client, présence pour un salon avec une liste de membres, et un préfixe cache pour l'état dont un nouvel arrivant a besoin immédiatement.
const bird = new BirdRealtime({ appKey: APP_KEY, region: "us1" });
// Public: anyone holding the app key can subscribe.
const scores = bird.subscribe("match-42");
// Private: your backend signs every subscription.
const order = bird.subscribe("private-order-ord_123");
// Presence: private, plus an identity the room can see.
const room = bird.subscribe("presence-room-42");
// Cache: the latest event replays to whoever joins next.
const build = bird.subscribe("cache-build-8821");
build.bind("bird:cache_miss", () => showSkeleton());
Le préfixe est la configuration.
Aucun registre de canaux à maintenir.
Les canaux sont le modèle d'adressage de l<hub>API Bird Realtime</hub>. Vous nen créez jamais : vous vous abonnez à un nom, et les trois premiers caractères de ce nom indiquent au edge comment le traiter. Un nom sans préfixe est public. private- demande à votre backend d'approuver chaque abonnement. presence- fait de même et associe une identité. private-encrypted- scelle le contenu avec une clé que Bird ne détient jamais. Les noms acceptent jusqu'à 164 caractères, sont sensibles à la casse, et constituent la seule partie d'un canal à concevoir avec soin, car un nom public est visible par quiconque possède la clé de l'application.
Cinq types de salon.
Même protocole, même client, même appel de publication. Seul le nom change.
- 01
Canaux publics.
Pas de point d'autorisation, pas d'inscription. Quiconque possède la clé de l'application peut s'abonner, ce qui les rend adaptés aux résultats de build, scores en direct, informations de vol ou pages de statut, mais inadaptés à tout ce qui est limité à un seul client. Évitez les identifiants dans le nom : orders ne révèle rien, orders-user-4821 révèle que l'utilisateur 4821 existe.
- 02
Canaux privés.
Un nom en private- route l'abonnement via votre propre endpoint, qui vérifie la session et signe l'identifiant de connexion et le nom du canal avec le secret de l'application. Vos règles, votre session, votre 403. Le edge vérifie la signature et rien d'autre n'atteint le canal.
- 03
Canaux de présence.
L'autorisation d'un canal privé plus une identité : chaque abonné reçoit la liste des membres et est informé des arrivées et des départs. C'est le seul type de canal avec une liste de membres.
- 04
Canaux chiffrés.
Un canal private-encrypted- transporte des contenus que votre serveur scelle avec une clé maître de 32 octets qui n'apparaît jamais dans une requête Realtime. Le edge et tout ce qui se trouve entre lui et le navigateur ne voient que du texte chiffré. Les noms de canaux et d'événements restent en clair : choisissez des noms qui ne divulguent pas ce que vous protégez.
- 05
Canaux avec cache.
Préfixez le nom avec cache-, après tout préfixe de type, et le canal mémorise le dernier événement publié via l'API et le rejoue à chaque nouvel abonné. L'abonnement sert aussi de récupération de l'état initial. Deux contraintes à intégrer dans votre conception : seul l'événement le plus récent est conservé, et il peut expirer avant le plafond de 30 minutes. Mettez donc l'état complet dans chaque payload et remplissez à partir du webhook cache-miss plutôt que de supposer que le cache est à jour.
Une publication, jusqu'à cent canaux.
La publication est un appel REST ordinaire depuis votre serveur. Nommez jusqu'à 100 canaux dans une seule requête et le edge diffuse l'événement à chacun d'eux. Un lot peut contenir jusqu'à 10 événements indépendants, chacun vers son propre canal. Transmettez l'identifiant de connexion du client actif via exclude_connection_id et l'onglet ayant déjà appliqué la modification localement sera ignoré. Demandez le nombre de connexions ou de membres avec include et la réponse vous indique l'état de chaque canal au moment de la publication. Réessayez avec la même clé d'idempotence et vous n'enverrez pas en double.
// One event, up to 100 channels, one request.
const result = await bird.realtime.publish(APP_ID, {
event: "score-updated",
channels: ["match-42", "cache-match-42"],
data: { home: 2, away: 1 },
// The tab that scored already rendered it locally.
exclude_connection_id: "26896.319537",
include: ["connection_count"],
});
for (const channel of result.data ?? []) {
console.log(channel.name, channel.connection_count);
}
Les clients peuvent communiquer directement entre eux.
Un indicateur de saisie ou une position de curseur n'a pas besoin de passer par votre API. Activez les événements client sur l'application et un client abonné peut déclencher un événement nommé client-something directement vers les autres membres du canal, limité à 10 par seconde par connexion. Ils ne fonctionnent que sur les canaux privés et de présence, et c'est volontaire : la clé de l'application est livrée dans votre page, donc l'autorisation est ce qui rend un client suffisamment fiable pour diffuser. Considérez ce qui arrive comme un signal, jamais comme un état faisant autorité, car le edge ne valide pas le contenu.
Ce qu'un canal retient et ne retient pas.
Une publication est confirmée dès que le edge a accepté l'événement. La livraison est asynchrone, il n'y a pas d'accusé de réception par client, et un client qui se déconnecte en cours de livraison ne recevra pas l'événement à la reconnexion. C'est le contrat honnête, et c'est pourquoi l'état durable appartient à votre base de données, les événements annonçant qu'il a changé. Les limites sont identiques sur tous les plans : 100 canaux par publication, 10 événements par lot, 10 Ko par payload, noms de canaux de 164 caractères.
Approfondir dans la documentation.
La vue d'ensemble Realtime définit les canaux, les membres et les connexions en une seule page. Publier des événements couvre la diffusion, les lots et l'exclusion, les canaux avec cache expliquent le rejeu, et interroger l'état d'un canal est la lecture côté serveur pour l'occupation et les comptages.
Mettez-le en pratique.
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Le reste de Realtime
Une application, une paire de clés. Explorez les autres fonctionnalités.
Abonnez-vous à un nom et commencez à publier.
Créez une application, intégrez la clé publique dans votre client et conservez le secret sur votre serveur. Le plan gratuit couvre 100 connexions simultanées.