كيفية استخدام واجهة YouTube IFrame API داخل React لتتبع تقدم الفيديو وفتح نافذة منبثقة

مقدمة عملية إلى دمج YouTube IFrame API مع React

عند تطوير تطبيقات تعليمية أو صحية أو تدريبية، لا يكفي أحياناً مجرد تضمين فيديو من YouTube داخل الصفحة، بل نحتاج إلى التفاعل مع حالة التشغيل نفسها. على سبيل المثال، قد ترغب في إظهار نافذة تسأل المستخدم عمّا إذا كان قد أكمل التمرين عند نهاية الفيديو، أو عند الوصول إلى نسبة مشاهدة مرتفعة مثل 95%.

في هذا الدليل، سنشرح بطريقة واضحة كيف يمكن استخدام YouTube IFrame API داخل مشروع مبني باستخدام React أو حتى Next.js، مع الاستفادة من مكتبة react-youtube لتسهيل عملية الربط، ومكتبة react-modal لإظهار نافذة منبثقة احترافية وسهلة الاستخدام.

لماذا قد تحتاج إلى التفاعل مع مشغل YouTube داخل التطبيق؟

في كثير من المشاريع، يكون الفيديو جزءاً أساسياً من تجربة المستخدم، وليس مجرد عنصر مرئي. على سبيل المثال:

• تطبيقات التدريب التي تحتاج إلى التأكد من مشاهدة المحتوى.
• منصات الرعاية الصحية التي تتابع التزام المريض بالتمارين.
• الأنظمة التعليمية التي تربط بين مشاهدة الفيديو وتنفيذ إجراء لاحق.
• المنتجات التفاعلية التي تعرض أسئلة أو تقييمات بعد انتهاء المقطع.

وهنا تظهر فائدة YouTube Player API، لأنها تتيح لك الاستماع إلى أحداث مثل الإيقاف المؤقت، التشغيل، نهاية الفيديو، وتغيّر الحالة بشكل عام.

فهم التحدي عند استخدام YouTube API مع React

توثيق YouTube الرسمي واضح ومفيد، لكنه يعتمد غالباً على أسلوب JavaScript التقليدي. وعند العمل داخل بيئة مثل React، قد تحتاج إلى تكييف هذا الأسلوب مع مفاهيم مثل components وhooks وإدارة الحالة.

بدلاً من بناء الربط يدوياً من الصفر، يمكن الاعتماد على مكتبة react-youtube، وهي طبقة خفيفة فوق YouTube IFrame Player API، وتسهّل تضمين المشغل والاستجابة للأحداث دون تعقيد إضافي.

المكتبات المطلوبة لتنفيذ الفكرة

لتنفيذ هذا السيناريو بشكل نظيف وعملي، ستحتاج إلى العناصر التالية:

• مكتبة react-youtube لتضمين فيديو YouTube والتعامل مع أحداثه.
• مكتبة react-modal لإنشاء نافذة منبثقة قابلة للوصول وسهلة الإغلاق.
• حالة داخلية عبر useState لإدارة ظهور النافذة.
• دالة لاستخراج videoId من رابط الفيديو.
• دالة لفحص الزمن الحالي مقارنة بمدة الفيديو.

إنشاء نافذة منبثقة باستخدام react-modal

استخدام مكتبة جاهزة للنوافذ المنبثقة يوفّر وقتاً كبيراً، خصوصاً في الجوانب المرتبطة بقابلية الاستخدام مثل:

• إغلاق النافذة بالنقر خارجها.
• التعامل مع لوحة المفاتيح.
• تحسين الوصول Accessibility.
• تطبيق سلوك متوقع ومتناسق للمستخدم.

يمكنك البدء بإضافة تنسيقات افتراضية للنافذة كما يلي:

const modalStyles = {
  content: {
    top: "50%",
    left: "50%",
    right: "auto",
    bottom: "auto",
    marginRight: "-50%",
    transform: "translate(-50%, -50%)"
  }
};

بعد ذلك، نستخدم useState لتحديد ما إذا كانت النافذة مفتوحة أم لا:

const [modalIsOpen, setModalIsOpen] = React.useState(false);

