Pelacakan aktivitas: API agen (untuk pengembang)

Panduan ini untuk pengembang. Agen desktop Kaam360 berkomunikasi dengan Kaam360 melalui API web kecil di /api/agent/v1. Deskripsi lengkapnya, untuk alat seperti Postman, ada di /api/agent/v1/openapi.json. Cara mengatur pelacakan di Kaam360 ada di panduan pelacakan aktivitas.

Aturan untuk setiap panggilan

• Hanya melalui HTTPS. HTTP biasa ditolak.
• Kirim JSON (Content-Type: application/json), kecuali tangkapan layar, yang berupa unggahan formulir.
• Setelah pendaftaran, kirim kunci perangkat pada setiap panggilan sebagai Authorization: Bearer diikuti kuncinya (diawali kad_). Simpan di penyimpanan aman sistem (Windows DPAPI, Keychain macOS). Kaam360 hanya menyimpan sidik jarinya.
• Jawaban berbentuk { "data": ... }. Penolakan berbentuk { "error": { "code", "message" } } dengan status HTTP: 401 untuk kunci yang salah atau dicabut (daftar lagi), 403 untuk komputer yang dijeda atau fitur yang dimatikan, 413 untuk terlalu banyak sekaligus, 422 untuk kolom yang salah, 429 untuk terlalu banyak panggilan (tunggu sebanyak detik di Retry-After).
• Jangan pernah mengirim ketukan tombol, teks yang diketik, kata sandi, atau isi pesan dan dokumen. Kirim hanya domain situs web.

1. Mendaftar: POST /register

Kirim kode pendaftaran dari Perangkat, id Anda sendiri untuk pemasangan ini (installId, dibuat sekali dan disimpan), nama komputer, os (windows atau macos), osVersion, agentVersion, dan jika diketahui, email kerja orangnya. Jawabannya berisi kunci perangkat (hanya ditampilkan kali ini) dan aturannya. Paling banyak 20 pendaftaran per jam dari satu alamat.

2. Melapor: POST /heartbeat

Setiap heartbeatSeconds (lima menit secara bawaan) kirim agentVersion, jam komputer (sentAtUtc), dan berapa banyak potongan yang menunggu. Jawabannya berisi aturan terkini (policy) dan apakah komputer dijeda atau belum punya orang. Gunakan GET /policy untuk membaca aturannya saja.

Aturan memberi tahu agen: trackingEnabled (jangan mencatat apa pun jika false), workHoursOnly dengan workStart, workEnd, workDays, dan zona waktunya, neverRecord (program dan domain yang dilewati), recordTitles, screenshots (enabled, intervalMinutes, blur, maxBytes), idleMinutes, uploadBatchSize, maxBatchSlices, maxBufferDays, noticeText (tampilkan saat pertama kali dijalankan dan dari ikon baki), dan minAgentVersion.

3. Mengirim aktivitas: POST /activity

Kirim batchId milik Anda, sentAtUtc, dan hingga 1000 potongan (paling besar 1 MB). Setiap potongan punya start dan end (UTC), app (programnya), title (hanya jika recordTitles menyala), domain, dan idle. Mengirim batchId yang sama lagi tidak melakukan apa pun, jadi silakan ulangi setelah koneksi terputus. Jawabannya menyebutkan berapa yang disimpan dan mengapa yang lain dibuang: tracking_off, no_person, invalid, too_long (lebih dari 4 jam), future, too_old (lebih dari 14 hari), never_record, atau outside_hours. Jam komputer yang meleset lebih dari satu menit dikoreksi; yang meleset lebih dari satu hari ditolak.

4. Mengirim tangkapan layar: POST /screenshots

Hanya jika tangkapan layar diaktifkan. Unggahan formulir dengan file (JPEG, PNG, atau WebP, paling besar 1 MB), takenAtUtc, app, domain, dan blurred. Kaburkan gambar terlebih dahulu jika blur menyala: gambar yang tajam ditolak. Tidak lebih sering daripada intervalnya. Tangkapan layar dari program yang tidak boleh dicatat atau di luar jam kerja tidak disimpan.

Offline

Simpan potongan di komputer selama tidak ada koneksi (dienkripsi, paling lama maxBufferDays) dan kirim dalam batch saat koneksi kembali.

5. Pembaruan: GET /update

Panggil GET /update dengan os (windows atau macos) dan versi agen sekali sehari. Jawabannya memberikan latestVersion, downloadUrl, sha256, sizeBytes, updateAvailable, dan updateRequired (agen lebih lama daripada versi terendah yang diterima organisasi). Unduh hanya dari downloadUrl di alamat Kaam360 yang sama, periksa ukuran dan sidik jari SHA-256 file, dan periksa tanda tangan kodenya sebelum menjalankannya. Penginstal terbaru juga ada di /download/agent/windows, dan paket Mac (.pkg) di /download/agent/macos, untuk siapa saja (ini program, bukan data: kode pendaftaranlah yang menghubungkan komputer). Untuk Mac, periksa bahwa paket diawali xar! dan, jika aplikasi Anda ditandatangani dengan Apple Developer ID, bahwa pkgutil --check-signature menampilkan tim yang sama.

Agen Windows dan Mac buatan Kaam360 mengikuti semua ini; kodenya ada di folder agents pada kode sumber Kaam360, dan docs/activity-agent.md menjelaskannya.