API Dynamic Ad Insertion VOD

L'API Dynamic Ad Insertion vous permet de demander et de suivre les flux de vidéo à la demande (VOD) avec insertion dynamique d'annonces. 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 HLS DAI pour la source de contenu et l'ID vidéo spécifiés.

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

Crée un flux DASH DAI pour la source de contenu et l'ID vidéo spécifié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, la clé API peut être transmise dans l'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 les paramètres suivants :

Paramètres
dai-ssb Facultatif

Définissez sur true pour créer un flux de balises côté serveur. La valeur par défaut est false. Le suivi du flux par défaut est initié par le client et pingé côté serveur.
Paramètres de ciblage DFP Facultatif Paramètres de ciblage supplémentaires.
Remplacer les paramètres de flux Facultatif Remplacez les valeurs par défaut d'un paramètre de création de flux.
Authentification HMAC Facultatif S'authentifier à l'aide d'un jeton HMAC.

Corps de la réponse

Si la requête aboutit, le corps de la réponse contient un nouvel Stream. Pour les flux de balises côté serveur, ce Stream ne contient que les champs stream_id et stream_manifest.

Open Measurement

Le champ Verifications contient des informations sur la validation Open Measurement pour les flux de balises non côté serveur. Verifications contient un ou plusieurs éléments Verification qui listent les ressources et les métadonnées dont vous avez besoin pour vérifier la lecture des créations avec un code de mesure tiers. Seule la région JavaScriptResource est compatible. Pour en savoir plus, consultez l'IAB Tech Lab et la spécification VAST 4.1.

Méthode : validation du média

Lorsque vous rencontrez un identifiant média d'annonce pendant la lecture, envoyez immédiatement une requête à l'aide de media_verification_url à partir du point de terminaison stream. media_verification_url est un chemin absolu. Les demandes de validation du contenu multimédia ne sont pas nécessaires pour les flux de balises côté serveur, où le serveur lance la validation du contenu multimé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}

Avertit l'API d'un événement de validation de contenu 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 du contenu multimédia réussit et que tous les pings sont envoyés.
  • HTTP/1.1 404 Not Found si la demande ne peut pas valider le média en raison d'un format d'URL incorrect ou d'une expiration.
  • HTTP/1.1 404 Not Found si une demande de validation précédente pour cet ID a abouti.
  • HTTP/1.1 409 Conflict si une autre requête envoie déjà des pings à ce moment-là.

ID des éléments multimédias des annonces (HLS)

Les identifiants de contenu multimédia des annonces seront encodés dans les métadonnées temporelles HLS à l'aide de la clé TXXX, réservée aux frames "informations textuelles définies par l'utilisateur". Le contenu du frame ne sera pas chiffré et commencera toujours par le texte "google_".

L'intégralité du contenu textuel du frame doit être ajoutée à l'URL media_verification_url pour chaque demande de validation d'annonce.

ID des éléments multimédias des annonces (DASH)

Les identifiants de contenu multimédia des annonces seront insérés dans le fichier manifeste à l'aide de l'élément EventStream de DASH.

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

Données de réponse

Flux

Le flux est utilisé pour afficher la liste de toutes les ressources d'un flux nouvellement créé 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 du flux.
total_duration number

Durée du flux en secondes.
content_duration number

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

Durée de validité du flux, au format "00h00m00s".
valid_until string

Date jusqu'à laquelle le flux est valide, au format RFC 3339.
subtitles [object(Subtitle)]

Liste des sous-titres. Omis si 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 au fichier MPD dans DASH. Il s'agit du seul champ, en plus de "stream_id", qui est présent dans la réponse lors de la création d'un flux de balises côté serveur.
media_verification_url string

URL de validation du média.
apple_tv object(AppleTV)

Informations facultatives spécifiques aux appareils AppleTV. HLS uniquement.
ad_breaks [object(AdBreak)]

Liste des coupures publicitaires. Omis s'il est vide.

AppleTV

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

URL des interstitiels.

AdBreak

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

Les types de pauses valides sont : "mid", "pre" et "post".
start number

Position dans le flux à laquelle la coupure commence, en secondes.
duration number

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

Liste des annonces. Omis s'il est vide.
"Annonce" décrit une annonce dans le flux. Il contient la position de l'annonce dans l'insertion, sa durée et certaines 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),
  "extensions": [],
}
Champs
seq number

