Una página de pedido puede necesitar una actualización al mismo tiempo que tu base de datos. Un webhook puede desencadenar el cambio en la base de datos. Tu servidor puede entonces publicar el estado resultante en las pantallas conectadas.
Bird Realtime entrega actualizaciones a través de WebSockets.
¿Qué son los canales, los miembros y las conexiones?
Un canal agrupa suscripciones. Una conexión es un WebSocket abierto. Un miembro es una identidad autenticada que se comparte con otros suscriptores.
Un canal de presence comparte qué miembros están suscritos. Un miembro puede usar varias conexiones, como pestañas de navegador independientes.
Bird crea un canal cuando su primera conexión se suscribe y lo elimina después de que la última se retira. Publicas en el nombre del canal sin crear un recurso de canal aparte.
Cada conexión recibe un identificador. Tu backend lo usa para aprobar una suscripción privada. Una publicación puede excluir esa conexión para evitar repetir su propia actualización.
Si un miembro abre tres pestañas, esas pestañas pueden crear tres conexiones bajo una misma identidad de miembro. Presence reporta al miembro uniéndose en la primera conexión y retirándose después de que se cierra la última. Cerrar la pestaña intermedia, por lo tanto, no elimina a ese miembro de la lista.
¿Quién puede suscribirse?
El prefijo del canal determina si una suscripción necesita autorización de tu backend.
Eliges un nombre de canal Bird de 1 a 164 caracteres, usando letras, dígitos y _ - = @ , . ;. Incluye el prefijo en esa longitud para que un nombre privado generado no supere el límite.
| Prefijo del nombre | Acceso |
|---|---|
| Sin prefijo private o presence | Público para clientes que tienen la app key. |
private- | Tu backend aprueba y firma cada suscripción. |
presence- | Tu backend aprueba la suscripción y proporciona la identidad de miembro compartida con los suscriptores. |
private-encrypted- | Acceso privado con el contenido de eventos cifrado mediante una clave que tú controlas. |
La app key aparece en el código del cliente, así que un nombre de canal público poco visible no protege datos confidenciales. Guarda el app secret en tu servidor y úsalo para firmar las aprobaciones de suscripción.
Para una suscripción privada, el cliente envía su identificador de conexión y el nombre del canal a tu endpoint de autorización. Tu servidor verifica el acceso antes de devolver la firma. Ese endpoint autoriza el acceso. No recibe cada evento publicado como lo haría un webhook.
¿Qué significa la diferencia en la práctica?
Usa webhooks para trabajo recuperable en tu servidor. Usa pub/sub para actualizaciones a clientes conectados.
Un webhook Bird envía un evento a un endpoint HTTPS que tú operas. Los reintentos abarcan aproximadamente 27,5 horas, con esperas ajustadas por variación aleatoria, sobrecarga del receptor y retrasos solicitados. Esa ventana le da a tu receptor tiempo para recuperarse. La reproducción de eventos perdidos puede recuperar entregas que siguen sin éxito.
Un canal Realtime envía tu evento publicado a los clientes suscritos. Un cliente desconectado puede perderlo. Un canal de caché puede entregar su último evento a un nuevo suscriptor mientras ese evento permanezca en caché. No conserva el historial de eventos intermedios.
Mantén el procesamiento confidencial del lado del servidor detrás de tu receptor de webhooks. Publica solo el estado que los clientes autorizados del canal pueden ver.
Los tipos de evento de webhook provienen del catálogo de Bird, como email.delivered. Con Realtime, tú eliges el nombre de evento de tu aplicación al publicar. El nombre event acepta de 1 a 200 caracteres. Los prefijos bird: y bird_internal: están reservados y no pueden nombrar los eventos de tu aplicación.
Los clientes también reciben eventos de protocolo sobre el éxito de la suscripción, cambios de miembros y conteos de conexiones. Esos eventos describen la conexión o el canal en sí, no el pedido o mensaje de tu aplicación.
¿Cómo los uso juntos?
Usa el evento almacenado del webhook para generar una actualización Realtime para los clientes conectados.
Recibe el evento de negocio en tu servidor. Actualiza el estado persistente antes de publicar. Luego publica el estado que necesitan los clientes conectados.
Para una página de pedido, el webhook puede desencadenar una actualización en la base de datos. Tu servidor entonces publica el estado del pedido actualizado para que la página del cliente cambie sin recargar.
Mantén ese estado de la base de datos legible tras la reconexión, porque un cliente desconectado puede perder publicaciones. Webhooks, polling o streaming compara las opciones de recuperación.
Realtime también tiene sus propios webhooks para la ocupación de canales y las llegadas o salidas de miembros. Configúralos a través del dashboard en lugar de la API pública de webhooks.
Descripción general de Realtime cubre las conexiones de clientes. Webhooks cubre las solicitudes entregadas a tu servidor.
En resumen
Un canal puede tener muchos suscriptores.
Una solicitud de webhook va a un único endpoint registrado. Una publicación va a los clientes suscritos a su canal.
Las suscripciones privadas necesitan aprobación del backend.
La app key aparece en el código del cliente. Los prefijos private y presence requieren una firma de tu servidor.
Los miembros pueden tener varias conexiones.
Un miembro que usa tres pestañas se une a presence en la primera conexión y se retira después de que se cierra la última.
Combina la recuperación de entregas con una vista conectada.
Usa la recuperación de webhooks para eventos del servidor y el estado almacenado para restaurar una vista Realtime después de una desconexión.