Começar a usar o SDK de DAI do IMA

Com os SDKs do IMA, é fácil integrar anúncios multimídia aos seus sites e apps. Os SDKs do IMA podem solicitar anúncios de qualquer de anúncios compatíveis com VAST e gerencie a reprodução de anúncios nos seus apps. Com os SDKs de DAI do IMA, os apps criam uma solicitação de streaming para anúncio e conteúdo de vídeo, seja VOD ou conteúdo ao vivo. Em seguida, o SDK retorna uma stream de vídeo combinado, para que você não precise alternar entre anúncios e conteúdo em vídeo no seu app.

Selecione a solução de DAI do seu interesse

Serviço completo Veiculação de pods

DAI de veiculação de conjuntos

Este guia demonstra como reproduzir um stream de Veiculação de conjunto DAI para transmissões ao vivo ou VOD conteúdo usando o SDK de DAI do IMA para HTML5 com um player de vídeo que depende do arquivo hls.js para reprodução. Se você quiser visualizar ou acompanhar um exemplo completo com suporte para HLS.js e reprodução no Safari, consulte a documentação Exemplo de disponibilização de pod HLS. Para suporte a DASH.js, consulte o exemplo de veiculação de conjunto do DASH (link em inglês). Faça o download destes apps de exemplo na versão do GitHub da DAI HTML5 .

Observação: O SDK de DAI do IMA para HTML5 é compatível com streams HLS e DASH, mas a reprodução de cada um exige uma um player de mídia ou extensão diferente, como HLS.js ou DASH.js, com variação e implementações.

Este guia explica como configurar o HLS.js e o SDK de DAI do IMA para reproduzir um stream HLS com observações importantes sobre as diferenças de implementação do DASH.

Consulte o IMA App de exemplo DASH.js como ponto de partida para implementar fluxos da DAI do DASH com o IMA.

Importante :para usar a Veiculação de conjunto DAI, é preciso trabalhar com uma Veiculação de conjunto parceiro e ter uma conta do Ad Manager 360 Advanced. Se você tiver uma conta do Ad Manager, entre em contato com o gerente de contas para mais detalhes. Para sobre como se inscrever no Ad Manager, acesse a Ajuda do Ad Manager do Shopping.

Observação:para informações sobre a integração com outras plataformas ou o uso SDKs do IMA do lado do cliente, consulte SDKs do Interactive Media Ads.

Visão geral da disponibilização de conjunto DAI

A implementação da veiculação de pods com o SDK de DAI do IMA envolve dois componentes principais: são demonstrados neste guia:

• PodStreamRequest / PodVodStreamRequest: um objeto que define uma solicitação de stream para servidores de publicidade do Google. As solicitações especificam um código de rede e a PodStreamRequest também requer uma chave de recurso personalizada e um parâmetro Chave de API. Ambos incluem outros parâmetros opcionais.

• StreamManager: um objeto que gerencia a comunicação entre o stream de vídeo e o SDK de DAI do IMA, como disparar pings de rastreamento e encaminhando eventos de stream para o editor.

Pré-requisitos

Antes de começar, os seguintes itens são necessários:

• Três arquivos vazios:

  • dai.html
  • dai.css
  • dai.js

• Python instalado em seu computador, ou um servidor da web ou outro aplicativo de desenvolvimento de teste para usar em testes

Configurar um ambiente de desenvolvimento

Como o SDK carrega dependências usando o mesmo protocolo que a página de que ele é carregado, você precisa usar um servidor da Web para testar seu aplicativo. Uma breve de iniciar um servidor de desenvolvimento local é usar o servidor integrado do Python.

1. Usando uma linha de comando, no diretório que contém o index.html execução do arquivo:

   python -m http.server 8000
   

   Observação :http.server está disponível apenas no Python 3.x.

2. Em um navegador da Web, acesse http://localhost:8000/

   Você também pode usar qualquer outro ambiente de desenvolvimento hospedado ou servidor da Web, como como o servidor HTTP Apache.

