سرگرمی کی نگرانی: ایجنٹ API (ڈویلپرز کے لیے)

یہ گائیڈ ڈویلپرز کے لیے ہے۔ Kaam360 کے ڈیسک ٹاپ ایجنٹ /api/agent/v1 پر ایک چھوٹے ویب API کے ذریعے Kaam360 سے بات کرتے ہیں۔ Postman جیسے ٹولز کے لیے اس کی پوری تفصیل /api/agent/v1/openapi.json پر ہے۔ Kaam360 میں نگرانی ترتیب دینے کا طریقہ سرگرمی کی نگرانی کی گائیڈ میں ہے۔

ہر کال کے اصول

• صرف HTTPS پر۔ سادہ HTTP رد ہو جاتا ہے۔
• JSON بھیجیں (Content-Type: application/json)، سوائے اسکرین شاٹس کے، جو فارم کی صورت میں اپ لوڈ ہوتے ہیں۔
• رجسٹریشن کے بعد ہر کال میں آلے کی چابی Authorization: Bearer کے بعد چابی لکھ کر بھیجیں (یہ kad_ سے شروع ہوتی ہے)۔ اسے سسٹم کے محفوظ اسٹور میں رکھیں (Windows DPAPI، macOS Keychain)۔ Kaam360 اس کا صرف فنگر پرنٹ رکھتا ہے۔
• جواب { "data": ... } ہوتے ہیں۔ انکار { "error": { "code", "message" } } اور HTTP حالت کے ساتھ ہوتا ہے: 401 غلط یا منسوخ چابی کے لیے (دوبارہ رجسٹر کریں)، 403 روکے گئے کمپیوٹر یا بند فیچر کے لیے، 413 ایک ساتھ بہت زیادہ کے لیے، 422 غلط فیلڈ کے لیے، 429 بہت زیادہ کالز کے لیے (Retry-After میں لکھے سیکنڈ انتظار کریں)۔
• کبھی کی اسٹروکس، لکھا ہوا متن، پاس ورڈ، یا پیغامات اور دستاویزات کا مواد نہ بھیجیں۔ ویب سائٹ کا صرف ڈومین بھیجیں۔

1. رجسٹر کریں: POST /register

آلات سے رجسٹریشن کوڈ، اس انسٹالیشن کے لیے اپنی id (installId، ایک بار بنائیں اور رکھیں)، کمپیوٹر کا نام، os (windows یا macos)، osVersion، agentVersion اور معلوم ہو تو اس شخص کی کام والی ای میل بھیجیں۔ جواب میں آلے کی چابی (صرف اسی بار دکھتی ہے) اور اصول ہوتے ہیں۔ ایک پتے سے ایک گھنٹے میں زیادہ سے زیادہ 20 رجسٹریشن ہو سکتی ہیں۔

2. رابطہ کریں: POST /heartbeat

ہر heartbeatSeconds (شروع میں پانچ منٹ) بعد agentVersion، کمپیوٹر کی گھڑی (sentAtUtc) اور انتظار میں موجود حصوں کی تعداد بھیجیں۔ جواب میں موجودہ اصول (policy) ہوتے ہیں، اور یہ کہ کمپیوٹر روکا گیا ہے یا ابھی کسی کو نہیں دیا گیا۔ صرف اصول پڑھنے کے لیے GET /policy استعمال کریں۔

اصول ایجنٹ کو بتاتے ہیں: trackingEnabled (false ہو تو کچھ ریکارڈ نہ کریں)، workHoursOnly کے ساتھ workStart، workEnd، workDays اور ٹائم زون، neverRecord (چھوڑنے والے پروگرام اور ڈومین)، recordTitles، screenshots (enabled، intervalMinutes، blur، maxBytes)، idleMinutes، uploadBatchSize، maxBatchSlices، maxBufferDays، noticeText (پہلی بار شروع ہونے پر اور ٹرے آئیکن سے دکھائیں) اور minAgentVersion۔

3. سرگرمی بھیجیں: POST /activity

اپنی batchId، sentAtUtc اور زیادہ سے زیادہ 1000 حصے بھیجیں (زیادہ سے زیادہ 1 MB)۔ ہر حصے میں start اور end (UTC)، app (پروگرام)، title (صرف جب recordTitles چالو ہو)، domain اور idle ہوتے ہیں۔ وہی batchId دوبارہ بھیجنے سے کچھ نہیں ہوتا، اس لیے کنکشن ٹوٹنے کے بعد بے فکر ہو کر دوبارہ بھیجیں۔ جواب بتاتا ہے کتنے رکھے گئے اور باقی کیوں رد ہوئے: tracking_off، no_person، invalid، too_long (4 گھنٹے سے زیادہ)، future، too_old (14 دن سے پرانا)، never_record یا outside_hours۔ ایک منٹ سے زیادہ غلط کمپیوٹر گھڑی درست کی جاتی ہے؛ ایک دن سے زیادہ غلط ہو تو رد کی جاتی ہے۔

4. اسکرین شاٹ بھیجیں: POST /screenshots

صرف جب اسکرین شاٹس چالو ہوں۔ فارم اپ لوڈ جس میں file (JPEG، PNG یا WebP، زیادہ سے زیادہ 1 MB)، takenAtUtc، app، domain اور blurred ہوں۔ blur چالو ہو تو پہلے تصویر دھندلی کریں: صاف تصویر رد ہو جاتی ہے۔ وقفے سے زیادہ بار نہیں۔ کبھی ریکارڈ نہ ہونے والے پروگرام کا یا کام کے اوقات کے باہر کا اسکرین شاٹ نہیں رکھا جاتا۔

آف لائن

کنکشن نہ ہو تو حصے کمپیوٹر پر رکھیں (خفیہ کر کے، زیادہ سے زیادہ maxBufferDays تک) اور کنکشن واپس آنے پر بیچ میں بھیجیں۔

5. اپ ڈیٹس: GET /update

دن میں ایک بار os (windows یا macos) اور ایجنٹ کے ورژن کے ساتھ GET /update بلائیں۔ جواب میں latestVersion، downloadUrl، sha256، sizeBytes، updateAvailable اور updateRequired ہوتے ہیں (ایجنٹ تنظیم کے قبول کردہ کم سے کم ورژن سے پرانا ہے)۔ صرف اسی Kaam360 پتے پر موجود downloadUrl سے ڈاؤن لوڈ کریں، چلانے سے پہلے فائل کا سائز، SHA-256 فنگر پرنٹ اور کوڈ دستخط جانچیں۔ سب سے نیا انسٹالر ہر کسی کے لیے /download/agent/windows پر بھی ہے (یہ ایک پروگرام ہے، ڈیٹا نہیں: کمپیوٹر کو رجسٹریشن کوڈ جوڑتا ہے)۔ Mac پیکج (.pkg) /download/agent/macos پر ہے؛ Mac پر جانچیں کہ فائل xar! سے شروع ہو اور، اگر آپ کی ایپ پر Apple Developer ID کے دستخط ہیں، تو pkgutil --check-signature وہی ٹیم دکھائے۔

Kaam360 کا بنایا ہوا Windows ایجنٹ یہ سب کرتا ہے؛ اس کا کوڈ Kaam360 سورس کے agents فولڈر میں ہے اور docs/activity-agent.md اس کی وضاحت کرتا ہے۔