Com a API Dynamic Ad Insert, é possível solicitar e acompanhar streams lineares (AO VIVO) da DAI.
Serviço: dai.google.com
Todos os URIs abaixo são relativos a https://dai.google.com
Método: stream
Métodos | |
---|---|
stream |
POST /linear/v1/hls/event/{assetKey}/stream
Cria um stream de DAI para o ID de evento fornecido. |
Solicitação HTTP
POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream
Cabeçalho da solicitação
Parâmetros | |
---|---|
api‑key |
string A chave de API fornecida ao criar um stream precisa ser válida para a rede do editor. Em vez de fornecê-la no corpo da solicitação, a chave de API pode ser transmitida no cabeçalho da autorização HTTP com o seguinte formato: Authorization: DCLKDAI key="<api-key>" |
Parâmetros de caminho
Parâmetros | |
---|---|
assetKey |
string ID do evento da transmissão. |
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 | ||
---|---|---|
dai-ssb |
Opcional | Defina como |
Parâmetros de segmentação do DFP | Opcional | Parâmetros de segmentação adicionais. |
Substituir os parâmetros do stream | Opcional | Modifique os valores padrão de um parâmetro de criação de stream. |
Autenticação HMAC | Opcional | Faça a autenticação usando um token baseado em HMAC. |
Corpo da resposta
Se a solicitação for bem-sucedida, o corpo da resposta incluirá uma nova
Stream
. Para streams de beacon do lado do servidor, Stream
contém apenas os campos stream_id
e stream_manifest
.
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 e verificar a reprodução do criativo. Somente JavaScriptResource
é compatível. Para mais informações, consulte o IAB Tech Lab e a especificação VAST 4.1.
Método: verificação de mídia
Depois de encontrar um identificador de mídia do anúncio durante a reprodução, faça uma solicitação imediatamente usando o media_verification_url recebido do endpoint stream acima. Essas solicitações não são necessárias para fluxos de beacon 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 sobre 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 a formatação ou expiração do URL incorreta.HTTP/1.1 404 Not Found
se uma solicitação de verificação anterior desse ID for bem-sucedida.HTTP/1.1 409 Conflict
se outra solicitação já estiver enviando pings no momento.
IDs de mídia do anúncio (HLS)
Os identificadores de mídia do anúncio serão codificados em metadados com marcação de tempo HLS usando a chave
TXXX
, reservada para frames de "informações de texto definidas pelo usuário". O
conteúdo do frame não será criptografado e sempre vai começar com o texto
"google_"
.
Todo o conteúdo de texto do frame precisa ser anexado ao URL de verificação do anúncio antes de cada solicitação de verificação.
Método: metadata
O endpoint de metadados em metadata_url
retorna informações usadas para criar uma interface
do anúncio. O endpoint de metadados não está disponível para streams de beacon do servidor,
em que o servidor é responsável por iniciar a verificação da mídia de 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 for bem-sucedida, a resposta retornará uma instância de
PodMetadata
.
Como trabalhar com metadados
Os metadados têm três seções distintas: tags
, ads
e breaks
do anúncio. O ponto de entrada nos dados é a seção tags
. A partir daí, navegue pelas tags
e encontre a primeira entrada, cujo nome é 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 do anúncio semelhante a 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 correto do prefixo de mídia do anúncio, 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úncio, para indexar os objetos breaks
.
Dados de resposta
Fluxo
O stream é usado para renderizar uma lista de recursos de um stream recém-criado no formato JSON.Representação JSON |
---|
{ "stream_id": string, "stream_manifest": string, "hls_master_playlist": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "polling_frequency": number, } |
Campos | |
---|---|
stream_id |
string O identificador de stream do GAM. |
stream_manifest |
string O URL do manifesto do stream, usado para recuperar a playlist multivariante em HLS ou o MPD em DASH. |
hls_master_playlist |
string (DESCONTINUADO) URL da playlist multivariante de HLS. Use "stream_manifest". |
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 pesquisar informações periódicas sobre os próximos eventos de anúncios de streaming. |
session_update_url |
string O URL de atualização da sessão usado para mudar os parâmetros de segmentação desse stream. Os valores originais dos parâmetros de segmentação são capturados durante a solicitação inicial de criação de stream. |
polling_frequency |
number Frequência de pesquisa, em segundos, ao solicitar metadata_url ou Heartbeat_url. |
PodMetadata
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 dos segmentos de tag indexados por prefixo de tag. |
ads |
map[string, object(Ad)] Mapa de anúncios indexados por ID do anúncio. |
ad_breaks |
map[string, object(AdBreak)] Mapa de intervalos de anúncio indexados por ID de intervalo de anúncio. |
TagSegment
Tagsegment contém uma referência a um anúncio, seu intervalo de anúncio e tipo de evento. Tagsegment com type="progress" não pode receber um ping no 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 desta tag. |
type |
string O tipo de evento desta tag. |
AdBreak
O 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é, intermediário e pós. |
duration |
number Duração total do anúncio para este 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 barreira. |
ads |
number Número de anúncios no intervalo de anúncio. |
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 ID do intervalo de anúncio deste anúncio. |
position |
number Posição do anúncio no intervalo de anúncio, 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 opcional do anunciante. |
ad_system |
string Sistema de anúncios opcional. |
ad_id |
string ID do anúncio opcional. |
creative_id |
string ID opcional do criativo. |
creative_ad_id |
string ID opcional do anúncio do criativo. |
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 opcionais do Open Measurement que listam os recursos e metadados necessários para executar o código de medição de terceiros e verificar a reprodução de criativos. |
slate |
boolean Booleano opcional indicando que a entrada atual é barreira. |
icons |
[object(Icon)] Uma lista de ícones, omitida se estiver vazia. |
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 de <Extension> no VAST. |
companions |
[object(Companion)] Complementares opcionais que podem ser exibidos com este anúncio. |
interactive_file |
object(InteractiveFile) Criativo interativo opcional (SIMID) que deve ser exibido durante a reprodução do anúncio. |
Icon
Ícone que 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
ClickData contém informações sobre o clique de um ícone.Representação JSON |
---|
{ "url": string, } |
Campos | |
---|---|
url |
string |
FallbackImage
FallbackImage contém informações sobre uma imagem substituta 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
O 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 wrapper. |
creative_id |
string ID do criativo usado para o anúncio wrapper. |
creative_ad_id |
string ID do anúncio 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 do Open Measurement, o que facilita a visibilidade e a medição da verificação de terceiros. Atualmente, só há suporte para recursos JavaScript. 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 foi 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 o payload do JavaScript. |
api_framework |
string APIFramework é o nome do framework de vídeo que aplica o código de verificação. |
browser_optional |
boolean Define se este script pode ser executado fora de um navegador. |
TrackingEvent
O TrackingEvent contém URLs que devem 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 rastreamento que receberá o 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. |
id_registry |
string Uma string usada para identificar o URL do site de registro em que o ID universal do anúncio do criativo selecionado é catalogado. |
Complementar
O complementar contém informações para anúncios complementares que podem ser exibidos junto 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 clique deste complementar. |
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 do complementar. |
width |
int32 A largura em pixels deste complementar. |
resource |
string Para complementares estáticos e iframe, esse será o URL a ser carregado e exibido. Para complementares HTML, é o snippet HTML que deve ser mostrado como o complementar. |
type |
string Tipo do complementar. Ele pode ser estático, iframe ou HTML. |
ad_slot_id |
string O ID do espaço deste complementar. |
api_framework |
string O framework da API para esse complemento. |
tracking_events |
[object(TrackingEvent)] Lista de eventos de rastreamento para este complementar. |
InteractiveFile
InteractiveFile contém informações do criativo interativo (ou seja, SIMID) que precisa ser exibido 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 para o criativo interativo. |
type |
string O tipo MIME do arquivo fornecido como o recurso. |
variable_duration |
boolean Se este criativo pode pedir a extensão da duração. |
ad_parameters |
string O valor do nó <AdParameters> no VAST. |