ثم نضيف مكوّن النافذة المنبثقة داخل الواجهة:

<Modal
  isOpen={modalIsOpen}
  onRequestClose={() => setModalIsOpen(false)}
  contentLabel="Exercise Completed"
  style={modalStyles}
>
  <div>
    <h3>Completed the exercise?</h3>
    <button onClick={handleExerciseComplete}>
      Complete exercise
    </button>
  </div>
</Modal>

ما يحدث هنا بسيط ومهم في الوقت نفسه:

• الخاصية isOpen ترتبط مباشرةً بحالة النافذة.
• الخاصية onRequestClose تعيد الحالة إلى false عند طلب الإغلاق.
• الخاصية style تستقبل كائن التنسيقات الذي أنشأناه.

أما الدالة التي تُنفذ عند ضغط الزر، فيمكن أن تبدأ بشكل تجريبي على النحو التالي:

const handleExerciseComplete = () => console.log("Do something");

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

تجهيز رابط الفيديو واستخراج videoId

مكتبة react-youtube لا تعتمد على رابط الفيديو الكامل، بل تحتاج إلى قيمة videoId. لكن في بيئات العمل الحقيقية، غالباً ما يتعامل فريق المحتوى مع الرابط الكامل لأنه أبسط وأكثر وضوحاً.

لهذا السبب، من الأفضل استقبال الرابط كما هو، ثم استخراج المعرّف منه برمجياً.

تخزين رابط الفيديو داخل الحالة

لنبدأ بإنشاء حالة لتخزين الرابط:

const [videoUrl, setVideoUrl] = React.useState("");

ثم نضيف حقل الإدخال:

<input
  value={videoUrl}
  onChange={(e) => setVideoUrl(e.target.value)}
/>

استخراج المعرّف من رابط YouTube

قد يأتي رابط YouTube بأكثر من صيغة، مثل:

• https://www.youtube.com/watch?t=746&v=LRini_YIs2I&feature=youtu.be
• https://www.youtube.com/watch?v=N1pIYI5JQLE

في الحالتين، نحتاج إلى أخذ النص الواقع بعد v= وحتى قبل & إن وُجد. يمكن تنفيذ ذلك بهذه الطريقة:

let videoCode;

if (videoUrl) {
  videoCode = videoUrl.split("v=")[1].split("&")[0];
}

هذه الطريقة مناسبة للحالة المطروحة في المقال، لكنها ليست الأشمل لكل أنواع روابط YouTube. إذا كنت تبني نظاماً إنتاجياً، فمن الأفضل لاحقاً دعم صيغ إضافية مثل الروابط المختصرة وروابط embed.

التحقق من نسبة مشاهدة الفيديو

الآن نصل إلى الجزء الأهم: كيف نعرف أن المستخدم وصل إلى نهاية الفيديو أو إلى نسبة معينة مثل 95%؟

توفر واجهة YouTube API دوال مساعدة جاهزة، من أبرزها:

• getDuration() للحصول على مدة الفيديو الكلية.
• getCurrentTime() للحصول على الزمن الحالي الذي وصل إليه المشغل.

وباستخدام هاتين القيمتين، يمكننا حساب النسبة المشاهدة وفتح النافذة عندما تتجاوز العتبة المطلوبة:

const checkElapsedTime = (e) => {
  const duration = e.target.getDuration();
  const currentTime = e.target.getCurrentTime();

  if (currentTime / duration > 0.95) {
    setModalIsOpen(true);
  }
};

في هذا السياق، يشير e.target إلى مشغل الفيديو نفسه، وهو ما يعادل الكائن player المذكور في توثيق YouTube الرسمي. وهذا يعني أنك تستطيع استخدام المزيد من دوال الواجهة البرمجية بالطريقة ذاتها لتوسيع خصائص التفاعل مستقبلاً.

إضافة مكوّن react-youtube وربطه بالأحداث

بعد تجهيز معرّف الفيديو ودالة التحقق، يمكننا تضمين المكوّن الخاص بالفيديو بسهولة:

<YouTube
  videoId={videoCode}
  onStateChange={(e) => checkElapsedTime(e)}
/>

