إرسال أحداث SDK - التقاط الأحداث من جهة العميل

معظم الأحداث المتعلقة بالاحتيال تقع على الجهاز: تسجيل الدخول، والجلسة، وجولة اللعب، والقياسات الزمنية التي تفصل الإنسان عن البرنامج الآلي. يرسل مسار الجهاز هذه الأحداث دون وضع مفتاح API في المتصفح. يُصدر خادمك بيانات اعتماد قصيرة الصلاحية مقصورة على مستخدم واحد، ثم يرسل التطبيق الأحداث بها.

التدفق

إصدار بيانات اعتماد للمراقبة

يستدعي خادمك POST /v3/events/sdk-token/ بمفتاح API الخاص بك وvendor_data الخاص بالمستخدم.

الإرسال من الجهاز

يرسل التطبيق طلب POST إلى POST /v1/events/ (أو POST /v1/events/batch/) مع الرأس X-Monitoring-Token.

تعمل القواعد كالمعتاد

يُثرى الحدث ويُجمّع ويُقيَّم بـالقواعد نفسها تماماً التي تُقيَّم بها الأحداث المرسلة من الخادم.

إصدار بيانات الاعتماد

يتطلب إصدار بيانات الاعتماد تفعيل استيعاب الأحداث للتطبيق. وما دام معطلاً، فإن نقطة النهاية هذه ترد بالرمز 403 مع {"code": "event_monitoring_disabled"} بدلاً من إصدار بيانات اعتماد لا يمكنها الكتابة أبداً.

curl -X POST https://verification.didit.me/v3/events/sdk-token/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user_391",
    "allowed_event_categories": ["auth", "session", "gameplay"],
    "ttl_seconds": 900,
    "max_uses": 1000,
    "bind_to_origin": "https://operator.example"
  }'

{
  "monitoring_token": "…",
  "expires_at": "2026-08-31T21:00:00Z",
  "allowed_event_categories": ["auth", "session", "gameplay"],
  "max_uses": 1000,
  "bind_to_origin": "https://operator.example"
}

الحقل	القيمة الافتراضية	ملاحظات
`vendor_data`	مطلوب	الكيان الذي تنتمي إليه كل الأحداث المرسلة ببيانات الاعتماد هذه.
`entity_type`	`individual`	`individual` أو `company`.
`allowed_event_categories`	الكل	يقلّص ما يمكن لبيانات اعتماد مسرّبة أن تكتبه.
`ttl_seconds`	900	60 - 86400.
`max_uses`	1000	استخدام واحد لكل حدث، لا لكل طلب.
`bind_to_origin`	لا شيء	عند تعيينه، يجب أن يطابق `Origin` في المتصفح تماماً.

الإرسال

curl -X POST https://verification.didit.me/v1/events/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "session-abc-login-1",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "session": { "session_id": "web-session-abc", "sequence": 1 },
    "device_context": { "fingerprint": "didit-fp-v2:a8c1" },
    "payload": { "method": "password" }
  }'

لاحظ ما لا تحمله الـ payload: لا مفتاح API، ولا الكيان المعني. ويُفرض الاثنان من جهة الخادم.

ما يفرضه الخادم

ربط الكيان. تُقيَّد بيانات الاعتماد بكيان واحد محدد في vendor_data وقت الإصدار. تُستبدل كتلة subject في نص الطلب، فلا يستطيع عميل تم العبث به الكتابة في الخط الزمني لمستخدم آخر.
سياق الشبكة. يُشتق عنوان IP ووكيل المستخدم وaccept-language وOrigin من الطلب، وتتقدم هذه القيم التي يحددها الخادم على أي تلميح يرسله العميل عند تقييم القواعد. ويسجّل دليل القاعدة الفرق بوصفه مصدر الحقل.
نطاق الفئات. لا يمكن لبيانات اعتماد مقصورة على session إرسال حدث payment، ويُرفض ذلك بالرمز 400.
ميزانية الاستخدام. تستهلك الدفعة استخداماً واحداً لكل حدث، فلا تستطيع دفعة من 500 حدث أن تمرّ عبر بيانات اعتماد ذات 10 استخدامات بوصفها استخداماً واحداً.
ربط Origin. عند تعيين bind_to_origin، يُرفض أي طلب لا يطابق Origin الخاص به، بما في ذلك الطلب الذي لا يحمل Origin إطلاقاً.

