Usługi YouTube API – wymagana minimalna funkcjonalność

Uwaga: Przestrzeganie zasad dla deweloperów YouTube zawiera wskazówki i przykłady, które pomogą Ci zadbać o to, aby Twoi klienci interfejsu API przestrzegali określonych części Warunków i zasad usług YouTube API (Warunków korzystania z usług API). Przewodnik zawiera informacje o tym, jak YouTube egzekwuje pewne aspekty Warunków korzystania z interfejsu API, ale nie zastępuje żadnych istniejących dokumentów.

Ten dokument określa minimalne wymagania funkcjonalne dotyczące klientów interfejsu API, którzy wdrażają określone funkcje usług interfejsu API YouTube („klienci interfejsu API”) lub zapewniają do nich dostęp.

Te wymagania i wytyczne zapewniają klientom interfejsu API spójne wrażenia użytkownika, które chronią interesy użytkowników YouTube, właścicieli treści i reklamodawców. Te zasady stanowią integralną część Warunków korzystania z interfejsu API YouTube i muszą być przestrzegane podczas tworzenia i wdrażania klientów API.

Wymagania w tym dokumencie mogą się zmieniać, abyśmy mogli zapewnić użytkownikom lepsze wrażenia podczas korzystania z istniejących funkcji YouTube. Będą się one również zmieniać w odpowiedzi na nowe i zaktualizowane funkcje YouTube. Czasami takie zmiany mogą wymagać zaktualizowania klientów interfejsu API w celu spełnienia nowych wymagań. Wszelkie zmiany będą dokumentowane w historii zmian Warunków usługi. Często sprawdzaj ten dokument lub subskrybuj jego kanał RSS, aby szybko dowiadywać się o zmianach, które mogą mieć wpływ na Twoich klientów interfejsu API.

Oprócz wymagań opisanych w tym dokumencie zalecamy stosowanie sprawdzonych metod opisanych w zasadach dotyczących usług YouTube API i omówionych w innych częściach dokumentacji usług YouTube API. Nawet jeśli nie jest to bezwzględnie wymagane, te praktyki pomagają klientom API szybciej odzyskiwać sprawność po błędach i optymalizować wykorzystanie limitu, jeśli korzystają z usług interfejsu API YouTube, które przydzielają limit. Jednocześnie te praktyki pomagają dbać o ekosystem YouTube, a przede wszystkim zapewniają użytkownikom klientów interfejsu API i aplikacji YouTube jak najlepsze wrażenia.

Umieszczony odtwarzacz YouTube i odtwarzanie filmów

Wymagania w tej sekcji dotyczą w szczególności umieszczonych odtwarzaczy YouTube. Zasady dotyczące usług interfejsu API YouTube obejmują też kilka zasad dotyczących klientów API, którzy odtwarzają treści audiowizualne YouTube.

Tożsamość i dane logowania klienta interfejsu API

Klienci API, którzy korzystają z odtwarzacza osadzonego YouTube (w tym z interfejsu YouTube IFrame Player API), muszą podać identyfikator w nagłówku żądania HTTP Referer. W niektórych środowiskach przeglądarka automatycznie ustawia wartość HTTP Referer, a klienty API muszą tylko zadbać o to, aby nie ustawiać wartości Referrer-Policy w sposób, który tłumi wartość Referer. YouTube zaleca używanie nagłówka strict-origin-when-cross-originReferrer-Policy, który jest już domyślnie włączony w wielu przeglądarkach.

Podobnie w przypadku integracji odtwarzacza umieszczonego YouTube w oknie utworzonym za pomocą JavaScriptu window.open klienci interfejsu API nie mogą używać funkcji noreferrer, która pomija wartość Referer.

Ustawianie odsyłającego

