YouTube API-Dienste – Erforderliche Mindestfunktionen

Hinweis:Die YouTube-Richtlinien für Entwickler einhalten enthält Anleitungen und Beispiele, die dir helfen, sicherzustellen, dass deine API-Clients bestimmte Abschnitte der Nutzungsbedingungen und Richtlinien der YouTube API-Dienste (API-Nutzungsbedingungen) einhalten. Der Leitfaden gibt Aufschluss darüber, wie YouTube bestimmte Aspekte der API-Nutzungsbedingungen durchsetzt, ersetzt aber keine bestehenden Dokumente.

In diesem Dokument werden die Mindestanforderungen an die Funktionalität von API-Clients definiert, die bestimmte Funktionen von YouTube API-Diensten implementieren oder Zugriff darauf bieten („API-Clients“).

Diese Anforderungen und Richtlinien sollen sicherstellen, dass API-Clients eine einheitliche Nutzererfahrung bieten, die die Interessen von YouTube-Nutzern, Rechteinhabern und Werbetreibenden schützt. Diese Regeln sind ein integraler Bestandteil der Nutzungsbedingungen für die YouTube API und müssen bei der Entwicklung und Implementierung von API-Clients eingehalten werden.

Die Anforderungen in diesem Dokument können sich ändern, damit wir die Nutzerfreundlichkeit bestehender YouTube-Funktionen verbessern können. Sie werden auch an neue und aktualisierte YouTube-Funktionen angepasst. Manchmal müssen Sie Ihre API-Clients aktualisieren, um neuen Anforderungen gerecht zu werden. Im Änderungsverlauf der Nutzungsbedingungen werden alle Änderungen dokumentiert. Sehen Sie sich dieses Dokument daher regelmäßig an oder abonnieren Sie den RSS-Feed, damit Sie schnell über Änderungen informiert werden, die sich auf Ihre API-Clients auswirken können.

Zusätzlich zu den Anforderungen in diesem Dokument empfehlen wir dringend, die in den Richtlinien für YouTube-API-Dienste beschriebenen Best Practices zu befolgen, die auch an anderer Stelle in der Dokumentation zu YouTube-API-Diensten erläutert werden. Auch wenn sie nicht unbedingt erforderlich sind, helfen diese Praktiken Ihren API-Clients, sich schneller von Fehlern zu erholen und die Kontingentnutzung zu optimieren, wenn sie YouTube API-Dienste verwenden, für die Kontingent zugewiesen wird. Gleichzeitig tragen diese Praktiken dazu bei, dass das YouTube-Ökosystem gesund bleibt und Nutzer Ihrer API-Clients und YouTube-Anwendungen die bestmögliche Erfahrung machen.

Eingebetteter YouTube-Player und Videowiedergabe

Die Anforderungen in diesem Abschnitt beziehen sich speziell auf eingebettete YouTube-Player. Die Richtlinien für YouTube API-Dienste enthalten auch mehrere Richtlinien, die für API-Clients relevant sind, die audiovisuelle YouTube-Inhalte wiedergeben.

Identität und Anmeldedaten des API-Clients

API-Clients, die den eingebetteten YouTube-Player (einschließlich der YouTube IFrame Player API) verwenden, müssen sich über den Anfrageheader HTTP Referer identifizieren. In einigen Umgebungen wird HTTP Referer automatisch vom Browser festgelegt. API-Clients müssen nur darauf achten, dass sie Referrer-Policy nicht so festlegen, dass der Wert Referer unterdrückt wird. YouTube empfiehlt die Verwendung von strict-origin-when-cross-origin Referrer-Policy, die in vielen Browsern bereits die Standardeinstellung ist.

Wenn der YouTube-Einbettungsplayer in ein mit JavaScript window.open erstelltes Fenster eingebettet wird, dürfen API-Clients die Funktion noreferrer nicht verwenden, da dadurch der Referer-Wert unterdrückt wird.

Referer festlegen

