A API Dynamic Ad Insertion permite solicitar e acompanhar transmissões ao vivo da DAI.
Serviço: dai.google.com
Todos os URIs são relativos a https://dai.google.com
.
Método: stream
Métodos | |
---|---|
stream |
POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream
Registra uma sessão de transmissão ao vivo do conjunto DAI. |
Solicitação HTTP
POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream
Parâmetros de caminho
Parâmetros | |
---|---|
network_code |
string
O código de rede do Google Ad Manager do editor. |
custom_asset_key |
string
O identificador personalizado associado a esse evento no Google Ad Manager. |
Corpo da solicitação
O corpo da solicitação é do tipo application/x-www-form-urlencoded
e contém os
seguintes parâmetros:
Parâmetros | ||
---|---|---|
Parâmetros de segmentação do DFP | Opcional | Parâmetros de segmentação adicionais. |
Modificar os parâmetros do stream | Opcional | Substitua os valores padrão de um parâmetro de criação de stream. |
Autenticação HMAC | Opcional | Autenticar usando um token baseado em HMAC. |
Corpo da resposta
Se a solicitação for concluída, o corpo da resposta conterá um novo objeto Stream
.
Open Measurement
A API DAI contém informações para a verificação do Open Measurement no campo
Verifications
. Esse campo contém um ou mais
elementos Verification
que listam os recursos e metadados necessários para executar
o código de medição de terceiros para verificar a reprodução do criativo. Somente
JavaScriptResource
é aceito. Para mais informações, consulte o
IAB Tech Lab e a
especificação VAST 4.1.
Método: segmento do conjunto
Métodos | |
---|---|
pod segment |
GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}
Cria um stream da DAI para o ID de evento especificado. |
Solicitação HTTP
GET https://dai.google.com/linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}
Parâmetros de caminho
Parâmetros | |
---|---|
network_code |
string
O código de rede do Google Ad Manager do editor. |
custom_asset_key |
string
É o identificador personalizado associado a este evento no Google Ad Manager. |
pod_identifier |
Os seguintes formatos são compatíveis: pod/{integer}
É o identificador numérico do intervalo de anúncio atual. Os IDs de conjuntos de anúncios são
atribuídos de modo incremental para cada evento de intervalo de anúncio, começando em
ad_break_id/{string}
O identificador de string do intervalo de anúncio atual. |
profile_name |
string
O nome do perfil de codificação de DAI do Google Ad Manager solicitado. O perfil de codificação precisa ser um dos perfis configurados para o evento selecionado. |
segment_number |
integer
O índice do segmento solicitado no conjunto de anúncios atual, começando em zero. |
segment_format |
string
A extensão de arquivo associada ao formato de segmento solicitado.
As extensões aceitas são: |
Parâmetros de consulta
Parâmetros | ||||||
---|---|---|---|---|---|---|
stream_id |
required |
string
O ID do stream da sessão do usuário atual. Esse valor é retornado por
uma solicitação bem-sucedida para o endpoint |
||||
sd |
required1
|
integer
A duração do segmento solicitado, em milissegundos. |
||||
so |
opcional |
O deslocamento do segmento solicitado dentro do conjunto de anúncios, em milissegundos.
Se você omitir o parâmetro |
||||
pd |
obrigatório2 |
integer
É a duração do conjunto de anúncios, em milissegundos. |
||||
auth-token |
required |
string
Um token HMAC assinado e codificado em URL para o conjunto de anúncios atual. |
||||
last |
opcional |
boolean
Indica o último segmento no intervalo de anúncio. Omita esse parâmetro para todos os outros segmentos. |
||||
scte35 |
opcional |
string
Indicador SCTE-35 codificado em base64 para este intervalo de anúncio. |
||||
cust_params |
opcional |
string
Um conjunto de pares de chave-valor usado para a segmentação de campanhas do Ad Manager. Esses pares precisam ser representados como uma string de consulta codificada pelo URL. Exemplo:
|
Notas de rodapé
-
sd
não é obrigatório para segmentos de inicialização. ↩ -
pd
não é necessário para eventos com intervalos de anúncio sem duração ativados. ↩
Exemplo
GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/ad_break_id/adbreak-2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST
GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/pod/2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST
Corpo da resposta
Se for bem-sucedido, o corpo da resposta será um segmento de transmissão reproduzível que corresponde ao formato e aos parâmetros especificados na solicitação.
Método: manifesto do pod HLS
Recupera um manifesto de bloco de anúncios HLS de uma transmissão ao vivo que está pronto para ser carregado e reproduzido por um player de vídeo do cliente.
Métodos | |
---|---|
GET |
GET /linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset}/pod/{pod_id}.m3u8;
API para recuperar uma playlist multivariante HLS para um conjunto de anúncios. |
Solicitação HTTP
GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}.m3u8?stream_id={stream_id}&pd={pod_duration}
Parâmetros de caminho
Parâmetros | |
---|---|
network_code |
string
O código de rede do Google Ad Manager do editor. |
custom_asset_key |
string
O identificador personalizado associado a este evento no Google Ad Manager. |
pod_id |
integer
O identificador numérico do intervalo de anúncio atual. Os IDs de bloco de anúncios são
atribuídos de forma incremental para cada evento de intervalo de anúncio, começando em
|
Parâmetros de consulta
Parâmetros | ||||||
---|---|---|---|---|---|---|
stream_id |
Obrigatório |
string
O código de stream da sessão do usuário atual. Esse valor é retornado por uma solicitação bem-sucedida para o endpoint |
||||
pd |
Obrigatório |
integer
A duração do conjunto de anúncios, em milissegundos. |
||||
scte35 |
opcional |
string
Indicador SCTE-35 codificado em base64 para este intervalo de anúncio. |
||||
cust_params |
opcional |
string
Um conjunto de pares de chave-valor usado para a segmentação de campanhas do Ad Manager. Esses pares precisam ser representados como uma string de consulta codificada pelo URL. Exemplo:
|
Corpo da resposta
Se bem-sucedido, o corpo da resposta será uma playlist multivariante de HLS.
Método: manifesto do pod DASH
Recupera um manifesto de conjunto de anúncios MPEG-DASH de uma transmissão ao vivo que está pronta para ser carregada e reproduzida por um player de vídeo do cliente.
Métodos | |
---|---|
GET |
GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset}/stream/{stream_id}/pod/{pod_id}/manifest.mpd
API para recuperar uma playlist mpd MPEG-DASH para um conjunto de anúncios. |
Solicitação HTTP
GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/stream/{stream_id}/pod/{pod_id}/manifest.mpd?pd={pod_duration}
Parâmetros de caminho
Parâmetros | |
---|---|
network_code |
string
O código de rede do Google Ad Manager do editor. |
custom_asset_key |
string
O identificador personalizado associado a esse evento no Google Ad Manager |
stream_id |
string
O ID do stream da sessão do usuário atual. Esse valor é retornado
por uma solicitação bem-sucedida ao endpoint |
pod_id |
integer
O identificador numérico do intervalo de anúncio atual. Os IDs de conjuntos de anúncios são
atribuídos de modo incremental para cada evento de intervalo de anúncio, começando em
|
Parâmetros de consulta
Parâmetros | ||||||
---|---|---|---|---|---|---|
pd |
Obrigatório |
integer
A duração do conjunto de anúncios, em milissegundos. |
||||
scte35 |
opcional |
string
Indicador SCTE-35 codificado em base64 para este intervalo de anúncio. |
||||
cust_params |
opcional |
string
Um conjunto de pares de chave-valor usado para a segmentação de campanhas do Ad Manager. Esses pares precisam ser representados como uma string de consulta codificada pelo URL. Exemplo:
|
Corpo da resposta
Se bem-sucedido, o corpo da resposta será uma playlist mpd MPEG-DASH.
Método: modelo de período de pod DASH
Métodos | |
---|---|
pods |
GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json
Solicita um modelo de período do DASH do Google Ad Manager. Esse modelo contém macros que você precisa preencher com os parâmetros do stream. Depois que essas macros forem preenchidas, o modelo vai se tornar o período de intervalo de anúncio e poderá ser integrado ao seu manifesto DASH. |
Solicitação HTTP
GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json
Parâmetros de caminho
Parâmetros | |
---|---|
network_code |
string
O código de rede do Google Ad Manager do editor. |
custom_asset_key |
string
É o identificador personalizado associado a este evento no Google Ad Manager. |
Parâmetros de consulta
Parâmetros | ||
---|---|---|
stream_id |
required |
string
O ID do stream da sessão do usuário atual. Esse valor é retornado por
uma solicitação bem-sucedida para o endpoint |
Corpo da resposta
Se a solicitação for bem-sucedida, o corpo da resposta incluirá um novo
objeto PodTemplateResponse
.
Método: verificação de mídia
Depois de encontrar um identificador de mídia do anúncio durante a reprodução, faça imediatamente uma solicitação usando o media_verification_url obtido do endpoint stream acima. Essas solicitações não são necessárias para transmissões de beacon do lado do servidor, em que o servidor inicia a verificação de mídia.
As solicitações para o endpoint media verification
são idempotentes.
Métodos | |
---|---|
media verification |
GET /{media_verification_url}/{ad_media_id}
Notifica a API de um evento de verificação de mídia. |
Solicitação HTTP
GET https://{media-verification-url}/{ad-media-id}
Corpo da resposta
media verification
retorna as seguintes respostas:
HTTP/1.1 204 No Content
se a verificação de mídia for bem-sucedida e todos os pings forem enviados.HTTP/1.1 404 Not Found
se a solicitação não puder verificar a mídia devido à formatação ou à expiração do URL incorreta.HTTP/1.1 404 Not Found
se uma solicitação de verificação anterior para esse ID tiver sido bem-sucedida.HTTP/1.1 409 Conflict
se outra solicitação já estiver enviando pings no momento.
IDs da mídia do anúncio
Os identificadores de mídia do anúncio serão codificados em uma faixa de metadados separada: metadados
cronometrados para o fluxo de transporte HLS ou emsg para arquivos mp4. Os identificadores de mídia de anúncios
sempre começam com a string google_
.
Todo o conteúdo de texto da entrada de metadados precisa ser anexado ao URL de verificação do anúncio antes de fazer cada solicitação de verificação de anúncio.
Método: metadata
O endpoint de metadados em metadata_url
retorna informações usadas para criar uma interface
de anúncios. O endpoint de metadados não está disponível para streams de beacon no servidor,
em que o servidor é responsável por iniciar a verificação da mídia do anúncio.
Métodos | |
---|---|
metadata |
GET /{metadata_url}/{ad-media-id} GET /{metadata_url}
Recupera informações de metadados do anúncio. |
Solicitação HTTP
GET https://{metadata_url}/{ad-media-id}
GET https://{metadata_url}
Corpo da resposta
Se funcionar, a resposta vai retornar uma instância de
PodMetadata
.
Como analisar metadados
Os metadados têm três seções distintas: tags
, ads
e anúncio breaks
. O ponto
de entrada nos dados é a seção tags
. Depois, itere as tags e encontre a primeira entrada cujo nome seja um prefixo do ID de mídia do anúncio encontrado no stream de vídeo. Por exemplo, você
pode ter um ID de mídia de anúncio parecido com este:
google_1234567890
Em seguida, você encontra um objeto de tag chamado google_12345
. Nesse caso, ele corresponde ao
ID da mídia do anúncio. Depois de encontrar o objeto de prefixo de mídia de anúncio correto, você pode procurar
IDs de anúncios, IDs de intervalos de anúncios e o tipo de evento. Os IDs de anúncios são usados para indexar os
objetos ads
, e os IDs de intervalo de anúncios são usados para indexar os objetos breaks
.
Dados de resposta
Stream
O stream é usado para renderizar uma lista de recursos para um stream recém-criado no formato JSON.Representação JSON |
---|
{ "stream_id": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "heartbeat_url": string, "polling_frequency": number, "pod_manifest_url": string, "manifest_format": string, } |
Campos | |
---|---|
stream_id |
string É o identificador de stream do GAM. |
media_verification_url |
string O URL de verificação de mídia usado como endpoint de base para rastrear eventos de reprodução. |
metadata_url |
string URL de metadados usado para consultar informações periódicas sobre os próximos eventos de anúncios do fluxo. |
session_update_url |
string O URL de atualização da sessão usado para atualizar os parâmetros de segmentação desse fluxo. Os valores originais dos parâmetros de segmentação são capturados durante a solicitação inicial de criação de fluxo. |
heartbeat_url |
string O URL do sinal de funcionamento, usado para manter o stream de beacon do servidor ativo, precisa receber um ping a cada {PollingFrequency} segundos. Preenchido para streams de beacon do lado do servidor. |
polling_frequency |
number A frequência de pesquisa, em segundos, ao solicitar metadata_url ou heartbeat_url. |
pod_manifest_url |
string O modelo de URL do manifesto do pod é usado para gerar o URL para extrair o manifesto do pod de um stream, correspondendo ao URL da playlist multivariante no HLS ou do MPD no DASH. Preenchido para eventos de transmissão ao vivo do tipo Inserção de anúncios dinâmicos POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType |
manifest_format |
string O formato do manifesto é o formato do manifesto recuperado do pod_manifest_url, traço ou hls. |
PodMetadata
O PodMetadata contém informações de metadados sobre anúncios, intervalos de anúncios e tags de ID de mídia.Representação JSON |
---|
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], } |
Campos | |
---|---|
tags |
map[string, object(TagSegment)] Mapa de segmentos de tags indexados por prefixo. |
ads |
map[string, object(Ad)] Mapa de anúncios indexados por ID do anúncio. |
ad_breaks |
map[string, object(AdBreak)] Mapa dos intervalos de anúncio indexados por ID. |
TagSegment
O segmento de tag contém uma referência a um anúncio, ao intervalo de anúncio e ao tipo de evento. O TagSegment com type="progress" não pode ser pingado para o endpoint de verificação de mídia do anúncio.Representação JSON |
---|
{ "ad": string, "ad_break_id": string, "type": string, } |
Campos | |
---|---|
ad |
string O ID do anúncio desta tag. |
ad_break_id |
string O ID do intervalo de anúncio da tag. |
type |
string Tipo de evento desta tag. |
AdBreak
"AdBreak" descreve um único intervalo de anúncio no stream. Ele contém uma duração, um tipo (meio/pré/pós) e o número de anúncios.Representação JSON |
---|
{ "type": string, "duration": number, "expected_duration": number, "ads": number, } |
Campos | |
---|---|
type |
string Os tipos de intervalo válidos são: pré, meio e pós. |
duration |
number Duração total do anúncio para esse intervalo de anúncio, em segundos. |
expected_duration |
number Duração esperada do intervalo de anúncio (em segundos), incluindo todos os anúncios e qualquer slate. |
ads |
number Número de anúncios no intervalo. |
Anúncio
O anúncio descreve um anúncio no stream.Representação JSON |
---|
{ "ad_break_id": string, "position": number, "duration": number, "title": string, "description": string, "advertiser": string, "ad_system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, "clickthrough_url": string, "click_tracking_urls": [], "verifications": [object(Verification)], "slate": boolean, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "universal_ad_id": object(UniversalAdID), "extensions": [], "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
Campos | |
---|---|
ad_break_id |
string O ID do intervalo de anúncio. |
position |
number Posição deste anúncio no intervalo, começando em 1. |
duration |
number Duração do anúncio, em segundos. |
title |
string Título opcional do anúncio. |
description |
string Descrição opcional do anúncio. |
advertiser |
string Identificador do anunciante opcional. |
ad_system |
string Sistema de anúncios opcional. |
ad_id |
string ID do anúncio opcional. |
creative_id |
string ID do criativo opcional. |
creative_ad_id |
string ID do anúncio do criativo opcional. |
deal_id |
string ID da transação opcional. |
clickthrough_url |
string URL de clique opcional. |
click_tracking_urls |
string URLs de rastreamento de cliques opcionais. |
verifications |
[object(Verification)] Entradas de verificação de medição aberta opcionais que listam os recursos e metadados necessários para executar o código de medição de terceiros para verificar a reprodução do criativo. |
slate |
boolean Bool opcional que indica se a entrada atual é slate. |
icons |
[object(Icon)] Uma lista de ícones, omitidos se estiverem vazios. |
wrappers |
[object(Wrapper)] Uma lista de wrappers, omitida se estiver vazia. |
universal_ad_id |
object(UniversalAdID) ID universal do anúncio opcional. |
extensions |
string Lista opcional de todos os nós <Extension> no VAST. |
companions |
[object(Companion)] Complementares opcionais que podem ser mostrados com este anúncio. |
interactive_file |
object(InteractiveFile) Criativo interativo opcional (SIMID) que precisa ser mostrado durante a veiculação do anúncio. |
PodTemplateResponse
A PodTemplateResponse representa o payload JSON retornado para um VTP para a união de pods.Representação JSON |
---|
{ "dash_period_template": string, "segment_duration_ms": int64, } |
Campos | |
---|---|
dash_period_template |
string O DashPeriodTemplate é o modelo XML para o período que precisa ser preenchido com os dados apropriados antes do agrupamento. |
segment_duration_ms |
int64 SegmentDurationMS é a duração dos segmentos do período em milissegundos. |
Ícone
O ícone contém informações sobre um ícone VAST.Representação JSON |
---|
{ "click_data": object(ClickData), "creative_type": string, "click_fallback_images": [object(FallbackImage)], "height": int32, "width": int32, "resource": string, "type": string, "x_position": string, "y_position": string, "program": string, "alt_text": string, } |
Campos | |
---|---|
click_data |
object(ClickData) |
creative_type |
string |
click_fallback_images |
[object(FallbackImage)] |
height |
int32 |
width |
int32 |
resource |
string |
type |
string |
x_position |
string |
y_position |
string |
program |
string |
alt_text |
string |
ClickData
O ClickData contém informações sobre um clique no ícone.Representação JSON |
---|
{ "url": string, } |
Campos | |
---|---|
url |
string |
FallbackImage
FallbackImage contém informações sobre uma imagem de substituto do VAST.Representação JSON |
---|
{ "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, } |
Campos | |
---|---|
creative_type |
string |
height |
int32 |
width |
int32 |
resource |
string |
alt_text |
string |
Wrapper
Wrapper contém informações sobre um anúncio wrapper. Ele não incluirá um ID de transação se ele não existir.Representação JSON |
---|
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, } |
Campos | |
---|---|
system |
string Identificador do sistema de anúncios. |
ad_id |
string ID do anúncio usado para o anúncio de wrapper. |
creative_id |
string ID do criativo usado para o anúncio wrapper. |
creative_ad_id |
string ID do criativo usado para o anúncio wrapper. |
deal_id |
string ID da transação opcional para o anúncio wrapper. |
Verificação
A verificação contém informações sobre o Open Measurement, que facilita a medição de visibilidade e verificação de terceiros. Atualmente, apenas recursos JavaScript são compatíveis. Consulte https://iabtechlab.com/standards/open-measurement-sdk/Representação JSON |
---|
{ "vendor": string, "java_script_resources": [object(JavaScriptResource)], "tracking_events": [object(TrackingEvent)], "parameters": string, } |
Campos | |
---|---|
vendor |
string O fornecedor de verificação. |
java_script_resources |
[object(JavaScriptResource)] Lista de recursos JavaScript para a verificação. |
tracking_events |
[object(TrackingEvent)] Lista de eventos de rastreamento para a verificação. |
parameters |
string Uma string opaca transmitida para o código de verificação de inicialização. |
JavaScriptResource
JavaScriptResource contém informações para verificação via JavaScript.Representação JSON |
---|
{ "script_url": string, "api_framework": string, "browser_optional": boolean, } |
Campos | |
---|---|
script_url |
string URI para payload do JavaScript. |
api_framework |
string APIFramework é o nome do framework de vídeo que executa o código de verificação. |
browser_optional |
boolean Indica se esse script pode ser executado fora de um navegador. |
TrackingEvent
O TrackingEvent contém URLs que precisam receber um ping pelo cliente em determinadas situações.Representação JSON |
---|
{ "event": string, "uri": string, } |
Campos | |
---|---|
event |
string O tipo do evento de rastreamento. |
uri |
string O evento de acompanhamento que receberá um ping. |
UniversalAdID
O UniversalAdID é usado para fornecer um identificador de criativo exclusivo que é mantido em todos os sistemas de anúncios.Representação JSON |
---|
{ "id_value": string, "id_registry": string, } |
Campos | |
---|---|
id_value |
string O ID universal do anúncio do criativo selecionado para o anúncio. |
id_registry |
string Uma string usada para identificar o URL do site de registro em que o ID do anúncio universal do criativo selecionado está catalogado. |
Companion
O complementar contém informações sobre anúncios complementares que podem ser exibidos com o anúncio.Representação JSON |
---|
{ "click_data": object(ClickData), "creative_type": string, "height": int32, "width": int32, "resource": string, "type": string, "ad_slot_id": string, "api_framework": string, "tracking_events": [object(TrackingEvent)], } |
Campos | |
---|---|
click_data |
object(ClickData) Os dados de cliques do complemento. |
creative_type |
string O atributo CreativeType no nó <StaticResource> no VAST se for um complementar do tipo estático. |
height |
int32 A altura em pixels desse companheiro. |
width |
int32 A largura em pixels desse companheiro. |
resource |
string Para complementares estáticos e iframe, esse será o URL a ser carregado e exibido. Para complementares HTML, esse será o snippet de HTML que será exibido como complementar. |
type |
string Tipo do companheiro. Ele pode ser estático, iframe ou HTML. |
ad_slot_id |
string O ID do slot para esse companheiro. |
api_framework |
string O framework da API para esse complemento. |
tracking_events |
[object(TrackingEvent)] Lista de eventos de rastreamento deste complementar. |
InteractiveFile
O InteractiveFile contém informações sobre o criativo interativo (ou seja, SIMID) que precisa ser mostrado durante a reprodução do anúncio.Representação JSON |
---|
{ "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, } |
Campos | |
---|---|
resource |
string É o URL do criativo interativo. |
type |
string O tipo MIME do arquivo fornecido como recurso. |
variable_duration |
boolean Define se este criativo pode pedir uma extensão de duração. |
ad_parameters |
string O valor do nó <AdParameters> no VAST. |