API Dynamic Ad Insert VOD

A API de Inserção de anúncios dinâmicos permite solicitar e rastrear streams de vídeo on demand (VOD) da DAI. Os streams HLS e DASH são compatíveis.

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 de DAI HLS 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 do 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 fornecer a chave no corpo da solicitação, ela 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 beaconing do lado do servidor. O padrão é false. O rastreamento do fluxo padrão é iniciado pelo cliente e faz ping no lado do servidor.
Parâmetros de segmentação do DFP Opcional Outros parâmetros de segmentação.
Modificar os parâmetros de stream Opcional Substitua os valores padrão de um parâmetro de criação de stream.
Autenticação HMAC Opcional Autentique usando um token baseado em HMAC.

Corpo da resposta

Se a solicitação for bem-sucedida, o corpo da resposta vai conter um novo Stream. Para fluxos de beaconing 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 em fluxos de beaconing que não são do lado do servidor. Verifications contém um ou mais elementos Verification que listam os recursos e metadados necessários para verificar a reprodução de criativos com 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 imediatamente uma solicitação 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 streams de beaconing 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 {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 ID foi concluída.
  • HTTP/1.1 409 Conflict se outra solicitação já estiver enviando pings no momento.

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

Os identificadores de mídia de anúncios serão codificados em metadados com tempo 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 começará com o texto "google_".

Todo o conteúdo de texto do frame precisa ser anexado ao media_verification_url para cada solicitação de verificação de anúncio.

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

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

Cada EventStream terá um URI de ID de esquema urn:google:dai:2018. Eles vão conter eventos com o atributo messageData, que tem um ID de mídia de anúncio começando 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 de stream.
total_duration number

Duração do stream em segundos.
content_duration number

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

Período de validade da stream de duração, no formato "00h00m00s".
valid_until string

Data até quando o stream é válido, no formato RFC 3339.
subtitles [object(Subtitle)]

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

(DESCONTINUADO) URL da playlist master do HLS. Use stream_manifest. Somente HLS.
stream_manifest string

O manifesto do stream. Corresponde à playlist master em HLS e ao MPD em DASH. Este é o único campo, além de "stream_id", presente na resposta ao criar um fluxo de beaconing do lado do 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

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

URL de 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/final) e uma lista de anúncios.
Representação JSON
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
Campos
type string

Os tipos de quebra 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.
"Ad" descreve um anúncio no fluxo. 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 de anunciante opcional.
ad_system string

Sistema de anúncios opcional.
ad_id string

ID de publicidade opcional.
creative_id string

ID do criativo opcional.
creative_ad_id string

ID opcional do anúncio criativo.
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 opcionais de verificação de medição aberta que listam os recursos e os metadados necessários para executar o código de medição terceirizada e verificar a reprodução do criativo.
universal_ad_id object(UniversalAdID)

ID universal do anúncio opcional.
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.
skip_metadata object(SkipMetadata)

Metadados opcionais para anúncios puláveis. Se definido, isso indica que o anúncio é pulável e inclui instruções sobre como processar a interface de pular e o evento de rastreamento.
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

O tempo de apresentação deste evento.
type string

O tipo deste evento.

Legenda

A legenda descreve uma faixa de legenda complementar para o stream de vídeo. Ele armazena dois formatos de legenda: TTML e WebVTT. O atributo TTMLPath contém o URL do arquivo auxiliar TTML, e o atributo WebVTTPath contém um URL do arquivo auxiliar 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 pular anúncios puláveis.
Representação JSON
{
  "offset": number,
  "tracking_url": string,
}
Campos
offset number

O tempo até a opção pular indica o tempo em segundos que o player deve esperar para renderizar o botão "Pular". Omitido se não for fornecido no VAST.
tracking_url string

TrackingURL contém um URL que deve receber um ping no evento de pular.

Í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

ClickData contém informações sobre um clickthrough de í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 inclui um ID da 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 publicidade.
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 criativo do anúncio 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, que facilita a visibilidade e a medição de 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 ao código de verificação de bootstrap.

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 JavaScript.
api_framework string

APIFramework é o nome da estrutura de vídeo que exerce o código de verificação.
browser_optional boolean

Indica se o script pode ser executado fora de um navegador.

TrackingEvent

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 pingado.

UniversalAdID

O UniversalAdID é usado para fornecer um identificador exclusivo de criativo 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 está catalogado.

Companion

O campo "companion" 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 clique deste complemento.
creative_type string

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

A altura em pixels deste complemento.
width int32

A largura em pixels deste complemento.
resource string

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

Tipo de complemento. Ele pode ser estático, iframe ou HTML.
ad_slot_id string

O ID do slot para este complemento.
api_framework string

O framework de API para este complemento.
tracking_events [object(TrackingEvent)]

Lista de eventos de rastreamento para este complemento.

InteractiveFile

O InteractiveFile contém informações para o criativo interativo (ou seja, SIMID) que deve 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.