In Umgebungen, in denen HTTP Referer standardmäßig leer ist und nicht automatisch vom Browser festgelegt wird, müssen API-Clients Maßnahmen ergreifen, um ihre Identität auf andere Weise anzugeben. Bei WebView-Integrationen wie einer mobilen App oder einer Desktop-App ist HTTP Referer standardmäßig leer und Referer wird in der Regel mit einer der folgenden Methoden festgelegt:

  • Mobile App mit Player in einer lokalen HTML-Datei

    Bei dieser Konfiguration wird der Player in einer HTML-Datei geladen, die mit der App gebündelt ist. Wenn diese HTML-Datei geladen wird, wird durch Festlegen des Parameters baseUrl der Parameter Referer festgelegt.

  • Mobile App ohne lokale HTML-Datei

    In dieser Konfiguration wird der Player direkt von https://www.youtube.com/embed/VIDEO_ID geladen, ohne dass eine umschließende HTML-Datei erforderlich ist. Sie legen Referer fest, indem Sie es als HTTP-Header hinzufügen:

    • Android loadUrl mit dem Referer-HTTP-Header, der dem Parameter additionalHttpHeaders hinzugefügt wurde

    • iOS loadRequest: mit dem HTTP-Header Referer, der der Anfrage hinzugefügt wurde. Beispiel:

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

  • Mobile App mit Player auf einem nativen Browser-Tab

    • Android CustomTabs

      Verwenden Sie Intent.EXTRA_REFERRER, um den Referrer festzulegen. Verwenden Sie beim Erstellen des Uri unbedingt das Schema android-app:// anstelle von https://. Beispiel:

      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 unterstützt das Festlegen von Referer nicht. Legen Sie in diesem Fall stattdessen den Player-Parameter origin fest.

  • Desktop-App

    In dieser Konfiguration legen Sie Referer fest, indem Sie es als HTTP-Header hinzufügen:

Bei anderen Plattformen, auf denen HTTP Referer standardmäßig leer ist, legen Sie den Wert Referer fest, indem Sie die WebView konfigurieren, in der der Player geladen wird. Die genaue Technik kann je nach Plattform variieren.

Wenn Sie Inhaber einer Bibliothek, eines Frameworks, eines Plug-ins, eines Dienstes oder eines Wrappers sind, die von Entwicklern zum Einbetten des YouTube-Players verwendet werden, müssen Sie die App-ID aus der Umgebung abrufen (je nach Plattform ist das möglicherweise nicht möglich) oder Entwicklern erlauben, ihre App-ID zu übergeben, damit Referer (und der Player-Parameter widget_referrer, falls zutreffend) wie oben beschrieben festgelegt werden kann.

Format des Referrers

Wenn Sie den Referer explizit angeben, indem Sie einen WebView-Parameter festlegen oder einen HTTP-Header hinzufügen, ist das Format in der Regel eine vollständig qualifizierte URL. Geben Sie HTTPS als Protokoll an. In der URL muss der Domainname Ihre Anwendungs-ID („App-ID“) sein, die bei dem Store registriert ist, über den Ihre App an Endnutzer verteilt wurde. Wenn Ihre App Nutzern über einen alternativen Vertriebskanal zur Verfügung gestellt wird, verwenden Sie die App-ID, die während der App-Installation beim Betriebssystem registriert wird. In den meisten Fällen ist Ihre App-ID ein umgekehrter Domainname (auch als „Reverse-DNS-Format“ bezeichnet), z. B. com.google.android.youtube. Repräsentative Beispiele:

  • Android OS und Android-Apps unter ChromeOS: App-ID
  • Apple-Plattformen, einschließlich iOS, iPadOS und macOS: Bundle-ID
  • Samsung Tizen: App-ID
  • Linux-Distributionen:

Auf einigen Plattformen ist die App-ID kein umgekehrter Domainname. Verwenden Sie in diesen Fällen die eindeutige App-ID, die vom Store zugewiesen wird, über den die App vertrieben wird. Wenn die Store-App-ID eine generierte alphanumerische Zeichenfolge ist (die vom Store oder von Entwicklungstools zugewiesen wird und nicht vom App-Entwickler ausgewählt wurde), geben Sie sowohl den Anzeigenamen der App (wobei Leerzeichen durch Bindestriche ersetzt werden) als auch die Store-App-ID an, getrennt durch einen Punkt. Beispiel: <my-app-name>.<AppID>. Dieser Wert sollte sich bei Änderungen der App-Version nicht ändern. Wenn die App nicht in einem Store gehostet wird, verwenden Sie die App-ID, die bei der Installation der App im Betriebssystem registriert wird. Dies ist in der Regel eine eindeutige Kennung im App-Manifest. Lassen Sie alle Details zur App-Version und zur unterstützten Architektur weg. Repräsentative Beispiele:

  • Chrome Web Store: Im Store gehostet

    Die Store-App-ID ist in der Regel der letzte Teil des Pfads in der App-URL https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID>. Verwenden Sie den durch Bindestriche getrennten App-Namen und die App-ID des App-Shops, um den oben beschriebenen <my-app-name>.<AppID>-String zu erstellen.

  • Windows: Store-gehostet

    Die Store-App-ID ist in der Regel der letzte Teil des Pfads in der App-URL https://apps.microsoft.com/detail/<AppID>. Verwenden Sie die Store-App-ID, um den oben beschriebenen <my-app-name>.<AppID>-String zu erstellen. Der Name der App mit Bindestrich muss ebenfalls angegeben werden.

  • Windows: Nicht über den Store bereitstellen

    Windows-Apps enthalten im App-Manifest eine Paketidentität: Name_Version_Architecture_ResourceID_PublisherID. Verwenden Sie nur das Attribut Name.

  • Xbox: Store-gehostet

    Die Store-App-ID ist in der Regel der letzte Teil des Pfads in der App-URL https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID>. Verwenden Sie den durch Bindestriche getrennten App-Namen und die App-ID des App-Shops, um den oben beschriebenen <my-app-name>.<AppID>-String zu erstellen.

Für API-Clients mit einer hohen Anzahl von Anfragen an YouTube (siehe Nutzung und Kontingente) sind möglicherweise zusätzliche Anmeldedaten erforderlich, um auf den eingebetteten YouTube-Player zuzugreifen.

Wenn Sie diese Anforderungen nicht einhalten, kann es zu einer eingeschränkten Funktionalität des eingebetteten YouTube-Players kommen.

WebView-Typ

Wenn Sie den eingebetteten YouTube-Player in eine WebView einbinden, verwenden Sie einen der vom Betriebssystem bereitgestellten WebView-Typen, sofern verfügbar. Beispiel:

Größe des eingebetteten YouTube-Players

Eingebettete Player müssen einen Darstellungsbereich mit mindestens 200 x 200 Pixel haben. Wenn die Steuerung angezeigt wird, muss der Player groß genug sein, um die Steuerelemente vollständig anzuzeigen, ohne dass der Darstellungsbereich dabei die genannte Mindestgröße unterschreitet. Für 16:9-Player empfehlen wir eine Breite von mindestens 480 Pixel und eine Höhe von mindestens 270 Pixel.

Automatische Wiedergabe und Scripted Playbacks

In diesem Abschnitt geht es um die automatische Wiedergabe. Sie gilt für eingebettete YouTube-Player, die entweder den Player-Parameter autoplay verwenden oder die automatische Wiedergabe programmatisch über die YouTube IFrame Player API oder einen anderen YouTube-API-Dienst starten.

  • Bei eingebetteten Playern, die ein Video automatisch abspielen, sollte die Wiedergabe sofort beim Laden der Seite oder sobald der eingebettete Player vollständig sichtbar ist, gestartet werden. Ein API-Client darf die automatische Wiedergabe jedoch erst starten, wenn der Player sichtbar ist und mehr als die Hälfte des Players auf der Seite oder dem Bildschirm zu sehen ist.

  • Auf einer Seite oder einem Bildschirm darf nicht mehr als ein YouTube-Player vorhanden sein, in dem Inhalte automatisch gleichzeitig abgespielt werden.

  • YouTube-Thumbnails, die eine Wiedergabe starten, müssen mindestens 120 Pixel breit und 70 Pixel hoch sein.

YouTube-Player-Attribute