Position de l'annonce dans la coupure.
start number

Position de l'annonce dans le flux (en secondes).
duration number

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

Titre facultatif de l'annonce.
description string

Description facultative de l'annonce.
advertiser string

Identifiant d'annonceur facultatif.
ad_system string

Système publicitaire facultatif.
ad_id string

ID d'annonce facultatif.
creative_id string

ID de la création facultatif.
creative_ad_id string

Identifiant d'annonce pour la création (facultatif).
deal_id string

ID de l'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. Omitted if empty.
events [object(Event)]

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

Entrées de validation Open Measurement facultatives qui listent les ressources et les métadonnées requises pour exécuter le code de mesure tiers afin de valider la lecture de la création.
universal_ad_id object(UniversalAdID)

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

Éléments associés facultatifs pouvant être diffusés 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. Si cette valeur est définie, cela indique que l'annonce est désactivable et inclut des instructions sur la façon de gérer l'UI de désactivation et l'événement de suivi.
extensions string

Liste facultative de tous les nœuds <Extension> dans le VAST.

Événement

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

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

Type de cet événement.

Sous-titre

"Subtitle" décrit une piste de sous-titres sidecar pour le flux vidéo. Il stocke deux formats de sous-titres : TTML et WebVTT. L'attribut TTMLPath contient l'URL du fichier sidecar TTML, et l'attribut WebVTTPath contient de même l'URL du fichier sidecar WebVTT.
Représentation JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Champs
language string

Code de langue, tel que "en" ou "de".
language_name string

Nom descriptif de la langue. Il permet de différencier l'ensemble spécifique de sous-titres si plusieurs ensembles existent pour 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 aux clients les informations nécessaires pour gérer les événements de désactivation des annonces désactivables.
Représentation JSON
{
  "offset": number,
  "tracking_url": string,
}
Champs
offset number

Offset indique le temps en secondes pendant lequel le lecteur doit attendre avant d'afficher le bouton "Ignorer" dans l'annonce. Omettez-le si aucune valeur n'est fournie dans le VAST.
tracking_url string

TrackingURL contient une URL à laquelle un ping doit être envoyé lors de l'événement de désactivation.

Icône

Icon 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 le nombre de clics sur une icône.
Représentation JSON
{
  "url": string,
}
Champs
url string

FallbackImage

FallbackImage 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

Wrapper contient des informations sur une annonce wrapper. Il n'inclut pas d'ID de transaction 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

ID de l'annonce utilisée pour l'annonce wrapper.
creative_id string

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

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

ID de l'accord facultatif pour l'annonce wrapper.

Validation

La validation contient des informations pour Open Measurement, qui facilite la mesure de la visibilité et de la validation tierces. Actuellement, seules les ressources JavaScript sont acceptées. Consultez 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

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 du bootstrap.

JavaScriptResource

JavaScriptResource contient des informations pour la validation 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 exécute le code de validation.
browser_optional boolean

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

TrackingEvent

TrackingEvent contient des URL que le client doit pinguer dans certaines situations.
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 permet de fournir un identifiant unique pour les créations, qui est conservé dans tous les 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 utilisée pour identifier l'URL du site Web du registre où l'identifiant d'annonce universel de la création sélectionnée est catalogué.

Annonce associée

Companion contient des informations sur les annonces associées qui peuvent ê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 ce complément.
creative_type string

Attribut CreativeType du nœud <StaticResource> dans le VAST si la création associée est de type statique.
height int32

Hauteur de ce complément en pixels.
width int32

Largeur en pixels de ce complément.
resource string

Pour les composants statiques et iFrame, il s'agit de l'URL à charger et à afficher. Pour les annonces associées HTML, il s'agit de l'extrait de code HTML à afficher en tant qu'annonce associée.
type string

Type de ce complément. Il peut être statique, iframe ou HTML.
ad_slot_id string

ID de l'emplacement de cet élément associé.
api_framework string

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

Liste des événements de suivi pour ce complément.

InteractiveFile

InteractiveFile contient des informations sur la création interactive (c'est-à-dire SIMID) qui doivent être affichées pendant la lecture de l'annonce.
Représentation JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Champs
resource string

URL de la création interactive.
type string

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

Indique si cette création peut demander à ce que sa durée soit prolongée.
ad_parameters string

Valeur du nœud <AdParameters> dans VAST.