Panoramica di Realtime
Realtime invia eventi ai client connessi tramite WebSocket. Il tuo server pubblica un evento su un canale con nome e i client iscritti lo ricevono senza polling.
Usa Realtime per le variazioni che un client deve ricevere senza fare un'altra richiesta, ad esempio aggiornamenti di ordini, messaggi di chat, modifiche alla dashboard o job in background completati.
Canali, membri e connessioni
Tre parole descrivono il modello. Non sono intercambiabili.
Un channel è una stanza con nome. Esiste finché almeno una connessione è iscritta e scompare quando l'ultima si disconnette. I nomi dei canali ammettono fino a 164 lettere, cifre e questi caratteri: _ - = @ , . ;.
Una connection è un WebSocket aperto. Riceve un ID (26896.319537) al momento della connessione. L'autorizzazione firma questo ID e la pubblicazione può escluderlo dalla consegna.
Un member è un'identità autenticata su un canale presence. Un membro può avere più connessioni, ad esempio tre schede del browser. Gli eventi presence scattano quando la prima connessione del membro si iscrive e quando l'ultima si disconnette. Le schede intermedie non li producono.
I tre tipi di canale
Il prefisso del nome del canale seleziona il tipo di canale e il suo comportamento di autorizzazione.
| Nome | Chi può iscriversi | Ha membri |
|---|---|---|
| orders | chiunque possieda la chiave dell'app | no |
| private-orders | solo i client firmati dal tuo backend | no |
| presence-lobby | solo i client firmati dal tuo backend | sì |
Un canale public è leggibile da chiunque possieda la chiave dell'app, che viene distribuita nel codice client. Pubblica solo dati che ogni visitatore può vedere. Vedi Canali pubblici.
Un canale private richiede al tuo backend di approvare ogni iscrizione. Il client invia l'ID della connessione e il nome del canale al tuo endpoint, che restituisce una firma calcolata con il secret dell'app. Vedi Canali privati. Un canale private-encrypted-… cifra anche i payload con una chiave custodita dai tuoi server. Vedi Canali cifrati.
Un canale presence aggiunge un'identità all'autorizzazione del canale privato. Ogni iscritto riceve la lista dei membri e le variazioni tramite member_id e l'opzionale member_info. Vedi Canali presence.
Eventi ricevuti dal client
Gli eventi applicativi sono i tuoi: scegli il nome al momento della pubblicazione (order-updated, message.created) e associ un handler. Accanto a questi, il client riemette eventi di ciclo di vita con il prefisso bird:, che associ esattamente come i tuoi:
- bird:subscription_succeeded scatta una volta per canale quando l'iscrizione è attiva. Su un canale presence include la lista corrente dei membri, così puoi renderizzare la stanza prima che qualcuno si muova.
- bird:member_added e bird:member_removed scattano sui canali presence quando i membri arrivano e se ne vanno. member_added scatta quando la prima connessione di una persona si iscrive; member_removed solo quando l'ultima si disconnette. L'apertura e la chiusura di una seconda scheda non producono nessuno dei due.
- bird:connection_count indica quante connessioni sono iscritte al canale, se l'app ha il conteggio delle connessioni e gli eventi di conteggio connessioni abilitati. Conta le connessioni, quindi il membro con tre schede conta tre.
- bird:subscription_error scatta quando un'iscrizione viene rifiutata, nella maggior parte dei casi perché l'autorizzazione è fallita.
I nomi che iniziano con client- sono riservati agli eventi che i client inviano direttamente tra loro, una funzione regolata da un'impostazione separata dell'app e consentita solo sui canali privati e presence.
Il tuo server può anche ricevere eventi, come webhook, quando un canale diventa occupato o vuoto e quando i membri si uniscono o se ne vanno. Arrivano come eventi realtime.* attraverso gli stessi endpoint webhook del resto di Bird.
I client
Tre client ricevono eventi attraverso lo stesso protocollo. Usa @messagebird/realtime per browser e Node.js, BirdRealtime per iOS, macOS e Linux, oppure com.messagebird:bird-realtime per Android e la JVM server. Ognuno supporta iscrizioni, binding, presence, signin() ed eventi client.
Tieni il secret dell'app sul tuo server. I server SDK lo usano per pubblicare eventi, autorizzare canali e disconnettere membri.
App, chiavi e regioni
Un'app è un ambiente isolato con le proprie credenziali e il proprio namespace di canali. Due app non vedono mai i canali l'una dell'altra, ed è questo che rende l'app il confine giusto tra i tuoi ambienti di staging e produzione.
Ogni app usa una regione immutabile selezionata alla creazione. Usa List Realtime regions per recuperare gli identificatori accettati e scegli la regione più vicina ai tuoi utenti.
Ogni app ha tre valori con usi diversi:
- L'app ID (rap_…) identifica l'app nelle chiamate Bird API e compare in ogni path /v1/realtime/apps/….
- La key è pubblica. I browser si connettono con essa ed è sicuro distribuirla nel codice client.
- Il secret si accoppia con la chiave per autenticare le chiamate lato server e firmare l'autorizzazione dei canali. Viene mostrato una sola volta, alla creazione. Chiunque lo possieda può pubblicare sulla tua app e falsificare identità presence.
Gestisci le app e ruota le chiavi nella pagina Realtime apps. Crea una seconda chiave, distribuiscila e poi revoca quella vecchia.
Visibilità
La pagina Realtime metrics mostra tre valori per app o sull'intero spazio di lavoro per la finestra selezionata:
- Connessioni massime è il numero più alto di connessioni aperte nello stesso istante all'interno della finestra. Questo picco è il valore a cui si applica il limite di connessioni.
- Connessioni medie è la media dei picchi giornalieri. Non fa la media di ogni campione. Uno spazio di lavoro che ha un picco ogni pomeriggio e resta inattivo durante la notte mostra una media ben superiore alle ore di quiete.
- Messaggi conta le consegne di eventi, una per canale: una pubblicazione che nomina 50 canali conta come 50. Include anche gli eventi che il protocollo invia per conto tuo, quindi le iscrizioni presence e gli aggiornamenti del conteggio connessioni rientrano nello stesso numero, motivo per cui può superare le pubblicazioni effettuate dal tuo codice.
L'utilizzo è aggregato in bucket da un minuto, quindi il traffico recente può impiegare diversi minuti per comparire. L'API di utilizzo è disponibile solo nella dashboard. Per una visibilità programmatica, registra le pubblicazioni nei tuoi sistemi o ricava l'attività dai webhook realtime.*.
Piani e limiti
Il piano gratuito copre 100 connessioni simultanee e 200.000 messaggi al giorno, su tutte le app di uno spazio di lavoro. Creare più app non alza il tetto, perché si applica allo spazio di lavoro.
I piani a pagamento partono da 25 $ al mese per 250 connessioni simultanee e 500.000 messaggi al giorno, e arrivano fino a 30.000 connessioni e 90 milioni di messaggi al giorno. Prezzi di Realtime elenca ogni livello.
I limiti per richiesta si applicano a ogni piano: una pubblicazione nomina al massimo 100 canali, un batch contiene al massimo 10 eventi e il payload di un evento è limitato a 10 KB serializzati.
Prossimi passi
- Invia il tuo primo evento realtime percorre l'intero ciclo dall'inizio alla fine.
- Pubblicare eventi copre la pubblicazione dal tuo server, il batching e l'esclusione del client originante.
- Autorizzazione dei canali è il contratto che il tuo backend implementa per i canali privati e presence.
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.