App de player de vídeo do cliente para transmissões ao vivo

Com a API Google DAI Pod Serving, você pode realizar a inserção de anúncios do lado do servidor com a tecnologia do Google Ads e manter o controle da sua própria integração de vídeos.

Neste guia, mostramos como interagir com a API Pod Serving e conseguir uma funcionalidade semelhante com o SDK de DAI do IMA. Para perguntas específicas sobre funcionalidades compatíveis, entre em contato com seu gerente de contas do Google.

A API Pod Serving é compatível com streams de veiculação de conjuntos nos protocolos de streaming HLS ou MPEG-DASH. Este guia se concentra em streams HLS e destaca as principais diferenças entre HLS e MPEG-DASH em etapas específicas.

Para integrar a API Pod Serving ao seu aplicativo para streams VOD, faça o seguinte:

Fazer uma solicitação de registro de stream ao Ad Manager

Faça uma solicitação POST para o endpoint de registro de stream. Você recebe uma resposta JSON contendo o ID do stream a ser enviado ao servidor de manipulação de manifesto e aos endpoints da API Pod Serving associados.

Endpoint da API

POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/json

Parâmetros de caminho

{network_code} Código da rede do Google Ad Manager 360
{custom_asset} O identificador personalizado associado a este evento no Google AdManager.

Parâmetros do corpo codificados pelo formulário

Um conjunto opcional de parâmetros de segmentação codificados por formulário.

JSON de resposta

media_verification_url O URL de base para dar um ping nos eventos de rastreamento de reprodução. Um URL completo de verificação de mídia é formado anexando um ID de evento de anúncio a esse URL base.
metadata_url É o URL para solicitar os metadados do conjunto de anúncios.
stream_id A string usada para identificar a sessão de transmissão atual.
valid_for O tempo restante até a sessão de transmissão atual expirar, no formato dhms (dias, horas, minutos, segundos). Por exemplo, 2h0m0.000s representa uma duração de 2 horas.
valid_until O horário em que a sessão de stream atual expira, como uma string de data e hora ISO 8601 no formato yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.

Exemplo de solicitação (cURL)

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded"
     -d "cust_params="section%3Dsports%26page%3Dgolf%2Ctennis"
  https://dai.google.com/linear/pods/api/v1/network/21775744923/custom_asset/an-public-test-asset/stream

Exemplo de resposta

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

Em caso de erros, os códigos de erro HTTP padrão são retornados sem corpo de resposta JSON.

Analisar a resposta JSON e armazenar os valores relevantes.

Solicitar o manifesto de stream do manipulador de manifesto

Cada manipulador de manifesto tem formatos de solicitação e resposta diferentes. Entre em contato com o provedor do seu manipulador para entender os requisitos específicos dele. Se você estiver implementando seu próprio manipulador de manifesto, leia o guia sobre manipulador de manifestos para entender os requisitos desse componente.

Em geral, é necessário transmitir o ID do stream retornado pelo endpoint de registro acima ao seu manipulador de manifesto para que ele crie manifestos específicos da sessão. A menos que seja explicitamente declarado pelo manipulador de manifesto, a resposta à solicitação de manifesto é um stream de vídeo com conteúdo e anúncios.

Exemplo de solicitação (cURL)

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

Exemplo de resposta (HLS)

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

Iniciar a transmissão

Carregue o manifesto que você recebeu do servidor de manipulação de manifesto em um player de vídeo e inicie a reprodução.

Solicitar metadados do conjunto de anúncios do Ad Manager

Faça uma solicitação GET para o metadata_url que você recebeu na etapa 1. Essa etapa precisa ocorrer depois que você receber o manifesto integrado do manipulador de manifesto. Você, por sua vez, receberá um objeto JSON contendo os seguintes parâmetros:

tags Um conjunto de pares de chave-valor que contém todos os eventos de anúncios que aparecem no stream. As chaves são os primeiros 17 caracteres de um ID de evento de anúncio que aparece nos metadados cronometrados do stream. No caso de eventos do tipo progress, eles são o ID completo do evento de anúncio.

Cada valor é um objeto que contém os seguintes parâmetros:

ad O ID de um anúncio que corresponde a uma chave no objeto ads.
ad_break_id O ID de um intervalo de anúncio que corresponde a uma chave no objeto ad_breaks.
type O tipo de evento de anúncio. Os tipos de evento de anúncio são:
start Disparado no início do anúncio.
firstquartile Disparado no final do primeiro quartil.
midpoint Disparado no ponto médio do anúncio.
thirdquartile Disparado no final do terceiro quartil.
complete Disparado no final do anúncio.
progress Disparado periodicamente ao longo do anúncio para notificar o app de que um intervalo de anúncio está sendo reproduzido.
ads Um conjunto de pares de chave-valor que descreve todos os anúncios que aparecem no stream. As chaves são IDs de anúncios que correspondem aos valores encontrados no objeto tags listado acima. Cada valor é um objeto que contém os seguintes parâmetros:
ad_break_id O ID de um intervalo de anúncio que corresponde a uma chave no objeto ad_breaks.
position É a posição em que o anúncio é exibido no conjunto de anúncios no intervalo, em segundos de ponto flutuante.
duration A duração do anúncio em segundos de ponto flutuante.
clickthrough_url É o URL que deve ser aberto quando um usuário interagir com o anúncio, se compatível.
ad_breaks É um conjunto de pares de chave-valor que descreve todos os intervalos de anúncio que aparecem no stream. As chaves são IDs de intervalo de anúncio que correspondem aos valores encontrados nos objetos tags e ads listados acima. Cada valor é um objeto que contém os seguintes parâmetros:
type É o tipo de intervalo de anúncio. Os tipos de intervalo de anúncio são pre (anúncio precedente), mid (anúncio intermediário) e post (anúncio final).
duration A duração do intervalo de anúncio em segundos de ponto flutuante.
ads O número de anúncios neste intervalo de anúncio.

Armazene esses valores para associar a eventos de metadados com marcação de tempo no seu stream de vídeo.

Exemplo de solicitação (cURL)

curl https://dai.google.com/.../metadata

Exemplo de resposta

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

Detectar eventos de anúncio

Detecte metadados com marcação de tempo por meio de eventos de anúncios acionados no stream de áudio/vídeo do player de vídeo.

Para streams MPEG-TS, os metadados aparecem como tags ID3 v2.3 na banda. Cada tag de metadados tem o ID TXXX, e o valor começa com a string google_ seguida de uma série de caracteres. Esse valor é o ID do evento de anúncio.

O XXX em TXXX não é um marcador de posição. A string TXXX é o ID da tag ID3 reservada para "texto definido pelo usuário".

Exemplo de tag ID3

TXXXgoogle_1234567890123456789

Para streams de MP4, eles são enviados como eventos de emsg em banda que emulam tags ID3 v2.3. Cada caixa de emsg relevante tem um valor scheme_id_uri de https://aomedia.org/emsg/ID3 ou https://developer.apple.com/streaming/emsg-id3 e um valor de message_data começando com ID3TXXXgoogle_. Esse valor message_data, sem o prefixo ID3TXXX, é o ID do evento de anúncio.

Exemplo de caixa de emsg

A estrutura de dados pode variar, dependendo da biblioteca do seu player de mídia.

Se o ID do evento de anúncio for google_1234567890123456789, a resposta será semelhante a esta:

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

Algumas bibliotecas de players de mídia apresentam automaticamente eventos de emsg que emulam tags ID3 como tags ID3 nativas. Nesse caso, os streams MP4 apresentam tags ID3 idênticas a MPEG_TS.

Atualizar a interface do app cliente do player de vídeo

Cada ID de evento de anúncio pode ser combinado com uma chave no objeto tags da etapa 4. A correspondência desses valores é um processo de duas etapas:

  1. Verifique se há uma chave no objeto tags que corresponda ao ID completo do evento de anúncio. Se uma correspondência for encontrada, recupere o tipo de evento e os objetos ad e ad_break associados. Esses eventos precisam ter o tipo progress.

    Se não for encontrada uma correspondência para o ID do evento de anúncio completo, verifique se há uma chave correspondente aos 17 primeiros caracteres do objeto tags. Recupere o tipo de evento e os objetos ad e ad_break associados. Isso recupera todos os eventos com tipos diferentes de progress.

  2. Use as informações recuperadas para atualizar a interface do jogador. Por exemplo, quando você receber um start ou o primeiro evento progress, oculte os controles de busca do player e mostre uma sobreposição descrevendo a posição do anúncio atual no intervalo, por exemplo: "Anúncio 1 de 3".

Exemplos de IDs de evento de anúncio

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

Exemplo de objeto de tags

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

Enviar pings de verificação de mídia

Um ping de verificação de mídia precisa ser enviado ao Ad Manager sempre que um evento de anúncio com um tipo diferente de progress é recebido.

Para gerar o URL completo de verificação de mídia de um evento de anúncio, anexe o ID completo do evento de anúncio ao valor de media_verification_url da resposta de registro de stream.

Faça uma solicitação GET com o URL completo. Se a solicitação de verificação for bem-sucedida, você receberá uma resposta HTTP com o código de status 202. Caso contrário, você recebe o código de erro HTTP 404.

Exemplo de solicitação (cURL)

curl https://{...}/media/google_5555555555123456789

Exemplo de resposta bem-sucedida

HTTP/1.1 202 Accepted

Outros recursos