هنا نستخدم الخاصية onStateChange، وهي من أهم الخصائص لأنها تستدعي الدالة عند تغيّر حالة المشغل. وبذلك، في كل مرة يحدث فيها تغيير مثل الإيقاف أو الاستئناف أو الوصول إلى نهاية الفيديو، يمكننا فحص الزمن الحالي واتخاذ القرار المناسب.

أحداث أخرى مفيدة داخل react-youtube

إذا أردت بناء تجربة أكثر تطوراً، فالمكتبة تتيح لك الاستفادة من عدة أحداث جاهزة، مثل:

onReady={func}
onPlay={func}
onPause={func}
onEnd={func}
onError={func}
onStateChange={func}
onPlaybackRateChange={func}
onPlaybackQualityChange={func}

كل خاصية من هذه الخصائص تستقبل دالة يمكنك عبرها تنفيذ منطق مخصص. على سبيل المثال:

• استخدم onPlay لتسجيل بدء التفاعل مع الفيديو.
• استخدم onPause لقياس سلوك المشاهدة.
• استخدم onEnd لتنفيذ إجراء مباشر عند اكتمال العرض.
• استخدم onError لمراقبة المشكلات الفنية.

ملاحظات مهمة لتحسين جودة التنفيذ

الاعتماد على onStateChange يمنحك مرونة أكبر

بدلاً من ربط المنطق بحدث واحد فقط، يتيح لك onStateChange مراقبة سلوك المشغل بصورة أشمل. وهذا مفيد عندما ترغب في فتح النافذة عند الإيقاف المؤقت بعد 95% أو عند نهاية الفيديو تلقائياً.

تحسين تجربة فرق المحتوى

السماح بإدخال رابط الفيديو الكامل بدلاً من videoId فقط يجعل النظام أكثر سهولة لفريق التحرير أو إدارة المحتوى، ويقلل احتمالية الأخطاء أثناء النشر.

التوسّع لاحقاً نحو منطق أكثر دقة

في المشاريع الحقيقية، قد تحتاج إلى منع تكرار ظهور النافذة، أو تسجيل التقدم على مراحل، أو تخزين حالة المشاهدة محلياً أو على الخادم. البنية التي عرضناها هنا تُعد نقطة انطلاق ممتازة لهذا النوع من التطوير.

مثال مبسّط لسير العمل الكامل

1. يدخل المستخدم رابط فيديو YouTube داخل حقل الإدخال.
2. يقوم التطبيق باستخراج videoId من الرابط.
3. يتم تمرير المعرّف إلى مكوّن react-youtube.
4. عند تغيّر حالة المشغل، تُستدعى دالة checkElapsedTime.
5. إذا تجاوزت المشاهدة نسبة 95%، تظهر النافذة المنبثقة.
6. يمكن للمستخدم بعدها تأكيد إكمال التمرين عبر الزر المخصص.

لماذا يُعد هذا الأسلوب مناسباً لتطبيقات Next.js وReact؟

لأن هذا النهج يفصل بين منطق العرض ومنطق التفاعل:

• react-youtube يتكفل بتضمين المشغل.
• react-modal يدير واجهة النافذة المنبثقة.
• useState يتحكم في الحالة.
• الدوال المساعدة تتولى تحليل الرابط وقياس التقدم.

هذا الفصل يجعل الكود أوضح وأسهل في الصيانة والتوسعة، وهو أمر بالغ الأهمية في المشاريع الحديثة التي تتطور باستمرار.

الخلاصة التقنية

استخدام YouTube IFrame API داخل React ليس معقداً كما قد يبدو، خصوصاً عند الاعتماد على مكتبة react-youtube. الفكرة الأساسية تقوم على التقاط أحداث المشغل، ثم استخدام دوال مثل getDuration() وgetCurrentTime() لاتخاذ قرار منطقي داخل التطبيق. تقنياً، هذا الأسلوب عملي جداً للتطبيقات التي تحتاج إلى تتبع التفاعل مع الفيديو، كما أنه يمنحك أساساً مرناً لبناء تجارب أكثر ذكاءً مثل قياس الإنجاز، إظهار التنبيهات، وربط المشاهدة بإجراءات لاحقة داخل النظام.