Un canale esiste non appena qualcosa vi si iscrive e scompare quando l'ultima connessione se ne va. Il nome determina il tipo: pubblico per tutto ciò che un visitatore può leggere, privato per tutto ciò che è riservato a un cliente, presence per una stanza con un elenco partecipanti, e il prefisso cache per lo stato che un utente in ritardo deve ricevere immediatamente.
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());
Il prefisso è la configurazione.
Non c'è nessun registro canali da mantenere aggiornato.
I canali sono il modello di indirizzamento della Bird Realtime API. Non ne create mai uno: vi iscrivete a un nome, e i primi tre caratteri di quel nome indicano all'edge come trattarlo. Un nome senza prefisso è pubblico. private- richiede al vostro backend di approvare ogni iscrizione. presence- fa lo stesso e associa un'identità. private-encrypted- sigilla il payload con una chiave che Bird non possiede mai. I nomi possono avere fino a 164 caratteri, sono case-sensitive, e sono l'unica parte di un canale su cui riflettere attentamente, perché un nome pubblico è visibile a chiunque possieda la chiave dell'app.
Cinque tipi di stanza.
Stesso protocollo, stesso client, stessa chiamata di pubblicazione. Ciò che cambia è il nome.
- 01
Canali pubblici.
Nessun endpoint di autorizzazione, nessuna registrazione. Chiunque possieda la chiave dell'app può iscriversi, il che li rende perfetti per risultati di build, punteggi live, informazioni sui voli o una pagina di stato, e inadatti a tutto ciò che è riservato a un singolo cliente. Evitate gli identificatori nel nome: orders non rivela nulla, orders-user-4821 rivela che l'utente 4821 esiste.
- 02
Canali privati.
Un nome private- instrada l'iscrizione attraverso il vostro endpoint, che verifica la sessione e firma l'ID di connessione e il nome del canale con il segreto dell'app. Le vostre regole, la vostra sessione, il vostro 403. L'edge verifica la firma e nient'altro raggiunge il canale.
- 03
Canali presence.
Autorizzazione del canale privato più un'identità, così ogni iscritto ottiene l'elenco dei membri e viene informato di arrivi e partenze. Questo è l'unico tipo di canale con un elenco partecipanti.
- 04
Canali crittografati.
Un canale private-encrypted- trasporta payload che il vostro server sigilla con una chiave master da 32 byte che non compare mai in una richiesta Realtime. L'edge e tutto ciò che si trova tra esso e il browser vedono testo cifrato. I nomi di canale e evento restano in chiaro, quindi scegliete nomi che non rivelino cosa state proteggendo.
- 05
Canali con cache.
Anteponete cache- al nome, dopo qualsiasi prefisso di tipo, e il canale memorizza l'ultimo evento pubblicato via API e lo riproduce a ogni nuovo iscritto. L'iscrizione funge anche da fetch dello stato iniziale. Due vincoli da considerare nella progettazione: viene conservato solo l'evento più recente, e potrebbe scadere prima del limite di 30 minuti, quindi inserite l'intero stato in ogni payload e ripopolate dal webhook di cache-miss anziché assumere che la cache sia attiva.
Una pubblicazione, fino a cento canali.
La pubblicazione è una normale chiamata REST dal vostro server. Indicate fino a 100 canali in un'unica richiesta e l'edge distribuisce l'evento a tutti. Un batch trasporta fino a 10 eventi non correlati, ciascuno verso il proprio canale. Passate l'ID di connessione del client attivo come exclude_connection_id e la scheda che ha già applicato la modifica localmente verrà saltata. Richiedete il conteggio delle connessioni o dei membri con include e la risposta vi indicherà lo stato di ogni canale al momento della pubblicazione. Riprovate con la stessa chiave di idempotenza e non consegnerete due volte.
// 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);
}
I client possono comunicare direttamente tra loro.
Un indicatore di digitazione o la posizione di un cursore non deve passare dalla vostra API. Abilitate gli eventi client sull'app e un client iscritto può inviare un evento chiamato client-qualcosa direttamente agli altri nel canale, con un limite di 10 al secondo per connessione. Funzionano solo su canali privati e presence, ed è intenzionale: la chiave dell'app è presente nella vostra pagina, quindi l'autorizzazione è ciò che rende un client abbastanza affidabile per trasmettere. Trattate ciò che arriva come un segnale, mai come stato autorevole, perché l'edge non valida il payload.
Cosa ricorda e cosa non ricorda un canale.
Una pubblicazione restituisce una risposta appena l'edge ha accettato l'evento. La consegna è asincrona, non c'è ricevuta per singolo client, e un client che si disconnette durante la consegna non riceverà nuovamente l'evento alla riconnessione. Questo è il contratto onesto, ed è il motivo per cui lo stato durevole appartiene al vostro database e gli eventi annunciano che è cambiato. I limiti sono gli stessi su ogni piano: 100 canali per pubblicazione, 10 eventi per batch, 10 KB per payload, nomi di canale di 164 caratteri.
Approfondite nella documentazione.
La panoramica Realtime definisce canali, membri e connessioni in un'unica pagina. Pubblicare eventi copre broadcast, batch ed esclusione, canali con cache spiega il replay, e interrogare lo stato del canale è la lettura lato server per occupazione e conteggi.
Mettilo in pratica.
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Il resto di Realtime
Un'app, una coppia di chiavi. Esplorate le altre funzionalità.
Iscriviti a un nome e inizia a pubblicare.
Crea un'app, integra la chiave pubblica nel tuo client e mantieni il segreto sul tuo server. Il piano gratuito copre 100 connessioni simultanee.