تضمين فيديوهات YouTube في تطبيقات iOS مع مكتبة مساعد YouTube

youtube-ios-player-helper هي مكتبة مفتوحة المصدر تساعدك على تضمين مشغّل YouTube iframe في تطبيق iOS. تنشئ المكتبة WebView وجسرًا بين رمز الهدف ج لتطبيقك ورمز JavaScript في مشغّل YouTube، ما يسمح لتطبيق iOS بالتحكم في مشغّل YouTube. توضح هذه المقالة خطوات تثبيت المكتبة والبدء في استخدامها من تطبيق iOS.

تثبيت

تفترض هذه المقالة أنك أنشأت مشروعًا جديدًا لتطبيق العرض الفردي على iOS يستهدف أحدث إصدار من iOS، وأنك أضفت الملفات التالية عند إنشاء المشروع:

  • Main.storyboard
  • ViewController.h
  • ViewController.m

يمكنك تثبيت المكتبة من خلال CocoaPods أو من خلال نسخ المكتبة والملفات المصدر من صفحة المشروع على GitHub.

  • المكتبة متاحة للتثبيت عبر CocoaPods. بدلاً من ذلك، تتوفّر المكتبة وملفات المصدر عبر صفحة المشروع على GitHub ويمكن نسخها إلى مشروع حالي.

تثبيت المكتبة عبر CocoaPods

إذا كان مشروعك يستخدم CocoaPods، أضِف السطر أدناه إلى Podfile لتثبيت المكتبة. في هذا السطر، استبدِل x.y.z بأحدث إصدار من اللوحة، والذي سيتم تحديده على صفحة المشروع على GitHub.

pod "youtube-ios-player-helper", "~> x.y.z"

في موجه سطر الأوامر، اكتب pod install لتعديل مساحة العمل باستخدام التبعيات.

ملاحظة: عند استخدام CocoaPods، يجب فتح ملف .xcworkspace في Xcode، وليس ملف .xcodeproj.

يمكنك الاطّلاع على البرنامج التعليمي CocoaPods لمعرفة المزيد من المعلومات.

تثبيت المكتبة يدويًا

لتثبيت المكتبة المساعدة يدويًا، يمكنك إما تنزيل المصدر عبر رابط تنزيل GitHub أو إنشاء نسخة طبق الأصل من المستودع. بعد الحصول على نسخة محلية من الشفرة، اتبع الخطوات التالية:

  1. افتح نموذج المشروع في Xcode أو Finder.

  2. اختَر YTPlayerView.h وYTPlayerView.m ومجلد مواد العرض. إذا فتحت مساحة العمل في Xcode، تكون متاحة ضمن اللوحات -> لوحات التطوير -> YouTube-Player-iOS-Helper واللوحات -> لوحات التطوير -> YouTube-Player-iOS-Helper -> الموارد. في Finder (الباحث)، تتوفّر هذه المعلومات في الدليل الجذري للمشروع في دليلَي الصفوف ومواد العرض.

  3. اسحب هذه الملفات والمجلدات إلى مشروعك. تأكّد من تحديد الخيار نسخ العناصر إلى مجلد المجموعة الوجهة. عند سحب مجلد مواد العرض، تأكّد من وضع علامة في الخيار إنشاء مراجع مجلد لأي مجلدات مضافة.

من المفترض أن يتم تثبيت المكتبة الآن.

إضافة YTPlayerView من خلال واجهة الواجهة أو لوحة العمل

