API-сервисы YouTube – необходимый минимум функций

Примечание: Соблюдение правил разработчиков YouTube предоставляет руководство и примеры, которые помогут вам гарантировать, что ваши клиенты API следуют определенным частям условий и политик API YouTube (API TOS). Руководство дает представление о том, как YouTube обеспечивает соблюдение определенных аспектов API TOS, но оно не заменяет какие-либо существующие документы.

В настоящем документе определены минимальные функциональные требования к клиентам API, которые реализуют или предоставляют доступ к определенным функциям служб API YouTube («Клиенты API»).

Эти требования и рекомендации гарантируют, что клиенты API обеспечивают единообразный пользовательский опыт, защищающий интересы пользователей YouTube, владельцев контента и рекламодателей. Эти правила являются неотъемлемой частью Условий обслуживания API YouTube и должны соблюдаться при разработке и внедрении любых клиентов API.

Вам следует ожидать, что требования в этом документе изменятся, чтобы мы могли обеспечить лучший пользовательский опыт с существующими функциями YouTube. Они также будут меняться в ответ на новые и обновленные функции YouTube. Иногда такие изменения могут потребовать от вас обновления ваших API-клиентов для удовлетворения новых требований. История изменений Условий обслуживания будет документировать любые изменения, поэтому, пожалуйста, регулярно проверяйте этот документ или подпишитесь на его RSS-канал , чтобы вы могли быстро узнавать об изменениях, которые могут повлиять на ваших API-клиентов.

В дополнение к требованиям, изложенным в этом документе, мы настоятельно рекомендуем вам следовать лучшим практикам, описанным в Правилах API-сервисов YouTube и обсуждаемым в других местах документации API-сервисов YouTube. Даже если это не является строго обязательным, эти практики помогают вашим API-клиентам быстрее восстанавливаться после ошибок и оптимизировать использование квот, если они используют API-сервисы YouTube, выделяющие квоты. В то же время эти практики помогают обеспечить работоспособность экосистемы YouTube и, прежде всего, обеспечить наилучший возможный опыт для пользователей ваших API-клиентов и приложений YouTube.

Встроенный плеер YouTube и воспроизведение видео

Требования в этом разделе относятся конкретно к встроенным проигрывателям YouTube. Политики API сервисов YouTube также включают несколько политик, относящихся к API-клиентам, которые воспроизводят аудиовизуальный контент YouTube.

Идентификация и учетные данные клиента API

Клиенты API, использующие встроенный проигрыватель YouTube (включая API YouTube IFrame Player), должны предоставить идентификацию через заголовок запроса HTTP Referer . В некоторых средах браузер автоматически устанавливает HTTP Referer , и клиентам API нужно только убедиться, что они не устанавливают Referrer-Policy таким образом, чтобы подавить значение Referer . YouTube рекомендует использовать strict-origin-when-cross-origin Referrer-Policy, который уже установлен по умолчанию во многих браузерах.

Аналогично, при интеграции встроенного проигрывателя YouTube в окно, созданное с помощью JavaScript window.open , клиенты API не должны использовать функцию noreferrer , которая подавляет значение 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];
    

• Мобильное приложение с плеером внутри собственной вкладки браузера

  • CustomTabs Android

    Используйте Intent.EXTRA_REFERRER для установки реферера. Обязательно используйте схему android-app:// вместо https:// при создании Uri . Например:

    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, в котором загружен проигрыватель. Точная техника может различаться в зависимости от платформы.

Если вы являетесь владельцем библиотеки, фреймворка, плагина, сервиса или оболочки, используемых разработчиками для интеграции встроенного проигрывателя YouTube, вы должны извлечь идентификатор приложения из среды (это может быть невозможно в зависимости от платформы) или разрешить разработчикам передавать идентификатор своего приложения, чтобы Referer (и параметр проигрывателя widget_referrer , если применимо) можно было задать, как описано выше.

Формат реферера

