Presenza in tempo reale
Chi è qui. Senza interrogare la tua API.
Iscriviti a un canale di presenza e il roster attuale arriva con la sottoscrizione: la stanza si presenta già popolata, non vuota. Dopodiché, ogni client riceve gli stessi eventi di ingresso e uscita. Il tuo backend assegna a ciascun membro la propria identità al momento della firma della sottoscrizione, ed è questo a rendere la lista affidabile.
import type { Member } from "@messagebird/realtime";
const room = bird.subscribe("presence-room-42");
room.bind("bird:subscription_succeeded", () => {
// The roster is already here. Paint it before anyone moves.
render({ me: room.myId, members: [...room.members.values()] });
});
room.bind<Member>("bird:member_added", (member) => join(member.member_id));
room.bind<Member>("bird:member_removed", (member) => leave(member.member_id));
input.addEventListener("input", () => {
room.trigger("client-typing", { at: Date.now() });
});
Un membro è una persona, non un socket.
Tre schede sono un solo membro.
La presenza fa parte della Bird Realtime API e conta le identità, non le sessioni. Un membro entra nella lista quando la sua prima connessione si iscrive e la lascia quando l'ultima si chiude; le schede intermedie non producono nulla, quindi il roster non sfarfalla ogni volta che qualcuno apre una finestra duplicata. Se ti serve il conteggio dei socket, è un'impostazione dell'app separata e un evento separato.
Cosa ti offre la presenza
Il roster, le variazioni e l'identità su cui appoggiarli. Tutto firmato dal tuo backend.
- 01
Il roster, all'arrivo.
bird:subscription_succeeded trasporta la lista dei membri attuale, così il primo rendering mostra la stanza reale. Applichi ingressi e uscite sopra di essa invece di costruire la lista da zero.
- 02
Un'identità sotto il tuo controllo.
Il tuo endpoint di autorizzazione restituisce un member id e un member info opzionale, e firma esattamente quella stringa. Un client può chiedere di iscriversi ma non può scegliere chi è. Limita il member info a piccoli dati di profilo pubblici come un nome visualizzato o un avatar: ogni membro del canale lo riceve, ed è limitato a 1 KB.
- 03
Letture dal tuo server.
Elenca i membri di un canale, oppure richiedi member_count senza elencarli, direttamente dall'API. Nessuna delle due operazioni richiede una sottoscrizione, così un backend può sapere chi è in una stanza senza entrarci. Il conteggio dei membri è esclusivo della presenza; richiederlo su un canale pubblico o privato genera un errore di validazione, perché quei canali non hanno membri.
- 04
Eventi client tra peer.
Un canale di presenza è uno dei due contesti in cui un client può inviare un evento direttamente agli altri, così indicatori di digitazione e posizioni del cursore non toccano mai la tua API. Dieci al secondo per connessione, e il mittente non riceve il proprio evento.
- 05
Conteggio delle connessioni, quando lo desideri.
I membri rispondono a chi è qui. Attiva il conteggio delle connessioni e i relativi eventi, e bird:connection_count indica quanti socket sono aperti sul canale — il numero a cui la persona con tre schede contribuisce tre.
Eventi indirizzati al membro
A volte la destinazione è una persona, non una stanza.
Un membro autenticato può essere contattato direttamente, senza specificare un canale né autorizzare una sottoscrizione. Una sola chiamata raggiunge ogni connessione associata a quell'identità, su ogni scheda e dispositivo, e nessun altro, anche se un altro membro registra lo stesso nome evento. Se non ha connessioni attive la chiamata ha comunque successo: la consegna non viene accodata, quindi salva la notifica e caricala quando torna online. La stessa identità è ciò che il disconnect prende di mira quando una sessione deve terminare immediatamente.
// Address the person, not a channel. Every tab, every device.
await bird.realtime.members.send(APP_ID, "u_42", {
event: "order.shipped",
data: { order_id: "ord_123" },
});
// The roster, read from your server. No subscription needed.
const roster = await bird.realtime.channels.members(APP_ID, "presence-room-42");
// Password changed. Close every connection they hold.
await bird.realtime.members.disconnect(APP_ID, "u_42");
Una lista contatti non è una stanza.
La presenza risponde a chi è in questa stanza con me. Gli eventi watchlist rispondono se le persone che mi interessano sono online da qualche parte. L'identità firmata di un membro può contenere fino a 100 member id, e con gli eventi watchlist abilitati la connessione viene informata quando uno di loro va online o offline, con lo stato attuale dell'intera lista consegnato subito dopo il sign-in. Poiché la lista risiede nell'identità firmata, il tuo endpoint decide chi può osservare chi. Nessun canale per relazione, e le persone osservate non devono fare nulla oltre ad autenticarsi.
Approfondisci nella documentazione.
Canali di presenza copre il roster, il member info e le letture lato server. Autorizzazione dei canali è il contratto che il tuo backend implementa, invio di eventi a un membro confronta gli eventi membro con i canali privati, e eventi watchlist è la variante con lista di follow.
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. Esplora le altre funzionalità.
Mostra la stanza, non uno stato di caricamento.
Presenza, eventi client e consegna indirizzata ai membri sono inclusi in ogni app Realtime. Il piano gratuito copre 100 connessioni simultanee.