أداة التسجيل (Widget)
أداة التسجيل هي حزمة JS واحدة بلا اعتماديات (أقل من 60 كيلوبايت مضغوطة) تُركّب نموذج جذب عملاء محتملين داخل Shadow DOM في أي صفحة — موقعك، صفحة هبوط، أي مكان. لا تلمس أنماط الصفحة المضيفة أبدًا، ولا تلمس الصفحة المضيفة نواتها الداخلية أبدًا.
وسم السكربت
كل تثبيت ذاتي الاستضافة من Institflow يقدّم نسخته الخاصة من الأداة على المسار /widget.js — بلا شبكة توصيل محتوى (CDN)، وبلا مضيف منفصل تشير إليه. تولّد شاشة الإعدادات ← المطورون ← كود أداة التسجيل في تطبيق الويب الخاص بك الوسم أدناه بالضبط، بعنوان تثبيتك ومفتاحك القابل للنشر معبّأين مسبقًا؛ يظل عنوان السكربت قابلاً للتعديل هناك إذا كنت تفضّل استضافة الملف بنفسك.
<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 منفصلة أبدًا)، ويعرض حالة النجاح/الفشل الخاصة به داخل الصفحة نفسها — بلا تنقّل، بلا نافذة منبثقة.