שירותי YouTube API – הפונקציונליות המינימלית הנדרשת

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

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

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

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

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

נגן YouTube מוטמע והפעלת סרטונים

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

זהות ופרטי כניסה של לקוח API

לקוחות API שמשתמשים בנגן המוטמע של YouTube (כולל YouTube IFrame Player API) צריכים לספק זיהוי באמצעות כותרת הבקשה HTTP Referer. בסביבות מסוימות, הדפדפן יגדיר את HTTP Referer באופן אוטומטי, ולקוחות API צריכים רק לוודא שהם לא מגדירים את Referrer-Policy באופן שמבטל את הערך של Referer. ב-YouTube מומלץ להשתמש ב-strict-origin-when-cross-origin Referrer-Policy, שכבר מוגדר כברירת מחדל בדפדפנים רבים.

באופן דומה, אם מטמיעים את נגן YouTube בתוך חלון שנוצר באמצעות JavaScript window.open, לקוחות API לא יכולים להשתמש בתכונה noreferrer, שמסתירה את הערך Referer.

הגדרת ה-Referer

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

• אפליקציה לנייד עם נגן בתוך קובץ HTML מקומי

  בהגדרה הזו, הנגן נטען בקובץ HTML שמצורף לאפליקציה. כשקובץ ה-HTML הזה נטען, הגדרת הפרמטר baseUrl תגדיר את Referer.

  • ‫Android loadDataWithBaseURL
  • iOS loadHTMLString:baseURL:

• אפליקציה לנייד ללא קובץ HTML מקומי

  בהגדרה הזו, נגן הסרטונים נטען ישירות מ-https://www.youtube.com/embed/VIDEO_ID בלי קובץ HTML סוגר. מגדירים את Referer על ידי הוספתו ככותרת HTTP:

  • ‫Android‏ loadUrl עם כותרת ה-HTTP‏ Referer שנוספה לפרמטר additionalHttpHeaders

  • ‫iOS loadRequest: עם כותרת ה-HTTP‏ Referer שנוספה לבקשה. לדוגמה:

    NSString *bundleId = [[NSBundle mainBundle] bundleIdentifier];
    NSString *referrer = [[NSString stringWithFormat:@"https://%@", bundleId] lowercaseString];
    NSURL *referrerUrl = [NSURL URLWithString:referrer];
    
    NSString *destination = @"https://www.youtube.com/embed/VIDEO_ID";
    NSURL *destinationUrl = [NSURL URLWithString:destination];
    
    NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:destinationUrl];
    [request addValue:referrerUrl forHTTPHeaderField:@"Referer"];
    
    // Create an instance of WKWebView (omitted for simplicity), then load the NSMutableURLRequest.
    [webView loadRequest:request];
    

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

  • Android CustomTabs

    משתמשים ב-Intent.EXTRA_REFERRER כדי להגדיר את כתובת האתר המפנה. כשיוצרים את Uri, חשוב להשתמש בסכימה android-app:// במקום בסכימה https://. לדוגמה:

    String destinationUrl = "https://www.youtube.com/embed/VIDEO_ID";
    CustomTabsIntent customTabsIntent = new CustomTabsIntent.Builder().build()
    customTabsIntent.intent.putExtra(Intent.EXTRA_REFERRER, Uri.parse("android-app://" + context.getPackageName()));
    customTabsIntent.launchUrl(this, Uri.parse(destinationUrl));
    

  • iOS SFSafariViewController

    ‫SFSafariViewController לא תומך בהגדרה של Referer. במקרה כזה, צריך להגדיר במקום זאת את פרמטר הנגן origin.

• אפליקציה למחשב

  בהגדרה הזו, מגדירים את Referer על ידי הוספתו ככותרת HTTP:

  • ‫Microsoft .NET – משתמשים ב-HttpRequestHeaders.Referrer או ב-CoreWebView2HttpRequestHeaders.SetHeader
  • ‫macOS – פועלים לפי אותן ההוראות שמתוארות למעלה לגבי אפליקציות לנייד ל-iOS

בפלטפורמות אחרות שבהן HTTP Referer ריק כברירת מחדל, מגדירים את הערך של Referer על ידי הגדרת ה-WebView שבו נטען הנגן. הטכניקה המדויקת עשויה להשתנות בהתאם לפלטפורמה.

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

