> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> مرجع كامل لحقول أحداث المتصفح وأحداث الخادم: ماذا ترسل، وما الذي يفعله كل حقل، وكيف تُحفظ الأحداث وتُثرى ببيانات الجهاز والموقع الجغرافي.

كل حدث ترسله إلى تتبع التحويلات في 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`)    |

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

```json theme={null}
{
  "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` | معرّف المستخدم أو العميل الداخلي لديك         |

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

```json theme={null}
{
  "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 بشرط**، بناءً على قرار منصة إدارة الموافقة لديك:

```html theme={null}
<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` مباشرة في حمولة كل طلب إلى جانب بقية الحقول.