Services d'API YouTube – Fonctionnalités minimales requises

Remarque : Respecter le règlement pour les développeurs YouTube fournit des conseils et des exemples pour vous aider à vous assurer que vos clients API respectent certaines sections des Conditions d'utilisation et du Règlement des services d'API YouTube. Ce guide vous explique comment YouTube applique certains aspects des conditions d'utilisation de l'API, mais il ne remplace aucun document existant.

Ce document définit les exigences fonctionnelles minimales pour les clients API qui implémentent ou fournissent un accès à des fonctionnalités spécifiques des services d'API YouTube ("Clients API").

Ces exigences et consignes permettent de s'assurer que les clients de l'API offrent une expérience utilisateur cohérente qui protège les intérêts des utilisateurs, des propriétaires de contenu et des annonceurs YouTube. Ces règles font partie intégrante des Conditions d'utilisation de l'API YouTube et doivent être respectées lors du développement et de l'implémentation de tout client API.

Les exigences de ce document sont susceptibles d'évoluer afin de nous permettre d'améliorer l'expérience utilisateur avec les fonctionnalités YouTube existantes. Ils évolueront également en fonction des nouvelles fonctionnalités YouTube. Parfois, ces modifications peuvent vous obliger à mettre à jour vos clients API pour répondre aux nouvelles exigences. L'historique des modifications des conditions d'utilisation documente toutes les modifications. Veuillez donc le consulter régulièrement ou vous abonner à son flux RSS pour être informé rapidement des modifications susceptibles d'affecter vos clients API.

En plus des exigences décrites dans ce document, nous vous recommandons vivement de suivre les bonnes pratiques décrites dans le Règlement relatif aux services d'API YouTube et abordées ailleurs dans la documentation des services d'API YouTube. Même si elles ne sont pas strictement nécessaires, ces pratiques aident vos clients API à se remettre plus rapidement des erreurs et à optimiser leur utilisation du quota s'ils utilisent des services d'API YouTube qui allouent un quota. En même temps, ces pratiques contribuent à assurer la bonne santé de l'écosystème YouTube et, surtout, à offrir la meilleure expérience possible aux utilisateurs de vos clients API et des applications YouTube.

Lecteur YouTube intégré et lecture de vidéos

Les exigences de cette section concernent spécifiquement les lecteurs YouTube intégrés. Le Règlement relatif aux services d'API YouTube inclut également plusieurs règles concernant les clients API qui lisent du contenu audiovisuel YouTube.

Identité et identifiants du client de l'API

