خدمات YouTube API - حداقل عملکرد مورد نیاز

توجه: پیروی از خط‌مشی‌های برنامه‌نویس YouTube راهنمایی‌ها و مثال‌هایی را ارائه می‌دهد تا به شما کمک کند مطمئن شوید که مشتریان API شما از بخش‌های خاصی از شرایط و خط‌مشی‌های خدمات YouTube API (API TOS) پیروی می‌کنند. این راهنما بینشی را در مورد نحوه اجرای برخی جنبه‌های API TOS توسط YouTube ارائه می‌کند، اما جایگزین هیچ سند موجود نمی‌شود.

این سند حداقل الزامات عملکردی را برای کلاینت‌های API تعریف می‌کند که ویژگی‌های خاص سرویس‌های YouTube API ("مشتریان API") را اجرا می‌کنند یا به آنها دسترسی می‌دهند.

این الزامات و دستورالعمل‌ها تضمین می‌کنند که مشتریان API تجربه کاربری ثابتی را ارائه می‌کنند که از منافع کاربران YouTube، صاحبان محتوا و تبلیغ‌کنندگان محافظت می‌کند. این قوانین بخشی جدایی ناپذیر از شرایط سرویس YouTube API هستند و باید در توسعه و اجرای هر مشتری API دنبال شوند.

باید انتظار داشته باشید که الزامات این سند تغییر کند تا بتوانیم از تجربیات کاربر بهتر با ویژگی‌های موجود YouTube اطمینان حاصل کنیم. آنها همچنین در پاسخ به ویژگی های جدید و به روز شده YouTube تغییر خواهند کرد. گاهی اوقات، چنین تغییراتی ممکن است از شما بخواهد که API Client های خود را برای رفع نیازهای جدید به روز کنید. تاریخچه بازنگری شرایط خدمات هرگونه تغییر را مستند می کند، بنابراین لطفاً آن سند را مرتباً بررسی کنید یا در فید RSS آن مشترک شوید تا مطمئن شوید که می توانید به سرعت از تغییراتی که ممکن است بر مشتریان API خود تأثیر بگذارد مطلع شوید.

علاوه بر الزامات موجود در این سند، ما به شدت توصیه می‌کنیم بهترین شیوه‌های شرح داده شده در خط‌مشی‌های خدمات YouTube API را دنبال کنید و در جاهای دیگر در اسناد سرویس‌های YouTube API مورد بحث قرار گرفته است. حتی زمانی که به شدت مورد نیاز نیست، این روش‌ها به مشتریان API شما کمک می‌کند تا در صورت استفاده از سرویس‌های YouTube API که سهمیه را اختصاص می‌دهند، سریع‌تر از خطاها بازیابی کنند و استفاده از سهمیه خود را بهینه کنند. در عین حال، این شیوه‌ها به اطمینان از سلامت اکوسیستم YouTube و بالاتر از همه، ارائه بهترین تجربه ممکن به کاربران مشتریان API و برنامه‌های YouTube کمک می‌کنند.

پخش کننده جاسازی شده یوتیوب و پخش ویدیو

الزامات این بخش به طور خاص به پخش کننده های یوتیوب تعبیه شده مربوط می شود. خط‌مشی‌های خدمات YouTube API همچنین شامل چندین خط‌مشی مرتبط با مشتریان API است که محتوای سمعی و بصری YouTube را پخش می‌کنند.

شناسه و اعتبار مشتری API

مشتریان API که از پخش‌کننده جاسازی‌شده YouTube (از جمله YouTube IFrame Player API) استفاده می‌کنند، باید از طریق سرصفحه درخواست HTTP Referer شناسایی کنند. در برخی از محیط‌ها، مرورگر به‌طور خودکار HTTP Referer تنظیم می‌کند و مشتریان API فقط باید مطمئن شوند که Referrer-Policy به گونه‌ای تنظیم نمی‌کنند که مقدار Referer سرکوب کند. یوتیوب توصیه می‌کند از سیاست ارجاع‌دهنده- strict-origin-when-cross-origin استفاده کنید، که قبلاً در بسیاری از مرورگرها پیش‌فرض است.

به طور مشابه، اگر پخش کننده جاسازی شده YouTube را در پنجره ایجاد شده با استفاده از JavaScript window.open ادغام کنید، API Clients نباید از ویژگی noreferrer استفاده کند که مقدار Referer سرکوب می کند.

Referer را تنظیم کنید

در محیط‌هایی که HTTP Referer به‌طور پیش‌فرض خالی است و به‌طور خودکار توسط مرورگر تنظیم نشده است، API Clients باید برای ارائه هویت خود از طریق روش‌های جایگزین اقدام کنند. در ادغام‌های 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 تنظیم می کنید:

  • loadUrl Android با سرصفحه HTTP Referer اضافه شده به پارامتر additionalHttpHeaders

  • iOS loadRequest: با Referer HTTP Header به درخواست اضافه شده است. به عنوان مثال:

    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];
    

