ربط Zoom

EduBook بيتكلّم مع Zoom بطريقتين:

• Webhooks — Zoom بيـ push events لـ EduBook كل مرة طالب يدخل أو يخرج من ميتنج. النظام بيستخدمها لتسجيل الحضور تلقائي.
• API calls — للـ Enterprise، EduBook بيكلّم Zoom API لإنشاء ميتنج جديد كل ما تحفظ مجموعة أونلاين، عشان مش تحتاج تنسخ اللينك بإيدك.

الاتنين بيستخدموا Server-to-Server OAuth — نوع خاص من apps Zoom بيسجّل دخوله بالـ credentials بس، من غير user redirect. بتعمل Zoom app واحد لكل tenant وتلصق الـ credentials في EduBook.

الدوك ده بيمشي معاك في الـ setup الكامل. بياخد حوالي 10 دقايق.

الخطة المطلوبة

ربط Zoom feature في خطة Pro فما فوق. Enterprise كمان فيها إنشاء ميتنج تلقائي مع حفظ المجموعة.

1. اعمل Server-to-Server OAuth app في Zoom

1. سجّل دخول في marketplace.zoom.us بحساب Zoom اللي بتشغّل عليه حصصك.
2. القائمة الجاية في الأعلى ← Develop → Build App.
3. اختار Server-to-Server OAuth كنوع التطبيق.
4. ادّيله اسم (مثلاً EduBook Pro) واضغط Create.

دلوقتي إنت في wizard إعدادات الـ app. هنملا 5 tabs: App Credentials, Information, Feature, Scopes, وأخيراً Activation.

2. App Credentials — انسخ 3 قيم

أول tab بيظهر 3 قيم. انسخهم كلهم — هتلصقهم في EduBook في الخطوة 6.

الحقل	الاستخدام
Account ID	بيعرّف حسابك في Zoom.
Client ID	معرّف الـ app العام.
Client Secret	بيوثّق EduBook عند Zoom. اعتبره زي الباسورد — مش هتقدر تشوفه تاني بعد ما تخرج من الصفحة.

3. Information

املا الـ app info الأساسية اللي Zoom بيطلبها. مفيش حاجة منهم بتأثّر على EduBook — كله metadata بـ Zoom بيحتفظ بيه.

• Short description: “تكامل الحضور بـ EduBook”
• Long description: انسخ نفس الـ short
• Company name: اسم سنترك
• Developer contact: إيميلك

4. Feature ← Event Subscriptions

ده مكان ربط الـ webhooks.

1. فعّل Event Subscriptions (toggle ON).
2. ضيف Event notification endpoint جديد.
3. Subscription Name: EduBook Attendance
4. Event notification endpoint URL: افتح EduBook ← الإعدادات ← Integrations ← كارد Zoom وانسخ الـ URL اللي ظاهر هناك. شكله كده:

   https://license.edubookapp.com/api/webhooks/zoom?tenant=<your-id>

5. اضغط Validate. Zoom بيعمل فحص توقيع لمرة واحدة على endpoint بتاعك. استنى علامة الـ ✓ خضرا.
6. Add Events ← علّم:
   • Meeting ← Participant/Host joined meeting
   • Meeting ← Participant/Host left meeting
   • Meeting ← End Meeting
7. Secret Token — Zoom بيولّد واحد ويظهره. انسخه — هتلصقه في EduBook في الخطوة 6 كـ “Webhook Secret”.

5. Scopes — 4 بالظبط

Zoom بيستخدم scopes علشان يحدّد التطبيق بيقدر يعمل إيه. ضيف الـ 4 دول بس (دوّر بكلمة في tab الـ Scopes):

Scope	السبب
meeting:write:meeting:admin	لإنشاء ميتنجات (Enterprise auto-create).
meeting:read:meeting:admin	لقراءة metadata الميتنج.
meeting:read:participant:admin	مطلوبة لـ events دخول/خروج المشاركين.
user:read:user:admin	للتعرّف على صاحب الحساب وقت إنشاء الميتنج.

