Serviços da API do YouTube - Recursos mínimos obrigatórios

Observação:seguir as Políticas para desenvolvedores do YouTube oferece orientações e exemplos para ajudar você a garantir que seus clientes de API sigam partes específicas dos Termos e das Políticas dos serviços de API do YouTube (TOS da API). O guia oferece insights sobre como o YouTube aplica determinados aspectos dos Termos de Serviço da API, mas não substitui nenhum documento atual.

Este documento define os requisitos funcionais mínimos para clientes de API que implementam ou fornecem acesso a recursos específicos dos serviços de API do YouTube ("clientes de API").

Esses requisitos e diretrizes garantem que os clientes da API ofereçam uma experiência do usuário consistente que proteja os interesses dos usuários do YouTube, dos proprietários de conteúdo e dos anunciantes. Essas regras são parte integrante dos Termos de Serviço da API do YouTube e precisam ser seguidas no desenvolvimento e na implementação de qualquer cliente de API.

Os requisitos neste documento podem mudar para garantir melhores experiências do usuário com os recursos atuais do YouTube. Elas também vão mudar em resposta a recursos novos e atualizados do YouTube. Às vezes, essas mudanças exigem que você atualize os clientes da API para atender a novos requisitos. O histórico de revisões dos Termos de Serviço documenta todas as mudanças. Portanto, consulte esse documento com frequência ou assine o feed RSS dele para saber rapidamente sobre as mudanças que podem afetar seus clientes de API.

Além dos requisitos deste documento, recomendamos seguir as práticas recomendadas descritas nas Políticas dos Serviços de API do YouTube e discutidas em outros lugares na documentação dos Serviços de API do YouTube. Mesmo quando não são estritamente necessárias, essas práticas ajudam os clientes de API a se recuperar mais rapidamente de erros e a otimizar o uso da cota se usarem serviços de API do YouTube que alocam cota. Ao mesmo tempo, essas práticas ajudam a garantir a integridade do ecossistema do YouTube e, acima de tudo, a oferecer a melhor experiência possível aos usuários dos seus clientes de API e dos aplicativos do YouTube.

Player incorporado do YouTube e reprodução de vídeo

Os requisitos nesta seção se referem especificamente aos players incorporados do YouTube. As políticas dos serviços de API do YouTube também incluem várias políticas relevantes para clientes de API que reproduzem conteúdo audiovisual do YouTube.

Identidade e credenciais do cliente da API

Os clientes de API que usam o player incorporado do YouTube (incluindo a API YouTube IFrame Player) precisam fornecer identificação pelo cabeçalho de solicitação HTTP Referer. Em alguns ambientes, o navegador define automaticamente HTTP Referer, e os clientes da API só precisam garantir que não estão definindo Referrer-Policy de uma forma que suprima o valor Referer. O YouTube recomenda usar strict-origin-when-cross-originReferrer-Policy, que já é o padrão em muitos navegadores.

Da mesma forma, ao integrar o player incorporado do YouTube em uma janela criada com JavaScript window.open, os clientes da API não podem usar o recurso noreferrer, que suprime o valor Referer.

Definir o referenciador

Em ambientes em que HTTP Referer está vazio por padrão e não é definido automaticamente pelo navegador, os clientes da API precisam tomar medidas para fornecer a identidade por outros meios. Em integrações do WebView, como um app para dispositivos móveis ou para computador, HTTP Referer fica vazio por padrão, e o Referer geralmente é definido usando uma destas técnicas:

• App para dispositivos móveis com um player dentro de um arquivo HTML local

  Nessa configuração, o player é carregado em um arquivo HTML agrupado com o app. Ao carregar esse arquivo HTML, definir o parâmetro baseUrl define o Referer.

  • Android loadDataWithBaseURL
  • iOS loadHTMLString:baseURL:

• App para dispositivos móveis sem arquivo HTML local

  Nessa configuração, o player é carregado diretamente de https://www.youtube.com/embed/VIDEO_ID sem um arquivo HTML de inclusão. Para definir o Referer, adicione-o como um cabeçalho HTTP:

  • Android loadUrl com o cabeçalho HTTP Referer adicionado ao parâmetro additionalHttpHeaders

  • iOS loadRequest: com o cabeçalho HTTP Referer adicionado à solicitação. Exemplo:

    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 para dispositivos móveis com um player em uma guia nativa do navegador

  • Android CustomTabs

    Use Intent.EXTRA_REFERRER para definir o referenciador. Use o esquema android-app:// em vez de https:// ao criar o Uri. Exemplo:

    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

    O SFSafariViewController não aceita a definição do Referer. Nesse caso, defina o parâmetro do player origin.

