Dokumentasi API & Penggunaan

Memulai Cepat

SocketFlow adalah sebuah sistem perpesanan *real-time* yang dibangun menggunakan WebSocket (Socket.io) dan REST API. Panduan ini akan memandu Anda langkah demi langkah dalam memasang *library*, menyambungkan ke server, berlangganan *channel*, serta mengirim dan menerima data.

download

1. Pemasangan Library (Klien)

Karena server menggunakan protokol Socket.io, klien harus menggunakan *library* klien Socket.io yang sesuai (versi 4.x). Pilihlah cara instalasi yang sesuai dengan proyek Anda:

Pengguna NPM / Node.js (React, Vue, Svelte, dll):
npm install socket.io-client
Pengguna HTML Statis / CDN:
<script src="https://cdn.socket.io/4.8.1/socket.io.min.js"></script>
vpn_key

2. Autentikasi Keamanan

Sistem ini menerapkan lapisan keamanan. Setiap permintaan koneksi diwajibkan memiliki JWT Token. Anda dapat menyalin token Anda di halaman Settings setelah berhasil masuk ke sistem (Login).

electrical_services

3. Menyambungkan ke Server

Inisialisasi klien Socket.io dengan mengirimkan Token JWT Anda melalui objek auth. Anda bebas menyesuaikan URL dengan URL *production* Anda ketika sudah di-*deploy*. 

// Jika menggunakan NPM
import { io } from "socket.io-client";

// Jika menggunakan CDN, objek 'io' sudah tersedia secara otomatis di window

// Inisialisasi koneksi (Ubah localhost menjadi domain server Anda saat di-deploy)
const socket = io(window.location.origin, {
  auth: {
    token: "TOKEN_JWT_ANDA_DI_SINI"
  }
});

// Mengecek jika koneksi berhasil
socket.on("connect", () => {
  console.log("Berhasil terhubung dengan ID:", socket.id);
});

// Menangani gagal koneksi (Misal: Token salah atau expired)
socket.on("connect_error", (err) => {
  console.error("Koneksi ditolak:", err.message);
});
tag

4. Berlangganan Channel (Room)

Untuk mengelompokkan pesan dan tidak menabrak jalur pihak lain, sistem membagi pesan ke dalam Channel (mirip fungsi Group). Anda wajib melakukan langganan (subscribe) sebelum bisa menerima pesan dari suatu grup. 

// Memasuki atau berlangganan ke sebuah Channel (contoh: "iot-sensors")
socket.emit("subscribe", { channel: "iot-sensors" });

// Menunggu respon sukses dari server
socket.on("subscription_success", (data) => {
  console.log("Telah masuk ke dalam channel:", data.channel);
});

// Berhenti berlangganan dan keluar dari Channel
socket.emit("unsubscribe", { channel: "iot-sensors" });
send

5. Mengirim & Menerima Data

Untuk mengirim pesan (publish), gunakan event listener bernama client_event dan wajibkan Anda menyediakan nama channel tempat mem-*broadcast*-nya, sebuah eventName bebas, serta payload (bisa JSON).

Sebaliknya untuk menerima, Anda cukup mendengarkan menggunakan socket.on("NAMA_EVENT_ANDA", callback). 

// MENGIRIM PESAN
// Data akan dikirimkan secara massal ke semua anggota di dalam channel 'iot-sensors'
socket.emit("client_event", {
  channel: "iot-sensors",
  eventName: "suhu_update",
  payload: {
    suhu: 28.5,
    lokasi: "Gudang Utama",
    status: "Normal"
  }
});

// MENERIMA PESAN
// Di sisi komputer klien lain yang berlangganan pada channel 'iot-sensors'
socket.on("suhu_update", (payload) => {
  console.log("Menerima data suhu baru:", payload);
});
api

6. Memicu Event Lewat REST API (Webhook Server-to-Client)

Jika Anda memiliki aplikasi backend di bahasa pemrograman lain (seperti PHP/Laravel, Python, Java) yang kesulitan menyambung secara terus-menerus lewat WebSocket, Anda bisa memanfaatkan Endpoint HTTP REST API bawaan kami.

Ingat, selalu lekatkan Bearer Token pada Header Authorization di setiap request!

POST /api/trigger

Akan meneruskan payload langsung secara WebSocket ke semua klien yang berlangganan pada nama channel bersangkutan.

curl -X POST https://domain-anda.com/api/trigger \
  -H "Authorization: Bearer TOKEN_JWT_ANDA_DI_SINI" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "general",
    "eventName": "pengumuman_server",
    "payload": {
      "pesan": "Server akan melakukan maintenance dalam 5 menit!",
      "tipe": "kritis"
    }
  }'