Un canal existe en cuanto algo se suscribe a él y desaparece cuando la última conexión se va. Su nombre define el tipo: público para todo lo que un visitante puede leer, privado para todo lo que pertenece a un cliente, de presencia para una sala con lista de miembros, y con prefijo de caché para el estado que un usuario tardío necesita de inmediato.
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());
El prefijo es la configuración.
No hay un registro de canales que mantener sincronizado.
Los canales son el modelo de direccionamiento de la API de Bird Realtime. Nunca se crea uno: se suscribe a un nombre, y los tres primeros caracteres de ese nombre indican al edge cómo tratarlo. Un nombre sin prefijo es público. private- solicita que su backend apruebe cada suscripción. presence- hace lo mismo y adjunta una identidad. private-encrypted- sella la carga con una clave que Bird nunca posee. Los nombres admiten hasta 164 caracteres, distinguen entre mayúsculas y minúsculas, y son la única parte de un canal que debería considerar con cuidado, porque un nombre público es visible para cualquiera que tenga la clave de la aplicación.
Cinco tipos de sala.
Mismo protocolo, mismo cliente, misma llamada de publicación. Lo que cambia es el nombre.
- 01
Canales públicos.
Sin endpoint de autorización, sin registro. Cualquiera con la clave de la aplicación puede suscribirse, lo que los hace ideales para resultados de compilación, marcadores en vivo, información de vuelos o una página de estado, e inadecuados para cualquier cosa asociada a un solo cliente. Mantenga los identificadores fuera del nombre: orders no revela nada, orders-user-4821 revela que el usuario 4821 existe.
- 02
Canales privados.
Un nombre con private- enruta la suscripción a través de su propio endpoint, que verifica la sesión y firma el ID de conexión y el nombre del canal con el secreto de la aplicación. Sus reglas, su sesión, su 403. El edge verifica la firma y nada más llega al canal.
- 03
Canales de presencia.
Autorización de canal privado más una identidad, de modo que cada suscriptor obtiene la lista de miembros y recibe notificaciones de llegadas y salidas. Este es el único tipo de canal con lista de miembros.
- 04
Canales cifrados.
Un canal private-encrypted- transporta cargas que su servidor sella con una clave maestra de 32 bytes que nunca aparece en una solicitud de Realtime. El edge y todo lo que hay entre él y el navegador ven texto cifrado. Los nombres de canal y evento permanecen en claro, así que elija nombres que no revelen lo que está protegiendo.
- 05
Canales con caché.
Anteponga cache- al nombre, después de cualquier prefijo de tipo, y el canal recordará su último evento publicado vía API y lo reproducirá para cada nuevo suscriptor. La suscripción funciona también como la carga del estado inicial. Dos restricciones a tener en cuenta en el diseño: solo se conserva el evento más reciente y puede expirar antes del límite de 30 minutos, así que incluya el estado completo en cada carga y repóblelo desde el webhook de cache-miss en lugar de asumir que la caché está activa.
Una publicación, hasta cien canales.
Publicar es una llamada REST ordinaria desde su servidor. Nombre hasta 100 canales en una solicitud y el edge distribuye el evento a todos ellos. Un lote transporta hasta 10 eventos no relacionados, cada uno a su propio canal. Pase el ID de conexión del cliente que actúa como exclude_connection_id y la pestaña que ya aplicó el cambio localmente se omitirá. Solicite el conteo de conexiones o miembros con include y la respuesta le indicará el estado de cada canal en el momento de la publicación. Reintente con la misma clave de idempotencia y no entregará dos veces.
// 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);
}
Los clientes pueden comunicarse entre sí directamente.
Un indicador de escritura o la posición de un cursor no necesitan pasar por su API. Active los eventos de cliente en la aplicación y un cliente suscrito puede emitir un evento llamado client-algo directamente a los demás en el canal, con un límite de 10 por segundo por conexión. Solo funcionan en canales privados y de presencia, lo cual es deliberado: la clave de la aplicación se envía en su página, así que la autorización es lo que hace a un cliente lo suficientemente confiable para transmitir. Trate lo que llega como una señal, nunca como estado autoritativo, porque el edge no valida la carga.
Lo que un canal recordará y lo que no.
Una publicación retorna una vez que el edge ha aceptado el evento. La entrega es asíncrona, no hay acuse de recibo por cliente, y un cliente que se desconecta a mitad de la entrega no recibirá el evento de nuevo al reconectarse. Ese es el contrato honesto, y es por eso que el estado duradero pertenece a su base de datos y los eventos anuncian que cambió. Los límites son los mismos en todos los planes: 100 canales por publicación, 10 eventos por lote, 10 KB por carga, nombres de canal de 164 caracteres.
Profundice en la documentación.
La descripción general de Realtime define canales, miembros y conexiones en una sola página. Publicación de eventos cubre difusión, lotes y exclusión, canales con caché explica la reproducción, y consulta del estado del canal es la lectura del lado del servidor para ocupación y conteos.
Ponlo en práctica.
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
El resto de Realtime
Una aplicación, un par de claves. Explore las demás capacidades.
Suscríbete a un nombre y comienza a publicar.
Crea una app, incluye la clave pública en tu cliente y mantén la secreta en tu servidor. El plan gratuito cubre 100 conexiones simultáneas.