YouTube Player API Reference for iframe Embeds

ממשק ה-API של נגן ה-IFrame מאפשר להטמיע נגן וידאו של YouTube באתר שלכם ולשלוט בנגן באמצעות JavaScript.

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

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

דרישות

הדפדפן של המשתמש חייב לתמוך בתכונה postMessage של HTML5. רוב הדפדפנים המודרניים תומכים ב-postMessage.

נגנים מוטמעים חייבים לכלול חלון תצוגה בגודל של לפחות 200 על 200 פיקסלים. אם בנגן מוצגים לחצני בקרה, הוא חייב להיות גדול מספיק כדי להציג את הלחצנים במלואם בלי לכווץ את אזור התצוגה מתחת לגודל המינימלי. מומלץ להשתמש בנגנים ביחס גובה-רוחב של 16:9 ברוחב של לפחות 480 פיקסלים ובגובה של לפחות 270 פיקסלים.

כל דף אינטרנט שמשתמש ב-IFrame API חייב גם להטמיע את פונקציית JavaScript הבאה:

  • onYouTubeIframeAPIReady – ה-API יפעיל את הפונקציה הזו כשהדף יסיים להוריד את JavaScript של ה-API של הנגן, וכך תוכלו להשתמש ב-API בדף. לכן, הפונקציה הזו עשויה ליצור את אובייקטי הנגן שרוצים להציג כשהדף נטען.

תחילת העבודה

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

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '390',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          playerVars: {
            'playsinline': 1
          },
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