Criar um player de vídeo simples

Observação: este guia presume que você esteja usando a biblioteca HLS.js para reproduzir um HLS. riacho. O SDK de DAI do IMA para HTML5 também é compatível com streams DASH, biblioteca apropriada, como Shaka player ou DASH.js.

Primeiro, modifique dai.html para criar um elemento de vídeo HTML5 simples e um div para para elementos da interface do anúncio. Adicione também as tags necessárias para carregar o arquivo dai.css. e dai.js, além de importar o player de vídeo hls.js.

Em seguida, modifique dai.css para especificar o tamanho e a posição dos elementos da página. Por fim, em dai.js, defina variáveis para armazenar as informações de solicitação de stream e uma função initPlayer() a ser executada quando a página for carregada.

As constantes de solicitação de stream são as seguintes:

• BACKUP_STREAM: um URL para um stream de backup reproduzir caso o anúncio seja processado encontrar um erro fatal.

• STREAM_URL: usado apenas para transmissões ao vivo. O URL de stream de vídeo fornecido pelo o manipulador de manifesto ou um parceiro terceirizado usando a veiculação de pods. Ele deveria exigem que você insira o código de stream fornecido pelo SDK de DAI do IMA antes de fazer uma solicitação. Nesse caso, o URL de stream inclui um marcador, [[STREAMID]], que é substituído pelo ID do stream antes da solicitação.

• NETWORK_CODE: o código da rede da conta do Ad Manager 360.

• CUSTOM_ASSET_KEY: usado apenas para transmissões ao vivo. A chave de recurso personalizada que identifica seu evento de veiculação de conjunto no Ad Manager 360. Ela pode ser criada seu manipulador de manifesto ou um parceiro terceirizado de veiculação de pod.

• API_KEY: usado apenas para transmissões ao vivo. Uma chave de API opcional que pode ser necessário para recuperar um ID de stream do SDK de DAI do IMA.

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA DAI SDK Demo (HLS.JS)</h2>
    <video id="video"></video>
    <div id="ad-ui"></div>
</body>
</html>

dai.css

#video,
#ad-ui {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#ad-ui {
  cursor: pointer;
}

dai.js

var BACKUP_STREAM =
    'https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8'

// Stream Config.
const STREAM_URL = "https://encodersim.sandbox.google.com/masterPlaylist/...&stream_id=[[STREAMID]]";
const NETWORK_CODE = "51636543";
const CUSTOM_ASSET_KEY = "google-sample";
const API_KEY = "";

var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
}

Carregar o SDK de DAI do IMA

Em seguida, adicione o framework da DAI usando uma tag de script em dai.html, antes da tag para dai.js.

Observação :para receber registros mais detalhados do console, substitua ima3_dai.js por ima3_dai_debug.js. No entanto, ima3_dai_debug.js não deve ser usado em apps em produção.

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
...

Inicialize o StreamManager e faça uma solicitação de stream ao vivo ou VOD

Veiculação de conjunto de transmissão ao vivo

Para solicitar um conjunto de anúncios, crie um ima.dai.api.StreamManager, que é responsável por solicitar e gerenciar streams da DAI. O construtor recebe um elemento de vídeo e a instância resultante usa um elemento da interface de anúncios para lidar com o e interações.

Em seguida, defina uma função para solicitar a transmissão ao vivo de veiculação do pod. Essa função primeiro cria um PodStreamRequest, o configura com o streamRequest fornecidos na etapa 2 e, em seguida, chama streamManager.requestStream() a esse objeto de solicitação.

Importante :nenhum stream neste exemplo está protegido. Portanto, apiKey não é usados. Se o stream exigir uma chave de API, consulte Autenticar o stream de vídeo da DAI solicitações.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  requestLivePodStream(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
}

function requestLivePodStream(networkCode, customAssetKey, apiKey) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving live Stream Request
  const streamRequest = new google.ima.dai.api.PodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.customAssetKey = customAssetKey;
  streamRequest.apiKey = apiKey;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

Veiculação de conjunto de VOD

Para solicitar um conjunto de anúncios, crie um ima.dai.api.StreamManager, que é responsável por solicitar e gerenciar streams da DAI. O construtor recebe um elemento de vídeo e a instância resultante usa um elemento da interface de anúncios para lidar com o e interações.

Em seguida, defina uma função para solicitar o stream de VOD que veicula o pod. Essa função primeiro cria um PodVodStreamRequest, o configura com o streamRequest fornecidos na etapa 2 e, em seguida, chama streamManager.requestStream() a esse objeto de solicitação.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  requestVodPodStream(NETWORK_CODE);
}

function requestVodPodStream(networkCode) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving VOD Stream Request
  const streamRequest = new google.ima.dai.api.PodVodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

Processar eventos de stream

Veiculação de conjunto de transmissão ao vivo

Em seguida, implemente listeners de eventos para os principais eventos de vídeo. Este exemplo lida com STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED e AD_BREAK_ENDED eventos chamando uma função onStreamEvent(). Essa função lida com o fluxo o carregamento e erros, além de desativar os controles do player enquanto um anúncio é sendo reproduzido, o que é exigido pelo SDK. Quando o stream é carregado, o vídeo o player carrega e reproduz o URL fornecido usando uma função loadStream().

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    google.ima.dai.api.StreamEvent.Type.ERROR,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);
...
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
      console.log('Stream initialized');
      loadStream(e.getStreamData().streamId);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream('');
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

function loadStream(streamID) {
  var url;
  if(streamID) {
    url = STREAM_URL.replace('[[STREAMID]]', streamID);
  } else {
    console.log('Stream Initialization Failed');
    url = BACKUP_STREAM;
  }
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
}

Veiculação de conjunto de VOD

Em seguida, implemente listeners de eventos para os principais eventos de vídeo. Esse exemplo lida com STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED e eventos AD_BREAK_ENDED chamando uma função onStreamEvent(). Isso lida com erros e carregamento de stream, além de desabilitar o player controla durante a reprodução de um anúncio, o que é exigido pelo SDK.

Além disso, os streams de veiculação de conjunto de VOD exigem chamadas StreamManager.loadStreamMetadata() em resposta ao STREAM_INITIALIZED. Você também precisa solicitar um URL de stream da sua parceiro de tecnologia de vídeo (VTP, na sigla em inglês). Quando a chamada loadStreamMetadata() for concluída ele aciona um evento LOADED, em que você precisa chamar uma função loadStream(). pelo URL da transmissão para carregar e reproduzir.

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    google.ima.dai.api.StreamEvent.Type.ERROR,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);
...
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
      const streamId = e.getStreamData().streamId;
      // 'vtpInterface' is a place holder for your own video technology
      //  partner (VTP) API calls.
      vtpInterface.requestStreamURL({
        'streamId': streamId,
      })
      .then( (vtpStreamUrl) => {
        streamUrl = vtpStreamUrl;
        streamManager.loadStreamMetadata();
      }, (error) => {
        // Handle the error.
      });
      break;
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      loadStream(streamUrl);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

function loadStream(url) {
  if(url) {
    console.log('Loading:' + url);
    hls.loadSource(url);
  } else {
    console.log('Stream Initialization Failed');
    hls.loadSource(BACKUP_STREAM);
  }
  hls.attachMedia(videoElement);
}

Processar metadados de stream

Nesta etapa, você vai implementar listeners de eventos para que os metadados notifiquem o SDK quando de ocorrência de eventos de anúncio. A detecção de eventos de metadados in-stream pode variar dependendo formato (HLS ou DASH), tipo de transmissão (ao vivo ou VOD), seu o tipo de player e o tipo de back-end da DAI usado. Consulte nossa Programação Metadados para mais informações.

Formato de transmissão HLS (transmissões ao vivo e VOD, player HLS.js)

Se você estiver usando um player HLS.js, escute o evento FRAG_PARSING_METADATA de HLS.js para receber metadados ID3 e transmiti-los ao SDK com StreamManager.processMetadata().

