Antes de começar
Este guia abrange apenas as instruções de reprodução na ausência do SDK do IMA DAI.
Verifique se você já concluiu as etapas em Integrar o Google Ad Manager (GAM) a transmissões ao vivo antes.
Se o SDK do IMA não estiver disponível para a plataforma pretendida, o aplicativo precisará chamar as APIs necessárias e acionar as impressões de anúncios.
Para isso, você vai precisar das seguintes informações:
| Local |
A
região do Google Cloud
em que a configuração ativa foi criada:
LOCATION
|
| Número do projeto |
O número do projeto do Google Cloud que usa a API Video Stitcher:
PROJECT_NUMBER
|
| Token OAuth |
Um token OAuth de curta duração de uma conta de serviço com a função de usuário do Video Stitcher:
OAUTH_TOKEN Saiba mais sobre como criar tokens OAuth de curta duração. |
| Código de rede |
O código de rede do Ad Manager para solicitar anúncios:
NETWORK_CODE
|
| ID da configuração ao vivo |
O ID da configuração ao vivo que você especificou ao criar o evento de transmissão ao vivo:
LIVE_CONFIG_ID
|
| Chave de recurso personalizada |
A chave de recurso personalizada do Ad Manager gerada durante o processo de
criação de uma configuração para um evento de transmissão ao vivo
com a API Video Stitcher:
CUSTOM_ASSET_KEY
|
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. Em troca, você recebe uma resposta JSON contendo o ID do stream para enviar à API de junção de vídeos.
endpoint de API
POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
Parâmetros de caminho
NETWORK_CODE |
Seu código de rede do Google Ad Manager 360:
NETWORK_CODE
|
CUSTOM_ASSET_KEY |
O identificador personalizado associado a este evento no Google Ad Manager:
CUSTOM_ASSET_KEY
|
Parâmetros de corpo codificados em formulário
Um conjunto opcional de parâmetros de segmentação codificados em formulá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 do evento do anúncio a esse URL base.
MEDIA_VERIFICATION_URL
|
metadata_url |
O URL para solicitar metadados do conjunto de anúncios.
METADATA_URL
|
polling_frequency |
a frequência recomendada em milissegundos para consultar a "metadata_url".
POLLING_FREQUENCY
|
stream_id |
A string usada para identificar a sessão de transmissão atual.
STREAM_ID
|
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 transmissão 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/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/streamExemplo de resposta
{
"stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
"media_verification_url":"https://dai.google.com/.../media/",
"metadata_url":"https://dai.google.com/.../metadata",
"session_update_url":"https://dai.google.com/.../session",
"polling_frequency":10
}
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.
Gerar o URI de reprodução da sessão
Faça uma solicitação POST para o endpoint /livesessions da API Video Stitcher para
criar uma nova sessão ao vivo. Em troca, você recebe uma resposta JSON contendo
o manifesto de streaming para carregar no seu player de vídeo.
endpoint de API
POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json
Parâmetros de caminho
PROJECT_NUMBER |
O número do projeto do Google Cloud que usa a API Video Stitcher:
PROJECT_NUMBER
|
LOCATION |
A
região do Google Cloud
em que a configuração ativa foi criada:
LOCATION
|
Parâmetro do cabeçalho de autorização
OAUTH_TOKEN |
Um token OAuth de curta duração de uma conta de serviço com a função de usuário do Video Stitcher:
OAUTH_TOKEN |
Parâmetros de corpo codificados em JSON
liveConfig |
Uma string que contém o número do projeto, o local e o ID da configuração em tempo real com o seguinte formato:
projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID
|
adTracking |
Defina como "CLIENT" para ativar o rastreamento do lado do cliente. |
gamSettings |
Um objeto que contém o ID do stream com o seguinte
formato:
{"streamId":"STREAM_ID"}
|
JSON de resposta
name |
O nome da sessão ao vivo, que contém o ID da sessão. |
playUri |
O URI do manifesto de stream costurado, para carregar no player de vídeo
para reprodução.
PLAY_URI
|
liveConfig |
A mesma string liveConfig enviada para a API no corpo da solicitação.
|
gamSettings |
O mesmo objeto gamSettings enviado para a API no corpo da solicitação.
|
Exemplo de solicitação (cURL)
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer OAUTH_TOKEN" \
-d '@request.json' \
https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessionsrequest.json
{
"liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
"adTracking": "CLIENT",
"gamSettings": {
"streamId": "STREAM_ID"
}
}
Exemplo de resposta
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
"playUri": PLAY_URI,
"liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
"gamSettings": {
"streamId": STREAM_ID
}
}
Depois que a resposta for recebida, você poderá reproduzir a transmissão ao vivo com anúncios
fazendo referência ao URI de reprodução da sessão do campo playUri do
objeto de resposta.
A API Video Stitcher gera um ID de sessão exclusivo para
cada solicitação, que pode ser recuperado na última seção do campo name
do objeto de resposta.
Uma sessão inativa expira após 5 minutos. Uma sessão é considerada inativa se não houver nenhuma busca de manifesto em um período de tempo.
Consultar novos metadados do AdBreak
O aplicativo é responsável por recuperar metadados de cada intervalo de anúncio para saber quais impressões precisam ser acionadas. Para isso, defina um
timer para consultar regularmente as APIs DAI metadata_url em busca de novas informações
do anúncio. O intervalo de pesquisa é especificado no campo polling_frequency
da resposta de registro do stream.
Em troca, você recebe um objeto JSON com os seguintes parâmetros:
tags |
Um conjunto de pares de chave-valor que descrevem eventos de mídia de anúncios que vão ocorrer
no stream. Cada chave consiste nos primeiros 17 caracteres de
um ID de mídia do anúncio que vai aparecer nos metadados ID3 do fluxo ou, no
caso de eventos de "progresso", o ID de mídia do anúncio completo. Cada valor é um
objeto com as seguintes propriedades:
|
ads |
Um conjunto de pares de chave-valor que descrevem os anúncios que vão aparecer no
stream. Cada chave é um ID de anúncio. Cada valor é um objeto com as seguintes
propriedades:
|
ad_breaks |
Um conjunto de pares de chave-valor que descrevem os intervalos de anúncios que vão ocorrer
no stream. Cada chave é um ID de intervalo de anúncio. Cada valor é um
objeto com as seguintes propriedades:
|
Armazene esses valores após cada pesquisa para associar eventos de metadados cronometrados no fluxo de vídeo.
Exemplo de solicitação (cURL)
curl https://dai.google.com/.../metadata/Exemplo de resposta
{
"tags":{
"google_0492266569":{
"ad":"0000229836_ad1",
"ad_break_id":"0000229836",
"type":"firstquartile"
},
"google_1560331148":{
"ad":"0000229836_ad1",
"ad_break_id":"0000229836",
"type":"thirdquartile"
},
"google_1877686714378797835":{
"ad":"0000229836_slate",
"ad_break_id":"0000229836",
"type":"progress"
},
"google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
"ad":"0000229835_ad1",
"ad_break_id":"0000229835",
"type":"progress"
},
"google_2032765498":{
"ad":"0000229835_ad1",
"ad_break_id":"0000229835",
"type":"midpoint"
},
...
"google_5646900623":{
"ad":"0000229837_ad1",
"ad_break_id":"0000229837",
"type":"complete"
}
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15.01,
"title":"truman-e2e-creativeset4",
"description":"truman-e2e-creativeset4 ad",
"ad_system":"GDFP",
"ad_id":"39066884",
"creative_id":"58092079124",
"clickthrough_url":"https://pubads.g.doubleclick.net/...",
"universal_ad_id":{
"id_value":"58092079124",
"id_registry":"GDFP"
}
},
"0000229834_slate":{
"ad_break_id":"0000229834",
"position":-1,
"duration":14.974977777,
"slate":true
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15.01,
"expected_duration":29.984977776999997,
"ads":1
},
...
}
}
Ouvir eventos ID3 e eventos de reprodução da faixa
Para verificar se eventos específicos ocorreram em uma transmissão de vídeo, siga estas etapas para processar eventos ID3:
- Armazene os eventos de mídia em uma fila, salvando cada ID de mídia com o carimbo de data/hora, se mostrado pelo player.
- Em cada atualização de tempo do player ou em uma frequência definida (500 ms recomendado), verifique a fila de eventos de mídia para eventos reproduzidos recentemente comparando os carimbos de data/hora do evento com o indicador de reprodução.
- Para eventos de mídia que você confirma que foram reproduzidos, verifique o tipo procurando o ID de mídia nas tags de intervalo de anúncio armazenadas. Lembre-se de que o objeto de tags de intervalo de anúncio contém apenas uma versão truncada do ID de mídia, limitada aos primeiros 10 dígitos após o prefixo google_. Portanto, não há uma correspondência direta entre os IDs de verificação de mídia ID3 e as chaves no objeto de tags. Isso evita que os pings de verificação de evento sejam enviados antes que o evento ID3 chegue. 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 media_verification_url da resposta de criação de stream.
- Use eventos de "progresso" para acompanhar se um usuário está em um intervalo de anúncio. Não envie esses eventos para o endpoint de verificação de mídia para evitar um código de erro HTTP. Para outros tipos de evento, anexe o ID da mídia ao URL de verificação de mídia e faça uma solicitação GET para acompanhar a reprodução.
- Remova o evento de mídia da fila.
endpoint de API
GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com
Parâmetros de caminho
MEDIA_VERIFICATION_URL |
O valor retornado pelo endpoint de registro do stream, no campo media_verification_url:
MEDIA_VERIFICATION_URL
|
AD_MEDIA_ID |
O ID completo da mídia do anúncio, conforme aparece nos metadados ID3 do stream:
AD_MEDIA_ID
|
Valores de retorno esperados
HTTP/1.1 204 No Content |
Resposta vazia bem-sucedida. |
HTTP/1.1 404 Not Found |
O ID de verificação de mídia não foi reconhecido. |
HTTP/1.1 409 Conflict |
O ID de verificação de mídia já foi enviado. |
Exemplo de solicitação (cURL)
curl MEDIA_VERIFICATION_URLAD_MEDIA_IDExemplo de resposta
HTTP/1.1 204 No Content
Limitações
Se você usar a API em visualizações da Web, as seguintes limitações serão aplicadas em relação à segmentação:
- UserAgent: o parâmetro do user agent é transmitido como um valor específico do navegador, em vez da plataforma subjacente.
- rdid, idtype, is_lat: o ID do dispositivo não é transmitido corretamente, o que
limita a funcionalidade dos seguintes recursos:
- Limite de frequência
- Rotação sequencial de anúncios
- Segmentação e segmentação por público-alvo