ברשימה הבאה מפורטים פרטים נוספים על הדוגמה שלמעלה:

  1. התג <div> בקטע הזה מזהה את המיקום בדף שבו IFrame API יניח את נגן הווידאו. ה-constructor של אובייקט הנגן, שמתואר בקטע טעינה של נגן וידאו, מזהה את התג <div> לפי ה-id שלו כדי לוודא שה-API ממוקם את ה-<iframe> במיקום הנכון. באופן ספציפי, IFrame API יחליף את התג <div> בתג <iframe>.

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

  2. הקוד בקטע הזה טוען את קוד ה-JavaScript של IFrame Player API. בדוגמה הזו נעשה שימוש בשינוי DOM כדי להוריד את קוד ה-API, כדי לוודא שהקוד יאוחזר באופן אסינכרוני. (המאפיין async של התג <script>, שמאפשר גם הורדות אסינכררוניות, עדיין לא נתמך בכל הדפדפנים המודרניים, כפי שמתואר בתשובה הזו ב-Stack Overflow.

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

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

  5. ה-API יפעיל את הפונקציה onPlayerStateChange כשהסטטוס של הנגן ישתנה. הסטטוס יכול לציין שהנגן פועל, מושהה, הושלם וכו'. הפונקציה מציינת שכאשר מצב הנגן הוא 1 (הפעלה), הנגן אמור לפעול במשך שש שניות ואז לבצע קריאה לפונקציה stopVideo כדי להפסיק את הסרטון.

טעינה של נגן וידאו

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

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '390',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    playerVars: {
      'playsinline': 1
    },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

ב-constructor של נגן הווידאו מצוינים הפרמטרים הבאים:

  1. הפרמטר הראשון מציין את רכיב ה-DOM או את id של רכיב ה-HTML שבו ה-API יכניס את התג <iframe> שמכיל את הנגן.

    ה-IFrame API יחליף את האלמנט שצוין באלמנט <iframe> שמכיל את הנגן. הדבר עשוי להשפיע על הפריסה של הדף אם לרכיב שמוחלף יש סגנון תצוגה שונה מזה של רכיב <iframe> שהוכנס. כברירת מחדל, <iframe> מוצג כרכיב inline-block.

  2. הפרמטר השני הוא אובייקט שמציין את אפשרויות הנגן. האובייקט מכיל את המאפיינים הבאים:
    • width (מספר) – רוחב נגן הווידאו. ערך ברירת המחדל הוא 640.
    • height (מספר) – הגובה של נגן הווידאו. ערך ברירת המחדל הוא 390.
    • videoId (מחרוזת) – מזהה הסרטון ב-YouTube שמזהה את הסרטון שהנגן יטען.
    • playerVars (אובייקט) – המאפיינים של האובייקט מזהים פרמטרים של נגן שאפשר להשתמש בהם כדי להתאים אישית את הנגן.
    • events (אובייקט) – המאפיינים של האובייקט מזהים את האירועים שה-API מפעיל ואת הפונקציות (מאזיני האירועים) שה-API יפעיל כשהאירועים האלה מתרחשים. בדוגמה, ה-constructor מציין שפונקציית onPlayerReady תפעל כשהאירוע onReady יופעל, ופונקציית onPlayerStateChange תפעל כשהאירוע onStateChange יופעל.

כפי שצוין בקטע תחילת העבודה, במקום לכתוב בדף רכיב <div> ריק, שקוד ה-JavaScript של Player API יחליף לאחר מכן ברכיב <iframe>, אפשר ליצור את התג <iframe> בעצמכם. הדוגמה הראשונה בקטע דוגמאות מראה איך לעשות את זה.

<iframe id="player" type="text/html" width="640" height="390"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
  frameborder="0"></iframe>

שימו לב: אם כותבים את התג <iframe>, כשיוצרים את האובייקט YT.Player לא צריך לציין ערכים עבור width ו-height, שמצוינים כמאפיינים של התג <iframe>, או עבור הפרמטרים videoId ו-player, שמצוינים בכתובת ה-URL src. כצעד אבטחה נוסף, כדאי לכלול גם את הפרמטר origin בכתובת ה-URL, ולציין את הסכימה של כתובת ה-URL (http:// או https://) ואת הדומיין המלא של דף המארח כערך הפרמטר. האפשרות origin היא אופציונלית, אבל כדאי לכלול אותה כדי להגן מפני הזרקה של JavaScript זדוני של צד שלישי לדף שלכם, שתאפשר לגורם זדוני להשתלט על נגן YouTube.

דוגמאות נוספות ליצירת אובייקטים של נגני וידאו זמינות בקטע דוגמאות.

תפעול

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

פונקציות

פונקציות של הוספה לתור

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

ה-API תומך בשני תחבירים שונים לקריאה לפונקציות ההמתנה בתור.

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

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

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

  • תחביר של ארגומנטים

    loadVideoById("bHQqvYy5KYo", 5, "large")

  • תחביר של אובייקטים

    loadVideoById({'videoId': 'bHQqvYy5KYo',
               'startSeconds': 5,
               'endSeconds': 60});

פונקציות של רשימת סרטונים הבאים בתור

cueVideoById

  • תחביר של ארגומנטים

    player.cueVideoById(videoId:String,
                    startSeconds:Number):Void

  • תחביר של אובייקטים

    player.cueVideoById({videoId:String,
                     startSeconds:Number,
                     endSeconds:Number}):Void

הפונקציה הזו טוענת את התמונה הממוזערת של הסרטון שצוין ומכינה את הנגן להפעלת הסרטון. הנגן לא מבקש את קובץ ה-FLV עד שמפעילים את playVideo() או seekTo().

  • הפרמטר הנדרש videoId מציין את מזהה הווידאו ב-YouTube של הסרטון שרוצים להפעיל. ב-YouTube Data API, המזהה מצוין במאפיין id של המשאב video.
  • הפרמטר האופציונלי startSeconds מקבל ערך של מספר עשרוני/מספר שלם, ומציין את הזמן שבו הסרטון צריך להתחיל לפעול כשמפעילים את playVideo(). אם מציינים ערך של startSeconds ואז קוראים ל-seekTo(), הנגן יתחיל לפעול מהזמן שצוין בקריאה ל-seekTo(). כשהסרטון מוכן להפעלה, הנגן יפיץ אירוע video cued (5).
  • הפרמטר האופציונלי endSeconds, שנתמך רק בסינטקס של אובייקט, מקבל ערך של מספר עשרוני/מספר שלם ומציין את הזמן שבו הסרטון צריך להפסיק לפעול כשמפעילים את playVideo(). אם מציינים ערך endSeconds ואז קוראים ל-seekTo(), ערך endSeconds לא יהיה בתוקף יותר.

loadVideoById

  • תחביר של ארגומנטים

    player.loadVideoById(videoId:String,
                     startSeconds:Number):Void

  • תחביר של אובייקטים

    player.loadVideoById({videoId:String,
                      startSeconds:Number,
                      endSeconds:Number}):Void

הפונקציה הזו טוענת את הסרטון שצוין ומפעילה אותו.

  • הפרמטר הנדרש videoId מציין את מזהה הווידאו ב-YouTube של הסרטון שרוצים להפעיל. ב-YouTube Data API, המזהה מצוין במאפיין id של המשאב video.
  • הפרמטר האופציונלי startSeconds מקבל מספר עשרוני/מספר שלם. אם הוא יצוין, הסרטון יתחיל מהפריים הראשי הקרוב ביותר לזמן שצוין.
  • הפרמטר האופציונלי endSeconds מקבל מספר עשרוני/מספר שלם. אם יצוין ערך, ההפעלה של הסרטון תופסק בשעה שצוינה.

cueVideoByUrl

  • תחביר של ארגומנטים

    player.cueVideoByUrl(mediaContentUrl:String,
                     startSeconds:Number):Void

  • תחביר של אובייקטים

    player.cueVideoByUrl({mediaContentUrl:String,
                      startSeconds:Number,
                      endSeconds:Number}):Void

הפונקציה הזו טוענת את התמונה הממוזערת של הסרטון שצוין ומכינה את הנגן להפעלת הסרטון. הנגן לא מבקש את קובץ ה-FLV עד שמפעילים את playVideo() או seekTo().

  • הפרמטר הנדרש mediaContentUrl מציין כתובת URL מלאה של נגן YouTube בפורמט http://www.youtube.com/v/VIDEO_ID?version=3.
  • הפרמטר האופציונלי startSeconds מקבל ערך של מספר עשרוני/מספר שלם, ומציין את הזמן שבו הסרטון צריך להתחיל לפעול כשמפעילים את playVideo(). אם מציינים את startSeconds ואז קוראים ל-seekTo(), הנגן יתחיל להפעיל מהזמן שצוין בקריאה ל-seekTo(). כשהסרטון מוכן להפעלה, הנגן משדר אירוע video cued (5).
  • הפרמטר האופציונלי endSeconds, שנתמך רק בסינטקס של אובייקט, מקבל ערך של מספר עשרוני/מספר שלם ומציין את הזמן שבו הסרטון צריך להפסיק לפעול כשמפעילים את playVideo(). אם מציינים ערך endSeconds ואז קוראים ל-seekTo(), ערך endSeconds לא יהיה בתוקף יותר.

loadVideoByUrl

  • תחביר של ארגומנטים

    player.loadVideoByUrl(mediaContentUrl:String,
                      startSeconds:Number):Void

  • תחביר של אובייקטים

    player.loadVideoByUrl({mediaContentUrl:String,
                       startSeconds:Number,
                       endSeconds:Number}):Void

הפונקציה הזו טוענת את הסרטון שצוין ומפעילה אותו.

  • הפרמטר הנדרש mediaContentUrl מציין כתובת URL מלאה של נגן YouTube בפורמט http://www.youtube.com/v/VIDEO_ID?version=3.
  • הפרמטר האופציונלי startSeconds מקבל ערך של מספר עשרוני/מספר שלם, ומציין את הזמן שבו הסרטון צריך להתחיל לפעול. אם מציינים את הערך startSeconds (המספר יכול להיות מספר צף), הסרטון יתחיל מהפריים הראשי הקרוב ביותר לזמן שצוין.
  • הפרמטר האופציונלי endSeconds, שנתמך רק בסינטקס של אובייקט, מקבל ערך של מספר עשרוני/מספר שלם ומציין את הזמן שבו הסרטון צריך להפסיק לפעול.

הוספת פונקציות לרשימת ההמתנה

הפונקציות cuePlaylist ו-loadPlaylist מאפשרות לטעון פלייליסט ולהפעיל אותו. אם אתם משתמשים בתחביר אובייקט כדי לקרוא לפונקציות האלה, אתם יכולים גם להוסיף לרשימת ההמתנה (או לטעון) רשימה של סרטונים שהועלו על ידי משתמש.

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

cuePlaylist

  • תחביר של ארגומנטים

    player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
     הוספת הפלייליסט שצוין לתור. כשהפלייליסט מוכן להפעלה, הנגן יפיץ אירוע video cued (5).

    • הפרמטר הנדרש playlist מציין מערך של מזהי סרטונים ב-YouTube. ב-YouTube Data API, המאפיין id של המשאב video מזהה את המזהה של הסרטון.

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

    • הפרמטר האופציונלי startSeconds מקבל ערך של מספר עשרוני/מספר שלם, ומציין את הזמן שבו הסרטון הראשון בפלייליסט צריך להתחיל לפעול כשפונים לפונקציה playVideo(). אם מציינים ערך של startSeconds ואז קוראים ל-seekTo(), הנגן יתחיל לפעול מהזמן שצוין בקריאה ל-seekTo(). אם תוסיפו פלייליסט לתור ואז תפעילו את הפונקציה playVideoAt(), הנגן יתחיל לפעול בתחילת הסרטון שצוין.

  • תחביר של אובייקטים

    player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
     הוספה של רשימת הסרטונים שצוינה לתור. הרשימה יכולה להיות פלייליסט או פיד של סרטונים שהמשתמש העליך. האפשרות להוסיף לרשימת התוצאות בתור רשימה של תוצאות חיפוש יצאה משימוש והתמיכה בה תופסק החל מ-15 בנובמבר 2020.

    כשהרשימה מוכנה להפעלה, הנגן יפיץ אירוע video cued (5).

    • המאפיין האופציונלי listType מציין את סוג פיד התוצאות שאתם מאחזרים. הערכים החוקיים הם playlist ו-user_uploads. החל מ-15 בנובמבר 2020, לא תהיה יותר תמיכה בערך שהוצא משימוש, search. ערך ברירת המחדל הוא playlist.

    • המאפיין הנדרש list מכיל מפתח שמזהה את רשימת הסרטונים הספציפית שמערכת YouTube צריכה להציג.

      • אם הערך של המאפיין listType הוא playlist, המאפיין list מציין את מזהה הפלייליסט או מערך של מזהי סרטונים. ב-YouTube Data API, המאפיין id של המשאב playlist מזהה את המזהה של פלייליסט, והמאפיין id של המשאב video מציין מזהה של סרטון.
      • אם ערך המאפיין listType הוא user_uploads, המאפיין list מזהה את המשתמש שהסרטונים שהועלו על ידו יחזרו.
      • אם הערך של המאפיין listType הוא search, המאפיין list מציין את שאילתה החיפוש. הערה: הפונקציונליות הזו יצאה משימוש ולא תהיה נתמכת יותר החל מ-15 בנובמבר 2020.

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

    • המאפיין האופציונלי startSeconds מקבל ערך של מספר עשרוני/מספר שלם, ומציין את הזמן שבו הסרטון הראשון ברשימה אמור להתחיל לפעול כשפונים לפונקציה playVideo(). אם מציינים ערך של startSeconds ואז קוראים ל-seekTo(), הנגן יתחיל לפעול מהזמן שצוין בקריאה ל-seekTo(). אם תוסיפו רשימה ל-cue ואז תפעילו את הפונקציה playVideoAt(), הנגן יתחיל לפעול בתחילת הסרטון שצוין.

loadPlaylist

  • תחביר של ארגומנטים

    player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
     הפונקציה הזו טוענת את הפלייליסט שצוין ומפעילה אותו.

    • הפרמטר הנדרש playlist מציין מערך של מזהי סרטונים ב-YouTube. ב-YouTube Data API, המאפיין id של המשאב video מציין מזהה וידאו.

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

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

  • תחביר של אובייקטים

    player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
     הפונקציה הזו טוענת את הרשימה שצוינה ומפעילה אותה. הרשימה יכולה להיות פלייליסט או פיד של סרטונים שהמשתמש העליך. היכולת לטעון רשימה של תוצאות חיפוש יצאה משימוש והתמיכה בה תופסק החל מ-15 בנובמבר 2020.

    • המאפיין האופציונלי listType מציין את סוג פיד התוצאות שאתם מאחזרים. הערכים החוקיים הם playlist ו-user_uploads. החל מ-15 בנובמבר 2020, לא תהיה יותר תמיכה בערך שהוצא משימוש, search. ערך ברירת המחדל הוא playlist.

    • המאפיין הנדרש list מכיל מפתח שמזהה את רשימת הסרטונים הספציפית שמערכת YouTube צריכה להציג.

      • אם הערך של המאפיין listType הוא playlist, המאפיין list מציין מזהה פלייליסט או מערך של מזהי סרטונים. ב-YouTube Data API, המאפיין id של המשאב playlist מציין את המזהה של הפלייליסט, והמאפיין id של המשאב video מציין את המזהה של הסרטון.
      • אם ערך המאפיין listType הוא user_uploads, המאפיין list מזהה את המשתמש שהסרטונים שהועלו על ידו יחזרו.
      • אם הערך של המאפיין listType הוא search, המאפיין list מציין את שאילתה החיפוש. הערה: הפונקציונליות הזו יצאה משימוש ולא תהיה יותר נתמכת החל מ-15 בנובמבר 2020.

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

    • המאפיין האופציונלי startSeconds מקבל ערך של מספר עשרוני/מספר שלם, ומציין את השעה שבה הסרטון הראשון ברשימה אמור להתחיל לפעול.

רכיבי UI להפעלה והגדרות הנגן

הפעלת סרטון

player.playVideo():Void
הפעלת הסרטון הנוכחי שהוכן או נטען. מצב הנגן הסופי אחרי הפעלת הפונקציה הזו יהיה playing (1).

הערה: הפעלה נספרת במספר הצפיות הרשמי של הסרטון רק אם היא מופעלת באמצעות לחצן הפעלה מקורי בנגן.
player.pauseVideo():Void
השהיית הסרטון שפועל כרגע. מצב הנגן הסופי אחרי הפעלת הפונקציה הזו יהיה paused (2), אלא אם הנגן נמצא במצב ended (0) כשהפונקציה נקראת. במקרה כזה, מצב הנגן לא ישתנה.
player.stopVideo():Void
הפסקה וביטול של הטעינה של הסרטון הנוכחי. כדאי להשתמש בפונקציה הזו רק במצבים נדירים שבהם אתם יודעים שהמשתמש לא יצפה בסרטון נוסף בנגן. אם אתם רוצים להשהות את הסרטון, פשוט צריך להפעיל את הפונקציה pauseVideo. אם רוצים לשנות את הסרטון שמופעל בנגן, אפשר להפעיל אחת מהפונקציות של ההוספה לתור בלי להפעיל קודם את stopVideo.

חשוב: בניגוד לפונקציה pauseVideo, שמשאירה את הנגן במצב paused (2), הפונקציה stopVideo עשויה להעביר את הנגן לכל מצב שבו הוא לא מנגן, כולל ended (0), paused (2), video cued (5) או unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
דילוג לנקודת זמן ספציפית בסרטון. אם הנגן מושהה כשהפונקציה נקראת, הוא יישאר מושהה. אם הפונקציה תיקרא מסטטוס אחר (playing,‏ video cued וכו'), הנגן יפעיל את הסרטון.

  • הפרמטר seconds מזהה את הזמן שאליו הנגן צריך להתקדם.

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

  • הפרמטר allowSeekAhead קובע אם הנגן ישלח בקשה חדשה לשרת אם הפרמטר seconds מציין זמן מחוץ לנתוני הווידאו שנשמרו במטמון כרגע.

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

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

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

player.getSphericalProperties():Object
אחזור נכסים שמתארים את נקודת המבט הנוכחית של הצופה, או את התצוגה שלו, בהפעלת סרטון. בנוסף:
  • האובייקט הזה מאוכלס רק בסרטונים ב-360°, שנקראים גם סרטונים ספירליים.
  • אם הסרטון הנוכחי הוא לא סרטון 360° או אם הפונקציה נקראת ממכשיר שאין בו תמיכה, הפונקציה מחזירה אובייקט ריק.
  • במכשירים ניידים נתמכים, אם המאפיין enableOrientationSensor מוגדר כ-true, הפונקציה הזו מחזירה אובייקט שבו המאפיין fov מכיל את הערך הנכון והמאפיינים האחרים מוגדרים כ-0.
האובייקט מכיל את המאפיינים הבאים:
מאפיינים
yaw מספר בטווח [0, 360) שמייצג את הזווית האופקית של התצוגה במדידה בפרוגרסיה מעגלית, שמשקפת את מידת ההטיה של המשתמש שמאלה או ימינה. המיקום הנייטרלי, מול מרכז הסרטון בתצוגה שלו בפריסה ריבועית, מייצג 0°, והערך הזה עולה ככל שהצופה מסתובב שמאלה.
pitch מספר בטווח [-90, 90] שמייצג את הזווית האנכית של התצוגה במדידה בפרוגרסיה מעוקמת, שמשקפת את מידת ההתאמה של המשתמש לתצוגה כדי להביט למעלה או למטה. המיקום הנייטרלי, מול מרכז הסרטון בתצוגה שלו בפריסה ריבועית, מייצג 0°, והערך הזה עולה ככל שהצופה מביט למעלה.
roll מספר בטווח [-180, 180] שמייצג את זווית הסיבוב בכיוון השעון או נגד כיוון השעון של התצוגה, במדידה במעלות. המיקום הנייטרלי, שבו הציר האופקי בתצוגה האקווירטנגולרית מקביל לציר האופקי בתצוגה, מייצג 0°. הערך עולה ככל שהתצוגה מסתובבת בכיוון השעון, ויורד ככל שהתצוגה מסתובבת נגד כיוון השעון.

חשוב לזכור שבנגן המוטמע אין ממשק משתמש לכוונון תנועת התצוגה. אפשר לשנות את הרולר בשתי דרכים בלעדיות זו לזו:
  1. שימוש בחיישן הכיוון בדפדפן לנייד כדי לספק רוטציה לתצוגה. אם חיישן הכיוון מופעל, הפונקציה getSphericalProperties תמיד מחזירה את הערך 0 כערך של המאפיין roll.
  2. אם חיישן הכיוון מושבת, צריך להגדיר את הערך של תנועת הסיבוב לערך שאינו אפס באמצעות ה-API הזה.
fov מספר בטווח [30, 120] שמייצג את שדה הראייה של התצוגה במדידה בזוויות לאורך הקצה הארוך של אזור התצוגה. הקצה הקצר יותר מותאם באופן אוטומטי כך שיהיה יחסי ליחס הגובה-רוחב של התצוגה.

ערך ברירת המחדל הוא 100 מעלות. הפחתת הערך דומה להגדלת התצוגה של תוכן הסרטון, והגדלת הערך דומה להקטנת התצוגה. אפשר לשנות את הערך הזה באמצעות ה-API או באמצעות גלגל העכבר כשהווידאו במצב מסך מלא.
player.setSphericalProperties(properties:Object):Void
הגדרת כיוון הסרטון להפעלה של סרטון 360°. (אם הסרטון הנוכחי לא מוצג בפורמט 360°, השיטה לא מבצעת פעולה כלשהי ללא קשר לקלט).

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

בנוסף:
  • אם האובייקט מכיל מאפיינים לא ידועים ו/או לא צפויים, הנגן מתעלם מהם.
  • כפי שצוין בתחילת הקטע הזה, אין תמיכה בהפעלת סרטונים 360° בכל המכשירים הניידים.
  • כברירת מחדל, במכשירים ניידים נתמכים, הפונקציה הזו מגדירה רק את המאפיין fov ולא משפיעה על המאפיינים yaw,‏ pitch ו-roll בהפעלות של סרטונים ב-360 מעלות. פרטים נוספים זמינים במאפיין enableOrientationSensor שבהמשך.
הנכס properties שמוענק לפונקציה מכיל את המאפיינים הבאים:
מאפיינים
yaw ראו הגדרה למעלה.
pitch ראו הגדרה למעלה.
roll ראו הגדרה למעלה.
fov ראו הגדרה למעלה.
enableOrientationSensor הערה: המאפיין הזה משפיע על חוויית הצפייה ב-360° במכשירים נתמכים בלבד. ערך בוליאני שמציין אם הטמעת ה-IFrame צריכה להגיב לאירועים שמסמנים שינויים בכיוון של מכשיר נתמך, כמו DeviceOrientationEvent של דפדפן נייד. ערך ברירת המחדל של הפרמטר הוא true.

מכשירים ניידים נתמכים
  • כשהערך הוא true, נגן מוטמע מסתמך רק על התנועה של המכשיר כדי לשנות את המאפיינים yaw,‏ pitch ו-roll בהפעלות של סרטונים ב-360°. עם זאת, עדיין אפשר לשנות את המאפיין fov דרך ה-API, וה-API הוא למעשה הדרך היחידה לשנות את המאפיין fov במכשיר נייד. זאת התנהגות ברירת המחדל.
  • כשהערך הוא false, התנועה של המכשיר לא משפיעה על חוויית הצפייה ב-360°, וצריך להגדיר את כל המאפיינים yaw,‏ pitch,‏ roll ו-fov דרך ה-API.

מכשירים ניידים לא נתמכים
לערך של המאפיין enableOrientationSensor אין השפעה על חוויית ההפעלה.

הפעלת סרטון בפלייליסט

player.nextVideo():Void
הפונקציה הזו טוענת ומפעילה את הסרטון הבא בפלייליסט.

  • אם player.nextVideo() נקרא בזמן הצפייה בסרטון האחרון בפלייליסט, והפלייליסט מוגדר להפעלה רציפה (loop), הנגן יטען ויפעיל את הסרטון הראשון ברשימה.

  • אם player.nextVideo() נקרא בזמן הצפייה בסרטון האחרון בפלייליסט, והפלייליסט לא מוגדר להפעלה רציפה, ההפעלה תסתיים.

player.previousVideo():Void
הפונקציה הזו טוענת ומפעילה את הסרטון הקודם בפלייליסט.

  • אם player.previousVideo() נקרא בזמן הצפייה בסרטון הראשון בפלייליסט, והפלייליסט מוגדר להפעלה רציפה (loop), הנגן יטען ויפעיל את הסרטון האחרון ברשימה.

  • אם player.previousVideo() נקרא בזמן הצפייה בסרטון הראשון בפלייליסט, והפלייליסט לא מוגדר להפעלה רציפה, הנגן יפעיל מחדש את הסרטון הראשון בפלייליסט מההתחלה.

player.playVideoAt(index:Number):Void
הפונקציה הזו טוענת ומפעילה את הסרטון שצוין בפלייליסט.

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

שינוי עוצמת הקול בנגן

player.mute():Void
השתקת הנגן.
player.unMute():Void
ביטול ההשתקה של הנגן.
player.isMuted():Boolean
הפונקציה מחזירה את הערך true אם הנגן מושתק, ואת הערך false אם לא.
player.setVolume(volume:Number):Void
הגדרת עוצמת הקול. הערך יכול להיות מספר שלם בין 0 ל-100.
player.getVolume():Number
מחזירה את עוצמת הקול הנוכחית של הנגן, מספר שלם בין 0 ל-100. הערה: הפונקציה getVolume() תחזיר את עוצמת הקול גם אם הנגן מושתק.

הגדרת גודל הנגן

player.setSize(width:Number, height:Number):Object
הגדרת הגודל בפיקסלים של ה-<iframe> שמכיל את הנגן.

הגדרת מהירות ההפעלה

player.getPlaybackRate():Number
הפונקציה הזו מאחזרת את מהירות ההפעלה של הסרטון שפועל כרגע. מהירות ההפעלה שמוגדרת כברירת מחדל היא 1, שמציינת שהסרטון פועל במהירות רגילה. קצב ההפעלה יכול לכלול ערכים כמו 0.25,‏ 0.5,‏ 1,‏ 1.5 ו-2.
player.setPlaybackRate(suggestedRate:Number):Void
הפונקציה הזו קובעת את קצב ההפעלה המוצע לסרטון הנוכחי. אם קצב ההפעלה ישתנה, הוא ישתנה רק בסרטון שכבר הוגדר לו קליפ או שהוא כבר מופעל. אם מגדירים את קצב ההפעלה של סרטון עם קטעים מתוזמנים, הקצב הזה ימשיך לפעול כשפונים לפונקציה playVideo או שהמשתמש מפעיל את ההפעלה ישירות דרך אמצעי הבקרה של הנגן. בנוסף, קריאה לפונקציות להצגת סרטונים או פלייליסטים או לטעינתם (cueVideoById,‏ loadVideoById וכו') תאפס את קצב ההפעלה ל-1.

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

השיטה getAvailablePlaybackRates תחזיר את שיעורי ההפעלה האפשריים של הסרטון שפועל כרגע. עם זאת, אם מגדירים את הפרמטר suggestedRate לערך של מספר שלם או של נקודה צפה (float) שלא נתמכים, הנגן יעגל את הערך הזה כלפי מטה לערך הנתמך הקרוב ביותר בכיוון של 1.
player.getAvailablePlaybackRates():Array
הפונקציה הזו מחזירה את קבוצת שיעורי ההפעלה שבהם הסרטון הנוכחי זמין. ערך ברירת המחדל הוא 1, שמציין שהסרטון מופעל במהירות רגילה.

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

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

player.setLoop(loopPlaylists:Boolean):Void

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

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

הפרמטר הנדרש loopPlaylists מזהה את התנהגות הלולאה.

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

  • אם ערך הפרמטר הוא false, ההפעלות יסתיימו אחרי שנגן הווידאו יפעיל את הסרטון האחרון בפלייליסט.

player.setShuffle(shufflePlaylist:Boolean):Void

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

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

הפרמטר הנדרש shufflePlaylist מציין אם YouTube צריך לערבב את הפלייליסט.

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

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

סטטוס ההפעלה

player.getVideoLoadedFraction():Float
מחזירה מספר בין 0 ל-1 שקובע את אחוז הסרטון שמוצג בנגן כנתון במטמון. השיטה הזו מחזירה מספר מהימן יותר מהשיטות getVideoBytesLoaded ו-getVideoBytesTotal, שכבר לא בשימוש.
player.getPlayerState():Number
מחזירה את המצב של הנגן. הערכים האפשריים הם:
  • -1 – לא התחיל
  • 0 – הסתיים
  • 1 – הפעלה
  • 2 – מושהה
  • 3 – בתהליך אגירת נתונים
  • 5 – סרטון עם קריינות
player.getCurrentTime():Number
הפונקציה מחזירה את משך הזמן שחלף בשניות מאז שהסרטון התחיל לפעול.
player.getVideoStartBytes():Number
התכונה הוצאה משימוש ב-31 באוקטובר 2012. הפונקציה מחזירה את מספר הבייטים שממנו התחיל טעינת קובץ הסרטון. (השיטה הזו תמיד מחזירה עכשיו את הערך 0). תרחיש לדוגמה: המשתמש מקדים את הסרטון לנקודה שעדיין לא נטענה, והנגן שולח בקשה חדשה להפעלת קטע מהסרטון שעדיין לא נטען.
player.getVideoBytesLoaded():Number
התכונה הוצאה משימוש ב-18 ביולי 2012. במקום זאת, צריך להשתמש ב-method‏ getVideoLoadedFraction כדי לקבוע את אחוז הסרטון שנשמר במטמון.

השיטה הזו מחזירה ערך בין 0 ל-1000 שמשויך לחלק מהסרטון שנטען. כדי לחשב את החלק של הסרטון שנטען, אפשר לחלק את הערך של getVideoBytesLoaded בערך של getVideoBytesTotal.
player.getVideoBytesTotal():Number
התכונה הוצאה משימוש ב-18 ביולי 2012. במקום זאת, צריך להשתמש ב-method‏ getVideoLoadedFraction כדי לקבוע את אחוז הסרטון שנשמר במטמון.

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

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

אחזור פרטי הסרטון

player.getDuration():Number
הפונקציה מחזירה את משך הסרטון הנוכחי, בשניות. הערה: הפונקציה getDuration() תחזיר את הערך 0 עד שהמטא-נתונים של הסרטון יטענו. בדרך כלל, זה קורה מיד אחרי שהסרטון מתחיל לפעול.

אם הסרטון שפועל כרגע הוא אירוע בשידור חי, הפונקציה getDuration() תחזיר את משך הזמן שחלף מאז תחילת השידור החי של הווידאו. באופן ספציפי, מדובר בזמן שבו הסרטון הופעל בסטרימינג בלי שהפעלה שלו אופסה או הופסקה. בנוסף, משך הזמן הזה בדרך כלל ארוך יותר מזמן האירוע בפועל, כי השידור עשוי להתחיל לפני שעת ההתחלה של האירוע.
player.getVideoUrl():String
הפונקציה מחזירה את כתובת ה-URL של YouTube.com עבור הסרטון שנטען או שפועל כרגע.
player.getVideoEmbedCode():String
מחזירה את קוד ההטמעה של הסרטון שנטען או פועל כרגע.

אחזור פרטי הפלייליסט

player.getPlaylist():Array
הפונקציה הזו מחזירה מערך של מזהי הסרטונים בפלייליסט לפי הסדר הנוכחי שלהם. כברירת מחדל, הפונקציה הזו תחזיר את מזהי הסרטונים לפי הסדר שנקבע על ידי הבעלים של הפלייליסט. עם זאת, אם קראתם לפונקציה setShuffle כדי לערבב את הסדר של הפלייליסט, ערך ההחזרה של פונקציית getPlaylist() ישקף את הסדר המעורבב.
player.getPlaylistIndex():Number
הפונקציה הזו מחזירה את המדד של סרטון הפלייליסט שפועל כרגע.

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

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

הוספה או הסרה של רכיב מעקב אירועים

player.addEventListener(event:String, listener:String):Void
הוספת פונקציית האזנה ל-event שצוין. בקטע אירועים שבהמשך מפורטים האירועים השונים שהנגן עשוי להפעיל. המאזין הוא מחרוזת שמציינת את הפונקציה שתתבצע כשהאירוע שצוין יופעל.
player.removeEventListener(event:String, listener:String):Void
הסרת פונקציית האזנה ל-event שצוין. השדה listener הוא מחרוזת שמזהה את הפונקציה שלא תפעל יותר כשהאירוע שצוין יופעל.

גישה לקודמים ב-DOM ושינוי שלהם

player.getIframe():Object
השיטה הזו מחזירה את צומת ה-DOM של <iframe> המוטמע.
player.destroy():Void
הסרת ה-<iframe> שמכיל את הנגן.

אירועים

ה-API יוצר אירועים כדי להודיע לאפליקציה על שינויים בנגן המוטמע. כפי שצוין בקטע הקודם, אפשר להירשם לאירועים על ידי הוספת מאזין לאירועים בזמן יצירת האובייקט YT.Player, ואפשר גם להשתמש בפונקציה addEventListener.

ה-API יעביר אובייקט אירוע כארגומנט היחיד לכל אחת מהפונקציות האלה. לאובייקט האירוע יש את המאפיינים הבאים:

  • השדה target של האירוע מזהה את נגן הווידאו שתואם לאירוע.
  • השדה data של האירוע מציין ערך רלוונטי לאירוע. חשוב לציין שבאירועים onReady ו-onAutoplayBlocked לא מצוין מאפיין data.

ברשימה הבאה מפורטים האירועים שה-API מפעיל:

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

בדוגמה הבאה מוצגת פונקציה לדוגמה לטיפול באירוע הזה. אובייקט האירוע שה-API מעביר לפונקציה כולל את המאפיין target, שמזהה את הנגן. הפונקציה מאחזרת את קוד ההטמעה של הסרטון שנטען כרגע, מתחילה להפעיל את הסרטון ומציגה את קוד ההטמעה ברכיב הדף ש-id שלו שווה ל-embed-code. 
function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}
onStateChange
האירוע הזה מופעל בכל פעם שמצב הנגן משתנה. המאפיין data של אובייקט האירוע שה-API מעביר לפונקציית הקשבת האירועים יציין מספר שלם שתואם למצב החדש של הנגן. הערכים האפשריים הם:

  • -1 (לא התחיל)
  • 0 (הסתיים)
  • 1 (הפעלה)
  • 2 (מושהה)
  • 3 (אגירת נתונים)
  • 5 (הסרטון הופעל).

בפעם הראשונה שהנגן יטען סרטון, הוא ישדר אירוע unstarted (-1). כשסרטון מוכן להפעלה, הנגן משדר אירוע video cued (5). בקוד, אפשר לציין את ערכי המספרים השלמים או להשתמש באחד מהמשתנים הבאים במרחב השמות:

  • YT.PlayerState.ENDED
  • YT.PlayerState.PLAYING
  • YT.PlayerState.PAUSED
  • YT.PlayerState.BUFFERING
  • YT.PlayerState.CUED

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

ערך המאפיין data של אובייקט האירוע שה-API מעביר לפונקציית מאזין האירועים יהיה מחרוזת שמזהה את איכות ההפעלה החדשה. הערכים האפשריים הם:

  • small
  • medium
  • large
  • hd720
  • hd1080
  • highres

onPlaybackRateChange
האירוע הזה מופעל בכל פעם שמהירות ההפעלה של הסרטון משתנה. לדוגמה, אם קוראים לפונקציה setPlaybackRate(suggestedRate), האירוע הזה יופעל אם קצב ההפעלה ישתנה בפועל. האפליקציה צריכה להגיב לאירוע ולא להניח ששיעור ההפעלה ישתנה באופן אוטומטי כשפונקציית setPlaybackRate(suggestedRate) נקראת. באופן דומה, אסור להניח בקוד ששיעור ההפעלה של הסרטון ישתנה רק כתוצאה מקריאה מפורשת ל-setPlaybackRate.

ערך המאפיין data של אובייקט האירוע שה-API מעביר לפונקציית האירוע יהיה מספר שמזהה את קצב ההפעלה החדש. השיטה getAvailablePlaybackRates מחזירה רשימה של שיעורי ההפעלה התקפים לסרטון הנוכחי שמוגדר או מופעל.
onError
האירוע הזה מופעל אם מתרחשת שגיאה בנגן. ה-API יעביר אובייקט event לפונקציית ה-event listener. המאפיין data של האובייקט הזה יציין מספר שלם שמזהה את סוג השגיאה שהתרחשה. הערכים האפשריים הם:

  • 2 – הבקשה מכילה ערך פרמטר לא תקין. לדוגמה, השגיאה הזו מתרחשת אם מציינים מזהה סרטון שאינו מכיל 11 תווים, או אם מזהה הסרטון מכיל תווים לא תקינים, כמו סימני קריאה או כוכביות.
  • 5 – לא ניתן להפעיל את התוכן המבוקש בנגן HTML5 או שקיימת שגיאה אחרת שקשורה לנגן HTML5.
  • 100 – הסרטון המבוקש לא נמצא. השגיאה הזו מתקבלת כשסרטון הוסר (מסיבה כלשהי) או סומן כפרטי.
  • 101 – הבעלים של הסרטון המבוקש לא מאפשר להפעיל אותו בנגנים מוטמעים.
  • 150 – השגיאה הזו זהה לשגיאה 101. זו פשוט שגיאת 101 במסווה!
onApiChange
האירוע הזה מופעל כדי לציין שהנגן טען (או פרק) מודול עם שיטות API חשופות. האפליקציה יכולה להאזין לאירוע הזה ואז לבצע סקרים בנגן כדי לקבוע אילו אפשרויות גלויות למודול שנטען לאחרונה. לאחר מכן, האפליקציה תוכל לאחזר או לעדכן את ההגדרות הקיימות של האפשרויות האלה.

הפקודה הבאה מאחזרת מערך של שמות מודולים שאפשר להגדיר להם אפשרויות נגן:
player.getOptions();
 נכון לעכשיו, המודול היחיד שאפשר להגדיר לו אפשרויות הוא המודול captions, שמטפל בכתוביות בנגן. כשמתקבל אירוע onApiChange, האפליקציה יכולה להשתמש בפקודה הבאה כדי לקבוע אילו אפשרויות אפשר להגדיר למודול captions:
player.getOptions('captions');
 בדיקת הנגן באמצעות הפקודה הזו מאפשרת לוודא שיש גישה לאפשרויות שאליהן רוצים לגשת. הפקודות הבאות מאחזרות ומעדכנות את אפשרויות המודול:
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
 בטבלה הבאה מפורטות האפשרויות שבהן ה-API תומך:

מודול אפשרות תיאור
כתוביות fontSize האפשרות הזו קובעת את גודל הגופן של הכתוביות שמוצגות בנגן.

הערכים התקינים הם -1,‏ 0,‏ 1,‏ 2 ו-3. גודל ברירת המחדל הוא 0 והגודל הקטן ביותר הוא -1. הגדרה של האפשרות הזו למספר שלם נמוך מ--1 תגרום להצגת כתוביות בגודל הקטן ביותר, ואילו הגדרה של האפשרות הזו למספר שלם גבוה מ-3 תגרום להצגת כתוביות בגודל הגדול ביותר.
כתוביות reload האפשרות הזו טוענת מחדש את נתוני הכתוביות של הסרטון שפועל. הערך יהיה null אם תשלפו את הערך של האפשרות. מגדירים את הערך ל-true כדי לטעון מחדש את נתוני הכתוביות.
onAutoplayBlocked
האירוע הזה מופעל בכל פעם שהדפדפן חוסם הפעלה אוטומטית או תכונות של הפעלת סרטונים לפי סקריפט, שנקראות ביחד 'הפעלה אוטומטית'. המצב הזה כולל ניסיונות הפעלה באמצעות כל אחד מממשקי ה-API הבאים של נגן:

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

לפרטים מלאים, אפשר לעיין במדיניות הספציפית לדפדפנים (Apple Safari / Webkit,‏ Google Chrome,‏ Mozilla Firefox) ובמדריך של Mozilla להפעלה אוטומטית.

דוגמאות

יצירת אובייקטים מסוג YT.Player

  • דוגמה 1: שימוש ב-API עם <iframe> קיים

    בדוגמה הזו, אלמנט <iframe> בדף כבר מגדיר את הנגן שבו ישתמש ה-API. הערה: צריך להגדיר את הפרמטר enablejsapi לערך 1 בכתובת ה-URL src של הנגן, או להגדיר את המאפיין enablejsapi של האלמנט <iframe> לערך true.

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

    בדוגמה הזו נעשה שימוש בקוד הבא:

    <iframe id="existing-iframe-example"
        width="640" height="360"
        src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1"
        frameborder="0"
        style="border: solid 4px #37474F"
></iframe>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var player;
  function onYouTubeIframeAPIReady() {
    player = new YT.Player('existing-iframe-example', {
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange
        }
    });
  }
  function onPlayerReady(event) {
    document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00';
  }
  function changeBorderColor(playerStatus) {
    var color;
    if (playerStatus == -1) {
      color = "#37474F"; // unstarted = gray
    } else if (playerStatus == 0) {
      color = "#FFFF00"; // ended = yellow
    } else if (playerStatus == 1) {
      color = "#33691E"; // playing = green
    } else if (playerStatus == 2) {
      color = "#DD2C00"; // paused = red
    } else if (playerStatus == 3) {
      color = "#AA00FF"; // buffering = purple
    } else if (playerStatus == 5) {
      color = "#FF6DOO"; // video cued = orange
    }
    if (color) {
      document.getElementById('existing-iframe-example').style.borderColor = color;
    }
  }
  function onPlayerStateChange(event) {
    changeBorderColor(event.data);
  }
</script>

  • דוגמה 2: הפעלה רועשת

    בדוגמה הזו נוצר נגן וידאו בגודל 1280px על 720px. לאחר מכן, מאזין האירועים של האירוע onReady קורא לפונקציה setVolume כדי לשנות את עוצמת הקול להגדרה הגבוהה ביותר.

    function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    width: 1280,
    height: 720,
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

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

    function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: { 'autoplay': 1, 'controls': 0 },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

שליטה בסרטונים ב-360 מעלות

בדוגמה הזו נעשה שימוש בקוד הבא:

<style>
  .current-values {
    color: #666;
    font-size: 12px;
  }
</style>
<!-- The player is inserted in the following div element -->
<div id="spherical-video-player"></div>

<!-- Display spherical property values and enable user to update them. -->
<table style="border: 0; width: 640px;">
  <tr style="background: #fff;">
    <td>
      <label for="yaw-property">yaw: </label>
      <input type="text" id="yaw-property" style="width: 80px"><br>
      <div id="yaw-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="pitch-property">pitch: </label>
      <input type="text" id="pitch-property" style="width: 80px"><br>
      <div id="pitch-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="roll-property">roll: </label>
      <input type="text" id="roll-property" style="width: 80px"><br>
      <div id="roll-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="fov-property">fov: </label>
      <input type="text" id="fov-property" style="width: 80px"><br>
      <div id="fov-current-value" class="current-values"> </div>
    </td>
    <td style="vertical-align: bottom;">
      <button id="spherical-properties-button">Update properties</button>
    </td>
  </tr>
</table>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov'];
  var updateButton = document.getElementById('spherical-properties-button');

  // Create the YouTube Player.
  var ytplayer;
  function onYouTubeIframeAPIReady() {
    ytplayer = new YT.Player('spherical-video-player', {
        height: '360',
        width: '640',
        videoId: 'FAtdv94yzp4',
    });
  }

  // Don't display current spherical settings because there aren't any.
  function hideCurrentSettings() {
    for (var p = 0; p < PROPERTIES.length; p++) {
      document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = '';
    }
  }

  // Retrieve current spherical property values from the API and display them.
  function updateSetting() {
    if (!ytplayer || !ytplayer.getSphericalProperties) {
      hideCurrentSettings();
    } else {
      let newSettings = ytplayer.getSphericalProperties();
      if (Object.keys(newSettings).length === 0) {
        hideCurrentSettings();
      } else {
        for (var p = 0; p < PROPERTIES.length; p++) {
          if (newSettings.hasOwnProperty(PROPERTIES[p])) {
            currentValueNode = document.getElementById(PROPERTIES[p] +
                                                       '-current-value');
            currentValueNode.innerHTML = ('current: ' +
                newSettings[PROPERTIES[p]].toFixed(4));
          }
        }
      }
    }
    requestAnimationFrame(updateSetting);
  }
  updateSetting();

  // Call the API to update spherical property values.
  updateButton.onclick = function() {
    var sphericalProperties = {};
    for (var p = 0; p < PROPERTIES.length; p++) {
      var propertyInput = document.getElementById(PROPERTIES[p] + '-property');
      sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value);
    }
    ytplayer.setSphericalProperties(sphericalProperties);
  }
</script>

שילוב של Android WebView Media Integrity API

מערכת YouTube הרחיבה את Android WebView Media Integrity API כדי לאפשר לנגני מדיה מוטמעים, כולל נגני YouTube מוטמעים באפליקציות ל-Android, לאמת את האותנטיות של האפליקציה המוטמעת. בעקבות השינוי הזה, אפליקציות שמוטמעות שולחות באופן אוטומטי מזהה אפליקציה מאומת ל-YouTube. הנתונים שנאספים כתוצאה משימוש ב-API הזה הם המטא-נתונים של האפליקציה (שם החבילה, מספר הגרסה ואישור החתימה) ואסימון אימות המכשיר שנוצר על ידי Google Play Services.

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

היסטוריית הגרסאות

June 24, 2024

The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.

November 20, 2023

The new onAutoplayBlocked event API is now available. This event notifies your application if the browser blocks autoplay or scripted playback. Verification of autoplay success or failure is an established paradigm for HTMLMediaElements, and the onAutoplayBlocked event now provides similar functionality for the IFrame Player API.

April 27, 2021

The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars object to customize the player.

October 13, 2020

Note: This is a deprecation announcement for the embedded player functionality that lets you configure the player to load search results. This announcement affects the IFrame Player API's queueing functions for lists, cuePlaylist and loadPlaylist.

This change will become effective on or after 15 November 2020. After that time, calls to the cuePlaylist or loadPlaylist functions that set the listType property to search will generate a 4xx response code, such as 404 (Not Found) or 410 (Gone). This change also affects the list property for those functions as that property no longer supports the ability to specify a search query.

As an alternative, you can use the YouTube Data API's search.list method to retrieve search results and then load selected videos in the player.

October 24, 2019

The documentation has been updated to reflect the fact that the API no longer supports functions for setting or retrieving playback quality. As explained in this YouTube Help Center article, to give you the best viewing experience, YouTube adjusts the quality of your video stream based on your viewing conditions.

The changes explained below have been in effect for more than one year. This update merely aligns the documentation with current functionality:

  • The getPlaybackQuality, setPlaybackQuality, and getAvailableQualityLevels functions are no longer supported. In particular, calls to setPlaybackQuality will be no-op functions, meaning they will not actually have any impact on the viewer's playback experience.
  • The queueing functions for videos and playlists -- cueVideoById, loadVideoById, etc. -- no longer support the suggestedQuality argument. Similarly, if you call those functions using object syntax, the suggestedQuality field is no longer supported. If suggestedQuality is specified, it will be ignored when the request is handled. It will not generate any warnings or errors.
  • The onPlaybackQualityChange event is still supported and might signal a change in the viewer's playback environment. See the Help Center article referenced above for more information about factors that affect playback conditions or that might cause the event to fire.

May 16, 2018

The API now supports features that allow users (or embedders) to control the viewing perspective for 360° videos:

  • The getSphericalProperties function retrieves the current orientation for the video playback. The orientation includes the following data:
    • yaw - represents the horizontal angle of the view in degrees, which reflects the extent to which the user turns the view to face further left or right
    • pitch - represents the vertical angle of the view in degrees, which reflects the extent to which the user adjusts the view to look up or down
    • roll - represents the rotational angle (clockwise or counterclockwise) of the view in degrees.
    • fov - represents the field-of-view of the view in degrees, which reflects the extent to which the user zooms in or out on the video.
  • The setSphericalProperties function modifies the view to match the submitted property values. In addition to the orientation values described above, this function supports a Boolean field that indicates whether the IFrame embed should respond to DeviceOrientationEvents on supported mobile devices.

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

  • Documentation for the YouTube Flash Player API and YouTube JavaScript Player API has been removed and redirected to this document. The deprecation announcement for the Flash and JavaScript players was made on January 27, 2015. If you haven't done so already, please migrate your applications to use IFrame embeds and the IFrame Player API.

August 11, 2016

This update contains the following changes:

  • The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.

    The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.

June 29, 2016

This update contains the following changes:

  • The documentation has been corrected to note that the onApiChange method provides access to the captions module and not the cc module.

June 24, 2016

The Examples section has been updated to include an example that demonstrates how to use the API with an existing <iframe> element.

January 6, 2016

The clearVideo function has been deprecated and removed from the documentation. The function no longer has any effect in the YouTube player.

December 18, 2015

European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

  • The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

July 23, 2013

This update contains the following changes:

  • The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.

October 31, 2012

This update contains the following changes:

  • The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.

    In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)

  • When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.

  • The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 22, 2012

