API Linear de inserção de anúncios dinâmicos

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 fluxo da DAI para o código de evento especificado.

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 de autorização HTTP com o seguinte formato:

Authorization: DCLKDAI key="<api-key>"

Parâmetros de caminho

Parâmetros
assetKey string

O ID do evento do stream.
Observação: a chave do recurso de transmissão é um identificador que também pode ser encontrado na IU do 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
dai-ssb Opcional

Defina como true para criar um stream de beacon do lado do servidor. O valor padrão é false. O rastreamento do stream padrão é iniciado pelo cliente e recebe um ping no lado do servidor.
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 bem-sucedido, o corpo da resposta vai incluir um novo 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 de criativos. 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

Após encontrar um identificador de mídia de anúncio durante a reprodução, faça uma solicitação imediatamente usando o media_verification_url do endpoint stream acima. Essas solicitações não são necessárias para fluxos 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 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 à formatação ou expiração do URL incorreta.
  • HTTP/1.1 404 Not Found se uma solicitação de verificação anterior desse ID tiver sido bem-sucedida.
  • HTTP/1.1 409 Conflict se outra solicitação já estiver enviando pings nesse momento.

IDs de mídia do anúncio (HLS)

Os identificadores de mídia do anúncio serão codificados nos 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 do texto do frame precisa ser anexado ao URL de verificação do anúncio antes de 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 do 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 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 anúncio breaks. O ponto de entrada nos dados é a seção tags. Em seguida, percorra as 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, é possível ter um ID de mídia do anúncio parecido com este:

google_1234567890

Em seguida, você vai encontrar 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 de prefixo de mídia de 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

Streaming

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

Identificador do stream.
stream_manifest string

O manifesto do stream, correspondente à playlist principal em HLS ou ao MPD no DASH. Esse é o único campo além de "stream_id" que está presente na resposta ao criar um stream de beacon de servidor.
hls_master_playlist string

(Descontinuado) URL da playlist principal de HLS. Em vez disso, use "stream_manifest".
media_verification_url string

URL de verificação de mídia.
metadata_url string

URL de metadados da mídia do anúncio.
session_update_url string

URL de atualização da sessão.
polling_frequency number

Frequência recomendada de pesquisa do URL dos metadados, em segundos.

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 tag indexados por prefixo de tag.
ads map[string, object(Ad)]

Mapa de anúncios indexados por ID de 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 dessa tag.
ad_break_id string

É o ID do intervalo de anúncio dessa tag.
type string

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: antes, no meio e depois.
duration number

Duração total do anúncio desse 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.
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 deste anúncio.
position number

Posição desse 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 do criativo opcional.
creative_ad_id string

ID opcional do anúncio do criativo.
deal_id string

ID opcional da transação.
clickthrough_url string

URL de clique opcional.
click_tracking_urls string

URLs de rastreamento de cliques opcionais.
verifications [object(Verification)]

Entradas opcionais de verificação 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 que indica 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 o anúncio.
interactive_file object(InteractiveFile)

Criativo interativo opcional (SIMID) que deve ser exibido durante a reprodução do anúncio.

Icon

O ícone contém informações sobre um ícone do 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

Substituto Image 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 inclui 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 para o Open Measurement, o que facilita a medição da visibilidade e da verificação de terceiros. Atualmente, apenas recursos JavaScript são suportados. Acesse 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 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 o 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 de evento de rastreamento. Atualmente, a única opção é "verificationNotExecuted", conforme definido na especificação VAST 4.1.
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 para o anúncio.
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 sobre os 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,
}
Campos
click_data object(ClickData)

Os dados de clique para esse complementar.
creative_type string

O atributo CreativeType no nó <StaticResource> do VAST se for um complementar do tipo "estático".
height int32

A altura em pixels do complementar.
width int32

A largura em pixels do complementar.
resource string

Para complementares estáticos e iframe, esse será o URL a ser carregado e exibido. Para complementares em HTML, esse será o snippet HTML que deve ser mostrado como o complementar.
type string

Tipo desse complementar. Ele pode ser estático, iframe ou HTML.

InteractiveFile

O 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 do criativo interativo.
type string

O tipo MIME do arquivo fornecido como recurso.
variable_duration boolean

Se o criativo pode pedir que a duração seja estendida.
ad_parameters string

O valor do nó <AdParameters> no VAST.