• App para computador

  Nessa configuração, defina o Referer adicionando-o como um cabeçalho HTTP:

  • Microsoft .NET: use HttpRequestHeaders.Referrer ou CoreWebView2HttpRequestHeaders.SetHeader
  • macOS: siga as mesmas instruções descritas acima para apps móveis iOS.

Para outras plataformas em que HTTP Referer está vazio por padrão, defina o valor Referer configurando a WebView em que o player é carregado. A técnica exata pode variar de acordo com a plataforma.

Se você for o proprietário de uma biblioteca, estrutura, plug-in, serviço ou wrapper usado por desenvolvedores para integrar o player incorporado do YouTube, recupere o ID do app do ambiente (isso pode não ser possível, dependendo da plataforma) ou permita que os desenvolvedores transmitam o ID do app para que Referer (e o parâmetro do player widget_referrer, se apropriado) possa ser definido conforme descrito acima.

Formato do referenciador

Quando você fornece explicitamente o referenciador definindo um parâmetro WebView ou adicionando um cabeçalho HTTP, o formato geralmente é um URL totalmente qualificado. Especifique HTTPS como o protocolo. No URL, o nome de domínio precisa ser o identificador do aplicativo ("ID do app") registrado na loja que distribuiu o app para os usuários finais. Se o app for fornecido aos usuários por um canal de distribuição alternativo, use o ID registrado no sistema operacional durante a instalação. Na maioria dos casos, o ID do app é um nome de domínio invertido (também conhecido como "formato DNS reverso"), como com.google.android.youtube. Exemplos representativos:

• SO Android e apps Android no ChromeOS: ID do app
• Plataformas Apple, incluindo iOS, iPadOS e macOS: ID do pacote
• Samsung Tizen: ID do app
• Distribuições Linux:
  • Fedora: ID do app
  • Gnome: ID do app
  • Ubuntu: ID do app

Em algumas plataformas, o ID do app não é um nome de domínio invertido. Nesses casos, use o ID exclusivo do app atribuído pela loja que o distribui. Quando o ID do app da loja for uma string alfanumérica gerada (atribuída pela loja ou ferramentas de desenvolvimento, não escolhida pelo desenvolvedor do app), inclua o nome de exibição do app (substituindo espaços por hífens) e o ID do app da loja, delimitados por um ponto. Por exemplo, <my-app-name>.<AppID>. Esse valor precisa ser estável em todas as mudanças de versão do app. Se o app não estiver hospedado em uma loja, use o ID registrado no sistema operacional durante a instalação. Normalmente, esse é um identificador exclusivo no manifesto do app. Não inclua detalhes sobre a versão do app e a arquitetura compatível. Exemplos representativos:

• Chrome Web Store: hospedado na loja

  Normalmente, o ID do app na loja é a última parte do caminho no URL do app https://chromewebstore.google.com/detail/<hyphenated-app-name>/<AppID>. Use o nome do app com hífen e o ID do app da loja para criar a string <my-app-name>.<AppID> descrita acima.

• Windows: hospedado na loja

  Normalmente, o ID do app na loja é a última parte do caminho no URL do app https://apps.microsoft.com/detail/<AppID>. Use o ID do app da loja para criar a string <my-app-name>.<AppID> descrita acima. O nome do app com hífen também precisa ser incluído.

• Windows: distribuição fora da loja

  Os apps do Windows contêm uma identidade de pacote no manifesto do app: Name_Version_Architecture_ResourceID_PublisherID. Use apenas o atributo Name.

• Xbox: hospedado na loja

  Normalmente, o ID do app na loja é a última parte do caminho no URL do app https://www.xbox.com/<region>/games/store/<hyphenated-app-name>/<AppID>. Use o nome do app com hífen e o ID do app da loja para criar a string <my-app-name>.<AppID> descrita acima.

Para clientes de API com um grande número de solicitações ao YouTube (consulte Uso e cotas), talvez sejam necessárias credenciais adicionais para acessar o player incorporado do YouTube.

A não conformidade com esses requisitos pode resultar em funcionalidade reduzida no player incorporado do YouTube.

Tipo de WebView

Ao integrar o player incorporado do YouTube em uma WebView, use um dos tipos de WebView fornecidos pelo SO, quando disponível. Exemplo:

• SO Android: WebView ou CustomTabs
• Plataformas Apple, incluindo iOS, iPadOS e macOS: WKWebView ou SFSafariViewController

Tamanho do player incorporado do YouTube

É necessário que os players incorporados tenham uma Janela de visualização de pelo menos 200 px por 200 px. Se o player mostra controles, ele tem que ser grande o suficiente para exibir completamente os controles sem encolher a Janela visualização abaixo do tamanho mínimo. Recomendamos que players de 16:9 tenham pelo menos 480 pixels de largura e 270 pixels de altura.

Reprodução automática e com scripts

Esta seção aborda as reproduções automáticas. Ela se aplica a players incorporados do YouTube que usam o parâmetro do player autoplay ou iniciam a reprodução automática de forma programática usando o serviço da API IFrame Player do YouTube ou outro serviço da API do YouTube.

• Os players incorporados que reproduzem um vídeo automaticamente precisam iniciar a reprodução imediatamente quando a página é carregada ou assim que o player incorporado fica totalmente visível. No entanto, um cliente da API não pode iniciar uma reprodução automática até que o player esteja visível e mais da metade dele apareça na página ou tela.

• Uma página ou tela não pode ter mais de um player do YouTube que reproduza conteúdo automaticamente ao mesmo tempo.

• As miniaturas do YouTube que iniciam uma reprodução precisam ter pelo menos 120 pixels de largura e 70 pixels de altura.

Atributos do player do YouTube

