Une mise à jour de commande peut avoir deux consommateurs : votre base de données et le client qui consulte une page de commande. Ils ont besoin de comportements de récupération différents quand une connexion se coupe.
Votre base de données a besoin d'un enregistrement récupérable de l'événement. La page du client peut n'avoir besoin que du dernier état de la commande après reconnexion.
Quelles sont les quatre options ?
Bird propose les webhooks, Realtime, un flux d'événements de tableau de bord et des lectures API que vous pouvez interroger par polling.
Utilisez les webhooks pour recevoir des événements sur votre serveur. Utilisez Realtime pour mettre à jour les clients connectés. Le flux SSE envoie les modifications de ressources à une session de tableau de bord. Le polling permet à votre application de lire l'état des ressources selon un calendrier.
| Mécanisme | Direction | Authentification | Récupération après déconnexion |
|---|---|---|---|
| Webhooks | Bird envoie vers votre serveur. | Votre récepteur vérifie une signature avec son secret de point de terminaison. | Les livraisons échouées font l'objet de nouvelles tentatives. Les événements manqués peuvent être rejoués. |
| Realtime | Votre serveur publie vers les clients connectés. | Les clients se connectent avec une clé d'application. Les abonnements privés nécessitent une autorisation côté backend. | Les clients qui se reconnectent ont besoin d'une récupération d'état. |
| Flux SSE | Bird envoie les modifications de ressources à une session de tableau de bord. | Un cookie de session de tableau de bord. | Relisez la ressource pour obtenir son état. |
| Polling | Votre application interroge Bird pour obtenir l'état. | Une clé API. | Une lecture ultérieure renvoie l'état de la ressource, sans reconstituer chaque transition. |
Quand les webhooks sont-ils la bonne réponse ?
Utilisez les webhooks quand votre serveur doit réagir aux événements et récupérer les livraisons manquées.
Vous enregistrez un point de terminaison HTTPS accessible publiquement. Abonnez-le aux types d'événements dont vous avez besoin. Votre récepteur vérifie d'abord la signature. Il stocke ensuite l'événement. Il accuse réception de la livraison avant le début d'un traitement long.
Bird effectue jusqu'à huit tentatives sur environ 27,5 heures avant ajustements de temporisation. Cette fenêtre donne au récepteur le temps de se rétablir après une panne. Le rejeu des événements manqués offre un chemin de récupération supplémentaire.
Dédupliquez sur webhook-id car un même événement peut arriver plusieurs fois. Comparez les horodatages d'occurrence des événements avant d'écraser l'état, car les événements peuvent arriver dans le désordre.
Nouvelles tentatives de webhook échouées couvre les limites de récupération. Gestion des doublons couvre le stockage sûr de l'événement avant de renvoyer un succès.
Quand utiliser Realtime à la place ?
Utilisez Realtime quand un navigateur ou une application connectée a besoin de mises à jour au fil des publications de votre serveur.
Un canal est une destination nommée à laquelle les clients s'abonnent. Votre serveur publie un événement vers ce nom, et les clients abonnés le reçoivent via leurs connexions. Cela permet de mettre à jour une page de commande, une conversation de chat ou un indicateur de progression sans rechargement.
Realtime ne rejoue pas tous les événements qu'un client déconnecté a manqués. Conservez un état durable dans votre base de données et restaurez la vue après reconnexion.
Un canal avec cache conserve son dernier événement pour les nouveaux abonnés tant que cette valeur en cache reste disponible. Il ne conserve aucun historique d'événements. Si deux mises à jour surviennent pendant qu'un client est hors ligne, la dernière valeur en cache ne permet pas de récupérer la mise à jour intermédiaire.
La clé d'application apparaît dans le code client, donc un canal public peut être lu par un visiteur disposant de cette clé. Un canal commençant par private- exige que votre backend autorise l'abonnement. Un canal presence- partage aussi les identités des membres abonnés.
Les noms de canaux acceptent de 1 à 164 caractères composés de lettres, chiffres et _ - = @ , . ;. Le préfixe fait partie de cette limite, donc incluez-le quand vous validez un nom généré.
Realtime envoie aussi des webhooks quand un canal gagne son premier abonné ou perd le dernier. Les webhooks d'appartenance signalent quels membres ont rejoint ou quitté le canal. Configurez-les via le tableau de bord. Publication/abonnement versus webhooks explique comment les deux mécanismes s'articulent.
Bird dispose-t-il d'un point de terminaison SSE ?
Bird dispose d'un point de terminaison SSE, getEventsStream, pour les sessions de tableau de bord authentifiées.
GET /v1/events/stream signale les modifications apportées aux ressources API. Une notification identifie le type de ressource, l'identifiant et l'horodatage d'occurrence pour que le tableau de bord puisse récupérer les données de la ressource.
Le point de terminaison accepte un cookie de session de tableau de bord. Il n'accepte pas de clé API, donc utilisez les webhooks ou le polling pour une intégration par clé API.
Quand le polling est-il approprié ?
Utilisez le polling quand vous avez besoin de l'état d'une ressource, ne pouvez pas recevoir de requêtes entrantes ou n'avez pas d'événement public pour le changement.
Utilisez le polling pour vérifier si un opérateur a approuvé votre numéro gratuit pour l'envoi de SMS. Bird n'a pas d'événement webhook public pour cette décision de vérification. Lisez la vérification selon un calendrier via bird sms tfn verifications get, ou l'outil agent correspondant. L'opération de commande est en dehors du bundle public API.
Le polling convient aussi pour un réseau qui autorise les requêtes sortantes mais ne peut pas exposer de récepteur. Si vous avez seulement besoin de l'état actuel, la lecture de la ressource évite de la reconstituer à partir des événements passés.
Les lectures et les listings consomment des budgets de limitation du débit par identifiant actif au sein d'une organisation. Attendez avant de relancer une requête après une réponse HTTP 429. Adaptez l'intervalle à la rapidité avec laquelle votre application doit découvrir un changement.
Webhooks, Realtime et limites de débit couvrent la configuration de ces options.
Que choisir ?
Choisissez en fonction de qui consomme la mise à jour et de ce qui doit survivre à une déconnexion.
- Webhooks quand votre serveur doit traiter des événements avec des tentatives de renvoi et une récupération des événements manqués.
- Realtime quand des écrans connectés ont besoin de mises à jour et peuvent récupérer l'état stocké après reconnexion.
- Polling quand vous avez besoin de l'état d'une ressource, ne pouvez pas exposer de récepteur ou n'avez pas d'événement public.
- Le flux SSE pour une session de tableau de bord Bird authentifiée.
En bref
Choisissez les webhooks pour le traitement des événements côté serveur.
Utilisez les tentatives de renvoi et le rejeu des événements manqués quand votre serveur doit rétablir la livraison après une panne.
Choisissez Realtime pour les écrans connectés.
Restaurez la vue à partir de l'état stocké quand le client se reconnecte.
Choisissez le polling pour l'état des ressources.
Utilisez le polling quand vous ne pouvez pas exposer un récepteur, n'avez pas d'événement public ou avez seulement besoin de l'état de la ressource.
Utilisez le SSE pour une session de tableau de bord Bird.
Le flux nécessite l'authentification d'une session de tableau de bord.