Lewati ke konten utama

Pendahuluan

Buka koneksi WebSocket waktu nyata untuk menerima konten, pembaruan pesanan, dan pembaruan pengguna tanpa polling.

Informasi lebih lanjut tentang antarmuka pengguna modul ini https://doc.oneentry.cloud/docs/events/introduction

🎯 Apa yang dilakukan modul ini?​

Modul WS (WebSocket) memungkinkan Anda menerima notifikasi waktu nyata - pembaruan konten, perubahan pesanan, tindakan pengguna - melalui koneksi yang persisten, sehingga server mengirimkan pembaruan kepada Anda secara instan alih-alih Anda yang melakukan polling. Ini memungkinkan fitur langsung seperti notifikasi, obrolan langsung, dan dasbor waktu nyata.

Metode tunggal, connect(), membuka koneksi dan mengembalikan Socket dari socket.io. Ini adalah synchronous dan memerlukan pengguna yang terautentikasi, jadi autentikasi terlebih dahulu.

🚀 Panduan Cepat​

Inisialisasi modul dari defineOneEntry:


const { WS } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

connect() bersifat synchronous dan mengembalikan Socket dari socket.io (tanpa await). Pasang penangan acara dengan socket.on(...):

// connect() requires an authorized user — authenticate first via AuthProvider.
const socket = WS.connect();

socket.on('connect', () => {
  console.log('WebSocket connected');
});

// Listen for an event by its marker (configured in the Events module).
socket.on('my_event', (payload) => {
  console.log('Update received!', payload);
});

✨ Konsep Kunci​

Apa itu WebSocket?​

WebSocket adalah koneksi dua arah yang persisten antara klien dan server:

  • Koneksi Persisten - Tetap terbuka, tanpa handshake berulang
  • Dua Arah - Baik klien maupun server dapat mengirim pesan
  • Waktu Nyata - Pengiriman pesan instan
  • Berdasarkan Acara - Dengarkan acara dengan socket.on(...)
  • Efisien - Beban rendah dibandingkan dengan polling HTTP

WebSocket vs HTTP Polling​

FiturWebSocketHTTP Polling
KoneksiPersisten (tetap terbuka)Koneksi berulang
LatensiSub-detikBergantung pada interval (2-30s)
EfisiensiSangat efisienBoros (banyak respons kosong)
Beban ServerRendah (hanya acara)Tinggi (permintaan konstan)
Kasus PenggunaanPembaruan waktu nyataDiterima untuk pembaruan non-kritis

Siklus Hidup Koneksi​

1. Authenticate the user (AuthProvider.auth)
   ↓
2. Open the connection: const socket = WS.connect()
   ↓
3. Wait for the 'connect' event: socket.on('connect', ...)
   ↓
4. Listen for events: socket.on('<event_marker>', callback)
   ↓
5. Server pushes events as they occur
   ↓
6. Disconnect when done: socket.disconnect()

Acara apa yang tiba melalui koneksi​

Tidak ada katalog tetap untuk nama acara SDK. Acara terjadi sesuai dengan konfigurasi modul Events Anda di panel admin (acara harus memiliki opsi WebSocket yang diaktifkan). Anda mendengarkan acara berdasarkan penandanya dengan socket.on('<event_marker>', callback).

Payload tergantung pada sumber acara. Bidang payload yang umum (lihat connect() untuk contoh lengkap):

Bidang PayloadTiba untukBerisi
attributesSetiap acaraAtribut acara itu sendiri
productAcara katalog (produk)Atribut produk ditambah title
userAcara formulir penggunaBidang dari formulir pengguna
orderAcara pesananid pesanan dan atribut
email / codeFormulir pendaftaran / kodeBidang formulir tambahan

📋 Apa yang Perlu Anda Ketahui​

Otorisasi diperlukan​

connect() memerlukan pengguna yang terautentikasi — panggil AuthProvider.auth(...) sebelum terhubung. Koneksi diotentikasi dengan token akses pengguna ditambah token aplikasi Anda dari defineOneEntry(). Jika tidak ada pengguna yang terautentikasi, SDK mencatat kesalahan.

connect() bersifat synchronous​

connect() segera mengembalikan Socket dari socket.io — jangan await itu. Tunggu acara connect sebelum bergantung pada socket, lalu pasang penangan dengan socket.on(...).

socket.io dimuat sesuai permintaan​

