Com a API Dynamic Ad Insert, é possível solicitar e rastrear streams de vídeo on demand (VOD) da DAI. 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.
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 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 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 | Outros parâmetros de segmentação. |
Substituir parâmetros de stream | Opcional | Substitua 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 incluirá um novo
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 a verificação do Open Measurement para fluxos de beacon 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 do criativo 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 (links em inglês).
Método: verificação de mídia
Depois de encontrar um identificador de mídia do 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 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
,
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 media_verification_url de 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 com o uso do
elemento EventStream
do DASH.
Cada EventStream
terá um URI de ID de esquema de urn:google:dai:2018
.
Eles conterão eventos com o atributo messageData
contendo 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
Fluxo
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 da transmissão em segundos. |
content_duration |
number Duração do conteúdo, sem anúncios, em segundos. |
valid_for |
string A transmissão 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 (DESCONTINUADO) 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. Além de "stream_id", esse é o único campo presente na resposta ao criar 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)] Lista de anúncios. Omitido se estiver vazio. |
Anúncio
O anúncio descreve um anúncio no stream. Ele contém a posição do anúncio no intervalo, a duração 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), } |
Campos | |
---|---|
seq |
number Posição do anúncio no intervalo. |
start |
number Posição no stream em que o anúncio inicia, 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 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 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 do criativo. |
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. |
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. Ele armazena dois formatos de legendas: TTML e WebVTT. O atributo TTMLPath contém o URL para o arquivo secundário TTML, e o atributo WebVTTPath também contém um URL para o arquivo secundário do 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 caso haja 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. |
Icon
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 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 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 facilitam a medição da verificação e visibilidade 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 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 JavaScript. |
api_framework |
string APIFramework é o nome do framework de vídeo que executa 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 precisam 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 acompanhamento que receberá um 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 do anúncio universal do criativo selecionado está 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 cliques do anúncio 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 do complementar. |
resource |
string Para complementares estáticos e iframe, esse será o URL a ser carregado e exibido. Para complementares HTML, este será 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 deste complemento. |
tracking_events |
[object(TrackingEvent)] Lista de eventos de rastreamento deste complementar. |
InteractiveFile
InteractiveFile contém informações para o criativo interativo (por exemplo, SIMID) que precisam ser mostradas 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 Define se este criativo pode pedir uma extensão de duração. |
ad_parameters |
string O valor do nó <AdParameters> no VAST. |