App de player de vídeo do cliente para streams de VOD

A API Google DAI Pod Serving permite que você realize a inserção de anúncios do lado do servidor com o Google Ads, mantendo o controle da junção de vídeos.

Importante: antes de considerar essa API, verifique se já existe um SDK do DAI do IMA para a plataforma que você quer usar. O SDK da DAI do IMA é recomendado nas plataformas em que ele está disponível. A API de veiculação de pods é destinada a ser usada apenas em plataformas que não têm um SDK do IMA DAI.

Neste guia, mostramos como interagir com a API Pod Serving e ter funcionalidades semelhantes com o SDK DAI do IMA. Para dúvidas específicas sobre a funcionalidade com suporte, entre em contato com seu gerente de contas do Google.

A API de veiculação de conjuntos oferece suporte a transmissões de veiculação de conjuntos nos protocolos de streaming HLS ou MPEG-DASH. Este guia se concentra em transmissões HLS e destaca as principais diferenças entre HLS e MPEG-DASH em etapas específicas.

Para integrar a API Pod Serving ao seu app para transmissões VOD, siga estas etapas:

Faça uma solicitação de registro de stream para o Ad Manager

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

endpoint de API

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

Parâmetros de caminho

{network_code}

Seu código de rede do Google Ad Manager 360

Parâmetros do corpo JSON

targeting_parameters

Um objeto JSON que contém os parâmetros de segmentação do anúncio. Obrigatório

JSON de resposta

media_verification_url	O URL base para enviar eventos de acompanhamento de reprodução. Um URL de verificação de mídia completo é formado pela adição de um ID de evento do anúncio a esse URL base.
metadata_url	O URL para solicitar 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é que a sessão de transmissão atual expire, 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 streaming 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 \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

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.

Analise a resposta JSON e armazene os valores relevantes.

Dica: os URLs fornecidos na resposta da API estão sujeitos a mudanças sem aviso. Portanto, use os URLs fornecidos na resposta da API em vez de criá-los você mesmo. Isso ajuda a garantir que o código continue funcionando corretamente quando os URLs mudarem.

Solicitar o manifesto do stream do manipulador de manifesto

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

Em geral, é necessário transmitir o ID de stream retornado pelo endpoint de registro acima ao manipulador de manifesto para criar 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 que contém 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

Reproduzir o stream

Carregue o manifesto que você recebeu do servidor de manipulação 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 primeira etapa. Essa etapa precisa ocorrer depois que você receber o manifesto costurado do manipulador de manifesto. Em troca, você recebe 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 fluxo. As chaves são os primeiros 17 caracteres do ID de um evento de anúncio que aparecem nos metadados temporizados do stream ou, no caso de eventos do tipo progress, 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 Disparada no final do terceiro quartil. complete Disparado no fim do anúncio. progress É disparado periodicamente durante o 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 descrevem 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 esse anúncio aparece no conjunto de anúncios no intervalo de vídeo, em segundos de ponto flutuante. duration A duração do anúncio em segundos de ponto flutuante. clickthrough_url O URL que será aberto quando um usuário interagir com o anúncio, se houver suporte.
ad_breaks	Um conjunto de pares de chave-valor que descreve todos os intervalos de anúncios 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 (precedente), mid (intermediário) e post (final). duration A duração do intervalo de anúncio em segundos de ponto flutuante. ads O número de anúncios nesse intervalo.

Armazene esses valores para associar a eventos de metadados temporizados 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 temporizados por eventos de anúncios acionados no fluxo de áudio/vídeo do seu player de vídeo.

Para transmissões 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_ seguido por uma série de caracteres. Esse valor é o ID do evento do anúncio.

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

Exemplo de tag ID3

TXXXgoogle_1234567890123456789

Para fluxos MP4, eles são enviados como eventos emsg na 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 message_data que começa com ID3TXXXgoogle_. Esse valor message_data, sem o prefixo ID3TXXX, é o ID do evento do 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 vai ser esta:

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

Algumas bibliotecas de media player apresentam automaticamente eventos emsg que emulam tags ID3 como tags ID3 nativas. Nesse caso, os streams de MP4 apresentam tags ID3 idênticas como MPEG_TS.

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

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

1. Verifique se o objeto tags tem uma chave que corresponde ao ID completo do evento de anúncio. Se uma correspondência for encontrada, extraia 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 completo do evento de anúncio, verifique no objeto tags se há uma chave que corresponda aos primeiros 17 caracteres do ID do evento de anúncio. Extraia o tipo de evento e os objetos ad e ad_break associados. Isso vai recuperar todos os eventos com tipos diferentes de progress.

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

Exemplos de IDs de eventos de anúncios

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 for recebido.

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

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

Dica: os eventos de anúncio do tipo progress não devem ser enviados ao Ad Manager. Esses eventos têm como objetivo informar ao app de player de vídeo do cliente que um intervalo de anúncio está sendo reproduzido em situações em que o evento de início pode não ter sido recebido. Por exemplo, se o usuário procurar uma posição ou iniciar a reprodução em um carimbo de data/hora específico no meio de um anúncio, ele não vai receber um evento de início. Os eventos de progresso enviados ao Ad Manager são descartados, o que pode afetar negativamente a performance de um app.

Exemplo de solicitação (cURL)

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

Exemplo de resposta bem-sucedida

HTTP/1.1 202 Accepted

Outros recursos

• Documentação do SDK do IMA
• Comparação dos tipos de implementação do player da DAI