Etkinlik izleme: ajan API'si (geliştiriciler için)

Bu rehber geliştiriciler içindir. Kaam360 masaüstü ajanları Kaam360 ile /api/agent/v1 adresindeki küçük bir web API'si üzerinden konuşur. Postman gibi araçlar için tam tanımı /api/agent/v1/openapi.json adresindedir. İzlemenin Kaam360'ta nasıl ayarlanacağı etkinlik izleme rehberinde anlatılır.

Her çağrı için kurallar

• Yalnızca HTTPS üzerinden. Düz HTTP reddedilir.
• Form yüklemesi olan ekran görüntüleri dışında JSON gönderin (Content-Type: application/json).
• Kayıttan sonra cihaz anahtarını her çağrıda Authorization: Bearer ve ardından anahtar olarak gönderin (anahtar kad_ ile başlar). Bunu sistemin güvenli deposunda (Windows DPAPI, macOS Keychain) saklayın. Kaam360 yalnızca parmak izini tutar.
• Yanıtlar { "data": ... } biçimindedir. Bir ret, bir HTTP durumuyla birlikte { "error": { "code", "message" } } biçimindedir: yanlış ya da iptal edilmiş anahtar için 401 (yeniden kaydolun), duraklatılmış bir bilgisayar ya da kapatılmış bir özellik için 403, bir seferde çok fazlası için 413, yanlış bir alan için 422, çok fazla çağrı için 429 (Retry-After'daki saniye kadar bekleyin).
• Asla tuş vuruşlarını, yazılan metni, parolaları ya da mesajların ve belgelerin içeriğini göndermeyin. Bir web sitesinin yalnızca alan adını gönderin.

1. Kaydolun: POST /register

Cihazlar'daki kayıt kodunu, bu kurulum için kendi kimliğinizi (installId, bir kez oluşturulur ve saklanır), bilgisayarın adını, os (windows ya da macos), osVersion, agentVersion ve biliyorsanız kişinin iş e-postasını gönderin. Yanıt cihaz anahtarını (yalnızca bu kez gösterilir) ve kuralları içerir. Bir adresten saatte en fazla 20 kayıt gelir.

2. Bağlanın: POST /heartbeat

Her heartbeatSeconds'ta (varsayılan olarak beş dakika) agentVersion, bilgisayarın saatini (sentAtUtc) ve kaç dilimin beklediğini gönderin. Yanıt güncel kuralları (policy) ve bilgisayarın duraklatılmış olup olmadığını ya da henüz bir kişisi olup olmadığını içerir. Yalnızca kuralları okumak için GET /policy kullanın.

Kurallar ajana şunları söyler: trackingEnabled (false olduğunda hiçbir şey kaydetme), workStart, workEnd, workDays ve saat dilimiyle birlikte workHoursOnly, neverRecord (atlanacak programlar ve alan adları), recordTitles, screenshots (enabled, intervalMinutes, blur, maxBytes), idleMinutes, uploadBatchSize, maxBatchSlices, maxBufferDays, noticeText (ilk açılışta ve bildirim alanı simgesinden gösterin) ve minAgentVersion.

3. Etkinlik gönderin: POST /activity

Kendi batchId'nizi, sentAtUtc'yi ve en fazla 1000 dilimi (en fazla 1 MB) gönderin. Her dilimde start ve end (UTC), app (program), title (yalnızca recordTitles açıkken), domain ve idle bulunur. Aynı batchId'yi yeniden göndermek hiçbir şey yapmaz; bu yüzden kopan bir bağlantıdan sonra gönül rahatlığıyla yeniden deneyin. Yanıt kaç dilimin tutulduğunu ve diğerlerinin neden atıldığını söyler: tracking_off, no_person, invalid, too_long (4 saatten uzun), future, too_old (14 günden eski), never_record ya da outside_hours. Bir dakikadan fazla sapan bilgisayar saati düzeltilir; bir günden fazla sapan reddedilir.

4. Ekran görüntüsü gönderin: POST /screenshots

Yalnızca ekran görüntüleri etkinken. file (JPEG, PNG ya da WebP, en fazla 1 MB), takenAtUtc, app, domain ve blurred içeren bir form yüklemesi. blur açıkken önce resmi bulanıklaştırın: net bir resim reddedilir. Aralıktan daha sık göndermeyin. Asla kaydedilmeyecek bir programın ya da mesai dışında alınan bir ekran görüntüsü tutulmaz.

Çevrimdışı

Bağlantı yokken dilimleri bilgisayarda tutun (şifrelenmiş, en fazla maxBufferDays boyunca) ve bağlantı geri geldiğinde toplu olarak gönderin.

5. Güncellemeler: GET /update

Günde bir kez os (windows ya da macos) ve ajanın sürümüyle GET /update çağırın. Yanıt latestVersion, downloadUrl, sha256, sizeBytes, updateAvailable ve updateRequired (ajan, kuruluşun kabul ettiği en düşük sürümden eski) değerlerini verir. Yalnızca aynı Kaam360 adresindeki downloadUrl'den indirin, dosyanın boyutunu ve SHA-256 parmak izini kontrol edin ve çalıştırmadan önce kod imzasını kontrol edin. En yeni kurulum programı herkes için /download/agent/windows adresinde, Mac paketi (.pkg) ise /download/agent/macos adresindedir (bu bir programdır, veri değildir: bir bilgisayarı bağlayan şey kayıt kodudur). Mac için paketin xar! ile başladığını ve uygulamanız bir Apple Developer ID ile imzalandığında pkgutil --check-signature komutunun aynı ekibi gösterdiğini kontrol edin.

Kaam360'ın oluşturduğu Windows ve Mac ajanları bunların hepsine uyar; kodları Kaam360 kaynak kodundaki agents klasöründedir ve docs/activity-agent.md bunları anlatır.