Когда вы явно указываете Referer, устанавливая параметр WebView или добавляя заголовок HTTP, формат обычно представляет собой полностью определенный URL-адрес. Укажите HTTPS в качестве протокола. В URL-адресе доменное имя должно быть идентификатором вашего приложения («ID приложения»), зарегистрированным в магазине, который распространял ваше приложение среди конечных пользователей. Если ваше приложение предоставляется пользователям через альтернативный канал распространения, используйте идентификатор приложения, зарегистрированный в операционной системе во время установки приложения. В большинстве случаев идентификатор вашего приложения будет обратным доменным именем (также известным как «формат обратного DNS»), например com.google.android.youtube . Типичные примеры:

• ОС Android и приложения Android на ChromeOS: идентификатор приложения
• Платформы Apple, включая 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.

Тип веб-просмотра

При интеграции встроенного проигрывателя YouTube в WebView используйте один из типов WebView, предоставляемых ОС, если он доступен. Например:

• ОС Android: WebView или CustomTabs
• Платформы Apple, включая iOS, iPadOS, macOS: WKWebView или SFSafariViewController

Размер встроенного проигрывателя YouTube

Встроенные проигрыватели должны иметь область просмотра размером не менее 200x200 пикселей. Если проигрыватель отображает элементы управления, он должен быть достаточно большим, чтобы полностью отображать элементы управления, не уменьшая область просмотра ниже минимального размера. Мы рекомендуем проигрыватели 16:9 иметь ширину не менее 480 пикселей и высоту не менее 270 пикселей.

Автоматическое воспроизведение и воспроизведение по сценарию

В этом разделе рассматриваются автоматические воспроизведения. Он применяется к встроенным проигрывателям YouTube, которые либо используют параметр проигрывателя autoplay , либо программно инициируют автоматическое воспроизведение с помощью сервиса API YouTube IFrame Player или другого сервиса API YouTube.

• Встроенные проигрыватели, которые автоматически воспроизводят видео, должны инициировать воспроизведение немедленно после загрузки страницы или как только встроенный проигрыватель станет полностью видимым. Однако API-клиент не должен инициировать автоматическое воспроизведение, пока проигрыватель не станет видимым и более половины проигрывателя не будет видно на странице или экране.

• На странице или экране не должно быть более одного проигрывателя YouTube, которые автоматически воспроизводят контент одновременно.

• Любая миниатюра YouTube, инициирующая воспроизведение, должна быть не менее 120 пикселей в ширину и 70 пикселей в высоту.

Атрибуты проигрывателя YouTube

Атрибуты и параметры проигрывателя YouTube, включая, например, внешний вид фирменного стиля YouTube в проигрывателе, указаны в документации и спецификациях API YouTube (https://developers.google.com/youtube). Вы не должны вносить изменения в проигрыватель YouTube, которые явно не описаны в документации API.

Накладки и рамки

Вы не должны отображать наложения, рамки или другие визуальные элементы перед любой частью встроенного проигрывателя YouTube, включая элементы управления проигрывателем. Аналогично, вы не должны использовать наложения, рамки или другие визуальные элементы, чтобы скрыть любую часть встроенного проигрывателя, включая элементы управления проигрывателем.

Наведение мыши

Запрещается использовать наведение мыши или события касания в проигрывателе YouTube для инициирования каких-либо действий от имени пользователя, таких как открытие окна или подписка на канал.

Загрузка видео

Если клиенты API позволяют пользователям загружать контент на несколько платформ, пользователи должны иметь возможность выбирать и отменять выбор платформ, на которые они хотят загружать свои видео.

Требования к данным

Клиенты API, которые позволяют пользователям загружать видео на YouTube, должны позволять пользователям устанавливать значения в следующем списке. Любые свойства, которые не перечислены, являются необязательными.

Отображение комментариев

Добавление комментариев

Добавление ответов на комментарии

Редактирование или удаление ответов на комментарии

Запрет пользователю доступа к чату (или снятие запрета)