API Dynamic Ad Insert VOD

A API Dynamic ad insertion permite solicitar e acompanhar streams de vídeo on demand (VOD) da DAI. Os fluxos HLS e DASH são aceitos.

Serviço: dai.google.com

O caminho do método stream é relativo a https://dai.google.com

Método: stream

Métodos
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

Cria uma transmissão HLS DAI para a origem de conteúdo e o ID do vídeo especificados.

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

Cria uma transmissão DASH DAI para a origem de conteúdo e o ID do vídeo especificados.

Solicitação HTTP

POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/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
content-source string

O ID do CMS do stream.

video-id string

O ID do vídeo do stream.

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 no servidor. O padrão é false. O acompanhamento do stream padrão é iniciado pelo cliente e verificado no servidor.
Parâmetros de segmentação do DFP Opcional Parâmetros de segmentação adicionais.
Modificar os parâmetros do stream Opcional Modifique 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 bem-sucedida, o corpo da resposta conterá um novo Stream. Para transmissões de beacons do lado do servidor, esse Stream contém apenas os campos stream_id e stream_manifest.

Open Measurement

O campo Verifications contém informações para a verificação do Open Measurement para streams sem beacons do lado do servidor. O Verifications contém um ou mais elementos Verification que listam os recursos e metadados necessários para verificar a reprodução do criativo com o código de medição de terceiros. Somente JavaScriptResource é aceito. 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 de anúncio durante a reprodução, faça uma solicitação imediatamente usando o media_verification_url do endpoint stream. O media_verification_url é um caminho absoluto. As solicitações de verificação de mídia não são necessárias para transmissões de beacon no 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 {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 incorreta do URL.
  • HTTP/1.1 404 Not Found se uma solicitação de verificação anterior para esse documento de identidade foi bem-sucedida.
  • HTTP/1.1 409 Conflict se outra solicitação já estiver enviando pings no momento.

IDs de mídia de anúncios (HLS)

Os identificadores de mídia de anúncios serão codificados em metadados temporizados do 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 a media_verification_url para cada solicitação de verificação de anúncio.

IDs de mídia de anúncios (DASH)

Os identificadores de mídia de anúncios são inseridos no manifesto usando o elemento EventStream do DASH.

Cada EventStream terá um URI de ID do esquema de urn:google:dai:2018. Eles vão conter eventos com o atributo messageData que contém um ID de mídia do anúncio que começa com “google_”. Todo o conteúdo do atributo messageData precisa ser anexado ao media_verification_url para cada solicitação de verificação de anúncio.

Dados de resposta

Stream

O stream é usado para renderizar uma lista de todos os recursos de um stream recém-criado no formato JSON .
Representação JSON
{
  "stream_id": string,
  "total_duration": number,
  "content_duration": number,
  "valid_for": string,
  "valid_until": string,
  "subtitles": [object(Subtitle)],
  "hls_master_playlist": string,
  "stream_manifest": string,
  "media_verification_url": string,
  "apple_tv": object(AppleTV),
  "ad_breaks": [object(AdBreak)],
}
Campos
stream_id string

Identificador do stream.
total_duration number

Duração do streaming em segundos.
content_duration number

Duração do conteúdo, sem anúncios, em segundos.
valid_for string

A stream de duração é válida para o formato "00h00m00s".
valid_until string

Data de validade do stream, no formato RFC 3339.
subtitles [object(Subtitle)]

Uma lista de legendas. Omitido se estiver vazio. Somente HLS.
hls_master_playlist string

(SUSPENSO) URL da playlist principal HLS. Use stream_manifest. Somente HLS.
stream_manifest string

O manifesto do stream. Corresponde à playlist master no HLS e ao MPD no DASH. Esse é o único campo, além de "stream_id", que está presente na resposta ao criar um stream de beacon no servidor.
media_verification_url string

URL de verificação de mídia.
apple_tv object(AppleTV)

Informações opcionais específicas para dispositivos AppleTV. Somente HLS.
ad_breaks [object(AdBreak)]

Uma lista de intervalos de anúncio. Omitido se estiver vazio.

AppleTV

AppleTV contém informações específicas para dispositivos Apple TV.
Representação JSON
{
  "interstitials_url": string,
}
Campos
interstitials_url string

URL dos intersticiais.

AdBreak

"AdBreak" descreve um único intervalo de anúncio no stream. Ele contém uma posição, uma duração, um tipo (intermediário/precedente/seguinte) e uma lista de anúncios.
Representação JSON
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
Campos
type string

Os tipos de intervalo válidos são: mid, pre e post.
start number

Posição no stream em que o intervalo começa, em segundos.
duration number

Duração do intervalo de anúncio, em segundos.
ads [object(Ad)]

Uma lista de anúncios. Omitido se estiver vazio.
O anúncio descreve um anúncio no stream. Ele contém a posição do anúncio no intervalo, a duração do anúncio e alguns metadados opcionais.
Representação JSON
{
  "seq": number,
  "start": 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,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "events": [object(Event)],
  "verifications": [object(Verification)],
  "universal_ad_id": object(UniversalAdID),
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
  "skip_metadata": object(SkipMetadata),
  "extensions": [],
}
Campos
seq number

Posição do anúncio no intervalo.
start number

Posição no stream em que o anúncio começa, em segundos.
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 criativo do anúncio opcional.
deal_id string

ID da transação opcional.
clickthrough_url string

URL de clique opcional.
icons [object(Icon)]

Uma lista de ícones, omitida se estiver vazia.
wrappers [object(Wrapper)]

Uma lista de wrappers. Omitido se estiver vazio.
events [object(Event)]

Uma lista dos eventos no anúncio.
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.
universal_ad_id object(UniversalAdID)

ID universal do anúncio opcional.
companions [object(Companion)]

Complementos opcionais que podem ser mostrados com esse anúncio.
interactive_file object(InteractiveFile)

Criativo interativo opcional (SIMID) que precisa ser mostrado durante a veiculação do anúncio.
skip_metadata object(SkipMetadata)

Metadados opcionais para anúncios puláveis. Se definido, isso indica que o anúncio pode ser pulado e inclui instruções sobre como processar a IU de pular e o evento de acompanhamento.
extensions string

Lista opcional de todos os nós <Extension> no VAST.

Evento

O evento contém um tipo de evento e um horário de apresentação.
Representação JSON
{
  "time": number,
  "type": string,
}
Campos
time number

Horário da apresentação deste evento.
type string

O tipo do evento.

Legenda

A legenda descreve uma faixa de legenda do sidecar para o stream de vídeo. Ele armazena dois formatos de legenda: TTML e WebVTT. O atributo TTMLPath contém o URL do arquivo sidecar TTML, e o atributo WebVTTPath contém um URL para o arquivo sidecar WebVTT.
Representação JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Campos
language string

Um código de idioma, como "en" ou "de".
language_name string

Nome descritivo do idioma. Ele diferencia o conjunto específico de legendas se houver vários conjuntos para o mesmo idioma
ttml string

URL opcional para o arquivo sidecar TTML.
webvtt string

URL opcional para o arquivo sidecar WebVTT.

SkipMetadata

O SkipMetadata fornece as informações necessárias para que os clientes processem eventos de omissão para anúncios puláveis.
Representação JSON
{
  "offset": number,
  "tracking_url": string,
}
Campos
offset number

O deslocamento indica o tempo em segundos no anúncio que o player precisa esperar para renderizar o botão "Pular". Omitido se não for fornecido no VAST.
tracking_url string

O TrackingURL contém um URL que precisa receber um ping no evento de omissão.

Í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

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 de wrapper.
creative_id string

ID do criativo usado para o anúncio de wrapper.
creative_ad_id string

ID do criativo do anúncio usado para o wrapper.
deal_id string

ID da transação opcional para o anúncio de 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. No momento, apenas recursos JavaScript são aceitos. 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

O JavaScriptResource contém informações para verificação por 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 ser pingados 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 a ser verificado.

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 de publicidade 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 desse complemento.
creative_type string

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

A altura em pixels desse companheiro.
width int32

A largura em pixels desse companheiro.
resource string

Para companheiros estáticos e de iframe, esse é o URL que 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 para esse companheiro.

InteractiveFile

O InteractiveFile contém informações sobre o criativo interativo (ou seja, o 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

Indica se o criativo pode pedir a extensão da duração.
ad_parameters string

O valor do nó <AdParameters> no VAST.