API Dynamic Ad Insert VOD

Com a API Dynamic Ad Insert, é possível solicitar e rastrear a DAI em transmissões ao vivo de vídeo on demand (VOD). Há suporte para streams HLS e DASH.

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 um stream da DAI HLS para a origem do conteúdo e o ID do vídeo fornecidos.

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

Cria um stream da DASH DAI para a origem do conteúdo e o ID do vídeo fornecidos.

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, precisam ser válidos para a rede do editor.

Em vez de fornecê-la no corpo da solicitação, a chave de API pode ser passada no campo 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 da transmissão.

Corpo da solicitação

O corpo da solicitação é do tipo application/x-www-form-urlencoded e contém a parâmetros a seguir:

Parâmetros
dai-ssb Opcional

Defina como true para criar um stream de beacon do lado do servidor. O padrão é false. O rastreamento de stream padrão é iniciado pelo cliente e recebe um ping no lado do servidor.
Parâmetros de segmentação do DFP Opcional Outros parâmetros de segmentação.
Substituir parâmetros de stream Opcional Substituir 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 bem-sucedido, o corpo da resposta conterá uma nova Stream Para streams de beacon do lado do servidor, este Stream contém apenas os campos stream_id e stream_manifest.

Open Measurement

O campo Verifications contém informações para Open Verificação de medição para fluxos de beacon que não são do servidor. Verifications contém um ou mais elementos Verification que listam os recursos e os metadados necessários para verificar a reprodução de criativos com o código de medição de terceiros. Só há suporte para JavaScriptResource. 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 usando o media_verification_url do stream endpoint do Google Cloud. O media_verification_url é um caminho absoluto. As solicitações de verificação de mídia 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 de 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 tiver sido 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, reservado para "informações de texto definidas pelo usuário" frames. 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 deve 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 do anúncio serão inseridos no manifesto usando o uso de: Elemento EventStream do DASH.

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

Dados de resposta

Stream

O stream é usado para renderizar uma lista de todos os recursos de um novo transmissão 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 da transmissão em segundos.
content_duration number

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

A duração do stream é válida para, em "00h00m00s" .
valid_until string

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

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

(OBSOLETO) URL da playlist master de HLS. Use stream_manifest. somente HLS.
stream_manifest string

O manifesto do stream. Corresponde à playlist master em HLS e à MPD em DASH. Este é o único campo além de "stream_id" que está presente na resposta quando criando um stream de beacon 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

A 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

O intervalo de anúncio descreve um único intervalo de anúncio no stream. Ele contém uma posição, uma duração, um tipo (meio/pré/pós) 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: intermediário, anterior e posterior.
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),
}
Campos
seq number

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

Posição no fluxo em que o anúncio é iniciado, 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 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 do anúncio do criativo opcional.
deal_id string

ID da transação opcional.
clickthrough_url string

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

Uma lista de ícones, omitidos se estiverem vazios.
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 do Open Measurement que listam os recursos e os metadados necessários para executar o código de medição de terceiros a fim de verificar a reprodução de criativos.
universal_ad_id object(UniversalAdID)

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

Complementares opcionais que podem ser mostrados 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, indica que o anúncio é pulável e inclui instruções sobre como lidar com a ação de pular e evento de rastreamento.

Evento

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

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

O tipo deste evento.

Legenda

As legendas descrevem uma faixa de legenda do arquivo secundário para o stream de vídeo. Ela armazena dois formatos de subtítulo: TTML e WebVTT. O atributo TTMLPath contém o URL ao arquivo secundário TTML, e o atributo WebVTTPath também contém um URL ao arquivo secundário 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. Ela diferencia o conjunto específico de legendas se houver vários conjuntos para o mesmo idioma
ttml string

URL opcional do arquivo secundário TTML.
webvtt string

URL opcional do arquivo secundário WebVTT.

SkipMetadata

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

O deslocamento indica a quantidade de tempo em segundos no anúncio que o player deve aguardar a renderização do botão "Pular". Omitido se não for fornecido no VAST.
tracking_url string

O TrackingURL contém um URL que deve receber um ping no evento "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 o click-through 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

Wrapper contém informações sobre um anúncio wrapper. Ele não inclui um ID da transação, se não houver.
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 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, que facilita 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 ao 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 JavaScript.
api_framework string

APIFramework é o nome do framework de vídeo que reproduz código de verificação.
browser_optional boolean

Se esse script pode ser executado fora de uma navegador.

TrackingEvent

O TrackingEvent contém URLs que devem receber um ping pelo cliente em determinados em diferentes 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 é mantidos 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 onde o o ID universal do anúncio do criativo selecionado é catalogado.

Complementar

O companion contém informações para 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,
  "ad_slot_id": string,
  "api_framework": string,
  "tracking_events": [object(TrackingEvent)],
}
Campos
click_data object(ClickData)

Os dados de clique do complementar.
creative_type string

O atributo CreativeType no <StaticResource> no VAST se esse é um complemento do tipo estático.
height int32

A altura em pixels do complementar.
width int32

A largura em pixels desse complementar.
resource string

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

Tipo do complementar. Ele pode ser estático, iframe ou HTML.
ad_slot_id string

O ID do espaço para este complementar.
api_framework string

O framework da API deste complemento.
tracking_events [object(TrackingEvent)]

Lista de eventos de rastreamento para este complementar.

InteractiveFile

InteractiveFile contém informações para o criativo interativo (por exemplo, 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 o recurso.
variable_duration boolean

Define se o criativo pode pedir uma extensão de duração.
ad_parameters string

O valor do parâmetro <AdParameters> no VAST.