Zdarzenia klienckie

Zdarzenie klienckie trafia bezpośrednio od jednego zasubskrybowanego klienta do pozostałych na tym samym kanale. Twój backend otrzymuje kopię tylko wtedy, gdy zasubskrybujesz go do grupy webhooków client-events.

Używaj zdarzeń klienckich do krótkotrwałych sygnałów, takich jak wskaźniki pisania, pozycje kursora czy heartbeaty aktywności. Pozwalają uniknąć podróży w obie strony przez Twój API.

Nie używaj zdarzeń klienckich jako autorytatywnego stanu. Warstwa brzegowa Realtime nie waliduje ich payloadów, więc odbiorcy nie mogą ufać ich zawartości. Zapisane wiadomości czatu, zmiany stanu i akcje wrażliwe na uprawnienia wysyłaj przez serwer za pomocą Publikowania zdarzeń.

Włączanie zdarzeń klienckich

Włącz Client Events dla aplikacji na stronie Realtime apps. Możesz też ustawić client_events na true przez Realtime API. Ustawienie dotyczy całej aplikacji. Dopóki go nie włączysz, warstwa brzegowa Realtime odrzuca zdarzenia klienckie.

Wymagania dotyczące zdarzeń klienckich

Warstwa brzegowa Realtime wymusza trzy reguły:

Nazwa zaczyna się od client-. Ten zarezerwowany prefiks identyfikuje zdarzenia klienckie. Klienty odrzucają nazwy zdarzeń, które go pomijają.
Kanał jest prywatny lub presence. Kanał publiczny zostaje odrzucony i o to właśnie chodzi: klucz aplikacji jest osadzony w Twojej stronie, więc każdy mógłby zasubskrybować kanał publiczny i zacząć do niego pisać. Autoryzacja sprawia, że klient jest wystarczająco godny zaufania, by nadawać, a tylko kanały prywatne i presence ją posiadają.
Nadawca jest zasubskrybowany. Połączenie musi już znajdować się na kanale, do którego wysyła zdarzenie, więc klient nie może pisać do pokoju, do którego nigdy nie został wpuszczony.

Jeśli zdarzenie łamie jedną z tych reguł, warstwa brzegowa zwraca błąd na poziomie połączenia. Podczas tworzenia aplikacji binduj ten błąd:

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}")
}

Wysyłanie

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()) })
}

Opcjonalny payload może być ciągiem znaków, obiektem lub tablicą. trigger zwraca true po wysłaniu ramki i false, jeśli kanał nie jest zasubskrybowany. Aby wysłać od razu po dołączeniu, poczekaj na bird:subscription_succeeded.

Swift i Kotlin przyjmują payload jako wartość JSON danego języka: Any? zakodowany za pomocą JSONSerialization w Swifcie, JsonElement w Kotlinie.

Odbieranie

Binduj nazwę, którą wysłałeś, na tym samym kanale, dokładnie tak jak zdarzenie opublikowane przez serwer:

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

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

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

Połączenie nadawcy nie otrzymuje swojego zdarzenia. Inne połączenia należące do tej samej osoby otrzymują je, więc w razie potrzeby filtruj te kopie.

Limity częstotliwości

Każde połączenie może wysłać do 10 zdarzeń klienckich na sekundę. Ten sam limit obowiązuje każde połączenie w aplikacji.

Gdy połączenie przekroczy limit, warstwa brzegowa odrzuca zdarzenie i zgłasza błąd bez zamykania połączenia. Binduj zdarzenie error połączenia i ograniczaj wysyłanie sygnałów o wysokiej częstotliwości, takich jak ruch kursora.

Odbieranie zdarzeń klienckich na serwerze

Aby odbierać zdarzenia klienckie na serwerze, zasubskrybuj endpoint do grupy realtime.client_events. Pole type każdego webhooka dodaje prefiks realtime. do nazwy zdarzenia klienckiego, więc client-typing staje się realtime.client-typing:

Przykład kodu

{
  "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 pojawia się dla kanałów presence i jest nieobecne dla kanałów prywatnych. Sygnały o dużym natężeniu, takie jak pozycje kursora, generują jeden webhook na zdarzenie klienckie. Zobacz Webhooki Realtime, aby poznać kopertę, sygnaturę i inne grupy.

Kolejne kroki

Webhooki Realtime opisują odbieranie zdarzeń klienckich i aktywności kanałów na Twoim własnym endpointcie.
Kanały presence nadają zdarzeniom klienckim tożsamość członka oraz listę członków, na tle której można je wyświetlać.
Publikowanie zdarzeń to ścieżka po stronie serwera, do wszystkiego, czego klientowi nie należy powierzać.

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Poznaj możliwościRealtime Podążaj ścieżką naukiBuild your first integration Przewodnik wdrożeniowySend your first realtime event

Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy