API Dynamic Ad Insertion VOD

L'API d'insertion dynamique d'annonce vous permet de demander l'insertion dynamique d'annonce et d'en effectuer le suivi les flux de vidéo à la demande (VOD). Les flux HLS et DASH sont acceptés.

Service: dai.google.com

Le chemin d'accès de la méthode stream est relatif à https://dai.google.com.

Méthode: stream

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

Crée un flux d'insertion dynamique d'annonces HLS pour la source de contenu et l'ID vidéo donnés.

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

Crée un flux d'insertion dynamique d'annonces DASH pour la source de contenu et l'ID vidéo donnés.

Requête 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

En-tête de requête

Paramètres
api‑key string

La clé API, fournie lors de la création d'un flux, doit être valide pour le réseau de l'éditeur.

Au lieu de la fournir dans le corps de la requête, vous pouvez la transmettre dans le champ en-tête d'autorisation HTTP au format suivant:

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

Paramètres de chemin d'accès

Paramètres
content-source string

ID CMS du flux.

video-id string

ID vidéo du flux.

Corps de la requête

Le corps de la requête est de type application/x-www-form-urlencoded et contient le les paramètres suivants:

Paramètres
dai-ssb Facultatif

Définissez la valeur sur true pour créer un flux de balisage côté serveur. La valeur par défaut est false. Le paramètre de suivi du flux par défaut est initiée par le client et pinguée côté serveur.
Paramètres de ciblage dans DFP Facultatif <ph type="x-smartling-placeholder"></ph> Paramètres de ciblage supplémentaires.
Remplacer les paramètres de flux Facultatif <ph type="x-smartling-placeholder"></ph> Remplace les valeurs par défaut d'un paramètre de création de flux.
Authentification HMAC Facultatif <ph type="x-smartling-placeholder"></ph> Authentifiez-vous à l'aide d'un jeton basé sur HMAC.

Corps de la réponse

Si la requête aboutit, le corps de la réponse contient une nouvelle Stream Pour les flux de balisage côté serveur, ce Stream contient uniquement les champs stream_id et stream_manifest.

Open Measurement

Le champ Verifications contient des informations pour Open Validation des mesures pour les flux de balisage non côté serveur Verifications contient un ou plusieurs éléments Verification qui listent les ressources et les métadonnées, vous devez vérifier la lecture des créations à l'aide d'un code de mesure tiers. Seul JavaScriptResource est accepté. Pour plus d'informations, consultez l'IAB Tech Lab et les spécifications VAST 4.1.

Méthode: vérification des supports

Lorsqu'un identifiant de support publicitaire s'affiche pendant la lecture, effectuez immédiatement une requête à l'aide du media_verification_url de stream point de terminaison unique. media_verification_url est un chemin d'accès absolu. Les requêtes de validation de médias ne sont pas nécessaires pour les flux de balisage côté serveur. où le serveur lance la vérification du média.

Les requêtes envoyées au point de terminaison media verification sont idempotentes.

Méthodes
media verification GET {media_verification_url}/{ad_media_id}

Notifie l'API d'un événement de validation multimédia.

Requête HTTP

GET {media-verification-url}/{ad-media-id}

Corps de la réponse

media verification renvoie les réponses suivantes:

  • HTTP/1.1 204 No Content si la validation multimédia réussit et que tous les pings sont envoyés.
  • HTTP/1.1 404 Not Found si la requête ne peut pas valider le contenu multimédia en raison d'un format d'URL incorrect ou d'une expiration.
  • HTTP/1.1 404 Not Found si une précédente demande de validation a abouti pour cet ID.
  • HTTP/1.1 409 Conflict si une autre requête envoie déjà des pings pour le moment.

ID des supports publicitaires (HLS)

Les identifiants de supports publicitaires seront encodés dans des métadonnées minutées HLS à l'aide de la clé TXXX. réservé aux "informations textuelles définies par l'utilisateur" cadres. Le contenu du cadre ne sera pas chiffré et commencera toujours par le texte "google_".

L’intégralité du contenu textuel du cadre doit être ajouté à la media_verification_url) pour chaque demande de validation d'annonce.

ID d'élément multimédia d'annonce (DASH)

Les identifiants de supports publicitaires seront insérés dans le fichier manifeste à l'aide de l'attribut Élément EventStream de DASH.

Chaque élément EventStream aura un URI d'ID de schéma urn:google:dai:2018. Ils contiendront des événements dont l'attribut messageData contient ID d'élément multimédia publicitaire commençant par “google_”. L'intégralité du contenu de messageData doit être ajouté à la chaîne media_verification_url pour chaque annonce demande de validation.

Données de réponse

Flux

Le flux permet d'afficher la liste de toutes les ressources d'une ressource flux au format JSON .
Représentation 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)],
}
Champs
stream_id string

Identifiant de flux :
total_duration number

Durée de la diffusion en secondes.
content_duration number

Durée du contenu sans annonces, en secondes.
valid_for string

Durée de validité du flux, exprimée en "00h00m00s" .
valid_until string

Date limite de validité du flux, au format RFC 3339.
subtitles [object(Subtitle)]

Liste de sous-titres. Ignoré si le champ est vide. HLS uniquement.
hls_master_playlist string

(OBSOLÈTE) URL de la playlist principale HLS. Utilisez stream_manifest. HLS uniquement.
stream_manifest string

Fichier manifeste du flux. Correspond à la playlist principale dans HLS et à la description de la présentation du média dans DASH. C'est le seul champ en dehors de "stream_id" présente dans la réponse lorsque en créant un flux de balisage côté serveur.
media_verification_url string

URL de validation multimédia :
apple_tv object(AppleTV)

Informations facultatives propres aux appareils Apple TV. HLS uniquement.
ad_breaks [object(AdBreak)]

Liste des coupures publicitaires. Omis si vide.

AppleTV

Apple TV contient des informations spécifiques aux appareils Apple TV.
Représentation JSON
{
  "interstitials_url": string,
}
Champs
interstitials_url string

URL des interstitiels

AdBreak

Une coupure publicitaire décrit une seule coupure publicitaire dans le flux. Il contient une position, une durée, un type (milieu/avant/après) et une liste d'annonces.
Représentation JSON
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
Champs
type string

Les types de coupures valides sont les suivants: mid, pre et post.
start number

Position dans le flux où commence la coupure publicitaire, en secondes.
duration number

Durée de la coupure publicitaire, en secondes.
ads [object(Ad)]

Une liste d'annonces. Omis si vide.
Une annonce désigne une annonce diffusée dans le flux. Elle indique la position de l'annonce dans la durée de l'annonce et des métadonnées facultatives.
Représentation 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),
}
Champs
seq number

Position de l'annonce dans la coupure.
start number

Positionnement en secondes depuis le début du flux dans le flux.
duration number

Durée de l'annonce, en secondes.
title string

Titre de l'annonce facultatif.
description string

Description de l'annonce facultative.
advertiser string

Identifiant d'annonceur facultatif.
ad_system string

Système publicitaire facultatif.
ad_id string

Identifiant d'annonce facultatif.
creative_id string

ID de création facultatif.
creative_ad_id string

Identifiant d'annonce de création facultatif.
deal_id string

ID d'accord facultatif.
clickthrough_url string

URL de destination facultative.
icons [object(Icon)]

Liste d'icônes, omise si elle est vide.
wrappers [object(Wrapper)]

Liste des wrappers. Omis si vide.
events [object(Event)]

Liste des événements dans l'annonce.
verifications [object(Verification)]

Entrées facultatives de validation Open Measurement qui listent les ressources et les métadonnées requises pour exécuter le code de mesure tierce lors de la lecture des créations.
universal_ad_id object(UniversalAdID)

Identifiant d'annonce universelle facultatif.
companions [object(Companion)]

Créations associées facultatives qui peuvent s'afficher avec cette annonce.
interactive_file object(InteractiveFile)

Création interactive facultative (SIMID) à afficher pendant la lecture de l'annonce.
skip_metadata object(SkipMetadata)

Métadonnées facultatives pour les annonces désactivables. S'il est défini, il indique que l'annonce est désactivable et inclut des instructions sur la façon de gérer l'interface utilisateur permettant d'ignorer et le suivi des événements.

Événement

"Événement" contient un type d'événement et l'heure de présentation d'un événement.
Représentation JSON
{
  "time": number,
  "type": string,
}
Champs
time number

Heure de présentation de cet événement.
type string

Type d'événement.

Sous-titre

"Sous-titre" désigne une piste de sous-titres side-car pour le flux vidéo. Stockage de données deux formats de sous-titres: TTML et WebVTT. L'attribut TTMLPath contient l'URL au fichier side-car TTML. L'attribut WebVTTPath contient de la même manière une URL. au fichier side-car WebVTT.
Représentation JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Champs
language string

Un code de langue tel que "en" ou "de".
language_name string

Nom descriptif de la langue. Il différencie l’ensemble spécifique de sous-titres s'il existe plusieurs sous-titres dans la même langue
ttml string

URL facultative du fichier side-car TTML.
webvtt string

URL facultative du fichier side-car WebVTT.

SkipMetadata

SkipMetadata fournit les informations nécessaires aux clients pour gérer les événements de désactivation des annonces désactivables.
Représentation JSON
{
  "offset": number,
  "tracking_url": string,
}
Champs
offset number

Décalage (offset) indique la durée, en secondes, pendant laquelle le lecteur a diffusé l'annonce. doit attendre avant que le bouton "Ignorer" s'affiche. Omis s'ils ne sont pas fournis dans le fichier VAST.
tracking_url string

TrackingURL contient une URL qui doit être pinguée lors de l'événement "Ignorer".

Icône

L'icône contient des informations sur une icône VAST.
Représentation 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,
}
Champs
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 contient des informations sur un clic d'icône.
Représentation JSON
{
  "url": string,
}
Champs
url string

FallbackImage

L'image de remplacement contient des informations sur une image de remplacement VAST.
Représentation JSON
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
Champs
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

Le wrapper contient des informations sur une annonce wrapper. Il n'inclut pas ID de l'accord s'il n'existe pas.
Représentation JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Champs
system string

Identifiant du système publicitaire.
ad_id string

Identifiant d'annonce utilisé pour l'annonce wrapper.
creative_id string

ID de la création utilisé pour l'annonce wrapper.
creative_ad_id string

Identifiant de l'annonce de création utilisé pour l'annonce wrapper.
deal_id string

ID d'accord facultatif pour l'annonce wrapper.

Validation

Verification contient des informations pour Open Measurement, ce qui facilite des mesures tierces de la visibilité et de la validation. Actuellement, seules les ressources JavaScript sont compatibles. Voir https://iabtechlab.com/standards/open-measurement-sdk/
Représentation JSON
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
Champs
vendor string

Le fournisseur de services de vérification.
java_script_resources [object(JavaScriptResource)]

Liste des ressources JavaScript pour la validation.
tracking_events [object(TrackingEvent)]

Liste des événements de suivi pour la validation.
parameters string

Chaîne opaque transmise au code de validation d'amorçage.

JavaScriptResource

JavaScriptResource contient des informations à valider via JavaScript.
Représentation JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
Champs
script_url string

URI de la charge utile JavaScript.
api_framework string

APIFramework est le nom du framework vidéo qui utilise code de validation.
browser_optional boolean

Indique si ce script peut être exécuté en dehors d'un navigateur.

TrackingEvent

TrackingEvent contient des URL qui doivent être pinguées par le client dans certaines situations différentes.
Représentation JSON
{
  "event": string,
  "uri": string,
}
Champs
event string

Type d'événement de suivi.
uri string

Événement de suivi à pinguer.

UniversalAdID

UniversalAdID est utilisé pour fournir un identifiant de création unique sur les différents systèmes publicitaires.
Représentation JSON
{
  "id_value": string,
  "id_registry": string,
}
Champs
id_value string

Identifiant d'annonce universel de la création sélectionnée pour l'annonce.
id_registry string

Chaîne permettant d'identifier l'URL du site Web du registre où se trouve l'identifiant de l'annonce universelle de la création sélectionnée est catalogué.

Annonce associée

L'annonce associée contient des informations sur les annonces associées susceptibles d'être diffusées. avec l'annonce.
Représentation 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)],
}
Champs
click_data object(ClickData)

Données sur les clics pour cette création associée.
creative_type string

L'attribut CreativeType dans l'élément <StaticResource> dans l'annonce VAST si il s'agit d'une création associée de type statique.
height int32

Hauteur en pixels de cette création associée.
width int32

Largeur en pixels de cette création associée.
resource string

Pour les annonces associées statiques et iFrame, il s'agit de l'URL à charger. affiché. Pour les créations HTML associées, il s'agit de l'extrait de code HTML s'affichera en tant qu'élément associé.
type string

Type de cette création associée. Il peut s'agir d'un fichier statique, iFrame ou HTML.
ad_slot_id string

ID d'emplacement de cette création associée.
api_framework string

Framework d'API pour ce compagnon.
tracking_events [object(TrackingEvent)]

Liste des événements de suivi pour cette création associée.

InteractiveFile

InteractiveFile contient les informations relatives à la création interactive (par exemple, SIMID) à afficher pendant la lecture de l'annonce.
Représentation JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Champs
resource string

L'URL de la création interactive.
type string

Type MIME du fichier fourni en tant que ressource.
variable_duration boolean

Indique si la création peut demander un prolongement de la durée.
ad_parameters string

La valeur de l'élément <AdParameters> dans le composant VAST.