1. Visão geral
Este codelab descreve como criar um app receptor da Web personalizado 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 o SDK do Cast, é possível adicionar os componentes de interface necessários com base na 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 usa a API Break.
O que você vai aprender
- Como incluir intervalos VMAP e VAST no conteúdo para transmissão
- Como pular clipes de pausa
- Como personalizar o comportamento padrão de intervalo na busca
O que é necessário
- 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
Verifique se você tem a seguinte experiência antes de continuar este codelab.
- Conhecimento geral sobre desenvolvimento da Web.
- Como criar aplicativos receptores 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. Fazer o download do 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 acessá-lo. Se você já tiver um servidor disponível compatível com https, ignore 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, poderá usar o Firebase Hosting ou o ngrok.
Executar o servidor
Depois de configurar o serviço de sua preferência, navegue até app-start e inicie seu servidor.
Anote o URL do seu receptor hospedado. Você vai usá-lo na próxima seção.
4. Registrar um aplicativo no Play Console do Google Cast
É necessário registrar seu app para executar um receptor personalizado, conforme integrado neste codelab, em dispositivos Chromecast. Depois de registrar seu aplicativo, será gerado um ID do aplicativo. Ele precisa ser configurado para iniciar o aplicativo receptor da Web.
Clique em "Adicionar novo aplicativo"
Selecione "Custom Receiver", que é o que estamos criando.
Digite os detalhes do novo destinatário. Use o URL que aponta para o local em que você planeja hospedar seu aplicativo receptor da Web. Anote o ID do aplicativo gerado pelo console depois de registrar o aplicativo. O aplicativo remetente será configurado para usar esse identificador em uma seção posterior.
Também é necessário registrar um dispositivo com Google Cast para que ele possa acessar o aplicativo receptor antes da publicação. Após a publicação do app receptor, ele vai 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. Também é possível encontrar o número de série ao transmitir a tela do Chrome ao acessar o Play Console do SDK do Google Cast.
Leva de 5 a 15 minutos para o receptor e o dispositivo ficarem prontos para o teste. Após esse período, reinicie o dispositivo de transmissão.
5. Prepare o projeto inicial
Antes de iniciar este codelab, consulte o guia para desenvolvedores de anúncios, que fornece uma visão geral das APIs de intervalo de anúncio.
A compatibilidade com o Google Cast precisa ser adicionada ao app inicial transferido por download. Veja alguns termos do Google Cast usados 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 você começar a 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
Durante este codelab, a solução de hospedagem na Web escolhida precisa ser atualizada com as mudanças. Verifique se você está enviando as mudanças ao site do host ao continuar a validá-las e testá-las.
Design do app
Como mencionado, o codelab usa um aplicativo remetente para iniciar uma sessão de transmissão e um aplicativo receptor que será modificado para usar as APIs de intervalo de anúncio.
Neste codelab, a ferramenta Transmitir e de comando vai atuar como o remetente da Web para iniciar o app receptor. Para começar, abra a ferramenta em um navegador Chrome. Insira o ID do app do receptor que você recebeu no Play Console do SDK do Google Cast e clique em Definir para configurar o app remetente para testes.
Observação: se você notar que o ícone de transmissão não é exibido, verifique se o receptor da Web e os dispositivos de transmissão estão registrados corretamente no Play Console do Google Cast. Se você ainda não tiver feito isso, reinicie os dispositivos de transmissão que acabaram de ser registrados.
O app receptor é o foco deste codelab e consiste em uma visualização principal definida em index.html e um arquivo JavaScript chamado js/receiver.js. Eles são descritos em mais detalhes abaixo.
index.html
Esse arquivo HTML contém a interface do 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 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 a geração de registros à ferramenta Cast e Comando.
6. Adicionar VMAP ao seu conteúdo
O SDK do receptor da Web do Google Cast é compatível com anúncios especificados nas playlists de vários anúncios digitais em vídeo, também conhecidas como VMAP. A estrutura XML especifica os intervalos de anúncio de uma mídia e os metadados de clipes 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 interceptador de solicitação LOAD e a substitua pelo código abaixo. Ela contém um exemplo de URL de tag VMAP da DoubleClick e um valor correlator aleatório para garantir que as solicitações subsequentes para o 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 mudanças no js/receiver.js e faça upload do arquivo no servidor da Web. Inicie uma sessão de transmissão na ferramenta Transmitir e de comando clicando no ícone Transmitir. Os anúncios VMAP devem ser 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 vários tipos de anúncios. Esta seção destaca as APIs disponíveis para integrar anúncios do 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, deixe um comentário.
Copie o seguinte no seu arquivo js/receiver.js após o interceptador da solicitação de carregamento. Ele contém seis clipes de intervalo VAST da DoubleClick e um valor correlator aleatório. Esses clipes 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úncios precedentes (position definido como 0) e finais (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. Isso 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 pelo código a seguir. O trabalho do VMAP é comentado para mostrar os anúncios do 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 mudanças no js/receiver.js e faça upload do arquivo no servidor da Web. Inicie uma sessão de transmissão na ferramenta Transmitir e de comando clicando no ícone Transmitir. Os anúncios VAST serão reproduzidos, seguidos pelo conteúdo principal.
8. Pular intervalo 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 programaticamente intervalos e quebrem clipes 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 nos intervalos de anúncios finais. Ao usar os anúncios VAST configurados na seção anterior, há cinco intervalos definidos: um intervalo de anúncio precedente, três intervalos de anúncios intermediários (aos 15, 60 e 100 segundos) e, por fim, um intervalo de anúncio final. Depois de concluir as etapas, somente o anúncio precedente e o anúncio intermediário com posição de 15 segundos serão pulados.
Para isso, o aplicativo precisa chamar APIs disponíveis pelo BreakManager para definir um interceptador para carregamento com interrupção. Copie a linha a seguir no arquivo js/receiver.js, depois das linhas que contêm as variáveis context e playerManager para acessar uma referência à instância.
const breakManager = playerManager.getBreakManager();
O aplicativo precisa configurar um interceptador com uma regra para ignorar os intervalos de anúncio que ocorram antes dos 30 segundos, considerando os intervalos de anúncios finais, já que os valores de position são -1. Esse interceptador funciona como o interceptador LOAD em PlayerManager, mas é específico para carregar clipes de pausa. Defina isso após o interceptador de solicitação 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 a BreakClip que está sendo processada. Se um Break não tiver clipes de intervalo definidos, o intervalo em si será ignorado.
Salve as mudanças no js/receiver.js e faça upload do arquivo no servidor da Web. Inicie uma sessão de transmissão na ferramenta Transmitir e de comando clicando no ícone Transmitir. Os anúncios VAST devem ser processados. Os anúncios precedentes e intermediários (cujo position tem 15 segundos) não são reproduzidos.
9. Personalizar o comportamento do intervalo
Ao procurar intervalos passados, a implementação padrão recebe todos os itens Break com posições 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 de seekTo e que tem a propriedade isWatched definida como false. A propriedade isWatched desse intervalo é definida como true, e o jogador começa a reproduzir os clipes de pausa. Quando o intervalo for assistido, o conteúdo principal será retomado da posição seekTo. Se esse intervalo não existir, nenhum intervalo será reproduzido e o conteúdo principal será retomado na posição seekTo.
Para personalizar quais intervalos são reproduzidos em uma busca, o SDK do Cast fornece a API setBreakSeekInterceptor em BreakManager. Quando um aplicativo fornece sua lógica personalizada por meio dessa API, o SDK a chama sempre que uma operação de busca é realizada em uma ou mais pausas. A função de callback recebe um objeto que contém todas as quebras entre as posições seekFrom e seekTo. Em seguida, o aplicativo precisa modificar e retornar BreakSeekData.
Para mostrar seu uso, o exemplo abaixo substitui o comportamento padrão, tomando todos os intervalos que foram procurados e reproduzindo apenas o primeiro que aparece na linha do tempo.
Copie o seguinte no seu arquivo js/receiver.js na definição para 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 mudanças no js/receiver.js e faça upload do arquivo no servidor da Web. Inicie uma sessão de transmissão na ferramenta Transmitir e de comando clicando no ícone Transmitir. Os anúncios VAST devem ser processados. Os anúncios precedentes e intermediários (cujo position tem 15 segundos) não são reproduzidos.
Aguarde o tempo de reprodução atingir 30 segundos para passar por todos os intervalos pulados pelo interceptador do carregamento do clipe de pausa. Depois disso, 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 logs mostrados no Break Seek Interceptor. O comportamento padrão foi modificado para mostrar o intervalo mais perto do horário seekFrom.
10. Parabéns
Agora você já sabe como adicionar anúncios ao seu app receptor usando o SDK mais recente do Cast Receiver.
Para mais detalhes, consulte o guia para desenvolvedores sobre Intervalos de anúncios.