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/x-www-form-urlencoded
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/a-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. 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
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:
|
||||||||||||||||||
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_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:
|
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:
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 objetosad
ead_break
associados. Esses eventos precisam ter o tipoprogress
.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 objetosad
ead_break
associados. Isso recupera todos os eventos com tipos diferentes deprogress
.Use as informações recuperadas para atualizar a interface do jogador. Por exemplo, quando você receber um
start
ou o primeiro eventoprogress
, 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