פורמט של מפנה

כשמספקים באופן מפורש את הערך Referer על ידי הגדרת פרמטר WebView או הוספת כותרת HTTP, הפורמט הוא בדרך כלל כתובת URL מלאה. מציינים את הפרוטוקול HTTPS. בכתובת ה-URL, שם הדומיין צריך להיות מזהה האפליקציה (app ID) שרשום בחנות שדרכה האפליקציה הופצה למשתמשי הקצה. אם האפליקציה שלכם מסופקת למשתמשים דרך ערוץ הפצה חלופי, צריך להשתמש במזהה האפליקציה שרשום במערכת ההפעלה במהלך התקנת האפליקציה. ברוב המקרים, מזהה האפליקציה יהיה שם דומיין הפוך (שנקרא גם 'פורמט DNS הפוך'), כמו com.google.android.youtube. דוגמאות מייצגות:

• מערכת ההפעלה Android ואפליקציות ל-Android ב-ChromeOS: מזהה האפליקציה
• פלטפורמות של אפל, כולל iOS,‏ iPadOS ו-macOS: מזהה חבילה
• ‫Samsung Tizen: מזהה האפליקציה
• הפצות של Linux:
  • ‫Fedora: ‏ מזהה האפליקציה
  • ‫Gnome: ‏ מזהה אפליקציה
  • ‫Ubuntu: ‏ מזהה האפליקציה

בפלטפורמות מסוימות, מזהה האפליקציה לא זהה לשם הדומיין בהיפוך. במקרים כאלה, צריך להשתמש במזהה האפליקציה הייחודי שהוקצה על ידי החנות שמפיצה את האפליקציה. אם מזהה האפליקציה בחנות הוא מחרוזת אלפאנומרית שנוצרה (הוקצתה על ידי החנות או כלי הפיתוח, ולא נבחרה על ידי מפתח האפליקציה), צריך לכלול גם את שם התצוגה של האפליקציה (להחליף רווחים במקפים) וגם את מזהה האפליקציה בחנות, מופרדים באמצעות נקודה. לדוגמה: <my-app-name>.<AppID> הערך הזה צריך להיות יציב גם כשמשנים את גרסת האפליקציה. אם האפליקציה לא מתארחת בחנות, צריך להשתמש במזהה האפליקציה שרשום במערכת ההפעלה במהלך התקנת האפליקציה. בדרך כלל זהו מזהה ייחודי במניפסט האפליקציה. לא לכלול פרטים על גרסת האפליקציה והארכיטקטורה הנתמכת. דוגמאות מייצגות:

• חנות האינטרנט של Chrome: אירוח בחנות

  מזהה האפליקציה בחנות הוא בדרך כלל החלק האחרון בנתיב בכתובת ה-URL של האפליקציה https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID>. משתמשים בשם האפליקציה עם מקפים ובמזהה האפליקציה בחנות כדי ליצור את המחרוזת <my-app-name>.<AppID> שמתוארת למעלה.

• ‫Windows: אירוח בחנות

  מזהה האפליקציה בחנות הוא בדרך כלל החלק האחרון בנתיב בכתובת ה-URL של האפליקציה https://apps.microsoft.com/detail/<AppID>. משתמשים במזהה האפליקציה בחנות כדי ליצור את המחרוזת <my-app-name>.<AppID> שמתוארת למעלה. צריך לכלול גם את שם האפליקציה עם מקף.

• Windows: הפצה שלא דרך חנות

  אפליקציות ל-Windows מכילות זהות חבילה במניפסט האפליקציה: Name_Version_Architecture_ResourceID_PublisherID. משתמשים רק במאפיין Name.

• ‫Xbox: אירוח בחנות

  מזהה האפליקציה בחנות הוא בדרך כלל החלק האחרון בנתיב בכתובת ה-URL של האפליקציה https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID>. משתמשים בשם האפליקציה עם מקפים ובמזהה האפליקציה בחנות כדי ליצור את המחרוזת <my-app-name>.<AppID> שמתוארת למעלה.

יכול להיות שיידרשו פרטי כניסה נוספים ללקוחות API ששולחים מספר גדול של בקשות ל-YouTube (ראו שימוש ומכסות) כדי לגשת לנגן המוטמע של YouTube.

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

סוג WebView

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

• Android OS: ‏ WebView או CustomTabs
• פלטפורמות של אפל, כולל iOS, ‏iPadOS, ‏macOS: ‏ WKWebView או SFSafariViewController

גודל של נגן YouTube מוטמע

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

הפעלה אוטומטית והפעלות מתוסרטות

בקטע הזה מוסבר על הפעלות אוטומטיות. היא חלה על נגנים מוטמעים של YouTube שמשתמשים בפרמטר הנגן autoplay או שמפעילים באופן פרוגרמטי הפעלה אוטומטית באמצעות שירות YouTube IFrame Player API או שירות אחר של YouTube API.

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

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

• כל תמונה ממוזערת ב-YouTube שמתחילה הפעלה צריכה להיות ברוחב של 120 פיקסלים ובגובה של 70 פיקסלים לפחות.

מאפיינים של נגן YouTube

מאפיינים ופרמטרים של נגן YouTube – כולל, לדוגמה, המראה של המיתוג של YouTube בנגן – מפורטים במסמכי התיעוד והמפרטים של YouTube API‏ (https://developers.google.com/youtube). אסור לבצע שינויים בנגן YouTube שלא מתוארים במפורש במסמכי התיעוד של ה-API.

שכבות-על ומסגרות

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

העברות סמן העכבר

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

העלאת סרטונים

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

הדרישות לגבי הנתונים

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

	שם	תיאור
מאפייני משאבים
	snippet.title	נדרש. שם הסרטון. אם הערך ארוך מ-100 תווים, YouTube מחזיר שגיאה. מערכת YouTube תומכת בכל התווים התקפים בפורמט UTF-8, למעט < ו->.
	snippet.description	נדרש. בתיאור הסרטון. אם הערך גדול מ-5,000 בייט, YouTube מחזיר שגיאה. מערכת YouTube תומכת בכל התווים התקפים בפורמט UTF-8, למעט < ו->.
	status.privacyStatus	נדרש. הגדרת הפרטיות של הסרטון. המשתמשים צריכים להיות מסוגלים לבחור אם הסרטון שהם מעלים יהיה ציבורי, פרטי או לא רשום.
פרמטרים של בקשה
	onBehalfOfContentOwnerChannel	חובה בתנאים מסוימים. אם פרטי ההרשאה של הבקשה מזהים בעלי תוכן והפרמטר onBehalfOfContentOwner מוגדר, משתמש ה-API צריך גם להיות מסוגל לציין את ערוץ YouTube שאליו הסרטון מועלה.

הצגת תגובות

	שם	תיאור
מאפייני משאבים
	snippet.textDisplay	נדרש. הטקסט של התגובה. לקוח ה-API חייב (א) להציג את הטקסט המלא של תגובה או תשובה לתגובה, או (ב) לקצר את הטקסט ולספק לצופה דרך קלה לגשת לטקסט המלא מהגרסה המקוצרת. הדרישה הזו חלה על כל התגובות והתשובות לתגובות, ללא קשר לסוג המשאב שהתגובות משויכות אליו (סרטונים, ערוצים וכו'). שימו לב שערך המאפיין snippet.topLevelComment של המשאב commentThread הוא משאב comment, והמאפיין replies.comments[] הוא רשימה של משאבי comment. לכן, הדרישה הזו חלה גם על הנכסים snippet.topLevelComment.snippet.textDisplay ו-replies.comments[].snippet.textDisplay.
	snippet.title (channel)	חובה (הצעה). שם הערוץ. אם התגובה מתייחסת לערוץ, לקוח ה-API צריך להציג את שם הערוץ. אם התגובה מתייחסת לסרטון, לקוח ה-API צריך להציג את שם הערוץ שהסרטון הועלה אליו.
	snippet.title (video)	חובה בתנאים מסוימים (הצעה). שם הסרטון. הערך הזה צריך להיות מוצג אם התגובה מתייחסת לסרטון.
	snippet.moderationStatus	חובה בתנאים מסוימים. אם ערך הפרמטר moderationStatus בבקשת ה-API הוא heldForReview או likelySpam, צריך להציג את הסטטוס הזה בצורה ברורה באמצעות ערך המאפיין, שפה דומה (למשל, 'התגובה הזו בהמתנה לבדיקה'), כותרת (למשל, 'בהמתנה לבדיקה') או שפה ברורה אחרת. commentThreads.list השיטה תומכת באפשרות לאחזר תגובות על סמך סטטוס הניהול שלהן.

הוספת תגובות

	שם	תיאור
מאפייני משאבים
	snippet.title (channel)	נדרש. שם הערוץ. אם המשתמש מוסיף תגובה לגבי ערוץ, לקוח ה-API חייב להציג את שם הערוץ. אם המשתמש מוסיף תגובה על סרטון, לקוח ה-API צריך להציג את שם הערוץ שהעלה את הסרטון.
	snippet.title (video)	נדרש. אם המשתמש מוסיף תגובה על סרטון, לקוח ה-API צריך להציג את שם הסרטון.
דרישות אחרות
	Comment author's channel name	נדרש. לקוח ה-API צריך לציין באופן ברור את חשבון המשתמש ב-YouTube שאליו ישויך התגובה. אם פרטי ההרשאה של הבקשה מזהים בעלי תוכן והפרמטר onBehalfOfContentOwner מוגדר, משתמש ה-API צריך גם לציין את ערוץ YouTube שאליו תשויך התגובה.

הוספת תשובות לתגובות

	שם	תיאור
מאפייני משאבים
	snippet.textDisplay	נדרש. הטקסט של התגובה. לקוח ה-API צריך להציג את הטקסט של התגובה שהמשתמש משיב לה בהתאם לכללים שמוגדרים בקטע הצגת תגובות במסמך הזה.
	snippet.title (channel)	נדרש. שם הערוץ. אם המשתמש משיב לתגובה על ערוץ, לקוח ה-API צריך להציג את שם הערוץ. אם המשתמש משיב לתגובה על סרטון, לקוח ה-API צריך להציג את שם הערוץ שהעלה את הסרטון.
	snippet.title (video)	נדרש. אם המשתמש משיב לתגובה על סרטון, לקוח ה-API צריך להציג את שם הסרטון.
דרישות אחרות
	Comment author's channel name	נדרש. לקוח ה-API צריך לציין באופן ברור את חשבון המשתמש ב-YouTube שאליו תשויך התשובה לתגובה. אם אישורי ההרשאה של הבקשה מזהים בעלי תוכן והפרמטר onBehalfOfContentOwner מוגדר, משתמש ה-API צריך גם לציין את ערוץ YouTube שאליו תשויך התגובה לתגובה.

עריכה או מחיקה של תגובות לתגובות

	שם	תיאור
מאפייני משאבים
	snippet.textDisplay	נדרש. הטקסט של התגובה. לקוח ה-API צריך להציג את הטקסט של התגובה שהמשתמש עורך או מוחק, בהתאם לכללים שמוגדרים בקטע הצגת תגובות במסמך הזה.
	snippet.title (channel)	נדרש. שם הערוץ. אם המשתמש עורך או מוחק תגובה על ערוץ, לקוח ה-API חייב להציג את שם הערוץ. אם המשתמש עורך או מוחק תגובה על סרטון, לקוח ה-API צריך להציג את שם הערוץ שהעלה את הסרטון.
	snippet.title (video)	נדרש. אם המשתמש עורך או מוחק תגובה על סרטון, לקוח ה-API חייב להציג את שם הסרטון.
דרישות אחרות
	Comment author's channel name	נדרש. לקוח ה-API צריך לציין באופן ברור את חשבון המשתמש ב-YouTube שאליו משויך התגובה.

חסימת משתמשים בצ'אט בשידור חי (או ביטול חסימה)

	שם	תיאור
מאפייני משאבים
	snippet.title (channel)	נדרש. השם של הערוץ ב-YouTube שנחסם או שהחסימה שלו בוטלה. בנוסף, השם צריך להיות מקושר לערוץ או שכתובת ה-URL של הערוץ צריכה להיות מוצגת גם כן.
דרישות אחרות
	שם הערוץ של מחבר התגובה	נדרש. לקוח ה-API צריך לזהות בבירור את חשבון המשתמש ב-YouTube שמשמש להוספה או להסרה של החסימה.