> ## 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.

# واجهة أحداث المتصفح — POST /ct

> مرجع نقطة وصول جمع أحداث المتصفح، وهي التي يستخدمها SDK المتصفح من Scanova لإرسال مشاهدات الصفحة والنقرات والأحداث المخصصة من متصفحات الزوار.

تستقبل نقطة الوصول `/ct` أحداث المتصفح التي يرسلها SDK المتصفح من Scanova. وفي معظم الحالات لن تستدعيها بنفسك — فـ SDK يتولى ذلك. وتوثّق هذه الصفحة صيغة الطلب لمن يبني تكاملًا خاصًا أو يبحث عن خلل.

**الرابط الأساسي:** `https://t.scanova.io`

## نقطة الوصول

```
POST https://t.scanova.io/ct
```

لا حاجة إلى ترويسة مصادقة. إذ يجري التحقق من الطلبات بمطابقة ترويسة `Origin` أو `Referer` مع قائمة **Allowed Domains** الخاصة بالموقع.

## الطلب

**الترويسات:**

```http theme={null}
Content-Type: application/json
Origin: https://yoursite.com
```

**المحتوى:**

```json theme={null}
{
  "event_id": "f9ac7db6-f900-4d8e-8918-c846834195a8",
  "site_id": "YOUR_SITE_ID",
  "event_type": "cta_click",
  "scan_session_id": "7ad26d4f-3181-4ef8-b6ca-b8f59499dd43",
  "web_session_id": "2d0c328a-01d0-4010-85f4-f327130d1bd4",
  "visitor_id": "363fe851-7d8f-4090-902f-0f5a462829f5",
  "page_url": "https://yoursite.com/pricing",
  "referrer": "https://yoursite.com/",
  "timestamp": "2026-05-13T10:00:00.000Z",
  "device": {
    "user_agent": "Mozilla/5.0 ...",
    "screen_width": 1440,
    "screen_height": 900,
    "language": "en-US"
  },
  "metadata": {
    "button_text": "Start Free Trial",
    "section": "pricing"
  }
}
```

## الحقول

| الحقل             | النوع    | مطلوب | الوصف                                               |
| ----------------- | -------- | ----- | --------------------------------------------------- |
| `site_id`         | نص       | نعم   | معرّف موقع التتبع                                   |
| `event_type`      | نص       | نعم   | اسم الحدث بصيغة snake\_case                         |
| `event_id`        | نص UUID  | لا    | معرّف منع التكرار. يُنشأ تلقائيًا إن لم تُرسله.     |
| `scan_session_id` | نص UUID  | لا    | معرّف نسبة مسح رمز QR                               |
| `web_session_id`  | نص UUID  | لا    | معرّف جلسة المتصفح (بمهلة 30 دقيقة)                 |
| `visitor_id`      | نص UUID  | لا    | معرّف الزائر الدائم (كعكة صلاحيتها سنة)             |
| `page_url`        | نص       | لا    | رابط الصفحة الحالية                                 |
| `referrer`        | نص       | لا    | الرابط المُحيل                                      |
| `timestamp`       | ISO 8601 | لا    | وقت الحدث. وافتراضيًا وقت الاستلام.                 |
| `device`          | كائن     | لا    | user-agent وأبعاد الشاشة واللغة                     |
| `metadata`        | كائن     | لا    | بيانات خاصة بك. بحد أقصى 10 كيلوبايت وخمسة مستويات. |
| `consent`         | نص       | لا    | `granted` أو `denied` أو `pending`                  |

## الرد

**النجاح (`200`):**

```json theme={null}
{
  "event_id": "f9ac7db6-f900-4d8e-8918-c846834195a8"
}
```

**ردود الأخطاء:**

| الحالة | السبب                                                                   |
| ------ | ----------------------------------------------------------------------- |
| `400`  | حقل مطلوب مفقود أو `site_id` غير صالحة                                  |
| `403`  | قيمة `Origin` أو `Referer` في الطلب غير مدرجة في Allowed Domains للموقع |
| `413`  | الحمولة تتجاوز الحد المسموح                                             |
| `422`  | خطأ في التحقق من أحد الحقول                                             |
| `429`  | تجاوز حد المعدل (100 طلب في الدقيقة لكل عنوان IP)                       |

## CORS

تدعم نقطة الوصول `/ct` آلية CORS. وتُقبل طلبات المتصفح القادمة من النطاقات المسموح بها مع ما يلي:

```
Access-Control-Allow-Origin: <origin>
Access-Control-Allow-Methods: POST, OPTIONS
```

وتعيد الطلبات التمهيدية (`OPTIONS`) الرد `204` مع ترويسات CORS المناسبة.

## نقطة وصول الدفعات

لإرسال عدة أحداث متصفح في طلب واحد:

```
POST https://t.scanova.io/collect/batch
```

يغلّف محتوى الطلب مصفوفة:

```json theme={null}
{
  "events": [
    { "site_id": "...", "event_type": "pageview", ... },
    { "site_id": "...", "event_type": "scroll", "metadata": { "scroll_depth": 25 } }
  ]
}
```

بحد أقصى 100 حدث في طلب الدفعة الواحد.