הטמעה של סרטונים ב-YouTube באפליקציות ל-iOS באמצעות ספריית העזר של YouTube

‫youtube-ios-player-helper היא ספרייה בקוד פתוח שעוזרת להטמיע נגן iframe של YouTube באפליקציית iOS. הספרייה יוצרת WebView וגשר בין קוד ה-Objective-C של האפליקציה לבין קוד ה-JavaScript של נגן YouTube, וכך מאפשרת לאפליקציית iOS לשלוט בנגן YouTube. במאמר הזה מוסבר איך להתקין את הספרייה ולהתחיל להשתמש בה באפליקציה ל-iOS.

התקנה

במאמר הזה מניחים שיצרתם פרויקט חדש של אפליקציית תצוגה יחידה ב-iOS שמיועדת לגרסה העדכנית של iOS, ושאתם מוסיפים את הקבצים הבאים כשאתם יוצרים את הפרויקט:

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

אפשר להתקין את הספרייה באמצעות CocoaPods או להעתיק את הספרייה ואת קובצי המקור מדף הפרויקט ב-GitHub.

  • אפשר להתקין את הספרייה דרך CocoaPods. לחלופין, אפשר להוריד את הספרייה ואת קובצי המקור דרך דף הפרויקט ב-GitHub ולהעתיק אותם לפרויקט קיים.

התקנת הספרייה באמצעות CocoaPods

אם הפרויקט שלכם משתמש ב-CocoaPods, מוסיפים את השורה הבאה ל-Podfile כדי להתקין את הספרייה. בשורה הזו, מחליפים את x.y.z בגרסת ה-Pod העדכנית ביותר, שתזוהה בדף הפרויקט ב-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 ואת התיקייה Assets. אם פותחים את סביבת העבודה ב-Xcode, הקבצים האלה זמינים בנתיבים Pods -> Development Pods -> YouTube-Player-iOS-Helper ו-Pods -> Development Pods -> YouTube-Player-iOS-Helper -> Resources. ב-Finder, הקבצים האלה זמינים בספריית שורש של הפרויקט בספריות Classes ו-Assets.

  3. גוררים את הקבצים והתיקיות האלה לפרויקט. מוודאים שהאפשרות העתקת פריטים לתיקייה של קבוצת היעד מסומנת. כשגוררים את התיקייה Assets, מוודאים שהאפשרות Create Folder References for any added folders (יצירת הפניות לתיקיות לכל התיקיות שנוספו) מסומנת.

הספרייה אמורה להיות מותקנת עכשיו.

מוסיפים YTPlayerView דרך Interface Builder או Storyboard

כדי להוסיף YTPlayerView באמצעות Interface Builder או Storyboard:

  1. גוררים מופע של UIView אל התצוגה.

  2. בוחרים בכלי לבדיקת זהויות ומשנים את הסיווג של התצוגה ל-YTPlayerView.

  3. פותחים את ViewController.h ומוסיפים את הכותרת הבאה:

    #import “YTPlayerView.h”

    מוסיפים גם את המאפיין הבא:

    @property(nonatomic, strong) IBOutlet YTPlayerView *playerView;

  4. ב-Interface Builder, יוצרים חיבור מרכיב התצוגה שהגדרתם בשלב הקודם למאפיין playerView של View Controller.

  5. עכשיו פותחים את ViewController.m ומוסיפים את הקוד הבא לסוף של שיטת viewDidLoad:

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

יוצרים ומריצים את האפליקציה. כשהתמונה הממוזערת של הסרטון נטענת, לוחצים עליה כדי להפעיל את נגן הווידאו במסך מלא.

שליטה בהפעלת סרטונים

ל-method‏ ViewController::loadWithVideoId: יש וריאנט, loadWithVideoId:playerVars:, שמאפשר למפתחים להעביר משתני נגן נוספים לתצוגה. משתני ה-Player האלה תואמים לפרמטרים של ה-Player ב-IFrame Player API. הפרמטר playsinline מאפשר להפעיל את הסרטון ישירות בתצוגה במקום להפעיל אותו במסך מלא. כשסרטון מוצג בתוך השורה, האפליקציה שמכילה אותו ב-iOS יכולה לשלוט בהפעלה באופן פרוגרמטי.

מחליפים את הקריאה loadWithVideoId: בקוד הבא:

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

פותחים את לוח התכנון או את Interface Builder. גוררים שני כפתורים לתצוגה ונותנים להם את התוויות Play ו-Stop. פותחים את 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 API יש מקבילות ב-Objective-C, אבל יכול להיות שחלק מהשמות יהיו שונים קצת כדי להתאים יותר להנחיות הקידוד של Objective-C. חריגים בולטים הם שיטות ששולטות בעוצמת הקול של הסרטון, כי הן נשלטות על ידי החומרה של הטלפון או באמצעות מופעים מובנים של UIView שמיועדים למטרה הזו, כמו MPVolumeView.

פותחים את ה-storyboard או את Interface Builder וגוררים תוך כדי לחיצה על מקש Control כדי לחבר את הלחצנים Play ו-Stop ל-methods‏ playVideo: ו-stopVideo:.

עכשיו בונים ומריצים את האפליקציה. אחרי שהתמונה הממוזערת של הסרטון נטענת, אמורה להיות לכם אפשרות להפעיל ולהפסיק את הסרטון באמצעות לחצנים מקוריים בנוסף לכפתורי הנגן.

טיפול בקריאות חוזרות (callbacks) של הנגן

יכול להיות שימושי לטפל באירועי הפעלה באופן פרוגרמטי, כמו שינויים במצב ההפעלה ושגיאות בהפעלה. ב-JavaScript API, הפעולה הזו מתבצעת באמצעות רכיבי event listener. ב-Objective-C,עושים את זה באמצעות delegate.

הקוד הבא מראה איך לעדכן את הצהרת הממשק בקובץ ViewController.h כדי שהמחלקה תתאים לפרוטוקול הנציג. משנים את הצהרת הממשק של ViewController.h באופן הבא:

@interface ViewController : UIViewController<YTPlayerViewDelegate>

‫YTPlayerViewDelegate הוא פרוטוקול לטיפול באירועי הפעלה בנגן. כדי לעדכן את ViewController.m כך שיטפל בחלק מהאירועים, צריך קודם להגדיר את המופע ViewController כנציג של המופע YTPlayerView. כדי לבצע את השינוי הזה, מוסיפים את השורה הבאה ל-method‏ 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;
  }
}

מבצעים build ומריצים את האפליקציה. צופים בפלט של היומן ב-Xcode כשהמצב של הנגן משתנה. העדכונים אמורים להופיע כשהסרטון מופעל או נעצר.

הספרייה מספקת את הקבועים שמתחילים בקידומת kYT* כדי להקל על השימוש ולשפר את הקריאות. הרשימה המלאה של הקבועים האלה מופיעה ב-YTPlayerView.m.

שיטות מומלצות ומגבלות

הספרייה מבוססת על IFrame Player API, ויוצרת WebView ומעבדת את ה-HTML וה-JavaScript שנדרשים לנגן בסיסי. המטרה של הספרייה היא להיות קלה לשימוש ככל האפשר, ולכלול שיטות שמפתחים נדרשים לכתוב לעיתים קרובות בחבילה. יש כמה מגבלות שחשוב לשים לב אליהן:

  • הספרייה לא תומכת בהפעלת סרטונים בו-זמנית בכמה מופעים של YTPlayerView. אם לאפליקציה יש כמה מופעים של YTPlayerView, מומלץ להשהות או להפסיק את ההפעלה בכל המופעים הקיימים לפני שמתחילים את ההפעלה במופע אחר. באפליקציית הדוגמה שמגיעה עם הפרויקט, רכיבי ViewControllers משתמשים ב-NSNotificationCenter כדי לשלוח התראות על כך שההפעלה עומדת להתחיל. מערכות ViewController אחרות מקבלות התראה ומשהות את ההפעלה במופעים של YTPlayerView.
  • שימוש חוזר במופעי YTPlayerView קיימים שנטענו, כשהדבר אפשרי. כשצריך לשנות סרטון בתצוגה, אל תיצרו מופע חדש של UIView או מופע חדש של YTPlayerView, ואל תפעילו את loadVideoId: או את loadPlaylistId:. במקום זאת, השתמשו במשפחת הפונקציות cueVideoById:startSeconds:, שלא טוענות מחדש את WebView. יש עיכוב ניכר בטעינה של כל נגן ה-IFrame.
  • אי אפשר להפעיל בסרטונים פרטיים בנגן הזה, אבל אפשר להפעיל בו סרטונים לא רשומים. הספרייה הזו עוטפת את נגן ה-iframe הקיים, ולכן ההתנהגות של הנגן צריכה להיות כמעט זהה להתנהגות של נגן שמוטמע בדף אינטרנט בדפדפן לנייד.

משוב

מכיוון שמדובר בפרויקט בקוד פתוח, אתם יכולים לשלוח תיקונים ושיפורים להסתעפות הראשית של הפרויקט ב-GitHub.