1. Visão geral
Este codelab descreve como criar um app Custom Web Receiver 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 UI necessários de acordo com a Checklist de design do Google Cast.
A Checklist de Design do Google Cast é fornecida para padronizar as implementações do Cast e tornar as experiências dos usuários intuitivas em todas as plataformas compatíveis.
O que vamos criar?
Ao concluir este codelab, você terá criado um receptor do Cast que aproveita a API Break.
O que você vai aprender
- Como incluir intervalos VMAP e VAST no conteúdo para o Cast
- Como pular clipes de intervalo
- Como personalizar o comportamento de interrupção padrão ao buscar
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 de transmissão, 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ê tem a seguinte experiência antes de continuar este codelab.
- Conhecimento geral de desenvolvimento para a Web.
- Como criar aplicativos receptores da Web do 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 poder usar seu receptor da Web com um dispositivo de transmissão, ele precisa estar hospedado em algum lugar que o dispositivo possa acessar. Se você já tem um servidor compatível com HTTPS disponível, pule as instruções a seguir e anote o URL, porque ele será necessário na próxima seção.
Se você não tiver um servidor disponível para uso, use o Firebase Hosting ou o ngrok.
Executar o servidor
Depois de configurar o serviço escolhido, navegue até app-start e inicie o 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 aplicativo para poder executar um receptor personalizado nos dispositivos Chromecast, como o que criaremos neste codelab. Depois de registrar o aplicativo, um ID do aplicativo será gerado. O aplicativo remetente precisa ser configurado para iniciar o aplicativo Web Receiver.
Clique em "Adicionar novo aplicativo".
Selecione "Custom Receiver", que é o que estamos criando.
Insira os detalhes do novo receptor. Use o URL que aponta para onde você planeja hospedar o aplicativo Web Receiver. Anote o ID do aplicativo gerado pelo console depois que você registrar o aplicativo. O aplicativo remetente será configurado para usar esse identificador em uma seção posterior.
Você também precisa registrar um dispositivo de transmissão para que ele possa acessar o aplicativo receptor antes de você publicá-lo. Após a publicação, o aplicativo 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 "Add new Device".
Insira o número de série impresso na parte de trás do seu dispositivo de transmissão e dê um nome descritivo para ele. Também é possível encontrar o número de série pela transmissão de tela no Chrome ao acessar o Play Console 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 começar este codelab, é recomendável consultar o guia para desenvolvedores de anúncios, que oferece uma visão geral das APIs de intervalo de anúncio.
É necessário adicionar compatibilidade com o Google Cast ao app inicial que você transferiu por download. Confira 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 você já pode 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. Ao continuar validando e testando as mudanças, verifique se elas estão sendo enviadas para o site host.
Design de apps
Como mencionado, o codelab usa um aplicativo remetente para iniciar uma sessão do Cast e um aplicativo receptor que será modificado para usar as APIs de intervalo de anúncio.
Neste codelab, a Ferramenta de transmissão e comando vai funcionar 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 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 o ícone de transmissão não aparecer, verifique se o Web Receiver e os dispositivos de transmissão estão registrados corretamente no Play Console. Se ainda não tiver feito isso, reinicie os dispositivos de transmissão que acabaram de ser registrados.
O app receptor é o foco principal 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 abaixo.
index.html
Esse arquivo HTML contém a interface do usuário do app receptor fornecida pelo elemento cast-media-player. Ele também carrega o SDK do CAF e as bibliotecas 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 do Google Cast e carregar um recurso de vídeo na inicialização. Alguns recursos de depuração também foram adicionados para fornecer registros à ferramenta Cast e Comando.
6. Adicionar VMAP ao seu conteúdo
O SDK do Web Receiver do Google Cast oferece suporte a anúncios especificados por 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 associados do clipe de intervalo. 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ções LOAD e substitua pelo código abaixo. Ele contém um exemplo 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 mudanças em js/receiver.js e faça upload do arquivo para seu servidor da Web. Inicie uma sessão do Cast na Ferramenta de transmissão e comando clicando no ícone do Cast. Os anúncios VMAP devem ser veiculados, seguidos pelo conteúdo principal.
7. Adicionar VAST ao seu conteúdo
Como mencionado antes, o SDK do Web Receiver oferece suporte a muitos 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 conhecido como VAST. Se você implementou o código VMAP da seção anterior, coloque-o como comentário.
Copie o seguinte no seu arquivo js/receiver.js depois do interceptador de solicitação de carregamento. Ele contém seis clipes de interrupção VAST do DoubleClick e um valor de correlator aleatório. Esses clipes de intervalo escolar são atribuídos a cinco intervalos escolares. O position de cada intervalo é definido como um tempo em segundos relativo ao conteúdo principal, incluindo anúncios precedentes (position definido como 0) e anúncios 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 quebra é uma matriz, o que significa que vários clipes de quebra podem ser atribuídos a cada quebra.
No js/receiver.js file, localize o interceptador de mensagens LOAD e substitua pelo código a seguir. O trabalho do VMAP está comentado para mostrar 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 em js/receiver.js e faça upload do arquivo para seu servidor da Web. Inicie uma sessão do Cast na Ferramenta de transmissão e comando clicando no ícone do Cast. Os anúncios VAST devem ser veiculados, seguidos pelo conteúdo principal.
8. Pular intervalos de anúncio
O CAF tem uma classe chamada BreakManager, que ajuda a implementar regras de negócios personalizadas para comportamentos de anúncios. Um desses recursos permite que os aplicativos pulem intervalos e clipes de intervalo de maneira 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 anúncio final. Ao usar os anúncios VAST configurados na seção anterior, há cinco intervalos definidos: um anúncio precedente, três anúncios intermediários (aos 15, 60 e 100 segundos) e, finalmente, um anúncio final. Depois de concluir as etapas, apenas os anúncios precedentes e intermediários com posição de 15 segundos serão ignorados.
Para isso, o aplicativo precisa chamar as APIs disponíveis em BreakManager para definir um interceptador de carregamento de 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 receber 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 ocorrem antes de 30 segundos, sem esquecer dos 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 depois do 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 o BreakClip que está sendo processado. Se um Break não tiver nenhum clipe de interrupção definido, a interrupção será ignorada.
Salve as mudanças em js/receiver.js e faça upload do arquivo para seu servidor da Web. Inicie uma sessão do Cast na Ferramenta de transmissão e comando clicando no ícone do Cast. Os anúncios VAST precisam ser processados. Os anúncios pre-roll e o primeiro mid-roll (com position de 15 segundos) não são veiculados.
9. Personalizar o comportamento de busca de intervalos
Ao procurar intervalos anteriores, a implementação padrão obtém todos os itens Break cuja posição está entre os valores seekFrom e seekTo da operação de busca. Dessa lista de intervalos, o SDK reproduz o Break cujo position está mais próximo do valor seekTo e cuja propriedade isWatched está definida como false. A propriedade isWatched dessa pausa é definida como true, e o player começa a tocar os clipes da pausa. Depois que o intervalo é assistido, o conteúdo principal retoma a reprodução da posição seekTo. Se não houver uma pausa desse tipo, nenhuma pausa será reproduzida, 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 a lógica personalizada pela API, o SDK a chama sempre que uma operação de busca é realizada em uma ou mais interrupções. A função de callback recebe um objeto que contém todas as interrupções entre a posição seekFrom e a posição seekTo. Em seguida, o aplicativo precisa modificar e retornar o BreakSeekData.
Para mostrar o uso, o exemplo abaixo substitui o comportamento padrão ao usar todas as pausas que foram buscadas e reproduzir apenas a primeira que aparece na linha do tempo.
Copie o seguinte no arquivo js/receiver.js abaixo da definição do 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, nenhuma pausa será reproduzida.
Salve as mudanças em js/receiver.js e faça upload do arquivo para seu servidor da Web. Inicie uma sessão do Cast na Ferramenta de transmissão e comando clicando no ícone do Cast. Os anúncios VAST precisam ser processados. Os anúncios pre-roll e o primeiro mid-roll (com position de 15 segundos) não são veiculados.
Aguarde até que o tempo de reprodução chegue a 30 segundos para passar por todas as pausas ignoradas pelo interceptador de carga de clipe de pausa. Quando chegar ao ponto desejado, envie um comando de busca navegando até a guia Controle de mídia. Preencha a entrada Buscar na mídia com 300 segundos e clique no botão ATÉ. Observe os registros impressos no interceptor de busca de interrupção. O comportamento padrão agora precisa ser substituído para reproduzir o intervalo mais perto do tempo 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 publicidade.