Visión general de Realtime
Realtime envía eventos a clientes conectados a través de WebSockets. Tu servidor publica un evento en un canal con nombre y los clientes suscritos lo reciben sin hacer polling.
Usa Realtime para cambios que un cliente necesita sin hacer otra solicitud, como actualizaciones de pedidos, mensajes de chat, cambios en el dashboard o trabajos en segundo plano completados.
Canales, miembros y conexiones
Tres palabras describen el modelo. No son intercambiables.
Un canal es una sala con nombre. Existe mientras al menos una conexión está suscrita y desaparece cuando la última se va. Los nombres de canal admiten hasta 164 letras, dígitos y estos caracteres: _ - = @ , . ;.
Una conexión es un WebSocket abierto. Recibe un ID (26896.319537) cuando se conecta. La autorización firma este ID y la publicación puede excluirlo de la entrega.
Un miembro es una identidad autenticada en un canal de presencia. Un miembro puede tener varias conexiones, como tres pestañas del navegador. Los eventos de presencia se disparan cuando la primera conexión del miembro se une y cuando la última se va. Las pestañas intermedias no los producen.
Los tres tipos de canal
El prefijo del nombre del canal selecciona el tipo de canal y su comportamiento de autorización.
| Nombre | Quién puede suscribirse | Tiene miembros |
|---|---|---|
| orders | cualquiera con la clave de la app | no |
| private-orders | solo clientes que tu backend firma | no |
| presence-lobby | solo clientes que tu backend firma | sí |
Un canal público es legible por cualquiera con la clave de la app, que se incluye en el código del cliente. Publica solo datos que cualquier visitante pueda ver. Consulta Canales públicos.
Un canal privado pide a tu backend que apruebe cada suscripción. El cliente envía el ID de conexión y el nombre del canal a tu endpoint, que devuelve una firma calculada con el secreto de la app. Consulta Canales privados. Un canal private-encrypted-… también cifra los payloads con una clave que guardan tus servidores. Consulta Canales cifrados.
Un canal de presencia añade una identidad a la autorización de canal privado. Cada suscriptor recibe la lista de miembros y los cambios a través de member_id y opcionalmente member_info. Consulta Canales de presencia.
Eventos que recibe el cliente
Los eventos de aplicación son tuyos: eliges el nombre al publicar (order-updated, message.created) y vinculas un handler a él. Junto a ellos, el cliente reemite eventos de ciclo de vida bajo el prefijo bird:, que vinculas exactamente igual que los tuyos:
- bird:subscription_succeeded se dispara una vez por canal cuando la suscripción está activa. En un canal de presencia incluye la lista actual de miembros, para que puedas renderizar la sala antes de que alguien se mueva.
- bird:member_added y bird:member_removed se disparan en canales de presencia cuando los miembros llegan y se van. member_added se dispara cuando la primera conexión de una persona se suscribe; member_removed solo cuando la última se va. Una segunda pestaña que se abre y se cierra no produce ninguno de los dos.
- bird:connection_count indica cuántas conexiones están suscritas al canal, si la app tiene habilitados el conteo de conexiones y los eventos de conteo de conexiones. Cuenta conexiones, así que el miembro con tres pestañas cuenta tres.
- bird:subscription_error se dispara cuando una suscripción es rechazada, generalmente porque la autorización falló.
Los nombres que comienzan con client- están reservados para eventos que los clientes se envían directamente entre sí, lo cual es una configuración de app separada y solo se permite en canales privados y de presencia.
Tu servidor también puede recibir eventos, como webhooks, cuando un canal pasa a estar ocupado o vacío y cuando los miembros se unen o se van. Llegan como eventos realtime.* a través de los mismos endpoints de webhook que el resto de Bird.
Los clientes
Tres clientes reciben eventos a través del mismo protocolo. Usa @messagebird/realtime para navegadores y Node.js, BirdRealtime para iOS, macOS y Linux, o com.messagebird:bird-realtime para Android y la JVM del servidor. Cada uno soporta suscripciones, bindings, presencia, signin() y eventos de cliente.
Mantén el secreto de la app en tu servidor. Los SDK de servidor lo usan para publicar eventos, autorizar canales y desconectar miembros.
Apps, claves y regiones
Una app es un entorno aislado con sus propias credenciales y su propio espacio de nombres de canales. Dos apps nunca ven los canales de la otra, lo que convierte a la app en el límite adecuado entre tus entornos de staging y producción.
Cada app usa una región inmutable seleccionada al crearla. Usa Listar regiones de Realtime para obtener los identificadores aceptados y elige la región más cercana a tus usuarios.
Cada app tiene tres valores con usos distintos:
- El app ID (rap_…) identifica la app en las llamadas Bird API y aparece en cada ruta /v1/realtime/apps/….
- La clave es pública. Los navegadores se conectan con ella y es seguro incluirla en el código del cliente.
- El secreto se empareja con la clave para autenticar llamadas del lado del servidor y para firmar la autorización de canales. Se muestra una sola vez, al crearlo. Cualquiera que lo tenga puede publicar en tu app y falsificar identidades de presencia.
Gestiona apps y rota claves en la página Realtime apps. Crea una segunda clave, despliégala y luego revoca la anterior.
Visibilidad
La página Métricas de Realtime muestra tres valores por app o a nivel de todo el espacio de trabajo para la ventana seleccionada:
- Conexiones máximas es el número más alto de conexiones abiertas al mismo tiempo dentro de la ventana. Este pico es el valor al que se aplica el límite de conexiones.
- Conexiones promedio es la media de los picos diarios. No promedia cada muestra. Un espacio de trabajo que tiene picos cada tarde y está inactivo por la noche muestra un promedio muy por encima de sus horas tranquilas.
- Mensajes cuenta entregas de eventos, una por canal: una publicación que nombra 50 canales cuenta como 50. También incluye los eventos que el protocolo envía en tu nombre, así que las uniones de presencia y las actualizaciones de conteo de conexiones se suman al mismo número, por lo que puede superar las publicaciones que hizo tu código.
El consumo se agrega en intervalos de un minuto, así que el tráfico reciente puede tardar varios minutos en aparecer. El API de consumo solo está disponible en el dashboard por ahora. Para visibilidad programática, registra las publicaciones en tus sistemas o deriva la actividad de los webhooks de realtime.*.
Planes y límites
El plan gratuito cubre 100 conexiones simultáneas y 200.000 mensajes por día, entre todas las apps de un espacio de trabajo. Crear más apps no eleva el techo, porque se aplica al espacio de trabajo.
Los planes de pago comienzan en $25 por mes para 250 conexiones simultáneas y 500.000 mensajes por día, y escalan hasta 30.000 conexiones y 90 millones de mensajes por día. Precios de Realtime lista cada paso.
Los límites por solicitud aplican en todos los planes: una publicación nombra como máximo 100 canales, un lote lleva como máximo 10 eventos y el payload de un evento tiene un tope de 10 KB serializado.
Próximos pasos
- Envía tu primer evento de Realtime recorre el flujo completo de principio a fin.
- Publicar eventos cubre la publicación desde tu servidor, el envío por lotes y la exclusión del cliente que originó el evento.
- Autorizar canales es el contrato que tu backend implementa para canales privados y de presencia.
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.