YouTube API-Dienste – Erforderliche Mindestfunktionen

Hinweis:Die YouTube-Richtlinien für Entwickler einhalten enthält Anleitungen und Beispiele, die Ihnen helfen, sicherzustellen, dass Ihre 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 funktionalen Mindestanforderungen für 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 vor allem, dass 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.

API-Client-Identität und ‑Anmeldedaten

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 ihre Identität auf andere Weise angeben. 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 der Referrer-URL

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 wird), 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 App-Shop gehostet wird, verwenden Sie die App-ID, die bei der Installation der App im Betriebssystem registriert wird. Das 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: