مرجع نموذج الأحداث

كل حدث ترسله إلى تتبع التحويلات في Scanova — من المتصفح أو من الخادم لديك — يتبع البنية نفسها. وتوثّق هذه الصفحة كل حقل يمكنك تضمينه، وتشرح ما تفعله به مراحل المعالجة.

أحداث المتصفح (`POST /ct`)

يرسل SDK أحداث المتصفح تلقائيًا، أو ترسلها أنت يدويًا عبر scanova('track', ...). وهي تمثل الإجراءات التي تقع في متصفح الزائر.

الحقول التي يمكنك إرسالها

الحقل	النوع	مطلوب	الوصف
`event_id`	نص UUID	لا	معرّف فريد لهذا الحدث. ينشئه SDK تلقائيًا إن لم ترسله. أرسل معرّفًا ثابتًا من كودك إن أردت إعادة الإرسال بأمان.
`site_id`	نص	نعم	معرّف موقع التتبع لديك من لوحة التحكم.
`event_type`	نص	نعم	نوع الحدث. استخدم صيغة snake_case (مثل `page_view` أو `cta_click` أو `signup_completed`).
`scan_session_id`	نص UUID	لا	يضبطه SDK تلقائيًا من معامل الرابط `scnv`. ومطلوب لنسب الحدث إلى رمز QR.
`web_session_id`	نص UUID	لا	يضبطه SDK تلقائيًا لكل جلسة متصفح (بمهلة 30 دقيقة).
`visitor_id`	نص UUID	لا	يضبطه SDK تلقائيًا. ويبقى سنة كاملة عبر كعكة.
`page_url`	نص	لا	الرابط الكامل للصفحة الحالية بما فيه سلسلة الاستعلام.
`page_title`	نص	لا	عنوان الصفحة. لا يرسله SDK المتصفح؛ وهو مفيد فقط في الربط المباشر بالواجهة.
`referrer`	نص	لا	الرابط المُحيل.
`event_time`	نص ISO 8601	لا	وقت الحدث بتوقيت UTC. وبلا قيمة يُعتمد وقت الاستلام على الخادم. والقيمة الصريحة تبقى كما هي ولا تُستبدل بوقت الاستلام، فيقع الحدث المؤرخ سابقًا في المدة التي يذكرها — وهو أمر مفيد عند تعبئة البيانات أو نقلها. وللعلم: يرسل SDK المتصفح مفتاحًا باسم `timestamp` وهو حقل داخلي منفصل — فعند استدعاء الواجهة مباشرة استخدم `event_time`.
`device`	كائن	لا	سياق المتصفح والجهاز — انظر أدناه.
`metadata`	كائن	لا	بيانات مفاتيح وقيم خاصة بك. بحد أقصى 10 كيلوبايت وخمسة مستويات عمق. وبلا عناوين بريد صريحة.

حقول الكائن device:

الحقل	الوصف
`user_agent`	نص user-agent الخاص بالمتصفح
`screen_width`	عرض الشاشة بالبكسل
`screen_height`	ارتفاع الشاشة بالبكسل
`language`	لغة المتصفح (مثل `en-US`)

مثال على حمولة حدث متصفح

{
  "event_id": "f9ac7db6-f900-4d8e-8918-c846834195a8",
  "site_id": "N74rwgykxCwUe7SDFb2BMVN8Kc0aCQvKajiUKz9MSk3Bldn70jw8uLE3dUTgeS6r",
  "event_type": "cta_click",
  "scan_session_id": "7ad26d4f-3181-4ef8-b6ca-b8f59499dd43",
  "page_url": "https://yoursite.com/?scnv=7ad26d4f-3181-4ef8-b6ca-b8f59499dd43",
  "referrer": "",
  "timestamp": "2026-05-13T10:00:00.000Z",
  "device": {
    "user_agent": "Mozilla/5.0 ...",
    "screen_width": 1680,
    "screen_height": 1050,
    "language": "en-US"
  },
  "metadata": {
    "button_text": "Start Free Trial",
    "section": "pricing"
  }
}

أحداث الخادم (`POST /server-events`)

تُرسل أحداث الخادم من الخادم لديك باستخدام مفتاح API. وهي تمثل إجراءات تقع على خادمك، مثل عمليات الشراء المكتملة أو التسجيلات المؤكدة أو العملاء المحتملين الذين أُنشئوا في نظام CRM لديك.

الحقول التي يمكنك إرسالها

الحقل	النوع	مطلوب	الوصف
`event_id`	نص UUID	مستحسن	معرّف فريد للحدث لإعادة الإرسال بأمان. أنشئه مرة واحدة واحفظه وأعد استخدامه في كل محاولة.
`site_id`	نص	نعم	معرّف موقع التتبع لديك. ويجب أن يطابق الموقع المصرّح به لمفتاح API.
`event_name`	نص	نعم	اسم دلالي للحدث (مثل `purchase` أو `signup` أو `lead`).
`scan_session_id`	نص UUID	نعم	يربط حدث الخادم هذا بمسح رمز QR الذي نشأ عنه. مرّره من المتصفح إلى خادمك.
`web_session_id`	نص UUID	لا	معرّف جلسة الويب من المتصفح — مرّره إن توفر لربط الجلسات بشكل أدق.
`visitor_id`	نص UUID	لا	معرّف الزائر الدائم من المتصفح — مرّره إن توفر.
`event_time`	نص ISO 8601	لا	وقت وقوع الحدث. وافتراضيًا وقت الاستلام.
`conversion_value`	كائن	لا	`{ "amount": 99.99, "currency": "USD" }`. ويجب أن تكون العملة رمزًا من ثلاثة أحرف وفق ISO 4217.
`user_identifiers`	كائن	لا	معرّفات الزائر المشفّرة — انظر أدناه. ولا ترسل البريد أو الهاتف كما هو أبدًا.
`properties`	كائن	لا	بيانات وصفية خاصة بك من مفاتيح وقيم. بحد أقصى 10 كيلوبايت. وبلا عناوين بريد صريحة.
`consent`	نص	لا	`granted` أو `denied` أو `pending`.

