API Dynamic Ad Insertion Linear

L'API d'insertion dynamique d'annonces vous permet de demander et de suivre les flux linéaires (EN DIRECT) d'insertion dynamique d'annonces.

Service : dai.google.com

Tous les URI sont relatifs à https://dai.google.com

Méthode : stream

Méthodes
stream POST /linear/v1/hls/event/{assetKey}/stream

Crée un flux d'insertion dynamique d'annonces pour l'ID d'événement donné.

Requête HTTP

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/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
assetKey string

ID d'événement du flux.
Remarque : La clé d'asset du flux est un identifiant que vous pouvez également trouver dans l' interface utilisateur Ad Manager.

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-la 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

L'API DAI contient des informations pour la validation Open Measurement dans le champ Verifications. Ce champ contient un ou plusieurs éléments Verification qui listent les ressources et les métadonnées nécessaires à l'exécution du code de mesure tiers afin de vérifier la lecture de la création. Seul JavaScriptResource est accepté. Pour en savoir plus, consultez l'IAB Tech Lab et la spécification VAST 4.1.

Méthode : validation du média

Après avoir rencontré un identifiant de contenu multimédia publicitaire lors de la lecture, envoyez immédiatement une requête à l'aide de l'URL media_verification_url obtenue à partir du point de terminaison stream. Ces requêtes ne sont pas nécessaires pour les flux de balises côté serveur, où le serveur lance la vérification 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 https://{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 de validation des annonces avant d'envoyer chaque demande de validation.

Méthode : metadata

Le point de terminaison des métadonnées à l'adresse metadata_url renvoie des informations utilisées pour créer une UI d'annonce. Le point de terminaison des métadonnées n'est pas disponible pour les flux de balises côté serveur, où le serveur est responsable du lancement de la vérification du contenu multimédia publicitaire.

Méthodes
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

Récupère les informations sur les métadonnées des annonces.

Requête HTTP

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

Paramètres de requête

Paramètres
delta_token facultatif string

Jeton opaque représentant l'état de synchronisation actuel du client. Si un jeton est fourni, le serveur ne renvoie que les métadonnées qui ont été modifiées depuis la génération du jeton, ainsi qu'un nouveau next_delta_token dans la réponse. Si cet élément est omis, le serveur renvoie les métadonnées complètes pour l'ensemble de la fenêtre DVR.

Corps de la réponse

Si la requête aboutit, la réponse renvoie une instance de PodMetadata.

Utiliser des métadonnées

Les métadonnées comportent trois sections distinctes : tags, ads et breaks. Le point d'entrée dans les données est la section tags. À partir de là, parcourez les tags et recherchez la première entrée dont le nom est un préfixe pour l'ID du support publicitaire trouvé dans le flux vidéo. Par exemple, vous pouvez avoir un ID de support publicitaire qui ressemble à ceci :

google_1234567890

Vous trouverez ensuite un objet tag nommé google_12345. Dans ce cas, il correspond à l'ID de votre support publicitaire. Une fois que vous avez trouvé l'objet de préfixe de média d'annonce approprié, vous pouvez rechercher les ID d'annonce, les ID de coupure publicitaire et le type d'événement. Les ID d'annonces sont ensuite utilisés pour indexer les objets ads, et les ID de coupures publicitaires pour indexer les objets breaks.

Données de réponse

Flux

Stream permet d'afficher une liste de ressources pour un flux nouvellement créé au format JSON.
Représentation JSON
{
  "stream_id": string,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}
Champs
stream_id string

Identifiant de flux GAM.
stream_manifest string

URL du fichier manifeste du flux, utilisée pour récupérer la playlist multivariante au format HLS ou le fichier MPD au format DASH.
hls_master_playlist string

(OBSOLÈTE) URL de la playlist multivariante HLS. Utilisez plutôt "stream_manifest".
media_verification_url string

URL de validation du contenu multimédia utilisée comme point de terminaison de base pour le suivi des événements de lecture.
metadata_url string

URL des métadonnées utilisée pour interroger périodiquement des informations sur les prochains événements publicitaires du flux.
session_update_url string

URL de mise à jour de la session utilisée pour mettre à jour les paramètres de ciblage de ce flux. Les valeurs d'origine des paramètres de ciblage sont capturées lors de la première requête de création de flux.
polling_frequency number

Fréquence de sondage, en secondes, lors de la demande de metadata_url ou heartbeat_url.

PodMetadata

PodMetadata contient des informations de métadonnées sur les annonces, les pauses publicitaires et les tags d'ID de contenu multimédia.
Représentation JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
Champs
tags map[string, object(TagSegment)]

Carte des segments de balise indexés par préfixe de balise.
ads map[string, object(Ad)]

Carte des annonces indexées par ID d'annonce.
ad_breaks map[string, object(AdBreak)]

Carte des coupures publicitaires indexées par ID de coupure publicitaire.
next_delta_token string

Jeton opaque que le client doit utiliser lors de la prochaine interrogation.
obsolete_ad_break_ids string

Liste des ID de coupures publicitaires obsolètes qui doivent être supprimés du cache du client.

TagSegment

TagSegment contient une référence à une annonce, à sa coupure publicitaire et à son type d'événement. TagSegment avec type="progress" ne doit pas être envoyé au point de terminaison de validation du média publicitaire.
Représentation JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Champs
ad string

ID de l'annonce associée à ce tag.
ad_break_id string

ID de la coupure publicitaire de ce tag.
type string

Type d'événement de ce tag.

AdBreak

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

Les types de pause valides sont "pre", "mid" et "post".
duration number

Durée totale des annonces pour cette coupure publicitaire, en secondes.
expected_duration number

Durée attendue de la coupure publicitaire (en secondes), y compris toutes les annonces et le slate.
ads number

Nombre d'annonces dans la coupure publicitaire.
"Annonce" décrit une annonce dans le flux.
Représentation JSON
{
  "ad_break_id": string,
  "position": 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,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
Champs
ad_break_id string

ID de la coupure publicitaire de cette annonce.
position number

Position de cette annonce dans la coupure publicitaire, en commençant par 1.
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

ID de création facultatif.
deal_id string

ID de l'accord facultatif.
clickthrough_url string

URL de destination facultative.
click_tracking_urls string

URL de suivi des clics facultatives.
verifications [object(Verification)]

Entrées de vérification Open Measurement facultatives qui listent les ressources et les métadonnées requises pour exécuter le code de mesure tiers afin de vérifier la lecture de la création.
slate boolean

Booléen facultatif indiquant que l'entrée actuelle est une ardoise.
icons [object(Icon)]

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

Liste de wrappers, omise si elle est vide.
universal_ad_id object(UniversalAdID)

Identifiant d'annonce universel facultatif.
extensions string

Liste facultative de tous les nœuds <Extension> dans le VAST.
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.

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 clic 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. Pour le moment, seuls 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 sur le nœud <StaticResource> dans le VAST s'il s'agit d'une création associée de type statique.
height int32

Hauteur de ce complément en pixels.
width int32

Largeur de la création associée en pixels.
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.