Events
Telusuri arsip event hasil deteksi AI per kategori analitik (FRA, MPAA, MVAA, CE, LPR, PPE, General) dengan filter atribut, infinite scroll, panel detail, ekspor asinkron, Smart Search, dan feed WebSocket untuk integrator.
Pengenalan
Setiap kali analitik AI Visionaire melihat sesuatu yang diperintahkan untuk diperhatikan (wajah, plat kendaraan, orang melewati garis batas, pekerja tanpa helm), sistem mencatat satu event: gambar tangkapan, atribut hasil analisis, kamera sumber, dan waktu kejadian. Ibaratnya buku jurnal jaga yang ditulis otomatis.
Halaman Event History (/event-history) adalah tempat menelusuri seluruh event yang tersimpan, dikelompokkan ke dalam tujuh kategori analitik (FRA, MPAA, MVAA, CE, LPR, PPE, General Events) dengan kolom dan filter masing-masing. Dari sini Anda dapat menyaring event berdasarkan kamera, waktu, dan atribut deteksi; membuka panel detail beserta rekaman playback; melompat ke Face Search atau Plate Search; mengekspor ke PDF atau Excel; dan (bila diaktifkan) mencari dengan kalimat bahasa alami lewat Smart Search.
Bagi integrator, data yang sama tersedia melalui REST API: GET /api/event-history/{category} dengan cursor-based pagination dan filter multidimensi, GET /api/events/pipeline/{event_id} untuk detail satu event, serta dua channel WebSocket (/api/event_channel untuk semua deteksi mentah dan /api/alert_channel untuk event yang lolos Alert Rule).
Setiap event diidentifikasi oleh Event ID (event_id), pengenal yang dibuat engine analitik saat deteksi terjadi, misalnya 1780473522-a6d87102. UI menampilkan bagian uniknya saja (#A6D87102) di badge Event ID pada panel detail, lengkap dengan tombol salin. Nilai ini dipakai di tiga tempat: filter Event ID di panel Filter, deep link /event-history?open_event=<event_id>, dan endpoint GET /api/events/pipeline/{event_id}. Jangan tertukar dengan field id pada respons API, yang merupakan nomor baris di database.
Satu halaman, dua alamat
Menu sidebar Investigation → Event History membuka /event-history. Alamat /events menampilkan halaman yang sama persis; alamat ini dipakai sebagai halaman tujuan Smart Search dan oleh deep link dari ekstensi atau notifikasi. Tampilan Event History lama (tabel yang dikelompokkan per tanggal dengan paginasi klasik) sudah tidak ada; semua kemampuannya kini ada di halaman ini.
Alur Data Event
Diagram berikut menunjukkan dua jalur data yang relevan untuk halaman ini: REST untuk daftar dan detail event serta WebSocket untuk toast alert real-time.
Dalam bahasa sehari-hari: kamera mengirim video mentah ke Visionaire yang menganalisisnya. Setiap temuan dikirim ke backend API, yang menyimpannya ke database per kategori dan sekaligus memeriksa apakah temuan itu memenuhi Alert Rule yang aktif. Halaman Event History mengambil catatan dari database melalui REST setiap kali Anda membuka halaman, mengganti filter, atau menggulir ke bawah.
Apabila sebuah event memenuhi kondisi Alert Rule, sistem juga mendorongnya melalui WebSocket /api/alert_channel. Lenz menerima pesan itu langsung dan menampilkan toast notifikasi di pojok layar, bahkan ketika Anda sedang membuka halaman lain. Jalur ini terpisah dari REST dan tidak menunggu halaman di-refresh.
Cara Menggunakan
Melihat Daftar Event
Gunakan tampilan ini ketika Anda perlu memeriksa apa yang terjadi di satu kamera atau satu kategori analitik pada rentang waktu tertentu, misalnya saat menindaklanjuti laporan insiden atau melakukan audit harian.
Buka halaman Event History
Klik ikon Event History di grup Investigation pada sidebar kiri (tanda 1 pada gambar), atau buka /event-history langsung. Halaman ini memerlukan hak baca pada resource events.
Halaman terbuka dengan kategori Face Recognition (FRA), Rentang Tanggal hari ini (00:00–23:59 zona waktu browser Anda), urutan Waktu Event (↓), dan mode tabel. Panel Filter menempati sisi kiri; tombol Hide Filters (tanda 2) menyembunyikannya agar tabel lebih lebar, dan berubah menjadi Show Filters untuk memunculkannya kembali.
Kenali toolbar
Baris toolbar di atas daftar terdiri dari:
- Hide Filters / Show Filters: menyembunyikan atau memunculkan panel Filter.
- Hasil: jumlah event yang sudah dimuat dibanding total yang cocok dengan filter, misalnya
20 / 32.322. Angka pertama bertambah setiap kali Anda menggulir ke bawah. - Urutkan: dropdown urutan; pilihannya mengikuti kategori aktif (mis. Waktu Event, Kata Kunci, Status, Tanggal Dibuat untuk FRA; Nomor Plat untuk LPR; Estimasi untuk CE), masing-masing menurun (↓) atau menaik (↑).
- export: membuka dialog Ekspor Event (lihat Mengekspor Event). Tombol ini nonaktif ketika daftar kosong.
- Pengalih tampilan: ikon daftar untuk mode tabel, ikon kartu untuk mode grid (lihat Tampilan Tabel dan Grid).
Di panel Filter, tombol Reset mengembalikan semua filter ke nilai awal (termasuk kategori kembali ke FRA dan rentang ke hari ini) dan Apply menerapkan pilihan Anda. Filter baru dikirim ke server hanya setelah Anda menekan Apply; mengganti urutan di toolbar berlaku langsung.
Pilih kategori analitik
Kategori dipilih dari dropdown Kategori di bagian Filter Umum panel Filter. Kategori menentukan tabel mana yang dibaca di server, kolom tabel, filter atribut, dan opsi pengurutan yang tersedia. Mengganti kategori mengosongkan filter atribut kategori sebelumnya, tetapi mempertahankan Rentang Tanggal, Instance, dan Event ID.
| Label dropdown | Kode | Analitik yang termasuk | Kapan digunakan |
|---|---|---|---|
| Face Recognition (FRA) | fra | NFV4-FR, NFV4-FRA, varian NFV4H-*-FR | Menyelidiki siapa yang muncul di kamera pada waktu tertentu; status KNOWN / UNKNOWN, kemiripan, atribut wajah dan pakaian |
| People Analytics (MPAA) | mpaa | NFV4-MPA, NFV4-MPAA, NFV4-PAA, NFV4-MPA2 | Memantau pergerakan orang: hitung masuk/keluar garis (counting), berapa lama berada di area (dwelling), kepadatan (density), beserta atribut demografi dan pakaian |
| Vehicle Analytics (MVAA) | mvaa | NFV4-MVA, NFV4-MVAA, NFV4-MVAS | Memantau lalu lintas kendaraan: tipe, merek, warna, kecepatan, kendaraan yang berlama-lama di area terlarang |
| Crowd Estimation (CE) | ce | NFV4-CE | Memantau estimasi jumlah orang di suatu area per interval; apakah lokasi melebihi kapasitas aman |
| License Plate (LPR) | lpr | NFV4-LPR, NFV4-LPR2, NFV4-LPR3 | Menelusuri kendaraan berdasarkan nomor plat, tipe plat, status pendaftaran, dan arah di gerbang |
| Personal Protective Equipment (PPE) | ppe | NFV4-PPE | Memeriksa kepatuhan APD: pelindung kepala, warna helm, masker, pakaian pelindung, alas kaki, konteks kerja |
| General Events | general | Semua analitik di luar enam keluarga di atas (mis. NFV4D-PSMO, NFV4D-PPHO, NFV4D-FISO, NFV4D-PPFA, NFV4-XRAY) | Melihat event dari analitik khusus yang tidak memiliki tabel sendiri; kolomnya hanya Tipe Analitik, Label, Confidence Score, dan Jumlah |
Kategori yang dipilih tersimpan di URL sebagai ?category=lpr (kategori default fra tidak ditulis), sehingga tautan halaman dapat dibagikan.
Gunakan filter di panel kiri
Panel Filter terdiri dari tiga bagian yang dapat dilipat. Bagian Filter Umum berlaku untuk semua kategori:
- Kategori: dropdown kategori analitik (lihat langkah sebelumnya).
- Tipe Analitik: pilih satu atau beberapa ID analitik di dalam kategori. Daftar hanya menampilkan analitik yang lisensinya tersedia di deployment Anda; untuk General Events daftar diambil dari ID analitik yang benar-benar pernah menghasilkan event. Kosong berarti semua.
- Rentang Tanggal: tanggal dan jam awal serta akhir. Default hari ini; pencarian di server menggunakan zona waktu browser Anda.
- Stream: pilih satu atau beberapa kamera, dicari berdasarkan nama stream atau site. Daftar dibatasi ke stream yang menjalankan analitik dari kategori aktif, termasuk stream yang sudah dihapus tetapi masih memiliki riwayat event.
- Event ID: pencarian sebagian (substring) pada Event ID. Berguna ketika Anda menerima potongan ID dari notifikasi atau laporan.
- Filter per kategori: judul bagian mengikuti kategori aktif (Filter Pengenalan Wajah, Filter Analitik Orang, Filter Analitik Kendaraan, Filter Estimasi Keramaian, Filter Plat Nomor, Filter PPE, Filter Kejadian Umum). Pilihan checkbox dan chip warna diisi secara dinamis dari nilai yang pernah terdeteksi dan dari konfigurasi rules pipeline; bila belum ada data, muncul teks Tidak ada opsi tersedia.
- Reset dan Apply: menempel di bagian bawah panel.
Di mode Federation, field Instance muncul paling atas dengan placeholder Semua instance; lihat Federation Mode.
Bagian Pencarian muncul untuk tiga kategori dan melakukan pencocokan sebagian: Kata Kunci (FRA, mencari pada label/keyword hasil pengenalan), Merek (MVAA), dan Nomor Plat (LPR).
Filter atribut yang tersedia per kategori:
| Kategori | Filter atribut |
|---|---|
| FRA | Status, Jenis Kelamin, Masker, Kacamata, Usia, Ekspresi Wajah, Penutup Kepala, Warna Atasan, Warna Bawahan |
| MPAA | Tipe Logika, Area, Arah, Dari Garis, Ke Garis, Jenis Kelamin, Usia, Masker, Kacamata, Penutup Kepala, Warna Atasan, Warna Bawahan, Tipe Tubuh, Ekspresi Wajah, Sarung Tangan, Pakaian Atas, Pakaian Bawah, Warna Alas Kaki, Barang Bawaan |
| MVAA | Area, Arah, Tipe Logika (counting, dwelling, density, speed), Tipe Kendaraan, Merek, Warna, Vehicle Advance |
| CE | Area |
| LPR | Tipe Kendaraan, Tipe Plat, Status, Arah |
| PPE | Area, Arah, Tipe Logika, Dari Garis, Ke Garis, Kacamata Pengaman, Pelindung Wajah, Tali Pengaman, Pelindung Kepala, Warna Helm, Masker Wajah, Pakaian Pelindung, Warna Pakaian Pelindung, Jenis Alas Kaki, Konteks Kerja, Sarung Tangan |
| General | Label |
Setiap filter yang diterapkan tercermin di URL (?from=, ?to=, ?streams=, ?analytics=, ?status=, ?event_id=, ?keyword=, ?plate=, dan seterusnya) sehingga tampilan terfilter dapat disalin dan dibagikan ke rekan operator; siapa pun yang membuka tautan itu melihat hasil yang sama. Di sisi API, filter dikirim sebagai filter[<nama>] dan pencarian sebagai search[<nama>] ke GET /api/event-history/{category}.
Baca tabel dan gunakan tombol Cari
Mode tabel (default) menampilkan kolom Gambar (thumbnail), Waktu (tanggal dan jam), Lokasi (nama stream), kolom Instance di mode Federation, lalu kolom atribut sesuai kategori, misalnya Status, Identitas, Jenis Kelamin, Usia, Masker, Kacamata untuk FRA atau Nomor Plat, Nama Terdaftar, Tipe Kendaraan, Status untuk LPR. Atribut kategorikal (masker, kacamata, tipe kendaraan, dan sebagainya) tampil sebagai badge, warna tampil dengan titik warna, dan Tipe Logika diberi warna per logic (counting biru, dwelling oranye, density ungu, speed cyan). Pada event density yang mendeteksi banyak objek, kolom atribut menampilkan nilai objek pertama diikuti pil + N lagi.
Kolom Aksi di ujung kanan berisi tombol Cari (ikon teropong) ketika fitur investigasi aktif: pada FRA, tombol muncul untuk event yang memiliki face_id dan membuka Face Search (/face-search?id=<face_id>); pada LPR, tombol muncul untuk event yang memiliki nomor plat dan membuka Plate Search (/plate-search?id=<plat>). Tombol ini memerlukan toggle Face Investigation atau Plate Investigation di Preferensi → Fitur.
Klik di mana pun pada baris (selain tombol Cari) untuk membuka panel detail.
Tampilan Tabel dan Grid
Mode tabel cocok untuk membaca banyak atribut sekaligus; mode grid cocok untuk membandingkan gambar secara visual, misalnya memilah wajah atau plat dengan cepat. Klik ikon kartu pada pengalih tampilan di toolbar untuk beralih ke grid.
Setiap kartu grid berbentuk persegi dan menampilkan gambar event dengan badge nama kamera di kiri atas (ditambah badge instance di mode Federation) dan badge nilai utama di kanan atas: status KNOWN/UNKNOWN (FRA), nomor plat (LPR), arah masuk/keluar dan jenis kelamin (MPAA), atau tipe kendaraan dan arah (MVAA). Klik kartu untuk membuka panel detail.
Kedua mode memuat 20 event per permintaan dan menggunakan infinite scroll: gulir ke bawah dan halaman berikutnya dimuat otomatis menggunakan next_cursor dari respons sebelumnya, tanpa tombol halaman. Indikator di bagian bawah menampilkan Menampilkan X dari Y selama masih ada data, dan Semua N event dimuat ketika sudah habis. Mode tampilan yang dipilih tersimpan di browser dan dipakai lagi pada kunjungan berikutnya; di perangkat mobile, tampilan selalu grid.
Melihat Detail Event
Buka panel Detail Event
Klik baris tabel atau kartu grid. Panel Detail Event meluncur dari sisi kanan (di perangkat mobile, dari bawah). Header panel menempel di atas sehingga selalu terlihat: nama kamera, tanggal, jam, dan badge Event ID (tanda 1 pada gambar) dengan tombol salin ke clipboard.
Panel mengambil data lengkap event (termasuk gambar beresolusi penuh dan pipeline_data) dari GET /api/events/pipeline/{event_id}; di mode Federation permintaan diarahkan ke instance asal event.
Baca blok-blok di tab Detail
Isi tab Detail disusun dari atas ke bawah:
- Blok pengenalan (tanda 2), khusus FRA dan LPR. Pada FRA: Tangkapan Kamera di kiri dan, bila wajah dikenali, Hasil Pengenalan Wajah di kanan beserta foto terdaftar, nama, dan persentase kemiripan; bila tidak dikenali, kartu Wajah Tidak Dikenali menampilkan Kecocokan Terdekat (Tidak Terdaftar) dengan ID Wajah, nilai kesamaan, dan deteksi. Pada LPR: Pengenalan Plat Nomor dengan tangkapan plat, nomor plat, keyakinan plat, dan kartu Kendaraan Terdaftar atau Kendaraan Tidak Terdaftar. Tombol Cari pada gambar membuka Face Search atau Plate Search seperti di tabel.
- Cari penampilan serupa: tombol yang membawa gambar event ini ke halaman Person Re-ID (
/person-reid?event_id=) untuk menemukan orang yang sama di kamera lain. Hanya tampil bila fitur Person Re-ID aktif dan Anda punya hak bacanya. - Lokasi: peta dengan penanda kamera (dapat diperbesar) bila koordinat stream terisi.
- Floorplan: posisi kamera di denah bangunan, bila site kamera memiliki floorplan.
- Informasi Dasar: Lokasi, Tanggal, Waktu, Confidence (bila pipeline melaporkan satu nilai keyakinan), dan Koordinat.
- Atribut atau Objek Terdeteksi: seluruh atribut yang dianalisis pipeline (jenis kelamin, usia, warna pakaian, tipe kendaraan, dan seterusnya). Event density menampilkan satu kartu per objek terdeteksi beserta confidence masing-masing.
Dua angka pada blok pengenalan sering disalahartikan:
- Kesamaan (
similarity, FRA) adalah nilai 0 sampai 1 yang menunjukkan seberapa mirip wajah yang terdeteksi dengan foto referensi di database. Ini ukuran kedekatan fitur wajah secara matematis, bukan persentase keyakinan bahwa orangnya sama. - Confidence (
confidence,confidence_detection) adalah nilai 0 sampai 1 yang menunjukkan seberapa yakin model bahwa objek yang terdeteksi memang objek yang dimaksud (misalnya benar wajah, bukan gambar wajah di poster). Ini tidak sama dengan kesamaan.
Putar ulang rekaman di tab Playback
Tangkapan layar tab Playback belum tersedia di dokumentasi ini karena tab tersebut hanya dirender ketika fitur Media Server aktif dan stream yang bersangkutan benar-benar punya rekaman NVR.
Tab Playback muncul di sebelah tab Detail hanya jika fitur Media Server aktif dan stream kamera tersebut memiliki rekaman NVR. Video dimulai 45 detik sebelum waktu event dan gambar event dipakai sebagai poster sampai frame pertama diputar. Di samping video ada daftar event lain dari kamera yang sama dalam rentang 5 menit sebelum dan sesudah, dengan event yang paling dekat disorot; klik salah satunya untuk melompat. Timeline di bawah menandai posisi event, segmen rekaman hari itu, dan thumbnail event; geser dengan drag atau scroll, dan gunakan Ctrl + scroll untuk zoom. Tombol Lihat Lengkap membuka halaman playback penuh untuk kamera tersebut.
Bagikan event dengan deep link
Tambahkan ?open_event=<event_id> ke URL halaman, misalnya /event-history?open_event=1780473522-a6d87102, dan panel detail event tersebut terbuka otomatis saat halaman dimuat; parameter dihapus dari URL setelah dibaca agar panel tidak terbuka lagi saat navigasi berikutnya. Salin Event ID dari badge di header panel untuk membuat tautan ini.
Mengekspor Event
Ekspor berguna untuk laporan insiden, bukti kepatuhan, atau analisis lanjutan di spreadsheet. Klik export di toolbar untuk membuka dialog Ekspor Event.
Prop
Type
Klik Mulai Ekspor. Ekspor tidak dibuat di browser, melainkan dijalankan sebagai job asinkron di server (POST /api/event-history/{category}/export). Toast Tugas ekspor ditambahkan. Lacak progres di Pusat Tugas. muncul dan ikon Pusat Tugas di footer aplikasi menampilkan jumlah tugas aktif. Buka Pusat Tugas untuk melihat status (Menunggu, Memproses, Selesai, Gagal) dan klik Unduh ketika selesai; tombol Batalkan menghentikan job yang masih berjalan.
Ekspor lebih dari 1.000 rekaman dibagi menjadi beberapa file (1.000 rekaman per file) dan dikirim sebagai arsip ZIP. Di mode Federation, satu job dibuat untuk setiap instance yang dipilih (atau semua instance bila tidak ada yang dipilih), masing-masing menghasilkan file sendiri karena setiap instance mengekspor datanya sendiri.
Smart Search
Smart Search memungkinkan Anda mencari event dengan kalimat bebas, misalnya "orang memakai jaket merah membawa tas", tanpa memilih kategori atau atribut satu per satu. Mode ini tampil sebagai pengalih Normal / Smart Search di bagian paling atas panel Filter dan hanya tersedia bila toggle Smart Search aktif di Preferensi → Fitur.
Tangkapan layar mode ini belum tersedia karena toggle Smart Search mati secara bawaan dan baru dapat dinyalakan setelah URL layanan embedding diisi di Preferensi → Fitur.
- Klik tab Smart Search. Panel berganti menjadi panel Smart Search.
- Ketik deskripsi pada Kata Pencarian dan atur Rentang Tanggal.
- Klik Apply (tanda 3). Hasil ditampilkan dengan Skor kemiripan, dalam mode daftar atau grid, dan dimuat bertahap saat Anda menggulir. Klik hasil untuk membuka panel Detail Event yang sama.
Mode dan kata pencarian tersimpan di URL (?mode=smart-search&q=...&ss_from=...&ss_to=...). Di sisi API, mode ini memanggil GET /api/smart-search; lihat halaman Search untuk cara kerja mesin pencarinya dan kuota ekstraksi di menu Smart Search Quota.
Federation Mode
Jika organisasi Anda menjalankan beberapa instance Lenz, halaman ini dapat menampilkan event dari semua instance sekaligus. Aktifkan lewat Preferensi → Fitur → Federation Mode.
- Field Instance muncul paling atas di Filter Umum sebagai multi-select. Kosong (Semua instance) berarti agregasi seluruh instance; pilih satu atau beberapa instance untuk mempersempit. Mengganti pilihan instance mengosongkan filter Stream dan Tipe Analitik karena daftarnya berbeda per instance.
- Tabel mendapat kolom Instance dan kartu grid mendapat badge instance, keduanya menampilkan nama instance beserta alamatnya.
- Panel detail, gambar, tombol Cari, dan tautan Person Re-ID selalu diarahkan ke instance asal event.
- Ekspor membuat satu job per instance (lihat catatan di Mengekspor Event).
Di sisi API, kirim instance=<id> untuk satu instance, instance=a,b untuk beberapa, atau is_aggregated=true tanpa instance untuk semua. Federation Module menggabungkan hasil fan-out, mengurutkannya ulang berdasarkan (event_time, event_id), dan membangun ulang next_cursor sehingga infinite scroll tetap konsisten.
curl -X GET "${API_URL}/api/event-history/fra?is_aggregated=true&filter[timestamp_from]=2026-04-30T00:00:00%2B07:00&filter[timestamp_to]=2026-04-30T23:59:59%2B07:00&limit=20&include_total=true" \
-H "X-Api-Key: <api-key>"Toast Alert: Tidak Hanya di Halaman Ini
Penting untuk operator yang baru mengenal Lenz: toast notifikasi alert muncul di pojok kanan atas layar terlepas dari halaman mana yang sedang Anda buka, baik di Event History, Streams, Preferensi, maupun halaman lainnya. Anda tidak perlu berada di halaman Event History untuk menerima alert real-time.
Alert hanya muncul apabila event memenuhi minimal satu Alert Rule yang aktif. Jika Anda tidak melihat toast padahal kamera aktif mengirim event, pastikan Alert Rule sudah dikonfigurasi dan diaktifkan di menu Alert Rules. Alert yang sudah lewat dapat ditelusuri di halaman Alert History.
Fitur Utama
Tujuh Kategori Analitik
FRA, MPAA, MVAA, CE, LPR, PPE, dan General Events, masing-masing dengan kolom tabel, filter atribut, dan opsi pengurutan yang relevan secara otomatis.
Filter Multi-Dimensi
Kombinasikan Tipe Analitik, Rentang Tanggal, Stream, Event ID, dan atribut spesifik kategori; nilai pilihan diisi dinamis dari data yang pernah terdeteksi. Semua filter tercermin di URL.
Tabel dan Grid dengan Infinite Scroll
Beralih antara tabel kompak untuk membaca atribut dan grid visual untuk membandingkan gambar. Halaman berikutnya dimuat otomatis 20 event sekali gulir.
Panel Detail dan Playback
Header yang menempel dengan Event ID yang dapat disalin, blok pengenalan wajah atau plat, peta, floorplan, atribut lengkap, dan tab Playback dengan timeline rekaman NVR.
Lompat ke Investigasi
Tombol Cari membuka Face Search atau Plate Search dari satu event; tombol Cari penampilan serupa membawa gambar event ke Person Re-ID.
Ekspor Asinkron
PDF atau Excel, halaman saat ini atau semua event sesuai filter, dengan atau tanpa gambar. Job berjalan di server dan hasilnya diunduh dari Pusat Tugas.
Smart Search
Cari event dengan kalimat bahasa alami lintas kategori dan kamera; hasil diurutkan berdasarkan skor kemiripan.
Federation Aware
Tampilkan event dari semua instance sekaligus atau pilih beberapa instance; kolom Instance, panel detail, dan ekspor mengikuti instance asal event.
Feed WebSocket untuk Integrator
Berlangganan seluruh deteksi lewat /api/event_channel atau hanya event yang lolos Alert Rule lewat /api/alert_channel.
WebSocket Protocol untuk Integrator
Bagian ini ditujukan untuk integrator yang ingin berlangganan langsung ke feed real-time dari luar Lenz, misalnya untuk membangun sistem notifikasi eksternal, dashboard monitoring, atau alur otomasi.
WebSocket adalah koneksi jaringan yang tetap terbuka sehingga server dapat mendorong event begitu terjadi. Bayangkan perbedaan antara mengecek kotak surat setiap menit dengan tukang pos yang langsung mengetuk pintu saat ada paket: REST perlu di-poll berkala, WebSocket cukup dibuka sekali dan data mengalir masuk.
Sistem menyediakan dua channel WebSocket:
| Channel | Endpoint | Isi | Otentikasi |
|---|---|---|---|
| Event Channel | /api/event_channel | Semua event mentah dari Visionaire (setiap deteksi yang lewat pipeline) | Tidak ada; endpoint publik yang dikecualikan dari integration lock |
| Alert Channel | /api/alert_channel | Hanya event yang memenuhi minimal satu Alert Rule aktif, dibatasi ke stream yang boleh diakses pengguna | Query authorization=<access_token> (dipakai Lenz Dashboard) atau x-api-key=<key> (direkomendasikan untuk integrator) |
Endpoint Event Channel
wss://{BASE_URL}/api/event_channelGanti {BASE_URL} dengan hostname atau IP server backend Anda (tanpa protokol http:// atau https://).
Parameter Query
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
stream_ids | string | Tidak | ID stream yang ingin dimonitor, pisahkan dengan koma untuk beberapa stream. Kosong berarti semua stream. |
stream_id | string | Tidak | Bentuk tunggal dari stream_ids; dipertahankan untuk kompatibilitas. |
analytic_id | string | Tidak | ID analitik yang ingin diterima, pisahkan dengan koma. Contoh: NFV4-FR,NFV4-LPR. |
node_num | integer | Tidak | Nomor node Visionaire (default 0). |
logic | string | Tidak | Hanya event dengan logic type tertentu (mis. counting). |
disable_base64_image | boolean | Tidak | true untuk tidak menyertakan gambar base64 di payload; field primary_image_url / secondary_image_url tetap dikirim sehingga gambar dapat diambil terpisah. Sangat disarankan pada volume tinggi. |
instance | string | Tidak | Hanya di mode Federation: ID instance sumber. |
is_aggregated | boolean | Tidak | Hanya di mode Federation: true untuk menerima event dari semua instance. |
Otentikasi hanya diperlukan pada channel alert (/api/alert_channel), lewat query authorization=<access_token> atau x-api-key=<key>. event_channel bersifat publik dan mengabaikan kredensial apa pun yang dikirim. Kredensial dikirim sebagai query parameter, bukan header, karena browser tidak dapat mengatur header kustom saat WebSocket handshake. Detail mekanisme, masa berlaku token, dan contoh per jenis klien ada di Otentikasi: WebSocket.
Contoh Koneksi
const wsProtocol = location.protocol === 'https:' ? 'wss' : 'ws';
const baseUrl = location.host; // misalnya: lenz.contoh.com
const url = new URL(`${wsProtocol}://${baseUrl}/api/event_channel`);
url.searchParams.set('stream_ids', 'eb7022a64d9173a6,c1105b1c6e6b4f3a');
url.searchParams.set('analytic_id', 'NFV4-FR,NFV4-LPR');
url.searchParams.set('disable_base64_image', 'true');
const ws = new WebSocket(url.toString());
ws.onopen = () => {
console.log('Terhubung ke event channel');
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Event baru:', data);
};
ws.onclose = (event) => {
console.log('Koneksi tertutup:', event.code, event.reason);
};
ws.onerror = (error) => {
console.error('WebSocket error:', error);
};import WebSocket from 'ws';
const params = new URLSearchParams({
stream_ids: 'eb7022a64d9173a6,c1105b1c6e6b4f3a',
analytic_id: 'NFV4-FR,NFV4-LPR',
disable_base64_image: 'true',
});
const ws = new WebSocket(
`wss://api.contoh.com/api/event_channel?${params.toString()}`
);
ws.on('open', () => {
console.log('Terhubung ke event channel');
});
ws.on('message', (data) => {
const event = JSON.parse(data.toString());
handleEvent(event);
});
ws.on('close', (code, reason) => {
console.log(`Koneksi tertutup: ${code} ${reason}`);
// Implementasikan reconnect dengan exponential backoff
setTimeout(() => reconnect(), 5000);
});
ws.on('error', (error) => {
console.error('WebSocket error:', error.message);
});
function handleEvent(event) {
// Proses event berdasarkan analytic_id
switch (true) {
case event.analytic_id.includes('FR'):
console.log(`[FRA] ${event.stream_id} - Status: ${event.pipeline_data?.status}`);
break;
case event.analytic_id.includes('LPR'):
console.log(`[LPR] ${event.stream_id} - Plat: ${event.pipeline_data?.plate_number}`);
break;
default:
console.log(`[${event.analytic_id}] ${event.stream_id}`);
}
}# cURL tidak mendukung WebSocket secara native.
# Gunakan websocat (https://github.com/vi/websocat) sebagai alternatif:
websocat \
"wss://api.contoh.com/api/event_channel?stream_ids=eb7022a64d9173a6&disable_base64_image=true"Reconnect Otomatis
Lenz Dashboard menjalankan koneksi alert_channel di dalam Web Worker dengan reconnect otomatis. Sebaiknya Anda menerapkan pola yang sama di integrasi Anda:
| Parameter | Nilai |
|---|---|
| Jeda reconnect | min(1000 × 2^percobaan, 30000) + jitter milidetik; jitter acak hingga 1.000 ms untuk menghindari thundering herd |
| Batas percobaan | 10 kali; setelah itu koneksi dianggap terputus dan perlu dimulai ulang (Lenz memulai ulang saat halaman dimuat kembali) |
| Heartbeat | Ping setiap 30.000 ms (30 detik) untuk menjaga koneksi tetap hidup di balik proxy |
Penghitung percobaan direset ke nol setiap kali koneksi berhasil dibuka.
Alert Channel (untuk Toast dan Sistem Eksternal)
Channel wss://{BASE_URL}/api/alert_channel hanya mengirim event yang sudah lolos minimal satu Alert Rule aktif, dan hanya dari stream yang boleh diakses oleh pengguna atau API key yang dipakai. Cocok jika Anda hanya ingin menerima event signifikan, bukan seluruh aliran deteksi.
import WebSocket from 'ws';
const params = new URLSearchParams({
'x-api-key': '<api-key>',
disable_base64_image: 'false',
is_aggregated: 'true', // ambil dari semua instance dalam Federation
});
const ws = new WebSocket(`wss://api.contoh.com/api/alert_channel?${params}`);
ws.on('message', (data) => {
const event = JSON.parse(data.toString());
// event.alert_type_id dan event.alertable_id terisi; alert_history_id TIDAK dikirim
console.log(`Alert ${event.alert_type_id}: ${event.analytic_id} (${event.alertable_id})`);
});Payload alert_channel sama dengan event_channel, ditambah dua field:
| Field | Tipe | Deskripsi |
|---|---|---|
alert_type_id | number | ID Alert Type; gunakan untuk lookup warna, durasi, dan suara via /api/alert-type |
alertable_id | string | Nilai yang sama dengan kolom alertable_id pada tabel alert history; gunakan untuk menautkan pesan ini ke record REST |
Field alert_history_id tidak dikirim pada channel ini karena record alert history disimpan secara asinkron setelah pesan terkirim. Detail parameter, respons, dan cara menautkan pesan ke record REST ada di API Reference: Alert History.
Format Event Payload
WebSocket Event Payload
Setiap pesan yang diterima dari WebSocket memiliki struktur berikut. Operator tidak pernah melihat JSON ini secara langsung; bagian ini ditujukan untuk integrator yang mem-parsing data event secara programatik.
{
"event_id": "1780473522-a6d87102",
"analytic_id": "NFV4-FR",
"stream_id": "eb7022a64d9173a6",
"node_num": 0,
"label": "UNKNOWN",
"location": "Lobby Utama",
"primary_image_url": "/api/attachments?owner_type=primary&owner_id=1780473522-a6d87102",
"secondary_image_url": "/api/attachments?owner_type=secondary&owner_id=1780473522-a6d87102",
"primary_image": null,
"secondary_image": null,
"result": "UNKNOWN",
"timestamp": "2026-04-30T08:23:45+07:00",
"status": "UNKNOWN",
"logic": "face_recognition",
"pipeline_data": {
"event_id": "1780473522-a6d87102",
"face_id": "118747588341006337",
"similarity": 0.4893847107887268,
"status": "UNKNOWN",
"confidence_detection": 0.9988495111465454,
"variation": "13219648471735459236"
}
}Deskripsi Field Utama:
| Field | Tipe | Deskripsi |
|---|---|---|
event_id | string | Event ID dari engine analitik; kunci untuk deep link dan GET /api/events/pipeline/{event_id} |
analytic_id | string | ID analitik engine (contoh: NFV4-FR, NFV4-LPR, NFV4-MPAA) |
stream_id | string | ID stream/kamera sumber event |
node_num | integer | Nomor node Visionaire yang memproses event |
label | string | Label hasil deteksi (contoh: UNKNOWN, motorcycle, person) |
location | string | Nama lokasi/kamera seperti yang dikonfigurasi |
primary_image_url | string | URL gambar utama; dikirim juga saat disable_base64_image=true |
secondary_image_url | string | URL gambar kedua (tangkapan kamera untuk FRA, plat untuk LPR) |
primary_image | string | null | Gambar base64 (hanya jika disable_base64_image=false) |
result | string | Teks hasil analitik (bisa berupa nama orang, plat, dll.) |
timestamp | string | Waktu deteksi dalam format ISO 8601 |
status | string | Status hasil (contoh: KNOWN, UNKNOWN) |
logic | string | Logic type yang digunakan (counting, dwelling, density, dll.) |
instance | string | Hanya ada di mode Federation: ID instance asal event |
alert_type_id, alertable_id | number, string | Hanya ada pada pesan yang cocok dengan Alert Rule (lihat Alert Channel) |
pipeline_data | object | Data spesifik per analitik (lihat di bawah) |
pipeline_data per Kategori
Field pipeline_data berisi detail analitik yang bervariasi per kategori. Sekali lagi, bagian ini untuk integrator; operator melihat atribut ini dalam bentuk label di panel detail, bukan sebagai JSON.
{
"event_id": "1780473522-a6d87102",
"face_id": "118747588341006337",
"similarity": 0.9234,
"status": "KNOWN",
"confidence_detection": 0.9988,
"variation": "13219648471735459236"
}| Field | Deskripsi |
|---|---|
face_id | ID wajah yang terdeteksi dalam database |
similarity | Nilai kemiripan 0 sampai 1 (1 = identik) |
status | KNOWN atau UNKNOWN |
confidence_detection | Tingkat keyakinan deteksi wajah (0 sampai 1), terlepas dari identitas |
{
"event_id": "1780473600-3f9b21c0",
"plate_number": "B 1234 XYZ",
"label": "car",
"confidence": 0.9251,
"area_name": "Gerbang Masuk",
"bounding_box": {
"top": 0.409,
"left": 0.284,
"width": 0.247,
"height": 0.198
}
}| Field | Deskripsi |
|---|---|
plate_number | Nomor plat yang terbaca |
label | Jenis kendaraan (car, motorcycle, truck, dll.) |
confidence | Tingkat keyakinan pembacaan plat (0 sampai 1) |
area_name | Nama area/garis yang memicu event |
{
"event_id": "1780473655-91ab0c77",
"area_name": "Area Pintu Masuk",
"label": "person",
"confidence": 0.9998,
"count": 3
}| Field | Deskripsi |
|---|---|
area_name | Nama area atau garis virtual yang dikonfigurasi |
label | Jenis objek yang terdeteksi (person) |
confidence | Tingkat keyakinan deteksi (0 sampai 1) |
count | Jumlah orang (untuk mode counting) |
Atribut tambahan seperti jenis kelamin, usia, dan warna pakaian dikembalikan sebagai field tingkat atas pada respons REST (gender, age, upper_color, dst.), bukan di dalam pipeline_data.
{
"event_id": "1780473701-c04d5e18",
"area_name": "Gerbang Parkir",
"label": "car",
"confidence": 0.9875,
"count": 1
}| Field | Deskripsi |
|---|---|
area_name | Nama area atau garis virtual yang dikonfigurasi |
label | Jenis kendaraan yang terdeteksi |
confidence | Tingkat keyakinan deteksi (0 sampai 1) |
count | Jumlah kendaraan (untuk mode counting) |
Atribut tambahan seperti merek, warna, tipe kendaraan, dan kecepatan dikembalikan sebagai field tingkat atas pada respons REST (brand, color, vehicle_type, speed_kmh), bukan di dalam pipeline_data.
Tips & Troubleshooting
Selanjutnya
Alert
Konfigurasi Alert Rule yang menentukan event mana yang memicu toast, suara, dan notifikasi eksternal.
Alert History
Telusuri alert yang sudah terpicu, tandai tindak lanjut, dan ekspor riwayat alert.
Search (Smart Search)
Cara kerja pencarian bahasa alami lintas kategori yang juga dipakai oleh mode Smart Search di halaman ini.
Otentikasi
Panduan API Key, Bearer token, dan otentikasi WebSocket untuk mengamankan koneksi REST dan WebSocket.
API Reference — Assignment
Endpoint untuk mengelola Assignment analitik ke stream — template konfigurasi analitik, preset konfigurasi, dan drawing preset ROI.
API Reference: Events
Endpoint REST untuk membaca arsip event per kategori dengan cursor-based pagination, opsi filter, detail event, ekspor asinkron, serta WebSocket channel untuk feed event real-time.