حقول الكائن user_identifiers (كلها مشفّرة):

الحقل	الوصف
`email_hash`	بصمة SHA-256 لعنوان بريد المستخدم بأحرف صغيرة
`phone_hash`	بصمة SHA-256 لرقم هاتف المستخدم بصيغة E.164
`external_id`	معرّف المستخدم أو العميل الداخلي لديك

مثال على حمولة حدث خادم

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "site_id": "N74rwgykxCwUe7SDFb2BMVN8Kc0aCQvKajiUKz9MSk3Bldn70jw8uLE3dUTgeS6r",
  "event_name": "purchase",
  "scan_session_id": "7ad26d4f-3181-4ef8-b6ca-b8f59499dd43",
  "conversion_value": { "amount": 49.99, "currency": "USD" },
  "user_identifiers": {
    "email_hash": "b94d27b9934d3e08a52e52d7da7dabfac484efe04294e576fc583c381f2d9c5d",
    "external_id": "usr_1234"
  },
  "properties": {
    "order_id": "ord_9876",
    "plan": "pro"
  }
}

أعراف تسمية الأحداث

استخدم أسماء متسقة وواضحة بصيغة snake_case. فالتسمية المنظمة تجعل قراءة التقارير أيسر.

جيد	تجنّب
`page_view`	`pageView`, `PageView`, `pv`
`cta_click`	`click1`, `btnClick`
`signup_completed`	`signup`, `reg`
`purchase`	`buy`, `order_placed_final`

منع التكرار

تدعم أحداث المتصفح وأحداث الخادم كلتاهما حقل event_id لمنع التكرار:

إذا وصل event_id نفسه أكثر من مرة، يُحفظ المكرر لكن يُوسم بـ is_duplicate = 1
تُستبعد النسخ المكررة من طرق عرض التحليلات تلقائيًا
أعد دائمًا استخدام event_id نفسه عند إعادة إرسال حدث خادم فاشل

الخصوصية والنظام العام لحماية البيانات

لا ترسل عناوين بريد صريحة أبدًا في metadata أو properties. واستخدم user_identifiers بقيم مشفّرة.
يتحكم الحقل consent في التعامل مع البيانات الشخصية أثناء المعالجة:
- granted — تُحفظ جميع الحقول كالمعتاد
- denied أو pending — تُزال page_url وreferrer وcity وmetadata قبل الحفظ
- أما قيمة consent نفسها فتُحفظ دائمًا كسجل للمراجعة

إرسال الموافقة من المتصفح

لا يتضمن SDK المتصفح واجهة مدمجة للموافقة. والنهج المستحسن هو تحميل SDK بشرط، بناءً على قرار منصة إدارة الموافقة لديك:

<script>
  // Only load the SDK after the user grants consent
  if (userHasGrantedConsent()) {
    (function(w,d,s,o,f,js,fjs){
      w['ScanovaTrackingObject']=o;w[o]=w[o]||function(){(w[o].q=w[o].q||[]).push(arguments)};
      js=d.createElement(s),fjs=d.getElementsByTagName(s)[0];
      js.id=o;js.src=f;js.async=1;fjs.parentNode.insertBefore(js,fjs);
    })(window,document,'script','scanova','https://cdn.scanova.io/ct/js/qcg.min.js');
    scanova('init', 'YOUR_SITE_ID', { autoPageview: true });
  }
</script>

إرسال الموافقة من الخادم

في أحداث الخادم، مرّر قيمة consent مباشرة في حمولة كل طلب إلى جانب بقية الحقول.

نظرة عامة

SDK المتصفح

جهة الخادم

مرجع الواجهة

الموارد

أحداث المتصفح (`POST /ct`)

الحقول التي يمكنك إرسالها

مثال على حمولة حدث متصفح

أحداث الخادم (`POST /server-events`)

الحقول التي يمكنك إرسالها

مثال على حمولة حدث خادم

أعراف تسمية الأحداث

منع التكرار

الخصوصية والنظام العام لحماية البيانات

إرسال الموافقة من المتصفح

إرسال الموافقة من الخادم

​أحداث المتصفح (POST /ct)

​الحقول التي يمكنك إرسالها

​مثال على حمولة حدث متصفح

​أحداث الخادم (POST /server-events)

​الحقول التي يمكنك إرسالها

​مثال على حمولة حدث خادم

​أعراف تسمية الأحداث

​منع التكرار

​الخصوصية والنظام العام لحماية البيانات

​إرسال الموافقة من المتصفح

​إرسال الموافقة من الخادم

أحداث المتصفح (`POST /ct`)

الحقول التي يمكنك إرسالها

مثال على حمولة حدث متصفح

أحداث الخادم (`POST /server-events`)

الحقول التي يمكنك إرسالها

مثال على حمولة حدث خادم

أعراف تسمية الأحداث

منع التكرار

الخصوصية والنظام العام لحماية البيانات

إرسال الموافقة من المتصفح

إرسال الموافقة من الخادم