Eventi client

Un evento client viaggia direttamente da un client iscritto agli altri sullo stesso canale. Il tuo backend riceve una copia solo se lo iscrivi al gruppo webhook client-events.

Usa gli eventi client per segnali di breve durata come indicatori di digitazione, posizioni del cursore o heartbeat di attività. Evitano un passaggio di andata e ritorno attraverso il tuo API.

Non usare gli eventi client come stato autorevole. L'edge Realtime non valida i loro payload, quindi i destinatari non possono fidarsi del contenuto. Invia messaggi di chat salvati, cambiamenti di stato e azioni sensibili ai permessi attraverso il tuo server con Pubblicazione degli eventi.

Abilitare gli eventi client

Abilita Client Events per l'app nella pagina Realtime apps. Puoi anche impostare client_events su true tramite la API Realtime. L'impostazione si applica all'intera app. Finché non la abiliti, l'edge Realtime rifiuta gli eventi client.

Requisiti degli eventi client

L'edge Realtime applica tre regole:

Il nome inizia con client-. Questo prefisso riservato identifica gli eventi client. I client rifiutano i nomi di evento che lo omettono.
Il canale è privato o di presenza. Un canale pubblico viene rifiutato, ed è proprio questo il punto: la chiave dell'app è presente nella tua pagina, quindi chiunque potrebbe iscriversi a un canale pubblico e iniziare a scrivervi. L'autorizzazione è ciò che rende un client sufficientemente affidabile per trasmettere, e solo i canali privati e di presenza la prevedono.
Il mittente è iscritto. La connessione deve già essere sul canale in cui invia l'evento, quindi un client non può scrivere in una stanza in cui non è mai stato ammesso.

Se un evento viola una di queste regole, l'edge restituisce un errore a livello di connessione. Associa l'errore durante lo sviluppo:

bird.connection.bind("error", (e) => console.warn("edge refused:", e.message));

bird.onError { error in
    print("edge refused:", error.message)
}

bird.onError { error ->
    println("edge refused: ${error.message}")
}

Invio

import { BirdRealtime } from "@messagebird/realtime";

const bird = new BirdRealtime({
  appKey: "your-app-key",
  region: "us1",
  authEndpoint: "/bird/auth",
});

const room = bird.subscribe("presence-room-1");

input.addEventListener("input", () => {
  room.trigger("client-typing", { at: Date.now() });
});

let room = bird.subscribe("presence-room-1")

// From whatever your UI calls on a keystroke.
func typingChanged() throws {
    guard room.subscribed else { return }
    try room.trigger("client-typing", data: ["at": Date().timeIntervalSince1970])
}

val room = bird.subscribe("presence-room-1")

// From whatever your UI calls on a keystroke.
fun typingChanged() {
    if (!room.subscribed) return
    room.trigger("client-typing", buildJsonObject { put("at", System.currentTimeMillis()) })
}

Il payload opzionale può essere una stringa, un oggetto o un array. trigger restituisce true dopo l'invio del frame e false se il canale non è iscritto. Per inviare subito dopo l'iscrizione, attendi bird:subscription_succeeded.

Swift e Kotlin accettano il payload come valore JSON del proprio linguaggio: Any? codificato con JSONSerialization in Swift, JsonElement in Kotlin.

Ricezione

Associa il nome che hai inviato, sullo stesso canale, esattamente come un evento pubblicato dal server:

room.bind("client-typing", (data) => showTypingIndicator(data));

room.bind("client-typing") { data in
    showTypingIndicator(data)
}

room.bind("client-typing") { data ->
    showTypingIndicator(data)
}

La connessione che invia non riceve il proprio evento. Altre connessioni appartenenti alla stessa persona lo ricevono, quindi filtra quelle copie quando necessario.

Limiti di frequenza

Ogni connessione può inviare fino a 10 eventi client al secondo. Lo stesso limite si applica a ogni connessione sull'app.

Quando una connessione supera il limite, l'edge scarta l'evento e segnala un errore senza chiudere la connessione. Associa l'evento error della connessione e limita gli input ad alta frequenza come il movimento del cursore.

Ricevere eventi client sul tuo server

Per ricevere eventi client sul tuo server, iscrivi un endpoint al gruppo realtime.client_events. Il campo type di ogni webhook aggiunge il prefisso realtime. al nome dell'evento client, quindi client-typing diventa realtime.client-typing:

Esempio di codice

{
  "data": {
    "channel_name": "presence-room-1",
    "event": "client-typing",
    "data": "{\"at\":1785495600000}",
    "connection_id": "26896.319537",
    "member_id": "u_42"
  },
  "timestamp": "2026-07-31T09:00:00Z",
  "type": "realtime.client-typing"
}

member_id è presente per i canali di presenza ed è assente per i canali privati. Segnali ad alto volume come le posizioni del cursore producono un webhook per ogni evento client. Consulta Webhook Realtime per la risposta, la firma e gli altri gruppi.

Prossimi passi

Webhook Realtime tratta la ricezione degli eventi client e dell'attività sui canali sul tuo endpoint.
Canali di presenza danno agli eventi client un'identità membro e la lista dei membri su cui visualizzarli.
Pubblicazione degli eventi è il percorso lato server, per tutto ciò di cui un client non dovrebbe essere considerato affidabile.

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Esplora la funzionalitàRealtime Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneSend your first realtime event

Prova l'esercitazione e ottieni un brief di implementazione