socket.io-client (~41 kB) diimpor pertama kali connect() dipanggil, jadi proyek yang tidak pernah membuka socket tidak mengirimkannya — lihat Ukuran Bundle & Format Modul.

Tanda tangan tidak berubah dan penggunaan normal tidak terpengaruh: sampai chunk terpecahkan, objek yang dikembalikan mengantri apa pun yang Anda lakukan dengannya (on, emit, disconnect) dan memutarnya ke socket yang sebenarnya pada tick yang sama saat dibuat — sebelum koneksi dapat mengirimkan apa pun — jadi tidak ada acara yang hilang. Membaca status lebih awal juga akurat: socket yang baru dibuat juga tidak terhubung, jadi id adalah undefined dan connected adalah false.

Satu perbedaan: metode yang harus mengembalikan nilai (misalnya listeners()) tidak dapat menjawab sebelum chunk tiba, dan objek bersarang seperti socket.io hanya dapat diakses setelah dimuat.

Berlangganan setelah koneksi terbuka, bersihkan saat selesai​

Pasang penangan acara setelah acara connect terjadi, dan lepaskan mereka (socket.off) serta panggil socket.disconnect() saat koneksi tidak lagi diperlukan (misalnya saat komponen dibongkar atau pengguna keluar) untuk mencegah kebocoran memori di SPAs.

Penyambungan Kembali​

socket.io secara otomatis menyambung kembali secara default. Untuk menyesuaikan, dengarkan acara disconnect dan connect_error dan sambung kembali dengan backoff eksponensial, mengatur ulang penundaan pada connect yang berhasil.

📊 Tabel Referensi Cepat​

MetodeDeskripsiKasus Penggunaan
connect() 🔐Terhubung ke server WebSocketMembangun koneksi

🔐 connect() memerlukan pengguna yang terautentikasi — autentikasi terlebih dahulu melalui AuthProvider. Setelah terhubung, pasang penangan acara dengan socket.on(...).

❓ Pertanyaan Umum (FAQ)​

Bagaimana cara saya terhubung ke server WebSocket?​

Gunakan WS.connect() untuk membuka koneksi — ini bersifat synchronous dan mengembalikan Socket dari socket.io. Ini memerlukan pengguna yang terautentikasi, jadi panggil AuthProvider.auth(...) terlebih dahulu. Tunggu acara connect sebelum bergantung pada socket, lalu pasang penangan dengan socket.on('<event_marker>', callback).

Acara apa yang bisa saya langgani?​

Tidak ada daftar acara SDK yang tetap. Acara ditentukan oleh konfigurasi modul Events Anda di panel admin (dengan opsi WebSocket diaktifkan), dan Anda mendengarkan acara berdasarkan penandanya dengan socket.on('<event_marker>', callback). Lihat connect() untuk contoh payload (produk, pengguna, pesanan, formulir).

Bagaimana cara saya menangani pemutusan koneksi?​

socket.io secara otomatis menyambung kembali secara default. Untuk menyesuaikan, dengarkan acara disconnect dan connect_error dan sambung kembali dengan backoff eksponensial (misalnya, 1s, 2s, 4s, 8s, hingga maksimum), mengatur ulang penghitung penundaan pada connect yang berhasil.

Bagaimana cara saya mencegah kebocoran memori dengan langganan WebSocket?​

Lepaskan penangan acara (socket.off) dan panggil socket.disconnect() saat komponen dibongkar atau koneksi tidak lagi diperlukan. Di React, lakukan ini dalam pembersihan useEffect; di Vue, dalam beforeUnmount.

🎓 Praktik Terbaik​

  • Autentikasi terlebih dahulu - connect() memerlukan pengguna yang terautentikasi.
  • Jangan tunggu connect() - Ini bersifat synchronous dan mengembalikan Socket.
  • Berlangganan setelah koneksi terbuka - Pasang penangan setelah acara connect terjadi.
  • Bersihkan - Lepaskan penangan (socket.off) dan socket.disconnect() untuk mencegah kebocoran memori di SPAs.
  • Tangani penyambungan kembali - socket.io menyambung kembali secara otomatis; sesuaikan dengan disconnect / connect_error dan backoff jika diperlukan.
  • Validasi payload acara - Bentuk payload tergantung pada sumber acara; periksa bidang sebelum menggunakannya.

🔗 Dokumentasi Terkait​