• برنامه تلفن همراه با پخش کننده در برگه مرورگر بومی

  • CustomTabs اندروید

    برای تنظیم ارجاع دهنده Intent.EXTRA_REFERRER استفاده کنید. هنگام ایجاد Uri حتماً به جای https:// از طرح android-app:// استفاده کنید. به عنوان مثال:

    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 به طور پیش فرض خالی است، با پیکربندی WebView که پخش کننده در آن بارگذاری شده است، مقدار Referer را تنظیم کنید. تکنیک دقیق ممکن است بسته به پلت فرم متفاوت باشد.

اگر مالک کتابخانه، فریمورک، افزونه، سرویس یا پوششی هستید که توسط توسعه‌دهندگان برای ادغام پخش‌کننده تعبیه‌شده YouTube استفاده می‌شود، باید شناسه برنامه را از محیط بازیابی کنید (این ممکن است بسته به پلتفرم ممکن نباشد) یا به توسعه‌دهندگان اجازه دهید شناسه برنامه خود را ارسال کنند تا Referer (و پارامتر پخش کننده widget_referrer ، در صورت لزوم، در صورت لزوم تنظیم شود).

فرمت ارجاع دهنده

هنگامی که شما به صراحت Referer را با تنظیم یک پارامتر WebView یا اضافه کردن یک سربرگ HTTP ارائه می کنید، قالب معمولاً یک URL کاملا واجد شرایط است. HTTPS به عنوان پروتکل مشخص کنید. در URL، نام دامنه باید شناسه برنامه شما («شناسه برنامه») باشد که در فروشگاهی که برنامه شما را بین کاربران نهایی توزیع کرده است، ثبت شده است. اگر برنامه شما از طریق یک کانال توزیع جایگزین به کاربران ارائه می شود، از شناسه برنامه که در هنگام نصب برنامه در سیستم عامل ثبت شده است استفاده کنید. در اکثر موارد، شناسه برنامه شما یک نام دامنه معکوس شده (همچنین به عنوان "فرمت معکوس-DNS" شناخته می شود)، مانند com.google.android.youtube خواهد بود. نمونه های نمایندگی:

• سیستم عامل Android و برنامه‌های Android در ChromeOS: شناسه برنامه
• پلتفرم‌های اپل، از جمله iOS، iPadOS، macOS: Bundle ID
• Samsung Tizen: App ID
• توزیع های لینوکس:
  • فدورا: شناسه برنامه
  • Gnome: شناسه برنامه
  • اوبونتو: شناسه برنامه

در برخی از سیستم عامل ها، شناسه برنامه یک نام دامنه معکوس نیست. در این موارد، از شناسه برنامه منحصر به فرد اختصاص داده شده توسط فروشگاه توزیع کننده برنامه استفاده کنید. وقتی شناسه برنامه فروشگاه یک رشته الفبایی ایجاد شده است (تخصیص داده شده توسط فروشگاه یا ابزارهای توسعه، که توسط توسعه‌دهنده برنامه انتخاب نشده است)، نام نمایشی برنامه (جایگزینی فضاها با خط تیره) و شناسه برنامه فروشگاه را که با یک نقطه محدود شده‌اند، شامل شود. به عنوان مثال: <my-app-name>.<AppID> . این مقدار باید در تغییرات نسخه برنامه پایدار باشد. اگر برنامه در فروشگاهی میزبانی نمی شود، از شناسه برنامه که در هنگام نصب برنامه در سیستم عامل ثبت شده است استفاده کنید. این معمولاً یک شناسه منحصر به فرد در مانیفست برنامه است. جزئیات مربوط به نسخه برنامه و معماری پشتیبانی شده را حذف کنید. نمونه های نمایندگی:

• فروشگاه وب Chrome: میزبان فروشگاه

  شناسه برنامه فروشگاه معمولاً آخرین قسمت از مسیر در آدرس اینترنتی برنامه https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID> است. از نام برنامه خط‌دار و شناسه برنامه فروشگاه برای ساختن رشته <my-app-name>.<AppID> که در بالا توضیح داده شد.

• ویندوز: میزبانی فروشگاه

  شناسه برنامه فروشگاه معمولاً آخرین قسمت مسیر در آدرس اینترنتی برنامه https://apps.microsoft.com/detail/<AppID> است. از شناسه برنامه فروشگاه برای ساختن <my-app-name>.<AppID> که در بالا توضیح داده شد. نام برنامه خط فاصله نیز باید درج شود.

• ویندوز: توزیع غیر فروشگاهی

  برنامه‌های ویندوز حاوی هویت بسته در مانیفست برنامه هستند: Name_Version_Architecture_ResourceID_PublisherID . فقط از ویژگی Name استفاده کنید.

• ایکس باکس: میزبان فروشگاه

  شناسه برنامه فروشگاه معمولاً آخرین قسمت مسیر در آدرس اینترنتی برنامه https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID> است. از نام برنامه خط‌دار و شناسه برنامه فروشگاه برای ساختن رشته <my-app-name>.<AppID> که در بالا توضیح داده شد.