W środowiskach, w których HTTP Referer jest domyślnie puste i nie jest automatycznie ustawiane przez przeglądarkę, klienci interfejsu API muszą podjąć działania, aby podać swoją tożsamość w inny sposób. W przypadku integracji z komponentem WebView, np. w aplikacji mobilnej lub aplikacji na komputery, parametr HTTP Referer jest domyślnie pusty, a parametr Referer jest zwykle ustawiany za pomocą jednej z tych metod:

  • Aplikacja mobilna z odtwarzaczem w lokalnym pliku HTML

    W tej konfiguracji odtwarzacz jest wczytywany w pliku HTML dołączonym do aplikacji. Podczas wczytywania tego pliku HTML ustawienie parametru baseUrl spowoduje ustawienie parametru Referer.

  • Aplikacja mobilna bez lokalnego pliku HTML

    W tej konfiguracji odtwarzacz jest wczytywany bezpośrednio z https://www.youtube.com/embed/VIDEO_ID bez otaczającego go pliku HTML. Ustawiasz parametr Referer, dodając go jako nagłówek HTTP:

    • Android loadUrl z nagłówkiem HTTP Referer dodanym do parametru additionalHttpHeaders

    • iOS loadRequest: z nagłówkiem HTTP Referer dodanym do żądania. Na przykład:

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

  • Aplikacja mobilna z odtwarzaczem na karcie przeglądarki natywnej

    • Android CustomTabs

      Użyj parametru Intent.EXTRA_REFERRER, aby ustawić witrynę odsyłającą. Podczas tworzenia Uri używaj schematu android-app:// zamiast https://. Na przykład:

      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 nie obsługuje ustawienia Referer. W takim przypadku ustaw parametr odtwarzacza origin.

  • Aplikacja na komputery

    W tej konfiguracji ustaw Referer, dodając go jako nagłówek HTTP:

W przypadku innych platform, na których HTTP Referer jest domyślnie puste, ustaw wartość Referer, konfigurując element WebView, w którym wczytywany jest odtwarzacz. Dokładna technika może się różnić w zależności od platformy.

Jeśli jesteś właścicielem biblioteki, platformy, wtyczki, usługi lub otoki używanej przez deweloperów do integrowania osadzonego odtwarzacza YouTube, musisz pobrać identyfikator aplikacji ze środowiska (może to być niemożliwe w zależności od platformy) lub zezwolić deweloperom na przekazywanie identyfikatora aplikacji, aby można było ustawić parametr Referer (i parametr odtwarzacza widget_referrer, jeśli to konieczne) w sposób opisany powyżej.

Format odsyłającego

Jeśli jawnie podasz adres URL strony odsyłającej, ustawiając parametr WebView lub dodając nagłówek HTTP, format będzie zazwyczaj pełnym adresem URL. Określ HTTPS jako protokół. W adresie URL nazwa domeny musi być identyfikatorem aplikacji („app ID”) zarejestrowanym w sklepie, który rozpowszechnia Twoją aplikację wśród użytkowników. Jeśli Twoja aplikacja jest udostępniana użytkownikom za pomocą alternatywnego kanału dystrybucji, użyj identyfikatora aplikacji zarejestrowanego w systemie operacyjnym podczas instalacji aplikacji. W większości przypadków identyfikator aplikacji będzie odwróconą nazwą domeny (znaną też jako „format odwróconego DNS”), np. com.google.android.youtube. Przykłady:

Na niektórych platformach identyfikator aplikacji nie jest odwróconą nazwą domeny. W takich przypadkach użyj unikalnego identyfikatora aplikacji przypisanego przez sklep, który ją rozpowszechnia. Jeśli identyfikator aplikacji w sklepie jest wygenerowanym ciągiem alfanumerycznym (przypisanym przez sklep lub narzędzia deweloperskie, a nie wybranym przez dewelopera aplikacji), podaj zarówno nazwę wyświetlaną aplikacji (zastępując spacje myślnikami), jak i identyfikator aplikacji w sklepie, oddzielone kropką. Przykład: <my-app-name>.<AppID>. Ta wartość powinna być stabilna niezależnie od zmian wersji aplikacji. Jeśli aplikacja nie jest hostowana w sklepie, użyj identyfikatora aplikacji zarejestrowanego w systemie operacyjnym podczas instalacji aplikacji. Jest to zwykle unikalny identyfikator w pliku manifestu aplikacji. Nie podawaj żadnych szczegółów dotyczących wersji aplikacji i obsługiwanej architektury. Przykłady:

  • Chrome Web Store: hostowane w sklepie

    Identyfikator aplikacji w sklepie to zwykle ostatnia część ścieżki w adresie URL aplikacjihttps://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID>. Aby utworzyć ciąg znaków <my-app-name>.<AppID> opisany powyżej, użyj nazwy aplikacji z łącznikiem i identyfikatora aplikacji w sklepie.

  • Windows: hostowane w sklepie

    Identyfikator aplikacji w sklepie to zwykle ostatnia część ścieżki w adresie URL aplikacjihttps://apps.microsoft.com/detail/<AppID>. Użyj identyfikatora aplikacji w sklepie, aby utworzyć ciąg znaków <my-app-name>.<AppID> opisany powyżej. Musi też zawierać nazwę aplikacji z łącznikiem.

  • Windows: dystrybucja poza sklepem

    Aplikacje na Windowsa zawierają w pliku manifestu aplikacji tożsamość pakietu: Name_Version_Architecture_ResourceID_PublisherID. Używaj tylko atrybutu Name.

  • Xbox: hostowane w sklepie

    Identyfikator aplikacji w sklepie to zwykle ostatnia część ścieżki w adresie URL aplikacjihttps://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID>. Aby utworzyć ciąg znaków <my-app-name>.<AppID> opisany powyżej, użyj nazwy aplikacji z łącznikiem i identyfikatora aplikacji w sklepie.

W przypadku klientów API, którzy wysyłają do YouTube dużą liczbę żądań (patrz Wykorzystanie i limity), dostęp do umieszczonego odtwarzacza YouTube może wymagać dodatkowych danych logowania.

Niespełnienie tych wymagań może spowodować ograniczenie funkcjonalności umieszczonego odtwarzacza YouTube.

Typ WebView

Podczas integrowania umieszczonego odtwarzacza YouTube w widoku WebView używaj jednego z typów widoku WebView udostępnianych przez system operacyjny, jeśli jest to możliwe. Na przykład:

Rozmiar umieszczonego odtwarzacza YouTube

Odtwarzacz umieszczony na stronie musi mieć okno wyświetlania o rozmiarze co najmniej 200 x 200 pikseli. Jeżeli w odtwarzaczu mają być widoczne elementy sterujące, musi on być na tyle duży, aby elementy te były całkowicie widoczne bez zmniejszania okna wyświetlania poniżej rozmiaru minimalnego. W przypadku odtwarzaczy 16:9 zalecamy rozmiar co najmniej 480 pikseli szerokości i 270 pikseli wysokości.

Automatyczne odtwarzanie i odtwarzanie ze skryptem

Ta sekcja dotyczy automatycznego odtwarzania. Dotyczy to umieszczonych odtwarzaczy YouTube, które używają parametru odtwarzacza autoplay lub programowo inicjują automatyczne odtwarzanie za pomocą usługi YouTube IFrame Player API lub innej usługi YouTube API.

  • Odtwarzacze osadzone, które automatycznie odtwarzają film, powinny rozpocząć odtwarzanie natychmiast po załadowaniu strony lub gdy tylko odtwarzacz osadzony będzie w pełni widoczny. Klient interfejsu API nie może jednak inicjować automatycznego odtwarzania, dopóki odtwarzacz nie będzie widoczny, a ponad połowa odtwarzacza nie będzie widoczna na stronie lub ekranie.

  • Na stronie lub ekranie nie może być więcej niż 1 odtwarzacz YouTube, który automatycznie odtwarza treści jednocześnie.

  • Każda miniatura w YouTube, która inicjuje odtwarzanie, musi mieć co najmniej 120 pikseli szerokości i 70 pikseli wysokości.

Atrybuty odtwarzacza YouTube