لإضافة YTPlayerView عبر أداة إنشاء الواجهة أو لوحة العمل:

  1. اسحب مثيل UIView إلى ملفك الشخصي.

  2. اختَر أداة فحص الهوية وغيِّر فئة الملف الشخصي إلى YTPlayerView.

  3. افتح ViewController.h وأضف الرأس التالي:

    #import “YTPlayerView.h”

    إضافة الموقع التالي أيضًا:

    @property(nonatomic, strong) IBOutlet YTPlayerView *playerView;
  4. في أداة إنشاء الواجهة، يمكنك إنشاء اتصال من عنصر العرض الذي حدَّدته في الخطوة السابقة إلى الخاصية playerView الخاصة بوحدة التحكُّم في الملف الشخصي.

  5. افتح الآن ViewController.m وأضِف الرمز التالي في نهاية طريقة viewDidLoad:

    [self.playerView loadWithVideoId:@"M7lc1UVf-VE"];

إنشاء تطبيقك وتشغيله. عند تحميل الصورة المصغّرة للفيديو، انقر على الصورة المصغّرة للفيديو لتشغيل مشغّل الفيديو بملء الشاشة.

التحكم في تشغيل الفيديو

تتضمّن الطريقة ViewController::loadWithVideoId: صيغة، وهي loadWithVideoId:playerVars:، تسمح لمطوّري البرامج بتمرير متغيّرات إضافية في المشغّل إلى العرض. تتوافق متغيرات المشغّل هذه مع معلّمات المشغّلات في واجهة برمجة تطبيقات مشغّل IFrame. تتيح المَعلمة playsinline تشغيل الفيديو في العرض مباشرةً بدلاً من تشغيله في وضع ملء الشاشة. أثناء تشغيل فيديو مضمّن، يمكن للتطبيق الذي يحتوي على iOS التحكّم آليًا في تشغيل الفيديو.

استبدل المكالمة loadWithVideoId: بهذا الرمز:

NSDictionary *playerVars = @{
  @"playsinline" : @1,
};
[self.playerView loadWithVideoId:@"M7lc1UVf-VE" playerVars:playerVars];

افتح لوحة العمل أو أداة إنشاء الواجهة. اسحب زرَين إلى طريقة العرض، فأصبحا تحملان الاسم تشغيل وإيقاف. افتح ViewController.h وأضِف الطرق التالية التي سيتم ربطها بالأزرار:

- (IBAction)playVideo:(id)sender;
- (IBAction)stopVideo:(id)sender;

افتح الآن ViewController.m وحدد هاتين الوظيفتين:

- (IBAction)playVideo:(id)sender {
  [self.playerView playVideo];
}

- (IBAction)stopVideo:(id)sender {
  [self.playerView stopVideo];
}

تحتوي معظم دوال واجهة برمجة تطبيقات IFrame Player على مكافِئات للالهدف ج، على الرغم من أنّ بعض أسماء الأسماء قد تختلف قليلاً عن تلك الواردة في تلك الإرشادات. وهناك استثناءات بارزة وهي الطرق التي تتحكّم في مستوى صوت الفيديو، بما أنّها تتحكّم فيها أجهزة الهاتف أو تتضمّن مثيلات UIView مضمّنة مصمّمة لهذا الغرض، مثل MPVolumeView.

افتح لوحة العمل أو أداة إنشاء الواجهة، واسحب عنصر التحكّم لربط الزرين تشغيل وإيقاف بالطريقتين playVideo: وstopVideo:.

يمكنك الآن إنشاء التطبيق وتشغيله. بعد تحميل الصورة المصغّرة للفيديو، من المفترض أن تتمكن من تشغيل الفيديو وإيقافه باستخدام عناصر التحكم الأصلية بالإضافة إلى عناصر التحكم في المشغّل.

التعامل مع عمليات معاودة الاتصال بالمشغّل

وقد يكون من المفيد معالجة أحداث التشغيل آليًا، مثل تغييرات حالة التشغيل وأخطاء التشغيل. في واجهة برمجة تطبيقات JavaScript، يتم ذلك باستخدام أدوات معالجة أحداث. في الهدف ج، يتم ذلك من خلال تفويض.

يعرض الرمز التالي كيفية تعديل بيان الواجهة في ViewController.h بحيث تتوافق الفئة مع بروتوكول التفويض. غيّر إعلان واجهة ViewController.h على النحو التالي:

@interface ViewController : UIViewController<YTPlayerViewDelegate>

YTPlayerViewDelegate عبارة عن بروتوكول لمعالجة أحداث التشغيل في المشغّل. لتعديل ViewController.m للتعامل مع بعض الأحداث، عليك أولاً ضبط مثيل ViewController كمفوّض لمثيل YTPlayerView. لإجراء هذا التغيير، أضِف السطر التالي إلى طريقة viewDidLoad في ViewController.h.

self.playerView.delegate = self;

يمكنك الآن إضافة الطريقة التالية إلى ViewController.m:

- (void)playerView:(YTPlayerView *)playerView didChangeToState:(YTPlayerState)state {
  switch (state) {
    case kYTPlayerStatePlaying:
      NSLog(@"Started playback");
      break;
    case kYTPlayerStatePaused:
      NSLog(@"Paused playback");
      break;
    default:
      break;
  }
}

إنشاء التطبيق وتشغيله. شاهِد نتائج السجلّ في Xcode مع تغيّر حالة المشغّل. من المفترض أن تظهر لك تحديثات عند تشغيل الفيديو أو إيقافه.

وتوفّر المكتبة الثوابت التي تبدأ بالبادئة kYT* لتوفير الراحة وسهولة القراءة. للحصول على قائمة كاملة بهذه الثوابت، يمكنك الاطّلاع على YTPlayerView.m.

أفضل الممارسات والقيود

يتم إنشاء المكتبة في أعلى واجهة برمجة تطبيقات IFrame Player من خلال إنشاء WebView وعرض HTML وجافا سكريبت المطلوبَين للمشغل الأساسي. إنّ الهدف من المكتبة هو توفير طرق سهلة الاستخدام قدر الإمكان، بحيث يكون على مطوّري البرامج كتابتها في حزمة بسهولة. وهناك بعض القيود التي يجب ملاحظتها:

  • لا تتيح المكتبة تشغيل الفيديو المتزامن في نُسخ متعددة من YTPlayerView. إذا كان تطبيقك يتضمّن عدّة مثيلات من YTPlayerView، من أفضل الممارسات المقترَحة إيقاف التشغيل مؤقتًا أو إيقافه في أي مثيلات حالية قبل بدء التشغيل في مثيل آخر. في نموذج التطبيق الذي يتم شحنه مع المشروع، تستفيد وحدات التحكم في العرض من NSNotificationCenter لإرسال إشعارات بأن عملية التشغيل على وشك البدء. يتم إرسال إشعارات إلى وحدات التحكم الأخرى في المشاهدة وسيتم إيقاف التشغيل مؤقتًا في مثيلاتها من أجهزة YTPlayerView.
  • أعِد استخدام مثيلات YTPlayerView الحالية التي تم تحميلها، إن أمكن. عندما تحتاج إلى تغيير فيديو في طريقة عرض، لا تنشئ مثيل UIView جديدًا أو مثيل YTPlayerView جديد، ولا تستدعي loadVideoId: أو loadPlaylistId:. وبدلاً من ذلك، يمكنك استخدام مجموعة الدوال cueVideoById:startSeconds: التي لا تعيد تحميل WebView. يحدث تأخر ملحوظ عند تحميل مشغل IFrame بالكامل.
  • يتعذر على هذا المشغل تشغيل مقاطع فيديو خاصة، ولكن يمكنه تشغيل مقاطع فيديو غير مدرجة. وبما أنّ هذه المكتبة تغطي مشغّل iframe الحالي، يجب أن يكون سلوك المشغّل متطابقًا تقريبًا مع سلوك المشغّل المضمّن في صفحة ويب في متصفّح متوافق مع الأجهزة الجوّالة.

المساهمات

بما أنّ هذا المشروع مفتوح المصدر، يُرجى إرسال إصلاحات وتحسينات إلى الفرع الرئيسي لمشروع GitHub.