Attribute und Parameter des YouTube-Players, z. B. die Darstellung des YouTube-Brandings im Player, sind in der YouTube-API-Dokumentation und den YouTube-API-Spezifikationen (https://developers.google.com/youtube) beschrieben. Du darfst keine Änderungen am YouTube-Player vornehmen, die nicht explizit in der API-Dokumentation beschrieben sind.

Overlays und Frames

Sie dürfen keine Overlays, Frames oder andere visuelle Elemente vor einem eingebetteten YouTube-Player platzieren, auch nicht vor den Steuerelementen des Players. Ebenso dürfen Sie keine Overlays, Frames oder andere visuelle Elemente verwenden, um Teile eines eingebetteten Players, einschließlich der Steuerelemente des Players, zu verdecken.

Mouseovers

Sie dürfen keine Mouseover- oder Touch-Ereignisse in einem YouTube-Player verwenden, um im Namen des Nutzers Aktionen auszulösen, z. B. das Öffnen eines Fensters oder das Abonnieren eines Kanals.

Hochladen von Videos

Wenn API-Clients es Nutzern ermöglichen, Inhalte auf mehrere Plattformen hochzuladen, sollten Nutzer die Plattformen auswählen und abwählen können, auf die sie ihre Videos hochladen möchten.

Datenanforderungen

API-Clients, die Nutzern das Hochladen von Videos auf YouTube ermöglichen, müssen Nutzern die Möglichkeit geben, die Werte in der folgenden Liste festzulegen. Alle nicht aufgeführten Attribute sind optional.

  Name Beschreibung
Ressourceneigenschaften
snippet.title Erforderlich. Der Titel des Videos. YouTube gibt einen Fehler zurück, wenn der Wert 100 Zeichen überschreitet. YouTube unterstützt alle gültigen UTF-8-Zeichen mit Ausnahme von < und >.

snippet.description Erforderlich. Die Videobeschreibung. YouTube gibt einen Fehler zurück, wenn der Wert 5.000 Byte überschreitet. YouTube unterstützt alle gültigen UTF-8-Zeichen mit Ausnahme von < und >.
status.privacyStatus Erforderlich. Die Datenschutzeinstellung des Videos. Nutzer müssen auswählen können, ob das hochgeladene Video öffentlich, privat oder nicht gelistet sein soll.
Anfrageparameter
onBehalfOfContentOwnerChannel Bedingt erforderlich Wenn die Autorisierungsanmeldedaten der Anfrage einen Rechteinhaber identifizieren und der Parameter onBehalfOfContentOwner festgelegt ist, muss der API-Nutzer auch den YouTube-Kanal angeben können, auf den das Video hochgeladen wird.

Kommentare anzeigen

  Name Beschreibung
Ressourceneigenschaften
snippet.textDisplay Erforderlich. Der Text des Kommentars. Der API-Client muss entweder (a) den vollständigen Text eines Kommentars oder einer Antwort auf einen Kommentar anzeigen oder (b) den Text kürzen und dem Betrachter eine Möglichkeit bieten, einfach auf den vollständigen Text zuzugreifen.

Diese Anforderung gilt für alle Kommentare und Antworten auf Kommentare, unabhängig davon, mit welcher Art von Ressource die Kommentare verknüpft sind (Videos, Kanäle usw.).

Der Wert der Eigenschaft snippet.topLevelComment der Ressource commentThread ist eine comment-Ressource und die Eigenschaft replies.comments[] ist eine Liste von comment-Ressourcen. Daher gilt diese Anforderung auch für die Properties snippet.topLevelComment.snippet.textDisplay und replies.comments[].snippet.textDisplay.
snippet.title
(channel)		 Erforderlich (Vorschlag) Der Titel des Kanals.
  • Wenn sich der Kommentar auf einen Kanal bezieht, muss der API-Client den Namen des Kanals anzeigen.
  • Wenn sich der Kommentar auf ein Video bezieht, muss der API-Client den Namen des Kanals anzeigen, auf dem das Video hochgeladen wurde.
snippet.title
(video)		 Bedingt erforderlich (Vorschlag) Der Titel des Videos. Dieser Wert muss angezeigt werden, wenn sich der Kommentar auf ein Video bezieht.
snippet.moderationStatus Bedingt erforderlich Wenn der Parameterwert moderationStatus in der API-Anfrage heldForReview oder likelySpam ist, muss der Status in der Anzeige deutlich angegeben werden. Verwenden Sie dazu den Property-Wert, eine ähnliche Formulierung (z. B. „Dieser Kommentar wird zur Überprüfung zurückgehalten“), eine Überschrift (z. B. „Zur Überprüfung zurückgehalten“) oder eine andere eindeutige Formulierung. Die Methode commentThreads.list unterstützt das Abrufen von Kommentaren basierend auf ihrem Moderationsstatus.

Kommentare hinzufügen

  Name Beschreibung
Ressourceneigenschaften
snippet.title
(channel)		 Erforderlich. Der Titel des Kanals.
  • Wenn der Nutzer einen Kommentar zu einem Kanal hinzufügt, muss der API-Client den Namen des Kanals anzeigen.
  • Wenn der Nutzer einen Kommentar zu einem Video hinzufügt, muss der API-Client den Namen des Kanals anzeigen, auf dem das Video hochgeladen wurde.
snippet.title
(video)		 Erforderlich. Wenn der Nutzer einen Kommentar zu einem Video hinzufügt, muss der API-Client den Titel des Videos anzeigen.
Weitere Anforderungen
Comment author's channel name Erforderlich. Der API-Client muss das YouTube-Nutzerkonto, dem der Kommentar zugeordnet wird, eindeutig identifizieren. Wenn in den Autorisierungsanmeldedaten der Anfrage ein Rechteinhaber angegeben ist und der Parameter onBehalfOfContentOwner festgelegt ist, muss der API-Nutzer auch den YouTube-Kanal angeben können, dem der Kommentar zugeordnet wird.

Antworten auf Kommentare hinzufügen

  Name Beschreibung
Ressourceneigenschaften
snippet.textDisplay Erforderlich. Der Text des Kommentars. Der API-Client muss den Text des Kommentars, auf den der Nutzer antwortet, gemäß den Regeln im Abschnitt Kommentare anzeigen dieses Dokuments anzeigen.
snippet.title
(channel)		 Erforderlich. Der Titel des Kanals.
  • Wenn der Nutzer auf einen Kommentar zu einem Kanal antwortet, muss der API-Client den Namen des Kanals anzeigen.
  • Wenn der Nutzer auf einen Kommentar zu einem Video antwortet, muss der API-Client den Namen des Kanals anzeigen, auf dem das Video hochgeladen wurde.
snippet.title
(video)		 Erforderlich. Wenn der Nutzer auf einen Kommentar zu einem Video antwortet, muss der API-Client den Titel des Videos anzeigen.
Weitere Anforderungen
Comment author's channel name Erforderlich. Der API-Client muss das YouTube-Nutzerkonto, dem die Antwort auf den Kommentar zugeordnet wird, eindeutig identifizieren. Wenn in den Autorisierungsanmeldedaten der Anfrage ein Rechteinhaber angegeben ist und der Parameter onBehalfOfContentOwner festgelegt ist, muss der API-Nutzer auch den YouTube-Kanal angeben können, dem die Kommentarantwort zugeordnet wird.

Kommentarantworten bearbeiten oder löschen

  Name Beschreibung
Ressourceneigenschaften
snippet.textDisplay Erforderlich. Der Text des Kommentars. Der API-Client muss den Text des Kommentars, den der Nutzer bearbeitet oder löscht, gemäß den Regeln im Abschnitt Kommentare anzeigen dieses Dokuments anzeigen.
snippet.title
(channel)		 Erforderlich. Der Titel des Kanals.
  • Wenn der Nutzer einen Kommentar zu einem Kanal bearbeitet oder löscht, muss der API-Client den Namen des Kanals anzeigen.
  • Wenn der Nutzer einen Kommentar zu einem Video bearbeitet oder löscht, muss der API-Client den Namen des Kanals anzeigen, auf dem das Video hochgeladen wurde.
snippet.title
(video)		 Erforderlich. Wenn der Nutzer einen Kommentar zu einem Video bearbeitet oder löscht, muss der API-Client den Titel des Videos anzeigen.
Weitere Anforderungen
Comment author's channel name Erforderlich. Der API-Client muss das YouTube-Nutzerkonto, dem der Kommentar zugeordnet ist, eindeutig identifizieren.

Nutzer im Livechat sperren oder die Sperrung aufheben

  Name Beschreibung
Ressourceneigenschaften
snippet.title
(channel)		 Erforderlich. Der Name des YouTube-Kanals, der gesperrt oder entsperrt wird. Außerdem muss der Name mit dem Kanal verknüpft sein oder die Kanal-URL muss ebenfalls angezeigt werden.
Weitere Anforderungen
Kanalname des Verfassers des Kommentars Erforderlich. Der API-Client muss das YouTube-Nutzerkonto, das zum Hinzufügen oder Entfernen des Banns verwendet wird, eindeutig identifizieren.