Intervalos de anúncio

Visão geral

O SDK do receptor da Web oferece suporte nativo para intervalos de anúncio e anúncios complementares em um determinado fluxo de mídia. Ele fornece APIs para definir a posição do anúncio, a origem de anúncios e o comportamento dos intervalos de anúncio e dos clipes de intervalos associados a eles. Neste guia, Break refere-se a um intervalo para reprodução que contém um ou mais anúncios ou bumpers, e cada anúncio ou bumper é conhecido como um BreakClip Esses intervalos estão associados à mídia que está sendo carregada ou reproduzida.

Tipos de anúncio

O SDK do receptor da Web é compatível com a inserção de anúncios do lado do cliente (CSAI) e o servidor inserção de anúncios integrada (SSAI, na sigla em inglês). Anúncios agrupados pelo cliente podem ser definidos manualmente pelo ou extraídos dos arquivos de modelo VAST e VMAP. Os anúncios agrupados pelo servidor devem ser especificados manualmente antes do carregamento do conteúdo como anúncios incorporados ou dinamicamente, durante a reprodução do conteúdo, como incorporado expandido anúncios. As implementações de cada um desses tipos de anúncios são descritas em detalhes abaixo.

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

Tipos de linha do tempo do jogador

Ao criar uma instância de player, o SDK do receptor da Web seleciona um tipo de linha do tempo para oferecer suporte à reprodução de anúncios durante a reprodução do conteúdo. Cada cronograma permite que determinados tipos de quebra de linha a serem adicionados. O tipo de linha do tempo é determinado pelo tipos de anúncios presentes durante o tempo de carregamento no MediaInformation da LoadRequestData. Se houver intervalos de anúncio incorporados, a linha do tempo embedded será selecionada. Se Há intervalos de anúncio integrados ao cliente, o cronograma stitched é selecionado. Caso não haja anúncios, o SDK usará embedded por padrão. na linha do tempo. Depois de selecionada, a linha do tempo não pode ser alterada para a data item de mídia. A tabela abaixo fornece uma descrição detalhada de cada linha do tempo.

As Figuras 1 a 3 abaixo ilustram alguns conteúdos com tipos de anúncios variados e os respectivos respectivos valores da linha do tempo. O conteúdo é configurado com uma pausa de anúncio precedente. tem dois clipes de intervalo, além de intervalos intermediários e finais com um um clipe de intervalo único. É o tempo médio desde o início da reprodução do conteúdo. o tempo de mídia do conteúdo principal e o horário atual do intervalo em reprodução estão alinhados abaixo de cada figura.

Interromper posicionamento

O SDK do receptor da Web permite que os desenvolvedores especifiquem onde os intervalos de anúncio devem estar definido ao definir position do Break. Esse valor corresponde ao tempo de mídia do conteúdo principal e pode ser usado para criar intervalos de anúncio pre-roll, mid-roll e post-roll. Eles são definidos da seguinte maneira:

Matriz de interoperabilidade

Como um ponto de referência rápido, a Tabela 1 mostra uma visão geral dos tipos de anúncios e a compatibilidade com recursos relacionados a anúncios.

Eventos

Quando ocorrem eventos de quebra de chave, o SDK de transmissão envia eventos do tipo BreaksEvent Um app receptor pode se inscrever neles usando PlayerManager. addEventListener API.

Esses eventos podem ser usados para análise e rastreamento da reprodução de anúncios. Quando o VMAP (playlist de vários anúncios em vídeo) e VAST (Modelo de veiculação de anúncio em vídeo) são qualquer evento de rastreamento padrão fornecido nas respostas é automaticamente enviados pelo SDK.

Os tipos de evento estão listados na Tabela 2 junto com uma descrição detalhada de quando são disparados.

Inserção de anúncios

O SDK do Cast permite que os aplicativos insiram e removam anúncios em momentos diferentes. de uma sessão de transmissão. Os dois tipos de inserção de anúncios são estática e dinâmica. A inserção de anúncios estáticos exige que os anúncios sejam especificados no LoadRequestData antes da criação do jogador. A inserção de anúncios dinâmicos usa o BreakManager addBreak API para inserir intervalos no conteúdo já carregado. Cada tipo de inserção é compatível com determinados tipos de anúncios. A compatibilidade é fornecida na matriz de interoperabilidade.

