أداة التسجيل هي حزمة JS واحدة بلا اعتماديات (أقل من 60 كيلوبايت مضغوطة) تُركّب نموذج جذب عملاء محتملين داخل Shadow DOM في أي صفحة — موقعك، صفحة هبوط، أي مكان. لا تلمس أنماط الصفحة المضيفة أبدًا، ولا تلمس الصفحة المضيفة نواتها الداخلية أبدًا.

## وسم السكربت

كل تثبيت ذاتي الاستضافة من Institflow يقدّم نسخته الخاصة من الأداة على المسار `/widget.js` — بلا شبكة توصيل محتوى (CDN)، وبلا مضيف منفصل تشير إليه. تولّد شاشة **الإعدادات ← المطورون ← كود أداة التسجيل** في تطبيق الويب الخاص بك الوسم أدناه بالضبط، بعنوان تثبيتك ومفتاحك القابل للنشر معبّأين مسبقًا؛ يظل عنوان السكربت قابلاً للتعديل هناك إذا كنت تفضّل استضافة الملف بنفسك.

```http
<script
  src="https://<your-institute-address>/widget.js"
  data-key="ifl_pub_9c1f2e7a4b8d3c6f0a5e9b2d7c4f1a8e"
  data-locale="ar"
  data-course-id="0190a1b2-0000-7000-8000-000000000002"
></script>
```

ضَعه في أي مكان داخل محتوى صفحتك (body). تقرأ الأداة خصائص وسم `<script>` الخاص بها وقت التحميل — يجب أن يكون سكربتًا كلاسيكيًا (بلا `type="module"`)، لأن ذلك هو السبيل الوحيد لتعثر على وسمها الخاص في الصفحة.

## خصائص data-*

| الخاصية | مطلوبة | الوصف |
| --- | --- | --- |
| `data-key` | نعم | مفتاحك القابل للنشر (ifl_pub_…). لا تستخدم مفتاحًا سرّيًا أبدًا. |
| `data-locale` | لا | "en" أو "ar" أو "he" — الافتراضي هو لغة المتصفّح، وإلا فـ"en". |
| `data-course` | لا | اهتمام بمساق كنصّ حرّ، يُسجَّل مع الطلب. |
| `data-course-id` | لا | معرّف مساق من GET /public/courses — يُسجَّل كمرجع حقيقي، بخلاف data-course النصّي. |
| `data-group-id` | لا | معرّف مجموعة محدّدة من ذلك المساق. |
| `data-captcha-site-key` | لا | مفتاح موقع Cloudflare Turnstile (إعداد integration.captchaSiteKey). عند ضبطه يعرض النموذج تحقّقًا أمنيًا ولا يُرسل بدونه. |
| `data-theme` | لا | "light" أو "dark" أو "auto" (الافتراضي — يتبع تفضيل نظام تشغيل الزائر). |

## ما الذي ينشئه

الإرسال يستدعي `POST /api/v1/public/registrations` بمفتاحك القابل للنشر، وهذا:

- ينشئ طالبًا بحالة `lead`، موسومًا بـ`widget-lead`، في الفرع الافتراضي لمستأجر المفتاح.
- ينشئ (أو يعيد استخدام، بمطابقة رقم الهاتف، إن وُجد مسبقًا) وليّ أمر، مرتبطًا كأساسي ودافع.
- يُصدر الحدث `student.created` — نفس الحدث الذي تشترك فيه نقاط استقبال الويب هوك لديك مسبقًا.

من هنا فصاعدًا هو طالب عادي في نظامك: يظهر في `GET /api/v1/students` بحالة `lead`، جاهز للتسجيل بمجرّد متابعة أحد أفراد فريقك له.

> **قائمة النطاقات المصرَّح بها وحدود المعدّل**
>
> كل مفتاح قابل للنشر يعمل فقط من النطاقات التي صرّحت بها صراحة عند إنشائه — قائمة فارغة لا تقبل أي نطاق. الإرسالات محدودة المعدّل حسب عنوان IP (30/دقيقة) وحسب المفتاح (300/يوم).

## التنسيق والسمات

ألوان النموذج ومسافاته وتقويسه وخطوطه تأتي مباشرة من نفس رموز التصميم (design tokens) المستخدمة في بقيّة Institflow، فيبدو جزءًا أصيلًا من منتجك بدل إطار مضمَّن واضح. يحترم `data-theme` (أو تفضيل نظام التشغيل)، ويتحوّل تلقائيًا إلى اتّجاه من اليمين لليسار للغتَي `ar`/`he` باستخدام خصائص CSS منطقية (بلا ورقة أنماط RTL منفصلة أبدًا)، ويعرض حالة النجاح/الفشل الخاصة به داخل الصفحة نفسها — بلا تنقّل، بلا نافذة منبثقة.