متضيفش أي حاجة تانية — أي permission زيادة بيكبّر الـ blast radius لو الـ credential اتسرّب يوم.

6. الربط من EduBook

في EduBook ← الإعدادات ← Integrations ← Zoom:

1. الصق Account ID (من خطوة 2)
2. الصق Client ID (من خطوة 2)
3. الصق Client Secret (من خطوة 2)
4. الصق Webhook Secret Token (من خطوة 4)
5. اضغط ربط Zoom

EduBook هيختبر الـ credentials مع /oauth/token بتاع Zoom قبل الحفظ. لو الـ credentials غلط، هتشوف toast بـ error — مفيش حاجة هتتسجّل.

في حالة النجاح، الكارد بيتحوّل لـ متصل ✓ ويظهر Account ID والوقت اللي وصل فيه آخر event.

7. تنشيط الـ Zoom app

ارجع لـ Zoom Marketplace ← آخر tab Activation ← Activate your app.

من غير التنشيط، Zoom مش هيوصّل webhooks فعلياً. لو تخطّيت الخطوة دي الكونكشن هيظهر في EduBook كأنه سليم بس مفيش events بتجي.

8. اختبار الـ flow كامل

أسرع end-to-end test:

1. في EduBook، اعمل مجموعة أونلاين بـ provider = Zoom والصق لينك ميتنج Zoom انت بتحكم فيه. الـ Meeting ID هيتعبّى تلقائي من الـ URL.
2. ضيف طالب للمجموعة بنفس الإيميل اللي هيدخل بيه على Zoom.
3. ابدأ ميتنج Zoom وخلي الطالب يدخل. خليه يقعد على الأقل threshold المجموعة (افتراضي 30 دقيقة).
4. بعد ما يطلع (أو بعد ما الميتنج يخلص)، افتح صفحة حضور المجموعة — المفروض الطالب يكون marked حاضر بـ source: zoom.

في الإعدادات ← Integrations ← Zoom، حقل آخر حدث استقبلناه بيتحدّث مع كل join/leave event من Zoom.

لو الطالب ما اتـ match-ش؟

الحضور التلقائي بيـ match الطالب على Zoom بترتيب:

1. إيميل المشارك على Zoom ← إيميل الطالب (تطابق تام، case-insensitive)
2. تليفون المشارك ← تليفون الطالب، بعدين تليفون ولي الأمر (أرقام بس)

لو محصلش match، الحدث بيتسجّل بس الطالب مش بيتعلّم حاضر تلقائي. تأكد إن الطلاب بيدخلوا Zoom بنفس الإيميل أو التليفون اللي عندك في النظام. مطابقة الاسم (fuzzy) مش مدعومة عمداً — false positives كتير في الفصول الحقيقية.

فصل الربط

الإعدادات ← Integrations ← Zoom ← فصل الربط بيمسح الـ secrets من قاعدة بيانات EduBook (مشفّرين بـ AES-256-GCM، والفصل بيـ overwrite بـ NULL). الـ Zoom app في marketplace.zoom.us مش بيتمسّ — تقدر تربط تاني بنفس الـ credentials في أي وقت.

مشاكل وحلولها

زرار “Validate” في Zoom بيفشل بـ timeout — الـ deployment بتاع EduBook ممكن يكون cold. افتح الـ webhook URL في برواز الأول (هتشوف 404، طبيعي — ده بس بيـ warm الـ function)، وبعدين اضغط Validate تاني.

“آخر حدث استقبلناه” بيفضل فاضي بعد ميتنج حقيقي — اتأكد:

• الـ Zoom app متفعّل (خطوة 7).
• الـ events اللي اشتركت فيها فعلاً بتفير — راجع tab “Recent Events” في الـ Zoom app.
• Meeting ID بتاع المجموعة عندك بيطابق Zoom meeting id الفعلي.

الحضور التلقائي مش بيعلّم الطالب حاضر حتى بعد 30+ دقيقة — اتأكد إن الإيميل اللي دخل بيه الطالب على Zoom بيطابق بالظبط السجل في EduBook. المطابقة case-insensitive بس غير كده تطابق تام.