HarborOrganisationEspaces de travailProductionBac à sable
Agent d’envoi
Clé API · Équipe Opérations clientsALAlex Lee AdministrateurAutorisations mises à jour
Un canal est un nom. Rien à provisionner.
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, private pour tout ce qui est limité à un client, presence pour une salle avec une liste de membres, et un préfixe cache pour l'état dont un nouvel arrivant a besoin immédiatement.
channels.ts
4 subscribed
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.
Il n'y a pas de registre de canaux à synchroniser.
Les canaux sont le modèle d'adressage de l<hub>Bird Realtime API</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 attache une identité. private-encrypted- chiffre le contenu avec une clé que Bird ne détient jamais. Les noms acceptent jusqu'à 164 caractères, sont sensibles à la casse, et sont la seule partie d'un canal à concevoir avec soin, car un nom public est visible par quiconque possède la clé d'application.
Cinq types de salle.
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'enregistrement. Quiconque possède la clé d'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, et inadaptés à tout ce qui est limité à un seul client. Gardez les identifiants hors du nom : orders ne révèle rien, orders-user-4821 révèle que l'utilisateur 4821 existe.
- 02
Canaux privés.
Un nom private- route l'abonnement vers votre propre endpoint, qui vérifie la session et signe l'identifiant de connexion et le nom du canal avec le secret d'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 chiffre 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 révèlent pas ce que vous protégez.
- 05
Canaux 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 pour chaque nouvel abonné. L'abonnement sert aussi de récupération de l'état initial. Deux contraintes à intégrer dès la conception : seul l'événement le plus récent est conservé, et il peut expirer avant le plafond de 30 minutes. Placez donc l'état complet dans chaque payload et reconstituez-le depuis le webhook de 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 distribue l'événement à chacun d'eux. Un lot transporte jusqu'à 10 événements indépendants, chacun vers son propre canal. Passez l'identifiant de connexion du client actif dans exclude_connection_id et l'onglet qui a déjà appliqué la modification localement est 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 ne livrerez pas en double.
publish.ts
200 · accepted
// 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 dans le canal, plafonné à 10 par seconde et par connexion. Ils ne fonctionnent que sur les canaux privés et de présence, et c'est voulu : la clé d'application est intégrée à votre page, donc c'est l'autorisation qui rend un client suffisamment fiable pour diffuser. Traitez 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 ce qu'il ne retient pas.
Une publication renvoie une réponse 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 réel, et c'est pourquoi l'état durable appartient à votre base de données et les événements annoncent 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.
Approfondissez 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, le lot et l'exclusion, les canaux cache expliquent le rejeu, et interroger l'état d'un canal est la lecture côté serveur pour l'occupation et les compteurs.
Le reste de Realtime
Une application, une paire de clés. Explorez les autres fonctionnalités.
PrésenceQui est dans la salle, qui vient de partir, et comment joindre une personne directement.SécuritéAbonnements signés, connexions autorisées et chiffrement de bout en bout.WebhooksVotre serveur est notifié quand un canal se remplit, se vide ou manque son cache.TarifsConnexions et messages par plan, à partir du palier gratuit.Premiers pasDe l'inscription à votre premier événement publié.Vue d'ensemble de l'API RealtimeLe produit complet : canaux, présence, sécurité, webhooks et clients.
Évoluez sans
perdre le contrôle.
Organisez vos équipes en espaces de travail, contrôlez l'accès à l'API et tracez les modifications via les journaux d'audit.
HarborOrganisationActif
Journal d'audit
Production- Espace de travail
- Production
- Ressource
- Agent d’envoi
- Accès en lectureLecture et écriture
Équipe Opérations clientsRôle de l’acteur AdministrateurRésultat RéussiHeure 22 sept., 09:42:18 UTC
Réussi