Antes de começar
Este guia aborda somente as instruções de reprodução na ausência do SDK de DAI do IMA.
Verifique se você já concluiu as etapas Integrar o Google Ad Manager (GAM) a transmissões ao vivo de antemão.
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 fazer isso, você precisará das seguintes informações:
| Local |
O
Região do Google Cloud
em que a configuração em tempo real foi criada:
LOCATION
|
| Número do projeto |
O número do projeto do Google Cloud que usa o integrador de vídeos
API:
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 Leia mais sobre criação de tokens OAuth de curta duração. |
| Código da rede |
O código de rede do Ad Manager para solicitar anúncios:
NETWORK_CODE
|
| ID de configuração ativa |
O ID de configuração ao vivo que você especificou ao criar seu 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
criar uma configuração para um evento de transmissão ao vivo;
com a API Video Stitcher:
CUSTOM_ASSET_KEY
|
Fazer uma solicitação de registro de stream para o Ad Manager
Faça uma solicitação POST para o endpoint de registro do stream. Em troca, você recebe uma resposta JSON contendo o ID do stream para enviar à API de agrupamento 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 por formulário
Um conjunto opcional de tags codificadas por formulário parâmetros de segmentação
JSON de resposta
media_verification_url |
O URL base para dar um ping em eventos de rastreamento de reprodução. Uma verificação de mídia completa
O URL é formado pela anexação de um ID de evento de anúncio a esse URL de 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 pesquisar o "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é o término da sessão de transmissão atual em
dhms (dias, horas, minutos, segundos). Por exemplo:
2h0m0.000s representa uma duração de duas horas.
|
valid_until |
O horário em que a sessão de stream atual expira, como um ISO 8601
string de data e hora em 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 resposta JSON. corpo
Analise a resposta JSON e armazene os valores relevantes.
Gerar o URI de reprodução da sessão
Faça uma solicitação POST ao endpoint /livesessions da API de integrador de vídeos 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 |
O
Região do Google Cloud
em que a configuração em tempo real foi criada:
LOCATION
|
Parâmetro de cabeçalho de autorização
OAUTH_TOKEN |
Um token OAuth de curta duração de uma conta de serviço com o usuário do integrador de vídeo
função:
OAUTH_TOKEN |
Parâmetros de corpo codificados em JSON
liveConfig |
Uma string que contém o número do projeto
location e live config id pelos
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 e que contém o ID da sessão. |
playUri |
O URI do manifesto de fluxo agrupado, a ser carregado no player de vídeo
para reprodução.
PLAY_URI
|
liveConfig |
A mesma string liveConfig enviada à API na solicitação
corpo
|
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á assistir a transmissão ao vivo com o anúncio ao
fazer 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 recuperada da última seção do campo name
do objeto de resposta.
Uma sessão inativa expira após 5 minutos. Uma sessão é considerado inativo se não houver buscas de manifesto em um período de tempo de resposta.
Consultar novos metadados do AdBreak
O aplicativo é responsável por recuperar os metadados de cada intervalo de anúncio.
saiba 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 sondagem é especificado no polling_frequency.
na resposta de registro do stream.
Em troca, você recebe um objeto JSON contendo os seguintes parâmetros:
tags |
Um conjunto de pares de chave-valor descrevendo os eventos de mídia do anúncio que ocorrerão
no fluxo. Cada chave consiste nos 17 primeiros caracteres de
um ID de mídia do anúncio que vai aparecer nos metadados ID3 do stream ou na
caso de eventos `progress`, o ID da mídia do anúncio inteiro. Cada valor é um
com as seguintes propriedades:
|
ads |
Um conjunto de pares de chave-valor descrevendo os anúncios que serão exibidos no
riacho. Cada chave é um ID de anúncio. Cada valor é um objeto com o seguinte
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
com as seguintes propriedades:
|
Armazene esses valores após cada enquete para associar eventos de metadados com marcação de tempo seu stream 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
},
...
}
}
Detecte eventos ID3 e acompanhe os eventos de reprodução
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 do player ou em uma frequência definida (500 ms recomendado), verifique a fila de eventos de mídia para ver os eventos reproduzidos recentemente por comparando os carimbos de data/hora dos eventos com o marcador.
- Para eventos de mídia que você confirmou que foram reproduzidos, verifique o tipo pesquisando. o ID de mídia nas tags de intervalo de anúncio armazenadas. As tags de intervalo de anúncio contém somente uma versão truncada do ID de mídia, limitado ao primeiros 10 dígitos após o prefixo google_, para que não haja uma correspondência direta entre as chaves e os IDs de verificação de mídia ID3 no objeto de tags. Isso é para impedir que pings de verificação de evento sejam enviados antes do evento ID3 chega. 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.
- Usar "progresso" para acompanhar se um usuário está em um intervalo de anúncio. Não envie esses eventos ao endpoint de verificação de mídia para evitar uma solicitação código de erro. Para outros tipos de evento, anexe o ID da mídia de verificação e fazer uma solicitação GET para rastrear 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
Ao usar a API em WebViews, as seguintes limitações se aplicam com 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 foi transmitido corretamente, o que
limita a funcionalidade dos seguintes recursos:
- Limite de frequência
- Rotação sequencial de anúncios
- Segmentação de público-alvo