Atrybuty i parametry odtwarzacza YouTube, w tym np. wygląd logo YouTube w odtwarzaczu, są określone w dokumentacji i specyfikacjach interfejsu YouTube API (https://developers.google.com/youtube). Nie wolno wprowadzać w odtwarzaczu YouTube zmian, które nie są wyraźnie opisane w dokumentacji interfejsu API.

Nakładki i ramki

Nie wolno wyświetlać nakładek, ramek ani innych elementów wizualnych przed żadną częścią odtwarzacza YouTube umieszczonego na stronie, w tym przed elementami sterującymi odtwarzaczem. Podobnie nie wolno używać nakładek, ramek ani innych elementów wizualnych, aby zasłaniać jakąkolwiek część odtwarzacza, w tym elementy sterujące.

Przesunięcia kursora myszy

Nie wolno używać najazdów myszą ani zdarzeń dotykowych w odtwarzaczu YouTube do inicjowania w imieniu użytkownika żadnych działań, takich jak otwieranie okna czy subskrybowanie kanału.

Przesyłanie filmów wideo

Jeśli klienci API umożliwiają użytkownikom przesyłanie treści na wiele platform, użytkownicy powinni mieć możliwość wybierania i odznaczania platform, na które chcą przesyłać filmy.

Wymagania dotyczące danych

Klienci interfejsu API, którzy umożliwiają użytkownikom przesyłanie filmów do YouTube, muszą umożliwić użytkownikom ustawianie wartości na poniższej liście. Wszystkie właściwości, które nie są wymienione na liście, są opcjonalne.

  Nazwa Opis
Właściwości zasobu
snippet.title Wymagany. Tytuł filmu. Jeśli wartość przekracza 100 znaków, YouTube zwraca błąd. YouTube obsługuje wszystkie prawidłowe znaki UTF-8 z wyjątkiem < i >.

snippet.description Wymagany. Opis filmu. Jeśli wartość przekracza 5000 bajtów, YouTube zwraca błąd. YouTube obsługuje wszystkie prawidłowe znaki UTF-8 z wyjątkiem < i >.
status.privacyStatus Wymagany. ustawienia prywatności filmu; Użytkownicy muszą mieć możliwość określenia, czy przesłany film ma być publiczny, prywatny czy niepubliczny.
Parametry żądania
onBehalfOfContentOwnerChannel Wymagane warunkowo. Jeśli dane logowania w żądaniu identyfikują właściciela treści i ustawiony jest parametr onBehalfOfContentOwner, użytkownik interfejsu API musi też mieć możliwość określenia kanału w YouTube, na który przesyłany jest film.

Wyświetlanie komentarzy

  Nazwa Opis
Właściwości zasobu
snippet.textDisplay Wymagany. Tekst komentarza. Klient API musi (a) wyświetlać pełny tekst komentarza lub odpowiedzi na komentarz albo (b) obcinać tekst i udostępniać widzowi sposób łatwego uzyskania dostępu do pełnej wersji z wersji obciętej.

Ten wymóg dotyczy wszystkich komentarzy i odpowiedzi na komentarze, niezależnie od tego, z jakim typem zasobu są powiązane (filmy, kanały itp.).

Pamiętaj, że wartość właściwości snippet.topLevelComment zasobu commentThread jest zasobem comment, a właściwość replies.comments[] jest listą zasobów comment. Wymóg ten dotyczy też usług snippet.topLevelComment.snippet.textDisplay i replies.comments[].snippet.textDisplay.
snippet.title
(channel)		 Wymagany (sugestia) Tytuł kanału.
  • Jeśli komentarz dotyczy kanału, klient interfejsu API musi wyświetlić nazwę kanału.
  • Jeśli komentarz dotyczy filmu, klient interfejsu API musi wyświetlić nazwę kanału, na który został przesłany film.
snippet.title
(video)		 Wymagany warunkowo (sugestia) Tytuł filmu. Ta wartość musi być wyświetlana, jeśli komentarz dotyczy filmu.
snippet.moderationStatus Wymagane warunkowo. Jeśli wartość parametru moderationStatus w żądaniu API to heldForReview lub likelySpam, wyświetlany komunikat musi wyraźnie wskazywać ten stan za pomocą wartości właściwości, podobnego sformułowania (np. „Ten komentarz jest wstrzymany do sprawdzenia”), nagłówka (np. „Wstrzymany do sprawdzenia”) lub innego jednoznacznego sformułowania. Metoda commentThreads.list umożliwia pobieranie komentarzy na podstawie ich stanu moderacji.

Dodawanie komentarzy

  Nazwa Opis
Właściwości zasobu
snippet.title
(channel)		 Wymagany. Tytuł kanału.
  • Jeśli użytkownik dodaje komentarz dotyczący kanału, klient interfejsu API musi wyświetlić nazwę kanału.
  • Jeśli użytkownik dodaje komentarz do filmu, klient interfejsu API musi wyświetlić nazwę kanału, który przesłał film.
snippet.title
(video)		 Wymagany. Jeśli użytkownik dodaje komentarz do filmu, klient interfejsu API musi wyświetlić tytuł filmu.
Inne wymagania
Comment author's channel name Wymagany. Klient interfejsu API musi wyraźnie identyfikować konto użytkownika YouTube, do którego zostanie przypisany komentarz. Jeśli dane logowania w żądaniu identyfikują właściciela treści i parametr onBehalfOfContentOwner jest ustawiony, użytkownik interfejsu API musi też mieć możliwość określenia kanału w YouTube, do którego będzie przypisany komentarz.

Dodawanie odpowiedzi do komentarzy

  Nazwa Opis
Właściwości zasobu
snippet.textDisplay Wymagany. Tekst komentarza. Klient API musi wyświetlać tekst komentarza, na który odpowiada użytkownik, zgodnie z zasadami określonymi w sekcji Wyświetlanie komentarzy tego dokumentu.
snippet.title
(channel)		 Wymagany. Tytuł kanału.
  • Jeśli użytkownik odpowiada na komentarz dotyczący kanału, klient interfejsu API musi wyświetlić nazwę kanału.
  • Jeśli użytkownik odpowiada na komentarz dotyczący filmu, klient interfejsu API musi wyświetlić nazwę kanału, na który przesłano film.
snippet.title
(video)		 Wymagany. Jeśli użytkownik odpowiada na komentarz dotyczący filmu, klient interfejsu API musi wyświetlić tytuł filmu.
Inne wymagania
Comment author's channel name Wymagany. Klient interfejsu API musi wyraźnie identyfikować konto użytkownika YouTube, do którego zostanie przypisana odpowiedź na komentarz. Jeśli dane logowania w żądaniu identyfikują właściciela treści i ustawiony jest parametr onBehalfOfContentOwner, użytkownik interfejsu API musi też mieć możliwość określenia kanału w YouTube, do którego będzie przypisana odpowiedź na komentarz.

Edytowanie i usuwanie odpowiedzi na komentarze

  Nazwa Opis
Właściwości zasobu
snippet.textDisplay Wymagany. Tekst komentarza. Klient API musi wyświetlać tekst komentarza, który użytkownik edytuje lub usuwa, zgodnie z zasadami określonymi w sekcji Wyświetlanie komentarzy tego dokumentu.
snippet.title
(channel)		 Wymagany. Tytuł kanału.
  • Jeśli użytkownik edytuje lub usuwa komentarz dotyczący kanału, klient API musi wyświetlić nazwę kanału.
  • Jeśli użytkownik edytuje lub usuwa komentarz do filmu, klient interfejsu API musi wyświetlić nazwę kanału, który przesłał film.
snippet.title
(video)		 Wymagany. Jeśli użytkownik edytuje lub usuwa komentarz do filmu, klient API musi wyświetlić tytuł filmu.
Inne wymagania
Comment author's channel name Wymagany. Klient interfejsu API musi wyraźnie identyfikować konto użytkownika YouTube, do którego przypisany jest komentarz.

Blokowanie użytkownika na czacie na żywo (lub usuwanie blokady)

  Nazwa Opis
Właściwości zasobu
snippet.title
(channel)		 Wymagany. Nazwa kanału w YouTube, który jest blokowany lub odblokowywany. Dodatkowo nazwa musi zawierać link do kanału lub musi być wyświetlany adres URL kanału.
Inne wymagania
Nazwa kanału autora komentarza Wymagany. Klient interfejsu API musi wyraźnie identyfikować konto użytkownika YouTube, które jest używane do dodawania lub usuwania blokady.