Sign inGet started

Mengotorisasi channel

Klien mana pun yang memegang app key dapat berlangganan channel publik. Dua prefiks nama channel mengharuskan backend Anda mengotorisasi langganan. Anda tidak mengonfigurasi channel secara terpisah.
Channel bernama private-… mengharuskan backend Anda menyetujui setiap langganan. Channel bernama presence-… melakukan hal yang sama dan juga melampirkan identitas ke pelanggan, sehingga semua orang di channel dapat melihat siapa saja yang ada di sana. Nama lainnya bersifat publik.
Hanya backend Anda yang menyimpan app secret. Klien meminta server Anda menandatangani langganan tertentu, dan edge Realtime memverifikasi tanda tangan tersebut sebelum menerimanya. Server Anda memutuskan apakah pemanggil boleh berlangganan tanpa mengekspos secret ke klien.

Arahkan klien ke endpoint Anda

Berikan klien sebuah authEndpoint di backend Anda sendiri:
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");
Klien memanggil endpoint ini untuk setiap langganan private atau presence, termasuk langganan yang dipulihkan setelah koneksi ulang. Otorisasi berlaku untuk satu koneksi karena tanda tangan menyertakan connection ID-nya.
Klien browser memerlukan endpoint same-origin secara default. Atur allowCrossOriginAuth: true untuk menggunakan authEndpoint cross-origin. Klien browser mengirim authHeaders yang dikonfigurasi hanya ke endpoint same-origin.

Apa yang diterima dan dikembalikan endpoint Anda

Klien mengirim POST JSON:
Contoh kode
{ "connection_id": "26896.319537", "channel_name": "presence-room-1" }
Respons dengan tanda tangan:
Contoh kode
{ "auth": "your-app-key:8f9a…" }
Untuk channel presence, kembalikan juga identitas anggota sebagai JSON string, string yang sama dengan yang Anda tanda tangani:
Contoh kode
{
  "auth": "your-app-key:8f9a…",
  "member_data": "{\"member_id\":\"u_42\",\"member_info\":{\"name\":\"Ada\"}}"
}
member_id adalah identitas yang dilihat anggota lain dan nilai yang ditargetkan operasi disconnect. member_info adalah data JSON opsional yang dikirim ke setiap anggota channel. Batasnya 1 KB, jadi sertakan hanya data profil kecil yang tidak sensitif.
Otorisasi pemanggil di endpoint ini menggunakan session cookie atau bearer token. Kembalikan 403 Forbidden ketika pemanggil tidak boleh bergabung ke channel. Untuk channel presence, tetapkan identitas dalam respons yang sama.

String yang Anda tanda tangani

Gabungkan dengan titik dua, lalu HMAC-SHA256 dengan app secret dan encode ke heksadesimal. Awali hasilnya dengan app key dan titik dua.
Tipe channelString yang ditandatangani
private-…<connection_id>:<channel_name>
private-encrypted-…<connection_id>:<channel_name>
presence-…<connection_id>:<channel_name>:<member_data>
Untuk channel presence, tanda tangani persis string member_data yang Anda kembalikan. Serialisasi ulang objek yang sama dapat mengubah urutan key atau spasi dan membuat tanda tangan tidak valid.
Channel terenkripsi ditandatangani seperti channel private, dan respons auth-nya juga mengembalikan kunci dekripsi channel sebagai shared_secret. Helper SDK menambahkannya secara otomatis; Channel terenkripsi membahas derivasi dan perilaku channel.
Setiap SDK server menyediakan helper authorizeChannel. Helper ini menandatangani dengan kredensial app yang dikonfigurasi dan mengembalikan body respons tanpa melakukan permintaan jaringan. Untuk channel terenkripsi, helper juga menambahkan shared_secret.
app.post("/bird/auth", async (req, res) => {
  const { connection_id, channel_name } = req.body;

  // Your own authorization decision goes here.
  const user = getUserFromSession(req);
  if (!user || !mayJoin(user, channel_name)) return res.sendStatus(403);

  const memberData = channel_name.startsWith("presence-")
    ? JSON.stringify({ member_id: user.id, member_info: { name: user.name } })
    : undefined;

  res.json(
    await bird.realtime.authorizeChannel({
      connectionId: connection_id,
      channelName: channel_name,
      memberData,
    }),
  );
});
Kontrak penandatanganan sama di bahasa tanpa SDK: HMAC-SHA256 string tersebut dengan app secret, encode ke heksadesimal, dan awali dengan app key dan titik dua.

Anggota dan koneksi

Anggota adalah identitas, sedangkan koneksi adalah satu WebSocket terbuka. Jika seseorang membuka aplikasi Anda di tiga tab, satu anggota memiliki tiga koneksi. member_added terpicu ketika koneksi pertama berlangganan, dan member_removed terpicu ketika koneksi terakhir keluar. Koneksi lain mengubah jumlah koneksi channel tanpa menghasilkan event anggota.

Kegagalan umum

Langganan yang ditolak muncul sebagai error klien. Periksa penyebab umum berikut:
  • Tanda tangan tidak valid. String yang Anda tanda tangani tidak cocok. Hampir selalu karena member_data yang diserialisasi ulang, atau tanda tangan yang dihitung dari nama channel tanpa prefiks private- atau presence-.
  • Key tidak valid. Key di auth milik app lain, atau sudah dicabut. Merotasi key berarti memperbarui appKey klien dan secret yang digunakan endpoint Anda untuk menandatangani.
  • Data anggota tidak ada. Langganan presence diterima tanpa member_data. Channel presence tidak dapat diikuti secara anonim.
  • 403 dari endpoint Anda sendiri. Keputusan otorisasi Anda menolak, yang merupakan hasil yang diharapkan untuk pengguna yang tidak boleh bergabung.

Langkah selanjutnya

  • Kirim event realtime pertama Anda adalah panduan end-to-end yang menjadi dasar panduan ini.
  • Channel terenkripsi dibangun di atas tanda tangan ini untuk juga memberikan kunci dekripsi kepada pelanggan yang disetujui.
  • Channel presence membahas daftar anggota, event anggota, dan membaca presence dari server Anda.
  • Memutus koneksi anggota adalah tanda tangan lain yang dihitung backend Anda, dan yang memungkinkan Anda menutup koneksi anggota.
  • Webhook & event membahas event realtime.*, termasuk anggota yang bergabung dan keluar, di endpoint Anda sendiri.

Sumber daya terkait

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

Coba praktiknya dan dapatkan ringkasan implementasi