Une page de commande peut avoir besoin d'une mise à jour en même temps que votre base de données. Un webhook peut déclencher la modification en base. Votre serveur peut ensuite publier l'état résultant vers les écrans connectés.
Bird Realtime distribue les mises à jour via WebSockets.
Que sont les canaux, les membres et les connexions ?
Un canal regroupe les abonnements. Une connexion est un WebSocket ouvert. Un membre est une identité authentifiée partagée avec les autres abonnés.
Un canal de présence indique quels membres sont abonnés. Un membre peut utiliser plusieurs connexions, par exemple des onglets de navigateur distincts.
Bird crée un canal lorsque sa première connexion s'abonne et le supprime après le départ de la dernière. Vous publiez sur le nom du canal sans créer de ressource canal séparée.
Chaque connexion reçoit un identifiant. Votre backend l'utilise pour approuver un abonnement privé. Une publication peut exclure cette connexion pour éviter de renvoyer en écho sa propre mise à jour.
Si un membre ouvre trois onglets, ces onglets peuvent créer trois connexions sous une même identité de membre. La présence signale l'arrivée du membre sur la première connexion et son départ après la fermeture de la dernière connexion. Fermer l'onglet du milieu ne retire donc pas ce membre de la liste.
Qui est autorisé à s'abonner ?
Le préfixe du canal détermine si un abonnement nécessite une autorisation de votre backend.
Vous choisissez un nom de canal Bird de 1 à 164 caractères, composé de lettres, de chiffres et de _ - = @ , . ;. Incluez le préfixe dans cette longueur pour qu'un nom privé généré reste dans la limite.
| Préfixe du nom | Accès |
|---|---|
| Aucun préfixe private ou presence | Public pour les clients disposant de la clé d'application. |
private- | Votre backend approuve et signe chaque abonnement. |
presence- | Votre backend approuve l'abonnement et fournit l'identité de membre partagée avec les abonnés. |
private-encrypted- | Accès privé avec le contenu des événements chiffré à l'aide d'une clé que vous contrôlez. |
La clé d'application apparaît dans le code client : un nom de canal public obscur ne protège donc pas les données confidentielles. Conservez le secret d'application sur votre serveur et utilisez-le pour signer les approbations d'abonnement.
Pour un abonnement privé, le client envoie son identifiant de connexion et le nom du canal à votre endpoint d'autorisation. Votre serveur vérifie l'accès avant de renvoyer la signature. Cet endpoint autorise l'accès. Il ne reçoit pas chaque événement publié comme le ferait un webhook.
Que signifie cette différence en pratique ?
Utilisez les webhooks pour le travail récupérable sur votre serveur. Utilisez le pub/sub pour les mises à jour vers les clients connectés.
Un webhook Bird envoie un événement à un endpoint HTTPS que vous exploitez. Les réessais s'étalent sur environ 27,5 heures, avec des délais ajustés par une variation aléatoire, la surcharge du récepteur et les délais demandés. Cette fenêtre donne à votre récepteur le temps de se rétablir. Le rejeu des événements manqués peut récupérer les livraisons restées infructueuses.
Un canal Realtime envoie votre événement publié aux clients abonnés. Un client déconnecté peut le manquer. Un canal cache peut fournir son dernier événement à un nouvel abonné tant que cet événement reste en cache. Il ne conserve pas l'historique des événements intermédiaires.
Gardez le traitement confidentiel côté serveur derrière votre récepteur de webhook. Ne publiez que l'état que les clients autorisés du canal peuvent voir.
Les types d'événements webhook proviennent du catalogue de Bird, par exemple email.delivered. Avec Realtime, vous choisissez le nom d'événement de votre application lors de la publication. Le nom event accepte de 1 à 200 caractères. Les préfixes bird: et bird_internal: sont réservés et ne peuvent pas nommer vos événements applicatifs.
Les clients reçoivent aussi des événements de protocole concernant le succès de l'abonnement, les changements de membres et le nombre de connexions. Ces événements décrivent la connexion ou le canal lui-même, et non la commande ou le message de votre application.
Comment les utiliser ensemble ?
Utilisez l'événement stocké du webhook pour déclencher une mise à jour Realtime destinée aux clients connectés.
Recevez l'événement métier sur votre serveur. Mettez à jour l'état durable avant de publier. Publiez ensuite l'état dont les clients connectés ont besoin.
Pour une page de commande, le webhook peut déclencher une mise à jour en base de données. Votre serveur publie ensuite l'état de commande mis à jour pour que la page du client change sans rechargement.
Maintenez cet état en base de données lisible après une reconnexion, car un client déconnecté peut manquer des publications. Webhooks, polling ou streaming compare les options de récupération.
Realtime dispose aussi de ses propres webhooks pour l'occupation des canaux et les arrivées ou départs de membres. Configurez-les via le tableau de bord plutôt que via l'API de webhooks publics.
Présentation de Realtime couvre les connexions client. Webhooks couvre les requêtes livrées à votre serveur.
En bref
Un canal peut avoir de nombreux abonnés.
Une requête webhook est envoyée à un seul endpoint enregistré. Une publication est envoyée aux clients abonnés à son canal.
Les abonnements privés nécessitent une approbation du backend.
La clé d'application apparaît dans le code client. Les préfixes private et presence exigent une signature de votre serveur.
Les membres peuvent avoir plusieurs connexions.
Un membre utilisant trois onglets rejoint la présence sur la première connexion et la quitte après la fermeture de la dernière connexion.
Combinez la récupération de livraison avec une vue connectée.
Utilisez la récupération par webhook pour les événements serveur et l'état stocké pour restaurer une vue Realtime après une déconnexion.