Para reproduzir o vídeo automaticamente depois que tudo estiver carregado e pronto, ouça o o evento MANIFEST_PARSED de HLS.js para acionar a reprodução.

function loadStream(streamID) {
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  
  // Timed metadata is passed HLS stream events to the streamManager.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
  hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}

function parseID3Events(event, data) {
  if (streamManager && data) {
    // For each ID3 tag in the metadata, pass in the type - ID3, the
    // tag data (a byte array), and the presentation timestamp (PTS).
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
}

function startPlayback() {
  console.log('Video Play');
  videoElement.play();
}

DASH.js (formato de transmissões DASH, tipo de transmissão ao vivo e VOD)

Se você estiver usando um player DASH.js, faça o seguinte: você precisa usar strings diferentes para detectar metadados ID3 de transmissões ao vivo ou VOD. streams:

• Transmissões ao vivo: 'https://developer.apple.com/streaming/emsg-id3'
• Streams de VOD: 'urn:google:dai:2018'

Transmita os metadados ID3 para o SDK com StreamManager.processMetadata().

Para mostrar os controles de vídeo automaticamente depois que tudo estiver carregado e pronto, Detecte o evento MANIFEST_LOADED do DASH.js.

const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);

function processMetadata(metadataEvent) {
  const messageData = metadataEvent.event.messageData;
  const timestamp = metadataEvent.event.calculatedPresentationTime;

  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with dash.js.
  streamManager.processMetadata('ID3', messageData, timestamp);
}

function loadlistener() {
  showControls();

  // This listener must be removed, otherwise it triggers as addional
  // manifests are loaded. The manifest is loaded once for the content,
  // but additional manifests are loaded for upcoming ad breaks.
  dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}

Shaka Player com transmissões ao vivo (formato de streams DASH)

Se você estiver usando o player de Shaka para reprodução de transmissão ao vivo, use a string 'emsg' para detectar eventos de metadados. Em seguida, use os dados da mensagem do evento na chamada para StreamManager.onTimedMetadata().

shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));

function onEmsgEvent(metadataEvent) {
  // Use StreamManager.onTimedMetadata() if your video player provides
  // processed metadata, as with Shaka player livestreams.
  streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}

Shaka Player com transmissões VOD (formato de streams DASH)

Se você estiver usando o player de Shaka para Reprodução de stream de VOD, use a string 'timelineregionenter' para detectar eventos de metadados. Em seguida, use os dados da mensagem do evento na chamada para StreamManager.processMetadata() com a string 'urn:google:dai:2018'.

shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));

function onTimelineEvent(metadataEvent) {
  const detail = metadataEvent.detail;
  if ( detail.eventElement.attributes &&
       detail.eventElement.attributes['messageData'] &&
       detail.eventElement.attributes['messageData'].value ) {
        const mediaId = detail.eventElement.attributes['messageData'].value;
        const pts = detail.startTime;
        // Use StreamManager.processMetadata() if your video player provides raw
        // ID3 tags, as with Shaka player VOD streams.
        streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
       }
}

Processar eventos do jogador

Adicione listeners de eventos aos eventos pause e start do elemento de vídeo para permitir que o usuário retome a reprodução quando o SDK pausar durante os intervalos comerciais.

function loadStream(streamUrl) {
  ...
  
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);
}

function onStreamPause() {
  console.log('paused');
  if (isAdBreak) {
    videoElement.controls = true;
    adUiElement.style.display = 'none';
  }
}

function onStreamPlay() {
  console.log('played');
  if (isAdBreak) {
    videoElement.controls = false;
    adUiElement.style.display = 'block';
  }
}

Pronto! Agora você está solicitando e exibindo anúncios em um fluxo de veiculação de conjunto com SDK de DAI do IMA para HTML5. Para saber mais sobre os recursos avançados do SDK, consulte a outros guias ou os exemplos sobre GitHub (em inglês).