Les clients API qui utilisent le lecteur YouTube intégré (y compris l'API YouTube IFrame Player) doivent fournir une identification via l'en-tête de requête HTTP Referer. Dans certains environnements, le navigateur définit automatiquement HTTP Referer. Les clients de l'API n'ont qu'à s'assurer qu'ils ne définissent pas Referrer-Policy de manière à supprimer la valeur Referer. YouTube recommande d'utiliser strict-origin-when-cross-origin Referrer-Policy, qui est déjà la valeur par défaut dans de nombreux navigateurs.

De même, si vous intégrez le lecteur YouTube dans une fenêtre créée à l'aide de JavaScript window.open, les clients API ne doivent pas utiliser la fonctionnalité noreferrer, qui supprime la valeur Referer.

Définir le Referer

Dans les environnements où HTTP Referer est vide par défaut et n'est pas défini automatiquement par le navigateur, les clients API doivent prendre des mesures pour fournir leur identité par d'autres moyens. Dans les intégrations WebView telles qu'une application mobile ou une application pour ordinateur, HTTP Referer est vide par défaut et Referer est généralement défini à l'aide de l'une des techniques suivantes :

  • Application mobile avec lecteur intégré dans un fichier HTML local

    Dans cette configuration, le lecteur est chargé dans un fichier HTML fourni avec l'application. Lorsque ce fichier HTML est chargé, la définition du paramètre baseUrl définit Referer.

  • Application mobile sans fichier HTML local

    Dans cette configuration, le lecteur est chargé directement à partir de https://www.youtube.com/embed/VIDEO_ID sans fichier HTML d'encapsulation. Vous définissez Referer en l'ajoutant en tant qu'en-tête HTTP :

    • Android loadUrl avec l'en-tête HTTP Referer ajouté au paramètre additionalHttpHeaders

    • iOS loadRequest: avec l'en-tête HTTP Referer ajouté à la requête. Exemple :

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

  • Application mobile avec lecteur dans un onglet de navigateur natif

    • Android CustomTabs

      Utilisez Intent.EXTRA_REFERRER pour définir le site référent. Veillez à utiliser le schéma android-app:// au lieu de https:// lorsque vous créez le Uri. Exemple :

      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 n'est pas compatible avec la définition de Referer. Dans ce cas, définissez plutôt le paramètre du lecteur origin.

  • Application pour ordinateur

    Dans cette configuration, définissez Referer en l'ajoutant en tant qu'en-tête HTTP :

Pour les autres plates-formes où HTTP Referer est vide par défaut, définissez la valeur Referer en configurant la WebView dans laquelle le lecteur est chargé. La technique exacte peut varier selon la plate-forme.

Si vous êtes le propriétaire d'une bibliothèque, d'un framework, d'un plug-in, d'un service ou d'un wrapper utilisé par les développeurs pour intégrer le lecteur YouTube intégré, vous devez récupérer l'ID de l'application à partir de l'environnement (cela peut ne pas être possible, selon la plate-forme) ou autoriser les développeurs à transmettre leur ID d'application afin que Referer (et le paramètre du lecteur widget_referrer, le cas échéant) puisse être défini comme décrit ci-dessus.

Format du referrer

Lorsque vous fournissez explicitement le référent en définissant un paramètre WebView ou en ajoutant un en-tête HTTP, le format est généralement une URL complète. Spécifiez HTTPS comme protocole. Dans l'URL, le nom de domaine doit correspondre à l'identifiant de votre application ("ID d'application") enregistré auprès de la plate-forme qui a distribué votre application aux utilisateurs finaux. Si votre application est fournie aux utilisateurs par le biais d'un autre canal de distribution, utilisez l'ID d'application enregistré auprès du système d'exploitation lors de l'installation de l'application. Dans la plupart des cas, votre ID d'application sera un nom de domaine inversé (également appelé "format DNS inversé"), comme com.google.android.youtube. Exemples représentatifs :

Sur certaines plates-formes, l'ID de l'application n'est pas un nom de domaine inversé. Dans ce cas, utilisez l'ID unique de l'application attribué par la plate-forme qui la distribue. Lorsque l'ID de la plate-forme est une chaîne alphanumérique générée (attribuée par la plate-forme ou les outils de développement, et non choisie par le développeur de l'application), incluez à la fois le nom à afficher de l'application (en remplaçant les espaces par des tirets) et l'ID de la plate-forme, séparés par un point. Exemple : <my-app-name>.<AppID>. Cette valeur doit rester stable lorsque la version de l'application change. Si l'application n'est pas hébergée sur une plate-forme de téléchargement, utilisez l'ID d'application enregistré auprès du système d'exploitation lors de l'installation de l'application. Il s'agit généralement d'un identifiant unique dans le fichier manifeste de l'application. N'incluez aucun détail sur la version de l'application ni sur l'architecture compatible. Exemples représentatifs :

  • Chrome Web Store : hébergé sur le Store

    L'ID de l'application sur la plate-forme de téléchargement correspond généralement à la dernière partie du chemin d'accès dans l'URL de l'application https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID>. Utilisez le nom de l'application avec des tirets et l'ID de l'application sur la plate-forme pour créer la chaîne <my-app-name>.<AppID> décrite ci-dessus.

  • Windows : hébergé dans le Store

    L'ID de l'application sur la plate-forme de téléchargement correspond généralement à la dernière partie du chemin d'accès dans l'URL de l'application https://apps.microsoft.com/detail/<AppID>. Utilisez l'ID de l'application sur le Play Store pour créer la chaîne <my-app-name>.<AppID> décrite ci-dessus. Le nom de l'application avec tiret doit également être inclus.

  • Windows : distribution hors du Microsoft Store

    Les applications Windows contiennent une identité de package dans le fichier manifeste de l'application : Name_Version_Architecture_ResourceID_PublisherID. Utilisez uniquement l'attribut Name.

  • Xbox : hébergé sur le Store

    L'ID de l'application sur la plate-forme de téléchargement correspond généralement à la dernière partie du chemin d'accès dans l'URL de l'application https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID>. Utilisez le nom de l'application avec des tirets et l'ID de l'application sur la plate-forme pour créer la chaîne <my-app-name>.<AppID> décrite ci-dessus.

Pour les clients API qui envoient un grand nombre de requêtes à YouTube (voir Utilisation et quotas), des identifiants supplémentaires peuvent être nécessaires pour accéder au lecteur YouTube intégré.

Le non-respect de ces exigences peut entraîner une réduction des fonctionnalités du lecteur YouTube intégré.

Type de WebView

Lorsque vous intégrez le lecteur YouTube dans une WebView, utilisez l'un des types WebView fournis par l'OS, le cas échéant. Exemple :

Taille du lecteur YouTube intégré

La taille de la fenêtre d'affichage des lecteurs intégrés doit être de 200 x 200 pixels minimum. Si les commandes sont définies pour s'afficher, le lecteur doit être assez grand pour les afficher sans réduire la fenêtre d'affichage en deçà de sa taille minimale. Les dimensions recommandées des lecteurs 16:9 sont de 480 pixels de large et de 270 pixels de haut.

Lecture automatique et lectures avec script

Cette section traite des lectures automatiques. Il s'applique aux lecteurs YouTube intégrés qui utilisent le paramètre de lecteur autoplay ou qui lancent la lecture automatique de manière programmatique à l'aide du service de l'API YouTube IFrame Player ou d'un autre service de l'API YouTube.

  • Les lecteurs intégrés qui lancent automatiquement la lecture d'une vidéo doivent le faire immédiatement lorsque la page se charge ou dès que le lecteur intégré est entièrement visible. Toutefois, un client API ne doit pas lancer de lecture automatique tant que le lecteur n'est pas visible et que plus de la moitié du lecteur n'est pas visible sur la page ou l'écran.

  • Une page ou un écran ne doivent pas comporter plusieurs lecteurs YouTube qui lisent automatiquement du contenu simultanément.

  • Toute vignette YouTube qui lance la lecture d'une vidéo doit mesurer au moins 120 pixels de large et 70 pixels de haut.

Attributs du lecteur YouTube

Les attributs et les paramètres du lecteur YouTube (y compris, par exemple, l'apparence de la marque YouTube dans le lecteur) sont spécifiés dans la documentation et les spécifications de l'API YouTube (https://developers.google.com/youtube). Vous ne devez pas apporter au lecteur YouTube des modifications qui ne sont pas explicitement décrites dans la documentation de l'API.

Superpositions et cadres

Vous ne devez pas afficher de calques, de cadres ni d'autres éléments visuels devant une partie d'un lecteur YouTube intégré, y compris les commandes du lecteur. De même, vous ne devez pas utiliser de calques, de cadres ni d'autres éléments visuels pour masquer une partie d'un lecteur intégré, y compris les commandes du lecteur.

Survols

Vous ne devez pas utiliser de pointeurs de souris ni d'événements tactiles sur un lecteur YouTube pour initier une action au nom de l'utilisateur, comme ouvrir une fenêtre ou s'abonner à une chaîne.

Mettre en ligne des vidéos

Si les clients API permettent aux utilisateurs d'importer du contenu sur plusieurs plates-formes, ils doivent pouvoir sélectionner et désélectionner les plates-formes sur lesquelles ils souhaitent importer leurs vidéos.

Exigences en matière de données

Les clients API qui permettent aux utilisateurs de mettre en ligne des vidéos sur YouTube doivent leur permettre de définir les valeurs de la liste suivante. Toutes les propriétés qui ne sont pas listées sont facultatives.

  Nom Description
Propriétés des ressources
snippet.title Obligatoire. Titre de la vidéo. YouTube renvoie une erreur si la valeur dépasse 100 caractères. YouTube accepte tous les caractères UTF-8 valides, à l'exception de < et >.

snippet.description Obligatoire. Description de la vidéo. YouTube renvoie une erreur si la valeur dépasse 5 000 octets. YouTube accepte tous les caractères UTF-8 valides, à l'exception de < et >.
status.privacyStatus Obligatoire. les paramètres de confidentialité de la vidéo ; Les utilisateurs doivent pouvoir choisir si la vidéo mise en ligne sera publique, privée ou non répertoriée.
Paramètres de requête
onBehalfOfContentOwnerChannel Obligatoire sous certaines conditions. Si les identifiants d'autorisation de la requête identifient un propriétaire de contenu et que le paramètre onBehalfOfContentOwner est défini, l'utilisateur de l'API doit également pouvoir spécifier la chaîne YouTube sur laquelle la vidéo est mise en ligne.

Afficher les commentaires

  Nom Description
Propriétés des ressources
snippet.textDisplay Obligatoire. Texte du commentaire. Le client API doit (a) afficher le texte complet d'un commentaire ou d'une réponse à un commentaire, ou (b) tronquer le texte et permettre au lecteur d'accéder facilement au texte complet à partir de la version tronquée.

Cette exigence s'applique à tous les commentaires et réponses à des commentaires, quel que soit le type de ressource auquel les commentaires sont associés (vidéos, chaînes, etc.).

Notez que la valeur de la propriété snippet.topLevelComment de la ressource commentThread est une ressource comment et que la propriété replies.comments[] est une liste de ressources comment. Par conséquent, cette exigence s'applique également aux propriétés snippet.topLevelComment.snippet.textDisplay et replies.comments[].snippet.textDisplay.
snippet.title
(channel)		 Obligatoire (suggestion) : Titre de la chaîne.
  • Si le commentaire concerne une chaîne, le client API doit afficher le nom de la chaîne.
  • Si le commentaire concerne une vidéo, le client API doit afficher le nom de la chaîne qui l'a mise en ligne.
snippet.title
(video)		 Obligatoire sous certaines conditions (suggestion) Titre de la vidéo. Cette valeur doit être affichée si le commentaire concerne une vidéo.
snippet.moderationStatus Obligatoire sous certaines conditions. Si la valeur du paramètre moderationStatus dans la requête API est heldForReview ou likelySpam, l'affichage doit clairement identifier cet état à l'aide de la valeur de la propriété, d'une formulation similaire (par exemple, "Ce commentaire est en attente d'examen"), d'un en-tête (par exemple, "En attente d'examen") ou d'une autre formulation non ambiguë. La méthode commentThreads.list permet de récupérer les commentaires en fonction de leur état de modération.

Ajouter des commentaires

  Nom Description
Propriétés des ressources
snippet.title
(channel)		 Obligatoire. Titre de la chaîne.
  • Si l'utilisateur ajoute un commentaire sur une chaîne, le client de l'API doit afficher le nom de la chaîne.
  • Si l'utilisateur ajoute un commentaire sur une vidéo, le client API doit afficher le nom de la chaîne qui l'a mise en ligne.
snippet.title
(video)		 Obligatoire. Si l'utilisateur ajoute un commentaire sur une vidéo, le client API doit afficher le titre de la vidéo.
Autres exigences
Comment author's channel name Obligatoire. Le client API doit identifier clairement le compte utilisateur YouTube auquel le commentaire sera attribué. Si les identifiants d'autorisation de la requête identifient un propriétaire de contenu et que le paramètre onBehalfOfContentOwner est défini, l'utilisateur de l'API doit également pouvoir spécifier la chaîne YouTube à laquelle le commentaire sera attribué.

Ajouter des réponses aux commentaires

  Nom Description
Propriétés des ressources
snippet.textDisplay Obligatoire. Texte du commentaire. Le client API doit afficher le texte du commentaire auquel l'utilisateur répond, conformément aux règles définies dans la section Afficher les commentaires de ce document.
snippet.title
(channel)		 Obligatoire. Titre de la chaîne.
  • Si l'utilisateur répond à un commentaire sur une chaîne, le client API doit afficher le nom de la chaîne.
  • Si l'utilisateur répond à un commentaire sur une vidéo, le client API doit afficher le nom de la chaîne qui a mis en ligne la vidéo.
snippet.title
(video)		 Obligatoire. Si l'utilisateur répond à un commentaire sur une vidéo, le client API doit afficher le titre de la vidéo.
Autres exigences
Comment author's channel name Obligatoire. Le client API doit identifier clairement le compte utilisateur YouTube auquel la réponse au commentaire sera attribuée. Si les identifiants d'autorisation de la requête identifient un propriétaire de contenu et que le paramètre onBehalfOfContentOwner est défini, l'utilisateur de l'API doit également pouvoir spécifier la chaîne YouTube à laquelle la réponse au commentaire sera attribuée.

Modifier ou supprimer des réponses à des commentaires

  Nom Description
Propriétés des ressources
snippet.textDisplay Obligatoire. Texte du commentaire. Le client de l'API doit afficher le texte du commentaire que l'utilisateur modifie ou supprime, conformément aux règles définies dans la section Afficher les commentaires de ce document.
snippet.title
(channel)		 Obligatoire. Titre de la chaîne.
  • Si l'utilisateur modifie ou supprime un commentaire sur une chaîne, le client API doit afficher le nom de la chaîne.
  • Si l'utilisateur modifie ou supprime un commentaire sur une vidéo, le client API doit afficher le nom de la chaîne qui a mis en ligne la vidéo.
snippet.title
(video)		 Obligatoire. Si l'utilisateur modifie ou supprime un commentaire sur une vidéo, le client API doit afficher le titre de la vidéo.
Autres exigences
Comment author's channel name Obligatoire. Le client API doit identifier clairement le compte utilisateur YouTube auquel le commentaire est attribué.

Exclure un utilisateur du chat en direct (ou lever une exclusion)

  Nom Description
Propriétés des ressources
snippet.title
(channel)		 Obligatoire. Nom de la chaîne YouTube qui est suspendue ou rétablie. De plus, le nom doit être associé à la chaîne ou l'URL de la chaîne doit également être affichée.
Autres exigences
Nom de la chaîne de l'auteur du commentaire Obligatoire. Le client API doit identifier clairement le compte utilisateur YouTube utilisé pour ajouter ou supprimer l'exclusion.