This update contains the following changes:

  • The example in the Loading a video player section that demonstrates how to manually create the <iframe> tag has been updated to include a closing </iframe> tag since the onYouTubeIframeAPIReady function is only called if the closing </iframe> element is present.

August 6, 2012

This update contains the following changes:

  • The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.

  • The API supports several new functions and one new event that can be used to control the video playback speed:

    • Functions

      • getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
      • getPlaybackRate – Retrieve the playback rate for the cued or playing video.
      • setPlaybackRate – Set the playback rate for the cued or playing video.

    • Events

July 19, 2012

This update contains the following changes:

  • The new getVideoLoadedFraction method replaces the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods. The new method returns the percentage of the video that the player shows as buffered.

  • The onError event may now return an error code of 5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.

  • The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.

    Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and the onYouTubeIframeAPIReady function will be called first.

  • The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api) will continue to work.

July 16, 2012

This update contains the following changes:

  • The Operations section now explains that the API supports the setSize() and destroy() methods. The setSize() method sets the size in pixels of the <iframe> that contains the player and the destroy() method removes the <iframe>.

June 6, 2012

This update contains the following changes:

  • We have removed the experimental status from the IFrame Player API.

  • The Loading a video player section has been updated to point out that when inserting the <iframe> element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.

    In addition, that section now notes that the insertion of the <iframe> element could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.

March 30, 2012

This update contains the following changes:

  • The Operations section has been updated to explain that the IFrame API supports a new method, getIframe(), which returns the DOM node for the IFrame embed.

March 26, 2012

This update contains the following changes:

  • The Requirements section has been updated to note the minimum player size.