Servizi API di YouTube - Funzionalità minima obbligatoria

Nota:il rispetto delle norme per gli sviluppatori di YouTube fornisce indicazioni ed esempi per aiutarti a garantire che i tuoi client API seguano sezioni specifiche dei Termini e delle Norme dei servizi API di YouTube (TOS API). La guida offre informazioni su come YouTube applica determinati aspetti dei TdS dell'API, ma non sostituisce alcun documento esistente.

Questo documento definisce i requisiti funzionali minimi per i client API che implementano o forniscono l'accesso a funzionalità specifiche dei servizi API di YouTube ("client API").

Questi requisiti e linee guida garantiscono che i client API offrano un'esperienza utente coerente che protegga gli interessi di utenti, proprietari dei contenuti e inserzionisti di YouTube. Queste regole sono parte integrante dei Termini di servizio delle API di YouTube e devono essere seguite nello sviluppo e nell'implementazione di qualsiasi client API.

I requisiti descritti in questo documento sono soggetti a modifiche per garantire un'esperienza utente migliore con le funzionalità di YouTube esistenti. Inoltre, cambieranno in risposta alle funzionalità nuove e aggiornate di YouTube. A volte, queste modifiche potrebbero richiedere l'aggiornamento dei client API per soddisfare i nuovi requisiti. La cronologia delle revisioni dei Termini di servizio documenterà eventuali modifiche, pertanto ti invitiamo a consultare spesso questo documento o a iscriverti al relativo feed RSS per essere informato rapidamente delle modifiche che potrebbero influire sui tuoi client API.

Oltre ai requisiti descritti in questo documento, ti consigliamo vivamente di seguire le best practice descritte nelle norme dei servizi API di YouTube e discusse altrove nella documentazione dei servizi API di YouTube. Anche se non strettamente necessarie, queste pratiche aiutano i client API a ripristinarsi più rapidamente in caso di errori e a ottimizzare l'utilizzo della quota se utilizzano servizi API di YouTube che allocano la quota. Allo stesso tempo, queste pratiche contribuiscono a garantire la salute dell'ecosistema di YouTube e, soprattutto, a offrire la migliore esperienza possibile agli utenti dei tuoi client API e delle applicazioni YouTube.

Player incorporato di YouTube e riproduzione video

I requisiti di questa sezione riguardano in modo specifico i player YouTube incorporati. Le Norme relative ai servizi API di YouTube includono anche diverse norme pertinenti ai client API che riproducono contenuti audiovisivi di YouTube.

Identità e credenziali del client API