التجميع في دفعات

curl -X POST https://verification.didit.me/v1/events/batch/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "events": [ { "…": "…" }, { "…": "…" } ] }'

حتى 500 حدث في كل دفعة إرسال، مع النتائج نفسها لكل عنصر كما في نقطة نهاية الدفعات على الخادم. دفعة الإرسال الافتراضية المناسبة هي 25 حدثاً، أو 5 ثوانٍ، أو انتقال الصفحة أو التطبيق إلى الخلفية.

ما الذي يُحذف عند الضغط العكسي

إذا اضطررت إلى إسقاط أحداث، فأسقط الأرخص منها. يمكن إسقاط هذه الأحداث بأمان: session.page_view · session.sdk_heartbeat · session.sdk_loaded · session.device_seen · session.bot_signal_observed · bonus.promotion_viewed · affiliate.referral_clicked أما هذه فلا، فأرسلها أولاً: كل حدث من فئات security وpayment وdispute وresponsible_gambling، إضافة إلى gameplay.bet_placed وgameplay.bet_settled وgameplay.p2p_settlement. تعيد نقاط نهاية القوائم التصنيف نفسه لكل حدث في is_droppable، فيمكن أن يُوجَّه العميل بهذا الحقل بدلاً من نسخة مكتوبة يدوياً في الشيفرة.

توافق الرؤوس

الرأس القياسي هو X-Monitoring-Token. يُقبل X-Transaction-Token بوصفه اسماً مستعاراً مؤقتاً، حتى يتمكن تطبيق يملك بالفعل مسار بيانات اعتماد للمعاملات من الانتقال تدريجياً.

الاسم المستعار انتقالي، وسيُزال قبل إتاحة واجهة الأحداث للعموم. أرسل X-Monitoring-Token في الشيفرة الجديدة.

اختيار المسار

	مسار الجهاز	مسار الخادم
نقطة النهاية	`POST /v1/events/`	`POST /v3/events/`
المصادقة	`X-Monitoring-Token`	`x-api-key`
الكيان المعني	مرتبط ببيانات الاعتماد	موجود في الـ payload
الأنسب لـ	تسجيلات الدخول، والجلسات، واللعب، والقياسات	المدفوعات، والنزاعات، والأحداث المشتقة من السجل المالي، والتعبئة الرجعية

ينتج المساران سجلات أحداث متطابقة، ويشغّلان القواعد نفسها. استخدم مسار الخادم كلما لم يكن هناك مستخدم نهائي حاضر.

استيعاب الأحداث

الغلاف، والفئات، والاحتفاظ بالبيانات، وidempotency.

القواعد على الأحداث

قواعد السرعة والنسبة والتسلسل والارتباط.

البدء

الميزات

المرجع

Console

إرسال أحداث SDK - التقاط الأحداث من جهة العميل

التدفق

إصدار بيانات الاعتماد

الإرسال

ما يفرضه الخادم

التجميع في دفعات

ما الذي يُحذف عند الضغط العكسي

توافق الرؤوس

اختيار المسار

التالي

استيعاب الأحداث

القواعد على الأحداث

​التدفق

​إصدار بيانات الاعتماد

​الإرسال

​ما يفرضه الخادم

​التجميع في دفعات

​ما الذي يُحذف عند الضغط العكسي

​توافق الرؤوس

​اختيار المسار

​التالي

استيعاب الأحداث

القواعد على الأحداث

التدفق

إصدار بيانات الاعتماد

الإرسال

ما يفرضه الخادم

التجميع في دفعات

ما الذي يُحذف عند الضغط العكسي

توافق الرؤوس

اختيار المسار

التالي