Client event

Client event berjalan langsung dari satu klien yang berlangganan ke klien lain di channel yang sama. Backend Anda menerima salinannya hanya jika Anda mendaftarkannya ke grup webhook client-events.

Gunakan client event untuk sinyal berumur pendek seperti indikator mengetik, posisi kursor, atau heartbeat aktivitas. Client event menghindari perjalanan bolak-balik melalui API Anda.

Jangan gunakan client event sebagai state otoritatif. Edge Realtime tidak memvalidasi payload-nya, sehingga penerima tidak bisa memercayai isinya. Kirim pesan chat tersimpan, perubahan state, dan tindakan sensitif izin melalui server Anda dengan Publishing events.

Mengaktifkan client event

Aktifkan Client Events untuk aplikasi di halaman Realtime apps. Anda juga dapat mengatur client_events ke true melalui API Realtime. Pengaturan ini berlaku untuk seluruh aplikasi. Sampai Anda mengaktifkannya, edge Realtime menolak client event.

Persyaratan client event

Edge Realtime menerapkan tiga aturan:

Nama diawali dengan client-. Prefiks khusus ini mengidentifikasi client event. Klien menolak nama event yang tidak menyertakannya.
Channel harus private atau presence. Channel public ditolak, dan memang itulah tujuannya: app key dikirim bersama halaman Anda, sehingga siapa pun bisa berlangganan channel public dan mulai menulis ke dalamnya. Otorisasi adalah yang membuat klien cukup tepercaya untuk melakukan broadcast, dan hanya channel private serta presence yang memilikinya.
Pengirim sudah berlangganan. Koneksi harus sudah berada di channel yang dituju, sehingga klien tidak bisa menulis ke ruang yang tidak pernah diizinkan masuk.

Jika sebuah event melanggar salah satu aturan ini, edge mengembalikan error tingkat koneksi. Bind error tersebut saat pengembangan:

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

Mengirim

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

Payload opsional dapat berupa string, objek, atau array. trigger mengembalikan true setelah mengirim frame dan false jika channel belum di-subscribe. Untuk mengirim segera setelah bergabung, tunggu bird:subscription_succeeded.

Swift dan Kotlin menerima payload sebagai nilai JSON bahasa masing-masing: Any? yang di-encode dengan JSONSerialization di Swift, JsonElement di Kotlin.

Menerima

Bind nama yang Anda kirim, di channel yang sama, persis seperti event yang dipublikasikan server:

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

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

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

Koneksi pengirim tidak menerima event-nya sendiri. Koneksi lain milik orang yang sama tetap menerimanya, jadi filter salinan tersebut jika perlu.

Batas laju

Setiap koneksi dapat mengirim hingga 10 client event per detik. Batas yang sama berlaku untuk setiap koneksi pada aplikasi.

Ketika sebuah koneksi melebihi batas, edge membuang event tersebut dan melaporkan error tanpa menutup koneksi. Bind event error pada koneksi dan batasi input berfrekuensi tinggi seperti pergerakan kursor.

Menerima client event di server Anda

Untuk menerima client event di server Anda, daftarkan endpoint ke grup realtime.client_events. type setiap webhook menambahkan prefiks realtime. ke nama client event, sehingga client-typing menjadi realtime.client-typing:

Contoh kode

{
  "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 muncul untuk channel presence dan tidak ada untuk channel private. Sinyal volume tinggi seperti posisi kursor menghasilkan satu webhook per client event. Lihat Realtime webhooks untuk envelope, signature, dan grup lainnya.

Langkah selanjutnya

Realtime webhooks membahas penerimaan client event, dan aktivitas channel, di endpoint Anda sendiri.
Presence channels memberi client event identitas anggota, serta daftar anggota untuk menampilkannya.
Publishing events adalah jalur sisi server, untuk segala hal yang tidak boleh dipercayakan kepada klien.

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Jelajahi kemampuannyaRealtime Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first realtime event

Coba praktiknya dan dapatkan ringkasan implementasi