Inserção de anúncios estáticos

A inserção de anúncios estáticos é caracterizada pela adição dos metadados relevantes antes até a criação de jogadores. Essas informações são fornecidas MediaInformation do LoadRequestData. Por exemplo, isso pode ser definido no endereço de e-mail do remetente solicitação de carregamento original ou ela pode ser inserida pelo aplicativo Web Receiver interceptando a solicitação LOAD. Depois que o LoadRequestData for retornado ao SDK do receptor da Web para processamento, o player será criado. Saiba mais em carregar mídia. O exemplo abaixo mostra um anúncio combinado manualmente com o cliente sendo adicionado à solicitação LOAD interceptador

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

Inserção de anúncios dinâmicos

A inserção de anúncios dinâmicos é caracterizada pela definição de um intervalo comercial durante o conteúdo a reprodução. Para isso, recupere uma instância de BreakManager e chame as addBreak API. Ele usa pelo menos dois parâmetros, um incorporado expandido Break e uma matriz de BreakClip. Uma terceira propriedade opcional é incluída para forçar o envio das alterações ao remetentes conectados por uma transmissão MediaStatus quando definido como true. Quando adicionando quebras e quebras de clipes, os IDs correspondentes devem ser exclusivos. Esses anúncios só podem ser adicionados depois que o player for criado. O SDK do receptor da Web é acionado as PLAYER_LOADING assim que o player for criado. Confira o exemplo abaixo que mostra o uso no um manipulador de eventos que responde a alterações nos metadados ID3 de um fluxo e cria objetos Break e BreakClip para inseri-lo na linha do tempo.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

Remoção de anúncios dinâmicos

Para remover pausas dinâmicas, o aplicativo deve chamar removeBreakById durante a reprodução. A função usa um identificador de string da pausa a ser removido da linha do tempo. O breakId especificado deve apontar para um objeto incorporado intervalo de anúncio expandido. Se qualquer outro tipo de intervalo de anúncio for detectado, vão continuar no cronograma. Veja o exemplo abaixo que remove uma pausa.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.removeBreakById('break_midroll_embedded_expanded');

Comportamento de pausas

O SDK define um comportamento padrão para quando o jogador entrar e sair de intervalos e oferece uma maneira de personalizá-lo ainda mais usando algumas das APIs fornecidas no BreakManager

Comportamento de pausa padrão

Quando um Break é inserido pela reprodução normal ou buscando por um Break, o SDK vai avaliar se o usuário já a viu, verificando ou não as isWatched . Quando criado, o valor padrão de uma pausa para essa propriedade é false. Se a propriedade for true, a pausa não será reproduzida quando for inserida no o conteúdo continuará sendo reproduzido. Se a propriedade for false, a quebra será tocado quando inserido.

Ao buscar intervalos anteriores, a implementação padrão recebe todos os Break itens com position entre o valor da operação de busca seekFrom e seekTo e a distribuição dos valores dos dados. Nessa lista de intervalos, o SDK vai tocar a Break, que tem position está o mais próximo do valor seekTo e cuja propriedade isWatched está definida como false. A propriedade isWatched desse intervalo será definida como true, e o o player começará a reproduzir os clipes de pausa. Depois de assistir ao intervalo, o conteúdo principal retomará a reprodução na posição seekTo. Se não houver existir um intervalo, nenhum intervalo será reproduzido e o conteúdo principal será retomado tocando na posição seekTo.

Durante a reprodução com pausa, o SDK vai transmitir todas as atualizações relevantes para os dispositivos aplicativos remetentes na MediaStatus Esses aplicativos usarão as transmissões para atualizar a interface de usuário dos anúncios lendo as breakStatus . Essa propriedade é definida somente durante a reprodução em pausa.

Os aplicativos receptores também podem consultar diretamente informações relativas à posição do marcador em relação ao tempo atual do BreakClip mostrado chamando PlayerManager getBreakClipCurrentTimeSec. Da mesma forma, os aplicativos podem consultar a duração da BreakClip atual ao chamar getBreakClipDurationSec.

Comportamento de intervalo personalizado

O comportamento padrão para intervalos e clipes de pausa pode ser modificada com o setBreakClipLoadInterceptor e setBreakSeekInterceptor métodos fornecidos em BreakManager.