I client API che utilizzano il player incorporato di YouTube (inclusa l'API YouTube IFrame Player) devono fornire l'identificazione tramite l'intestazione della richiesta HTTP Referer. In alcuni ambienti, il browser imposta automaticamente HTTP Referer e i client API devono solo assicurarsi di non impostare Referrer-Policy in modo da eliminare il valore Referer. YouTube consiglia di utilizzare strict-origin-when-cross-origin Referrer-Policy, che è già l'impostazione predefinita in molti browser.

Allo stesso modo, se si integra il player YouTube incorporato in una finestra creata utilizzando JavaScript window.open, i client API non devono utilizzare la funzionalità noreferrer, che elimina il valore Referer.

Imposta il referrer

Negli ambienti in cui HTTP Referer è vuoto per impostazione predefinita e non viene impostato automaticamente dal browser, i client API devono intervenire per fornire la propria identità con mezzi alternativi. Nelle integrazioni WebView, come un'app mobile o un'app desktop, HTTP Referer è vuoto per impostazione predefinita e Referer viene in genere impostato utilizzando una di queste tecniche:

  • App mobile con il player all'interno di un file HTML locale

    In questa configurazione, il player viene caricato in un file HTML incluso nel bundle dell'app. Quando carichi questo file HTML, l'impostazione del parametro baseUrl imposta Referer.

  • App mobile senza file HTML locale

    In questa configurazione, il player viene caricato direttamente da https://www.youtube.com/embed/VIDEO_ID senza alcun file HTML di inclusione. Imposta Referer aggiungendolo come intestazione HTTP:

    • Android loadUrl con l'intestazione HTTP Referer aggiunta al parametro additionalHttpHeaders

    • iOS loadRequest: con l'intestazione HTTP Referer aggiunta alla richiesta. Ad esempio:

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

  • App mobile con il player all'interno di una scheda del browser nativa

    • Android CustomTabs

      Utilizza Intent.EXTRA_REFERRER per impostare il referrer. Assicurati di utilizzare lo schema android-app:// anziché https:// quando crei Uri. Ad esempio:

      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 non supporta l'impostazione di Referer. In questo caso, imposta il parametro del player origin.

  • App per computer

    In questa configurazione, imposta Referer aggiungendolo come intestazione HTTP:

Per le altre piattaforme in cui HTTP Referer è vuoto per impostazione predefinita, imposta il valore di Referer configurando la WebView in cui viene caricato il player. La tecnica esatta può variare in base alla piattaforma.

Se sei il proprietario di una libreria, un framework, un plug-in, un servizio o un wrapper utilizzato dagli sviluppatori per integrare il player incorporato di YouTube, devi recuperare l'ID app dall'ambiente (potrebbe non essere possibile, a seconda della piattaforma) o consentire agli sviluppatori di inserire il proprio ID app in modo che Referer (e il parametro del player widget_referrer, se appropriato) possa essere impostato come descritto sopra.

Formato referrer

Quando fornisci esplicitamente il referrer impostando un parametro WebView o aggiungendo un'intestazione HTTP, il formato è in genere un URL completo. Specifica HTTPS come protocollo. All'interno dell'URL, il nome di dominio deve essere l'identificatore dell'applicazione ("ID app") registrato nello store che ha distribuito l'app agli utenti finali. Se la tua app viene fornita agli utenti tramite un canale di distribuzione alternativo, utilizza l'ID app registrato con il sistema operativo durante l'installazione dell'app. Nella maggior parte dei casi, l'ID app sarà un nome di dominio invertito (noto anche come "formato DNS inverso"), ad esempio com.google.android.youtube. Esempi rappresentativi:

  • Sistema operativo Android e app per Android su ChromeOS: ID app
  • Piattaforme Apple, tra cui iOS, iPadOS, macOS: ID bundle
  • Samsung Tizen: ID app
  • Distribuzioni Linux:

Su alcune piattaforme, l'ID app non è un nome di dominio invertito. In questi casi, utilizza l'ID app univoco assegnato dallo store che distribuisce l'app. Quando l'ID app dello store è una stringa alfanumerica generata (assegnata dallo store o dagli strumenti di sviluppo, non scelta dallo sviluppatore dell'app), includi sia il nome visualizzato dell'app (sostituendo gli spazi con i trattini) sia l'ID app dello store, separati da un punto. Ad esempio: <my-app-name>.<AppID>. Questo valore deve rimanere stabile anche in caso di modifiche alla versione dell'app. Se l'app non è ospitata su uno store, utilizza l'ID app registrato con il sistema operativo durante l'installazione dell'app. In genere si tratta di un identificatore univoco nel manifest dell'app. Escludi tutti i dettagli sulla versione dell'app e sull'architettura supportata. Esempi rappresentativi:

  • Chrome Web Store: ospitato nello store

    L'ID app dello store è in genere l'ultima parte del percorso nell'URL dell'app https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID>. Utilizza il nome dell'app con il trattino e l'ID app dello store per creare la stringa <my-app-name>.<AppID> descritta sopra.

  • Windows: store-hosted

    L'ID app dello store è in genere l'ultima parte del percorso nell'URL dell'app https://apps.microsoft.com/detail/<AppID>. Utilizza l'ID app dello Store per creare la stringa <my-app-name>.<AppID> descritta sopra. Deve essere incluso anche il nome dell'app con il trattino.

  • Windows: distribuzione non dallo Store

    Le app per Windows contengono un'identità del pacchetto nel manifest dell'app: Name_Version_Architecture_ResourceID_PublisherID. Utilizza solo l'attributo Name.

  • Xbox: store-hosted

    L'ID app dello store è in genere l'ultima parte del percorso nell'URL dell'app https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID>. Utilizza il nome dell'app con il trattino e l'ID app dello store per creare la stringa <my-app-name>.<AppID> descritta sopra.

Per i client API con un numero elevato di richieste a YouTube (vedi Utilizzo e quote), potrebbero essere necessarie credenziali aggiuntive per accedere al player incorporato di YouTube.

Il mancato rispetto di questi requisiti potrebbe comportare una riduzione della funzionalità del player incorporato di YouTube.

Tipo di WebView

Quando integri il player incorporato di YouTube in una WebView, utilizza uno dei tipi di WebView forniti dal sistema operativo, se disponibili. Ad esempio:

Dimensioni del player YouTube incorporato

Per i player incorporati, la visualizzazione deve essere di almeno 200 px per 200 px. Nel caso in cui siano presenti i controlli, il player dovrà avere dimensioni tali da mostrare i controlli senza ridurre la visualizzazione al di sotto del valore minimo. I player in formato 16:9 devono avere una larghezza minima di 480 pixel e un'altezza minima di 270 pixel.

Riproduzione automatica e riproduzioni basate su script

Questa sezione riguarda le riproduzioni automatiche. Si applica ai player incorporati di YouTube che utilizzano il parametro del player autoplay o che avviano la riproduzione automatica in modo programmatico utilizzando il servizio API YouTube IFrame Player o un altro servizio API di YouTube.

  • I player incorporati che riproducono automaticamente un video devono avviare la riproduzione immediatamente al caricamento della pagina o non appena il player incorporato è completamente visibile. Tuttavia, un client API non deve avviare la riproduzione automatica finché il player non è visibile e più della metà del player non è visibile nella pagina o sullo schermo.

  • Una pagina o una schermata non deve avere più di un player YouTube che riproduce automaticamente i contenuti contemporaneamente.

  • Qualsiasi miniatura di YouTube che avvia la riproduzione deve avere una larghezza di almeno 120 pixel e un'altezza di 70 pixel.

Attributi del player di YouTube

Gli attributi e i parametri del player di YouTube, inclusa, ad esempio, la visualizzazione del brand YouTube nel player, sono specificati nella documentazione e nelle specifiche dell'API YouTube (https://developers.google.com/youtube). Non devi apportare modifiche al player YouTube che non siano descritte esplicitamente nella documentazione dell'API.

Overlay e cornici

Non devi mostrare overlay, frame o altri elementi visivi davanti a qualsiasi parte di un player incorporato di YouTube, inclusi i controlli del player. Allo stesso modo, non devi utilizzare overlay, frame o altri elementi visivi per oscurare qualsiasi parte di un player incorporato, inclusi i controlli del player.

Mouse-over

Non devi utilizzare i passaggi del mouse o gli eventi tocco su un player YouTube per avviare azioni per conto dell'utente, ad esempio aprire una finestra o iscriversi a un canale.

Caricamento dei video

Se i client API consentono agli utenti di caricare contenuti su più piattaforme, gli utenti devono essere in grado di selezionare e deselezionare le piattaforme su cui vogliono caricare i propri video.

Requisiti dei dati

I client API che consentono agli utenti di caricare video su YouTube devono consentire agli utenti di impostare i valori nell'elenco seguente. Tutte le proprietà non elencate sono facoltative.

  Nome Descrizione
Proprietà delle risorse
snippet.title Required. Il titolo del video. YouTube restituisce un errore se il valore supera i 100 caratteri. YouTube supporta tutti i caratteri UTF-8 validi, ad eccezione di < e >.

snippet.description Required. La descrizione del video. YouTube restituisce un errore se il valore supera i 5000 byte. YouTube supporta tutti i caratteri UTF-8 validi, ad eccezione di < e >.
status.privacyStatus Required. L'impostazione della privacy del video. Gli utenti devono poter scegliere se il video caricato sarà pubblico, privato o non in elenco.
Parametri di richiesta
onBehalfOfContentOwnerChannel Obbligatorio condizionalmente. Se le credenziali di autorizzazione della richiesta identificano un proprietario dei contenuti e il parametro onBehalfOfContentOwner è impostato, l'utente API deve anche essere in grado di specificare il canale YouTube su cui viene caricato il video.

Visualizzazione dei commenti

  Nome Descrizione
Proprietà delle risorse
snippet.textDisplay Required. Il testo del commento. Il client API deve (a) visualizzare il testo completo di un commento o di una risposta a un commento oppure (b) troncare il testo e fornire un modo per consentire allo spettatore di accedere facilmente al testo completo dalla versione troncata.

Questo requisito si applica a tutti i commenti e a tutte le risposte ai commenti, indipendentemente dal tipo di risorsa a cui sono associati (video, canali e così via).

Tieni presente che il valore della proprietà snippet.topLevelComment della risorsa commentThread è una risorsa comment e la proprietà replies.comments[] è un elenco di risorse comment. Pertanto, questo requisito si applica anche alle proprietà snippet.topLevelComment.snippet.textDisplay e replies.comments[].snippet.textDisplay.
snippet.title
(channel)		 Obbligatorio (suggerimento). Il titolo del canale.
  • Se il commento riguarda un canale, il client API deve visualizzare il nome del canale.
  • Se il commento riguarda un video, il client API deve mostrare il nome del canale che ha caricato il video.
snippet.title
(video)		 Obbligatorio con condizione (suggerimento). Il titolo del video. Questo valore deve essere visualizzato se il commento riguarda un video.
snippet.moderationStatus Obbligatorio condizionalmente. Se il valore del parametro moderationStatus nella richiesta API è heldForReview o likelySpam, la visualizzazione deve identificare chiaramente lo stato utilizzando il valore della proprietà, un linguaggio simile (ad es. "Questo commento è in attesa di revisione"), un'intestazione (ad es. "In attesa di revisione") o un altro linguaggio inequivocabile. Il metodo commentThreads.list supporta la possibilità di recuperare i commenti in base al loro stato di moderazione.

Aggiunta di commenti

  Nome Descrizione
Proprietà delle risorse
snippet.title
(channel)		 Required. Il titolo del canale.
  • Se l'utente aggiunge un commento su un canale, il client API deve visualizzare il nome del canale.
  • Se l'utente aggiunge un commento a un video, il client API deve visualizzare il nome del canale che ha caricato il video.
snippet.title
(video)		 Required. Se l'utente aggiunge un commento su un video, il client API deve visualizzare il titolo del video.
Altri requisiti
Comment author's channel name Required. Il client API deve identificare chiaramente l'account utente YouTube a cui verrà attribuito il commento. Se le credenziali di autorizzazione della richiesta identificano un proprietario dei contenuti e il parametro onBehalfOfContentOwner è impostato, l'utente API deve anche essere in grado di specificare il canale YouTube a cui verrà attribuito il commento.

Aggiunta di risposte ai commenti

  Nome Descrizione
Proprietà delle risorse
snippet.textDisplay Required. Il testo del commento. Il client API deve visualizzare il testo del commento a cui l'utente sta rispondendo in conformità alle regole definite nella sezione Visualizzazione dei commenti di questo documento.
snippet.title
(channel)		 Required. Il titolo del canale.
  • Se l'utente risponde a un commento su un canale, il client API deve visualizzare il nome del canale.
  • Se l'utente risponde a un commento su un video, il client API deve visualizzare il nome del canale che ha caricato il video.
snippet.title
(video)		 Required. Se l'utente risponde a un commento su un video, il client API deve visualizzare il titolo del video.
Altri requisiti
Comment author's channel name Required. Il client API deve identificare chiaramente l'account utente YouTube a cui verrà attribuita la risposta al commento. Se le credenziali di autorizzazione della richiesta identificano un proprietario dei contenuti e il parametro onBehalfOfContentOwner è impostato, l'utente API deve anche essere in grado di specificare il canale YouTube a cui verrà attribuita la risposta al commento.

Modificare o eliminare le risposte ai commenti

  Nome Descrizione
Proprietà delle risorse
snippet.textDisplay Required. Il testo del commento. Il client API deve visualizzare il testo del commento che l'utente sta modificando o eliminando in conformità alle regole definite nella sezione Visualizzazione dei commenti di questo documento.
snippet.title
(channel)		 Required. Il titolo del canale.
  • Se l'utente sta modificando o eliminando un commento su un canale, il client API deve visualizzare il nome del canale.
  • Se l'utente sta modificando o eliminando un commento su un video, il client API deve visualizzare il nome del canale che ha caricato il video.
snippet.title
(video)		 Required. Se l'utente sta modificando o eliminando un commento su un video, il client API deve visualizzare il titolo del video.
Altri requisiti
Comment author's channel name Required. Il client API deve identificare chiaramente l'account utente YouTube a cui è attribuito il commento.

Escludere un utente dalla chat live (o rimuovere un'esclusione)

  Nome Descrizione
Proprietà delle risorse
snippet.title
(channel)		 Required. Il nome del canale YouTube che viene sospeso o ripristinato. Inoltre, il nome deve rimandare al canale o deve essere visualizzato anche l'URL del canale.
Altri requisiti
Nome del canale dell'autore del commento Required. Il client API deve identificare chiaramente l'account utente YouTube utilizzato per aggiungere o rimuovere il ban.