برای مشتریان API با تعداد درخواست‌های زیاد به YouTube (به استفاده و سهمیه‌ها مراجعه کنید)، ممکن است برای دسترسی به پخش‌کننده تعبیه‌شده YouTube به اعتبارنامه‌های بیشتری نیاز باشد.

رعایت نکردن این الزامات ممکن است منجر به کاهش عملکرد در پخش‌کننده تعبیه‌شده YouTube شود.

نوع WebView

هنگام ادغام پخش‌کننده تعبیه‌شده YouTube در WebView، در صورت وجود از یکی از انواع WebView ارائه‌شده توسط سیستم عامل استفاده کنید. به عنوان مثال:

• سیستم عامل اندروید: WebView یا CustomTabs
• پلتفرم های اپل، از جمله iOS، iPadOS، macOS: WKWebView یا SFSafariViewController

اندازه پخش کننده یوتیوب جاسازی شده

پخش‌کننده‌های جاسازی‌شده باید دیدی با ابعاد حداقل 200 پیکسل در 200 پیکسل داشته باشند. اگر پخش‌کننده کنترل‌ها را نمایش می‌دهد، باید به اندازه‌ای بزرگ باشد که کنترل‌ها را به‌طور کامل نمایش دهد، بدون اینکه درگاه دید کمتر از حداقل اندازه باشد. ما توصیه می کنیم پخش کننده های 16:9 حداقل 480 پیکسل عرض و 270 پیکسل قد داشته باشند.

پخش خودکار و پخش اسکریپت

این بخش پخش خودکار را پوشش می دهد. این برنامه برای پخش‌کننده‌های جاسازی‌شده YouTube اعمال می‌شود که یا از پارامتر پخش autoplay استفاده می‌کنند یا با استفاده از سرویس YouTube IFrame Player API یا سرویس YouTube API دیگر، پخش خودکار را به صورت برنامه‌ریزی شروع می‌کنند.

• پخش‌کننده‌های جاسازی‌شده که به‌طور خودکار یک ویدیو را پخش می‌کنند، باید بلافاصله پس از بارگیری صفحه یا به محض اینکه پخش‌کننده جاسازی‌شده کاملاً قابل مشاهده است، بازپخش را آغاز کنند. با این حال، یک سرویس گیرنده API نباید پخش خودکار را شروع کند تا زمانی که پخش کننده قابل مشاهده باشد و بیش از نیمی از پخش کننده در صفحه یا صفحه قابل مشاهده باشد.

• یک صفحه یا صفحه نباید بیش از یک پخش کننده YouTube داشته باشد که به طور خودکار محتوا را به طور همزمان پخش کند.

• هر تصویر کوچک YouTube که بازپخش را آغاز می کند باید حداقل 120 پیکسل عرض و 70 پیکسل ارتفاع داشته باشد.

ویژگی های YouTube Player

ویژگی ها و پارامترهای پخش کننده YouTube - از جمله، به عنوان مثال، ظاهر نام تجاری YouTube در پخش کننده - در اسناد و مشخصات YouTube API (https://developers.google.com/youtube) مشخص شده است. شما نباید تغییراتی در پخش کننده YouTube ایجاد کنید که به صراحت در اسناد API توضیح داده نشده است.

روکش ها و قاب ها

شما نباید پوشش‌ها، فریم‌ها یا سایر عناصر بصری را در مقابل هیچ بخشی از پخش‌کننده تعبیه‌شده YouTube، از جمله کنترل‌های پخش‌کننده، نمایش دهید. به طور مشابه، نباید از پوشش‌ها، فریم‌ها یا سایر عناصر بصری برای مبهم کردن بخشی از پخش‌کننده تعبیه‌شده، از جمله کنترل‌های پخش‌کننده، استفاده کنید.

Mouseovers

برای شروع هر اقدامی از طرف کاربر، مانند باز کردن یک پنجره یا اشتراک در یک کانال، نباید از ماوس یا رویدادهای لمسی در پخش کننده YouTube استفاده کنید.

در حال آپلود ویدیوها

اگر مشتریان API به کاربران اجازه می‌دهند محتوا را در چندین پلتفرم آپلود کنند، کاربران باید بتوانند پلتفرم‌هایی را که می‌خواهند ویدیوهای خود را در آن آپلود کنند، انتخاب کرده و از حالت انتخاب خارج کنند.

الزامات داده

کلاینت‌های API که به کاربران امکان می‌دهند ویدیوها را در YouTube آپلود کنند، باید کاربران را قادر به تنظیم مقادیر در لیست زیر کنند. هر ویژگی که در لیست نیست اختیاری است.

نمایش نظرات

افزودن نظرات

افزودن پاسخ های نظر

ویرایش یا حذف پاسخ های نظرات

ممنوع کردن کاربر از چت زنده (یا حذف ممنوعیت)