Interceptador de busca de intervalo

O interceptador de busca de intervalo permite que o app controle o comportamento de busca sobre intervalos de anúncios. A função é acionada quando uma operação de busca é solicitada. que busca avançar ou retroceder uma ou mais pausas. Quando chamado, o BreakSeekData é passado como um parâmetro para a função de retorno de chamada. O objeto BreakSeekData contém uma matriz de Break objetos cuja propriedade position é definida como um número entre o valor marcador de posição definido como seekFrom e o tempo de busca do destino seekTo.

Esse interceptador permite que os objetos Break nos respectivos intervalos sejam modificado. Quando implementado, o interceptador de busca de intervalo deve especificar qual anúncio pausas para reprodução, retornando um objeto BreakSeekData opcionalmente modificado. A o player continuará a reproduzir todos os intervalos incluídos no valor de retorno. Se um valor de null ou nada for retornado do interceptador de busca de intervalo, o intervalo será pulado.

Confira no exemplo abaixo uma implementação simples do interceptador que substitui o comportamento padrão de assistir a todos os intervalos comerciais procurados com o exceto aqueles que já foram assistidos.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

Interceptador de carregamento de clipe de interrupção

Ao usar o interceptador do carregamento de clipes de interrupção, um objeto BreakClip pode ser modificado. antes do início da reprodução.

O interceptador do carregamento do clipe de pausa é chamado somente para falhas na linha do tempo agrupadas e pode ser definido usando setBreakClipLoadInterceptor. Antes de inserir um Break, esse interceptador é chamado uma vez para cada indivíduo. BreakClip definido nesse intervalo. O SDK transmite o arquivo BreakClip como um parâmetro da função de callback. O aplicativo pode modificar BreakClip e a retorna para que o SDK possa buscar e exibir o intervalo. com a configuração atualizada. Se null ou nada for retornado, o intervalo o clipe é ignorado.

Confira abaixo um exemplo que modifica o contentUrl dos clipes de intervalo com uma chamada de função utilitária getUrlFromClipId em que a id do BreakClip está mapeado para um URL.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

Pular anúncio

O SDK do receptor da Web fornece APIs para pular intervalos de anúncio e clipes de intervalo individuais em um intervalo de anúncio. O SDK também permite que os usuários possam pular clipes de pausa ao que interagem com aplicativos emissores ou dispositivos smart display.

Clipes de intervalo puláveis do usuário

Definir clipes de pausa como puláveis permite que os usuários interajam com o remetente conectado aplicativos e dispositivos de smart display para pular o restante de uma em reprodução no momento. Definir o whenSkippable a um número não negativo de segundos ativará esse recurso para a objeto BreakClip. O player vai considerar o clipe de intervalo pulável quando o foi reproduzido durante esse número de segundos. Definir esse valor como 0 permite que os usuários pulem o clipe de pausa imediatamente.

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

Essas informações podem ser definidas na solicitação de carregamento original do remetente ou no app receptor. Quando pulado, um clipe de intervalo em um intervalo de anúncio da linha do tempo agrupada a reprodução do clipe de intervalo atual será interrompida. O player carregará a próxima quebrar clipe se houver ou carregar o conteúdo principal. Quando ignorado, a pausa é feita em uma o intervalo de anúncio na linha do tempo incorporada vai avançar para o fim do clipe de intervalo, e continuar a reprodução do stream nesse ponto.

Pular anúncios de forma programática

Os anúncios também podem ser pulados automaticamente sem nenhuma interação do usuário.

Para pular uma pausa inteira da reprodução, um aplicativo deve definir o isWatched propriedade de um Break para true. Isso pode ser feito a qualquer momento durante o carregamento reprodução de conteúdo ou sequência. A propriedade isWatched é avaliada pelo player quando a position de um intervalo é atendida no tempo atual do conteúdo principal. Em Nesse ponto, o jogador determina se uma pausa deve ser inserida ou não. Veja o exemplo abaixo, que passa por todas as pausas e modifica o quando o player estiver sendo carregado.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

Para pular um clipe de intervalo específico de forma programática, o interceptor de carregamento de clipe de pausa. De retornar null ou não retornar um valor na função de callback, o clipe esse intervalo será ignorado.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});