Os atributos e parâmetros do player do YouTube, incluindo, por exemplo, a aparência da marca do YouTube no player, são especificados na documentação e nas especificações da API do YouTube (https://developers.google.com/youtube). Não faça mudanças no player do YouTube que não estejam explicitamente descritas na documentação da API.

Sobreposições e frames

Não é permitido mostrar sobreposições, frames ou outros elementos visuais na frente de qualquer parte de um player incorporado do YouTube, incluindo os controles do player. Da mesma forma, não use sobreposições, frames ou outros elementos visuais para ocultar qualquer parte de um player incorporado, incluindo os controles.

Movimentações do mouse

Não é permitido usar eventos de passar o cursor ou de toque em um player do YouTube para iniciar qualquer ação em nome do usuário, como abrir uma janela ou se inscrever em um canal.

Como enviar vídeos

Se os clientes de API permitirem que os usuários façam upload de conteúdo para várias plataformas, eles precisam poder selecionar e desmarcar as plataformas em que querem enviar os vídeos.

Requisitos de dados

Os clientes de API que permitem aos usuários enviar vídeos para o YouTube precisam permitir que os usuários definam os valores na lista a seguir. Todas as propriedades que não estão listadas são opcionais.

	Nome	Descrição
Propriedades de recursos
	snippet.title	Obrigatório. O título do vídeo. O YouTube retorna um erro se o valor exceder 100 caracteres. O YouTube aceita todos os caracteres UTF-8 válidos, exceto < e >.
	snippet.description	Obrigatório. A descrição do vídeo. O YouTube retorna um erro se o valor exceder 5.000 bytes. O YouTube aceita todos os caracteres UTF-8 válidos, exceto < e >.
	status.privacyStatus	Obrigatório. A configuração de privacidade do vídeo. Os usuários precisam poder escolher se o vídeo enviado será público, privado ou não listado.
Parâmetros de solicitação
	onBehalfOfContentOwnerChannel	Obrigatório sob certas condições. Se as credenciais de autorização da solicitação identificarem um proprietário de conteúdo e o parâmetro onBehalfOfContentOwner estiver definido, o usuário da API também precisará especificar o canal do YouTube em que o vídeo está sendo enviado.

Mostrando comentários

	Nome	Descrição
Propriedades de recursos
	snippet.textDisplay	Obrigatório. O texto do comentário. O cliente da API precisa (a) mostrar o texto completo de um comentário ou resposta a comentário ou (b) truncar o texto e oferecer uma maneira para o espectador acessar facilmente o texto completo na versão truncada. Esse requisito se aplica a todos os comentários e respostas a comentários, independente do tipo de recurso a que eles estão associados (vídeos, canais etc.). O valor da propriedade snippet.topLevelComment do recurso commentThread é um recurso comment, e a propriedade replies.comments[] é uma lista de recursos comment. Por isso, essa exigência também se aplica às propriedades snippet.topLevelComment.snippet.textDisplay e replies.comments[].snippet.textDisplay.
	snippet.title (channel)	Obrigatório (sugestão). O título do canal. Se o comentário for sobre um canal, o cliente da API vai mostrar o nome dele. Se o comentário for sobre um vídeo, o cliente da API vai mostrar o nome do canal que enviou o conteúdo.
	snippet.title (video)	Obrigatório sob certas condições (sugestão). O título do vídeo. Esse valor precisa ser mostrado se o comentário for sobre um vídeo.
	snippet.moderationStatus	Obrigatório sob certas condições. Se o valor do parâmetro moderationStatus na solicitação de API for heldForReview ou likelySpam, a exibição precisará identificar claramente esse status usando o valor da propriedade, uma linguagem semelhante (por exemplo, "Este comentário está sendo retido para revisão"), um cabeçalho (por exemplo, "Retido para revisão") ou outra linguagem inequívoca. O método commentThreads.list permite recuperar comentários com base no status de moderação.

Como adicionar comentários

	Nome	Descrição
Propriedades de recursos
	snippet.title (channel)	Obrigatório. O título do canal. Se o usuário estiver adicionando um comentário sobre um canal, o cliente da API precisará mostrar o nome dele. Se o usuário estiver adicionando um comentário sobre um vídeo, o cliente da API precisará mostrar o nome do canal que enviou o conteúdo.
	snippet.title (video)	Obrigatório. Se o usuário estiver adicionando um comentário sobre um vídeo, o cliente da API precisará mostrar o título dele.
Outros requisitos
	Comment author's channel name	Obrigatório. O cliente da API precisa identificar claramente a conta de usuário do YouTube a que o comentário será atribuído. Se as credenciais de autorização da solicitação identificarem um proprietário do conteúdo e o parâmetro onBehalfOfContentOwner estiver definido, o usuário da API também precisará especificar o canal do YouTube a que o comentário será atribuído.

Adicionar respostas a comentários

	Nome	Descrição
Propriedades de recursos
	snippet.textDisplay	Obrigatório. O texto do comentário. O cliente da API precisa mostrar o texto do comentário que o usuário está respondendo de acordo com as regras definidas na seção Exibição de comentários deste documento.
	snippet.title (channel)	Obrigatório. O título do canal. Se o usuário estiver respondendo a um comentário sobre um canal, o cliente da API precisará mostrar o nome do canal. Se o usuário estiver respondendo a um comentário sobre um vídeo, o cliente da API precisará mostrar o nome do canal que enviou o conteúdo.
	snippet.title (video)	Obrigatório. Se o usuário estiver respondendo a um comentário sobre um vídeo, o cliente da API precisará mostrar o título do vídeo.
Outros requisitos
	Comment author's channel name	Obrigatório. O cliente da API precisa identificar claramente a conta de usuário do YouTube a que a resposta do comentário será atribuída. Se as credenciais de autorização da solicitação identificarem um proprietário do conteúdo e o parâmetro onBehalfOfContentOwner estiver definido, o usuário da API também precisará especificar o canal do YouTube a que a resposta do comentário será atribuída.

Editar ou excluir respostas a comentários

	Nome	Descrição
Propriedades de recursos
	snippet.textDisplay	Obrigatório. O texto do comentário. O cliente da API precisa mostrar o texto do comentário que o usuário está editando ou excluindo de acordo com as regras definidas na seção Como mostrar comentários deste documento.
	snippet.title (channel)	Obrigatório. O título do canal. Se o usuário estiver editando ou excluindo um comentário sobre um canal, o cliente da API precisará mostrar o nome dele. Se o usuário estiver editando ou excluindo um comentário sobre um vídeo, o cliente da API precisará mostrar o nome do canal que enviou o conteúdo.
	snippet.title (video)	Obrigatório. Se o usuário estiver editando ou excluindo um comentário sobre um vídeo, o cliente da API precisará mostrar o título do vídeo.
Outros requisitos
	Comment author's channel name	Obrigatório. O cliente da API precisa identificar claramente a conta de usuário do YouTube a que o comentário é atribuído.

Banir um usuário do chat ao vivo (ou remover uma proibição)

	Nome	Descrição
Propriedades de recursos
	snippet.title (channel)	Obrigatório. O nome do canal do YouTube que está sendo banido ou liberado. Além disso, o nome precisa estar vinculado ao canal ou o URL do canal também precisa ser exibido.
Outros requisitos
	Nome do canal do autor do comentário	Obrigatório. O cliente da API precisa identificar claramente a conta de usuário do YouTube usada para adicionar ou remover a proibição.