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

# كيف يعمل تتبع التحويلات

> مسار البيانات كاملًا من مسح رمز QR إلى تقرير التحويلات: نموذج النسبة، وعمر الجلسة، ومراحل معالجة الأحداث، مشروحة خطوة بخطوة من البداية إلى النهاية.

## الرحلة من المسح إلى التقرير

إليك ما يحدث منذ لحظة مسح الزائر لرمز QR وحتى ظهور ذلك الحدث في تقاريرك.

```mermaid theme={null}
sequenceDiagram
  participant User as الزائر
  participant QR as رمز QR
  participant Scanova as إعادة توجيه Scanova
  participant Site as موقعك
  participant SDK as SDK المتصفح
  participant API as واجهة التتبع
  participant Reports as التحليلات / التقارير

  User->>QR: يمسح رمز QR
  QR->>Scanova: يفتح الرابط المختصر scnv.io
  Scanova->>Site: يعيد التوجيه إلى رابطك مع ?scnv=<session_id>
  Site->>SDK: يُحمَّل SDK ويقرأ المعامل ?scnv
  SDK->>SDK: يحفظ scan_session_id في localStorage
  SDK->>API: يرسل حدث page_view ومعه scan_session_id
  User->>Site: ينقر، ويملأ نموذجًا، ويمرّر الصفحة
  SDK->>API: يرسل أحداث click / form_submit / scroll
  Site->>API: خادمك يرسل حدث purchase (من جهة الخادم)
  API->>Reports: تُعالَج الأحداث وتُنسب إلى رمز QR
```

## جلسة المسح

معامل الاستعلام `scnv` هو مفتاح النسبة. وهو يحمل **معرّف جلسة المسح** — وهو معرّف UUID يدل على مسح واحد بعينه لرمز QR بعينه من شخص بعينه في لحظة بعينها.

```
https://yoursite.com/landing?scnv=7ad26d4f-3181-4ef8-b6ca-b8f59499dd43
                                    └─────────────────────────────────────┘
                                           scan_session_id
```

عند تحميل SDK المتصفح في صفحة تحمل هذا المعامل، يقوم بما يلي:

1. يقرأ قيمة `scnv` من الرابط
2. يحفظها في `localStorage` بصلاحية 60 يومًا
3. يُرفقها باسم `scan_session_id` مع كل حدث يرسله ذلك المتصفح

وهذا يعني أن الزائر لو غادر ثم عاد خلال 60 يومًا، فإن إجراءاته اللاحقة تظل منسوبة إلى المسح الأصلي.

## النسبة عبر الصفحات والجلسات

يبقى معرّف جلسة المسح قائمًا عند التنقل بين صفحات النطاق نفسه. فإذا كان الزائر:

1. يمسح رمز QR ← فيصل إلى `/landing`
2. ثم ينتقل إلى `/pricing`
3. ثم يسجّل في `/signup`

فإن مشاهدات الصفحات الثلاث تُنسب إلى المسح نفسه، ما دام SDK مثبتًا في كل هذه الصفحات.

## أحداث المتصفح وأحداث الخادم

هناك نوعان من الأحداث:

| النوع             | يُرسل من                | المصادقة        | الأنسب لـ                                                      |
| ----------------- | ----------------------- | --------------- | -------------------------------------------------------------- |
| **أحداث المتصفح** | متصفح الزائر عبر SDK    | لا شيء (عامة)   | مشاهدات الصفحة، والنقرات، والتمرير، وإرسال النماذج             |
| **أحداث الخادم**  | الخادم لديك عبر الواجهة | تتطلب مفتاح API | عمليات الشراء والتسجيل والعملاء المحتملين وأي إجراء على الخادم |

يقبل النوعان قيمة `scan_session_id` التي تربطهما بمسح رمز QR. وفي أحداث الخادم، يحتاج خادمك إلى استلام `scan_session_id` من المتصفح — عادةً عبر حقل في نموذج، أو كعكة جلسة، أو استدعاء للواجهة.

## كيف تُعالَج الأحداث

ما إن تستقبل واجهة التتبع حدثًا حتى يمر بسلسلة من مراحل المعالجة:

1. **التحقق** — فحص الحقول المطلوبة وحجم المحتوى وصلاحية الموقع والنطاق
2. **منع التكرار** — وسم قيم `event_id` المتكررة بأنها مكررة (وتبقى محفوظة ولا تُحذف)
3. **إثراء بيانات الجهاز** — تحليل user-agent لاستخراج نوع الجهاز والمتصفح ونظام التشغيل
4. **إثراء بيانات الموقع الجغرافي** — تحويل عنوان IP إلى دولة ومدينة عبر GeoIP
5. **ربط الهوية** — تحويل `scan_session_id` إلى معرّف رمز QR ومعرّف المستخدم من قاعدة بيانات Scanova
6. **كشف الاحتيال** — تقييم استدلالي لرصد السلوك الشبيه بسلوك الروبوتات
7. **الخصوصية / النظام العام لحماية البيانات** — إزالة الحقول الشخصية إذا كانت `consent` بقيمة `denied` أو `pending`

تظهر الأحداث بعد معالجتها في تقارير لوحة التحكم بعد تأخير بسيط عند الاستقبال (أقل من 10 ثوانٍ عادةً).

## الهوية والجلسات

يحمل كل حدث يرسله SDK ثلاث قيم هوية منفصلة. وفهم الفرق بينها يعينك على قراءة التقارير:

| الهوية            | مفتاح الكعكة أو التخزين | المدة              | ما تمثله                                                                      |
| ----------------- | ----------------------- | ------------------ | ----------------------------------------------------------------------------- |
| `scan_session_id` | `localStorage._scnv`    | 60 يومًا           | مسح رمز QR المحدد الذي بدأ رحلة الزائر هذه. وهو مفتاح النسبة الأساسي.         |
| `web_session_id`  | الكعكة `_scnv_ws`       | 30 دقيقة من الخمول | جلسة تصفح متصلة واحدة. وتبدأ من جديد بعد 30 دقيقة بلا نشاط، كأي جلسة معتادة.  |
| `visitor_id`      | الكعكة `_scnv_vid`      | سنة واحدة          | معرّف مجهول دائم للمتصفح. يتيح التعرف على الزائر العائد عبر جلسات مسح متعددة. |

قد تكون لزائر واحد جلسات ويب كثيرة، وللجلسة الواحدة أحداث كثيرة. وكل الأحداث خلال 60 يومًا من المسح تتشارك القيمة `scan_session_id` نفسها.

## توفر البيانات

* تُستقبل الأحداث وتوضع في الطابور فور وصولها
* في الأحوال المعتادة تظهر الأحداث المعالجة في التقارير خلال ثوانٍ
* وقد يحدث تأخير قصير يصل إلى بضع دقائق في أوقات ذروة الزيارات