1. Informações gerais
Este codelab descreve como criar um app receptor personalizado da Web que usa a API Cast Ad Breaks.
O que é o Google Cast?
O Google Cast permite que os usuários transmitam conteúdo de um dispositivo móvel para uma TV. O dispositivo poderá ser usado como controle remoto para a reprodução de mídia na TV.
O SDK do Google Cast amplia seu app para controlar uma TV ou um sistema de som. Com ele, você pode adicionar os componentes de IU necessários de acordo com a Lista de verificação de design do Google Cast.
Essa lista é fornecida para padronizar as implementações do Google Cast e tornar as experiências do usuário intuitivas em todas as plataformas compatíveis.
O que vamos criar?
Ao concluir este codelab, você terá criado um Cast Receiver que aproveita a API Break.
Conteúdo
- Como incluir intervalos VMAP e VAST no conteúdo para transmissão
- Como pular clipes de intervalo
- Como personalizar o comportamento de quebra padrão na busca
Pré-requisitos
- A versão mais recente do navegador Google Chrome.
- Serviço de hospedagem HTTPS, como o Firebase Hosting ou o ngrok.
- Um dispositivo com Google Cast, como um Chromecast ou Android TV, configurado com acesso à Internet.
- Uma TV ou um monitor com entrada HDMI ou um Google Home Hub
Experiência
Confira se você já tem a experiência abaixo antes de continuar este codelab.
- Conhecimento geral em desenvolvimento da Web.
- Como criar aplicativos de receptor da Web do Google Cast.
Como você usará este tutorial?
Como você classificaria sua experiência com a criação de apps da Web?
2. Acessar o exemplo de código
Faça o download de todo o exemplo de código para seu computador...
e descompactar o arquivo ZIP salvo.
3. Implantar o receptor localmente
Para usar seu receptor da Web com um dispositivo de transmissão, ele precisa estar hospedado em um lugar onde o dispositivo de transmissão possa alcançá-lo. Se você já tem um servidor compatível com HTTPS disponível, pule as instruções a seguir e anote o URL, porque você precisará dele na próxima seção.
Se você não tiver um servidor disponível, use o Firebase Hosting ou o ngrok.
Executar o servidor
Depois de configurar o serviço de sua preferência, acesse app-start e inicie o servidor.
Anote o URL do seu receptor hospedado. Ele será usado na próxima seção.
4. Registrar um aplicativo no Console para desenvolvedores do Google Cast
Você precisa registrar seu aplicativo para executar um receptor personalizado, conforme integrado neste codelab, em dispositivos Chromecast. Depois de registrar seu aplicativo, um ID de aplicativo será gerado e o aplicativo Remetente precisa ser configurado para iniciar o aplicativo Receptor da Web.
Clique em "Adicionar novo aplicativo"
Selecione "Custom Receiver". É isso que estamos criando.
Insira os detalhes do novo destinatário. Use o URL que aponta para o local onde você planeja hospedar seu aplicativo de receptor da Web. Anote o ID do aplicativo gerado pelo console assim que registrar o aplicativo. O app remetente será configurado para usar esse identificador em uma seção posterior.
Você também precisa registrar um dispositivo com Google Cast para que ele possa acessar o aplicativo receptor antes de você publicá-lo. Assim que você publicar o aplicativo receptor, ele ficará disponível para todos os dispositivos com Google Cast. Para os fins deste codelab, é recomendável trabalhar com um aplicativo receptor não publicado.
Clique em "Adicionar novo dispositivo"
Insira o número de série impresso na parte de trás do seu dispositivo de transmissão e dê um nome descritivo a ele. Você também pode encontrar o número de série transmitindo a tela no Chrome ao acessar o Console para desenvolvedores do SDK do Google Cast.
Leva de 5 a 15 minutos para que o receptor e o dispositivo estejam prontos para o teste. Após esse período, reinicie o dispositivo de transmissão.
5. Preparar o projeto inicial
Antes de iniciar este codelab, leia o guia para desenvolvedores de anúncios, que oferece uma visão geral das APIs de intervalos de anúncio.
O suporte para Google Cast precisa ser adicionado ao app inicial que você transferiu por download. Veja aqui a terminologia do Google Cast usada neste codelab:
- Um app remetente é executado em um dispositivo móvel ou laptop.
- Um aplicativo receptor é executado no dispositivo com Google Cast.
Agora está tudo pronto para criar com base no projeto inicial usando seu editor de texto favorito:
- Selecione o diretório
app-startno download do exemplo de código. - Abra
js/receiver.jse index.html
Enquanto você trabalha neste codelab, a solução de hospedagem na Web escolhida precisa ser atualizada com as mudanças feitas. Verifique se você está enviando as alterações para o site do host ao continuar a validá-las e testá-las.
Design de apps
Como mencionado, este codelab usa um aplicativo remetente para iniciar uma sessão de transmissão e um aplicativo receptor que vai ser modificado para usar as APIs de intervalo de anúncio.
Neste codelab, a Ferramenta de transmissão e comando vai atuar como o Web Sender para iniciar o app receptor. Para começar, abra a ferramenta em um navegador Chrome. Digite o ID do app receptor que você recebeu no Play Console do SDK do Cast e clique em Definir para configurar o app remetente para teste.
Observação: se você perceber que o ícone de transmissão não aparece, verifique se o receptor da Web e os dispositivos de transmissão estão registrados corretamente no Console para desenvolvedores do Google Cast. Reinicie todos os dispositivos de transmissão recém-registrados, caso ainda não tenha feito isso.
O app receptor é o foco principal deste codelab e consiste em uma visualização principal definida no index.html e um arquivo JavaScript chamado js/receiver.js. Eles são descritos abaixo.
index.html
Esse arquivo HTML contém a IU do nosso app receptor fornecida pelo elemento cast-media-player. Ele também carrega as bibliotecas do SDK do CAF e do Cast Debug Logger.
receiver.js
Esse script gerencia toda a lógica do nosso app receptor. No momento, ele contém um receptor CAF básico para inicializar o contexto de transmissão e carregar um recurso de vídeo na inicialização. Alguns recursos de geração de registros de depuração também foram adicionados para fornecer registro de volta à ferramenta Cast e Command.
6. Adicione VMAP ao seu conteúdo
O SDK do receptor da Web do Cast oferece suporte para anúncios especificados por playlists de vários anúncios em vídeo digital, também conhecidas como VMAP. A estrutura XML especifica os intervalos de anúncio de uma mídia e os metadados de clipe de intervalo associados. Para inserir esses anúncios, o SDK fornece a propriedade vmapAdsRequest no objeto MediaInformation.
No arquivo js/receiver.js, crie um objeto VastAdsRequest. Localize a função LOAD request interceptor e substitua-a pelo código a seguir. Ele contém uma amostra de URL de tag VMAP da DoubleClick e fornece um valor de correlator aleatório para garantir que as solicitações subsequentes ao mesmo URL gerem um modelo XML com intervalos de anúncio que ainda não foram assistidos.
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');
// Create the VMAP Ads request data and append it to the MediaInformation.
const vmapUrl =
'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
Math.floor(Math.random() * Math.pow(10, 10));
let vmapRequest = new cast.framework.messages.VastAdsRequest();
vmapRequest.adTagUrl = vmapUrl;
loadRequestData.media.vmapAdsRequest = vmapRequest;
castDebugLogger.warn(
'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);
return loadRequestData;
});
Salve as alterações em js/receiver.js e faça o upload do arquivo no seu servidor da Web. Inicie uma sessão do Google Cast na Ferramenta de transmissão e comando clicando no ícone do Google Cast. Os anúncios VMAP serão reproduzidos, seguidos pelo conteúdo principal.
7. Adicionar o VAST ao seu conteúdo
Como mencionado anteriormente, o SDK do receptor da Web é compatível com muitos tipos de anúncios. Esta seção destaca as APIs disponíveis para integrar anúncios de modelo de veiculação de anúncio em vídeo digital, também conhecidos como VAST. Se você implementou o código VMAP da seção anterior, comente-o.
Copie o seguinte no arquivo js/receiver.js depois do interceptador de solicitação de carregamento. Ele contém seis clipes de quebra VAST da DoubleClick e um valor de correlator aleatório. Esses clipes de intervalo são atribuídos a cinco intervalos. O position de cada intervalo é definido como um tempo em segundos em relação ao conteúdo principal, incluindo intervalos de anúncio precedente (position definido como 0) e final (position definido como -1).
const addVASTBreaksToMedia = (mediaInformation) => {
mediaInformation.breakClips = [
{
id: 'bc1',
title: 'bc1 (Pre-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('preroll')
}
},
{
id: 'bc2',
title: 'bc2 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc3',
title: 'bc3 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc4',
title: 'bc4 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc5',
title: 'bc5 (Mid-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('midroll')
}
},
{
id: 'bc6',
title: 'bc6 (Post-roll)',
vastAdsRequest: {
adTagUrl: generateVastUrl('postroll')
}
}
];
mediaInformation.breaks = [
{id: 'b1', breakClipIds: ['bc1'], position: 0},
{id: 'b2', breakClipIds: ['bc2'], position: 15},
{id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
{id: 'b4', breakClipIds: ['bc5'], position: 100},
{id: 'b5', breakClipIds: ['bc6'], position: -1}
];
};
Observação:a propriedade breakClipIds de uma pausa é uma matriz, o que significa que vários clipes de intervalo podem ser atribuídos a cada intervalo.
No js/receiver.js file, localize o interceptador de mensagens LOAD e substitua-o pelo código a seguir. O trabalho VMAP é comentado para exibir anúncios de tipo VAST.
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');
// Create the VMAP Ads request data and append it to the MediaInformation.
// const vmapUrl =
// 'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
// Math.floor(Math.random() * Math.pow(10, 10));
// let vmapRequest = new cast.framework.messages.VastAdsRequest();
// vmapRequest.adTagUrl = vmapUrl;
// loadRequestData.media.vmapAdsRequest = vmapRequest;
// Append VAST ad breaks to the MediaInformation.
addVASTBreaksToMedia(loadRequestData.media);
castDebugLogger.warn(
'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);
return loadRequestData;
});
Salve as alterações em js/receiver.js e faça o upload do arquivo no seu servidor da Web. Inicie uma sessão do Google Cast na Ferramenta de transmissão e comando clicando no ícone do Google Cast. Os anúncios VAST devem ser reproduzidos, seguidos pelo conteúdo principal.
8. Ignorando intervalos de anúncio
O CAF tem uma classe chamada BreakManager, que ajuda você a implementar regras de negócios personalizadas para comportamentos de anúncios. Um desses recursos permite que os aplicativos pulem intervalos e quebrem clipes de forma programática com base em alguma condição. Este exemplo mostra como pular um intervalo de anúncio cuja posição está nos primeiros 30 segundos do conteúdo, mas não os intervalos finais. Ao usar os anúncios VAST configurados na seção anterior, há cinco intervalos definidos: um precedente, três intermediário (15, 60 e 100 segundos) e, por fim, um final. Depois de concluir as etapas, somente o anúncio precedente e intermediário com posição de 15 segundos serão ignorados.
Para fazer isso, o aplicativo precisa chamar as APIs disponíveis pelo BreakManager e definir um interceptador para interromper o carregamento. Copie a linha abaixo no arquivo js/receiver.js, após as linhas que contêm as variáveis context e playerManager para acessar uma referência à instância.
const breakManager = playerManager.getBreakManager();
O app precisa configurar um interceptador com uma regra para ignorar os intervalos de anúncio que ocorrem antes de 30 segundos, sem esquecer dos intervalos finais (já que os valores de position são -1). Esse interceptador funciona como o interceptador LOAD em PlayerManager, exceto que é específico para clipes de intervalos de carregamento. Defina após o interceptador de solicitações LOAD e antes da declaração da função addVASTBreaksToMedia.
Copie as seguintes informações no arquivo js/receiver.js:
breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
/**
* The code will skip playback of break clips if the break position is within
* the first 30 seconds.
*/
let breakObj = breakContext.break;
if (breakObj.position >= 0 && breakObj.position < 30) {
castDebugLogger.debug(
'MyAPP.LOG',
'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
return null;
} else {
return breakClip;
}
});
Observação:retornar null aqui ignora o BreakClip que está sendo processado. Se um Break não tiver clipes de interrupção definidos, a pausa em si será ignorada.
Salve as alterações em js/receiver.js e faça o upload do arquivo no seu servidor da Web. Inicie uma sessão do Google Cast na Ferramenta de transmissão e comando clicando no ícone do Google Cast. Os anúncios VAST devem ser processados. Os anúncios precedentes e intermediários (cujo position é de 15 segundos) não são reproduzidos.
9. Personalizar o comportamento de busca de intervalo
Ao buscar intervalos passados, a implementação padrão extrai todos os itens Break que estiverem na posição entre os valores seekFrom e seekTo da operação de busca. Nessa lista de intervalos, o SDK reproduz a Break em que o position está mais próximo do valor seekTo e a propriedade isWatched está definida como false. A propriedade isWatched desse intervalo é definida como true, e o jogador começa a reproduzir os clipes de intervalo. Quando o intervalo é assistido, o conteúdo principal retoma a reprodução na posição seekTo. Se essa pausa não existir, nenhuma interrupção será reproduzida, e a reprodução do conteúdo principal será retomada na posição seekTo.
Para personalizar quais interrupções de reprodução em uma busca, o SDK do Cast fornece a API setBreakSeekInterceptor em BreakManager. Quando um aplicativo fornece sua lógica personalizada por essa API, o SDK a chama sempre que uma operação de busca é realizada em uma ou mais quebras. A função de callback recebe um objeto que contém todos os intervalos entre as posições seekFrom e seekTo. O aplicativo precisará modificar e retornar o BreakSeekData.
Para mostrar seu uso, o exemplo abaixo substitui o comportamento padrão ocupando todos os intervalos que foram buscados e reproduzindo somente o primeiro que aparece na linha do tempo.
Copie o seguinte no seu arquivo js/receiver.js, na definição para o setBreakClipLoadInterceptor.
breakManager.setBreakSeekInterceptor((breakSeekData) => {
/**
* The code will play an unwatched break between the seekFrom and seekTo
* position. Note: If the position of a break is less than 30 then it will be
* skipped due to the setBreakClipLoadInterceptor code.
*/
castDebugLogger.debug(
'MyAPP.LOG',
'Break Seek Interceptor processing break ids ' +
JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));
// Remove all other breaks except for the first one.
breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
return breakSeekData;
});
Observação:se a função não retornar um valor ou se retornar null, nenhum intervalo será reproduzido.
Salve as alterações em js/receiver.js e faça o upload do arquivo no seu servidor da Web. Inicie uma sessão do Google Cast na Ferramenta de transmissão e comando clicando no ícone do Google Cast. Os anúncios VAST devem ser processados. Os anúncios precedentes e intermediários (cujo position é de 15 segundos) não são reproduzidos.
Aguarde o tempo de reprodução atingir 30 segundos para passar de todos os intervalos ignorados pelo interceptador de carga do clipe de intervalo. Quando chegar, envie um comando de busca navegando até a guia Controle de mídia. Preencha a entrada Seek Into Media com 300 segundos e clique no botão TO. Observe os registros mostrados no interceptador de busca de quebra. O comportamento padrão agora precisa ser substituído para reproduzir a pausa mais perto do tempo de seekFrom
10. Parabéns
Agora você já sabe como adicionar anúncios ao seu app receptor usando o SDK do receptor do Google Cast mais recente.
Para mais detalhes, consulte o Guia para desenvolvedores sobre intervalos de anúncio.