API Dynamic Ad Insertion Linear

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

Service: dai.google.com

Tous les URI ci-dessous sont liés à 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 de l'événement du flux.
Remarque: La clé d'élément de flux est un identifiant qui se trouve également dans l' interface utilisateur d'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 valeur sur true pour créer un flux de balisage côté serveur. La valeur par défaut est false. Le suivi du flux par défaut est lancé par le client et pingué côté serveur.
Paramètres de ciblage dans DFP Facultatif Paramètres de ciblage supplémentaires
Remplacer les paramètres de flux Facultatif Ignorez les valeurs par défaut d'un paramètre de création de flux.
Authentification HMAC Facultatif Authentifiez-vous à l'aide d'un jeton HMAC.

Corps de la réponse

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

Open Measurement

L'API d'insertion dynamique d'annonce contient des informations pour la validation Open Measurement dans le champ Verifications. Ce champ contient un ou plusieurs éléments Verification qui répertorient les ressources et les métadonnées requises pour exécuter le code de mesure tierce afin de vérifier la lecture des créations. Seul JavaScriptResource est accepté. Pour en savoir plus, consultez le site de l'IAB Tech Lab et la spécification VAST 4.1.

Méthode: vérification des supports

Lorsque vous rencontrez un identifiant de support publicitaire lors de la lecture, envoyez immédiatement une requête à l'aide de l'élément media_verification_url obtenu à partir du point de terminaison stream, ci-dessus. Ces requêtes ne sont pas nécessaires pour les flux de balisage côté serveur, où le serveur lance la vérification des contenus multimédias.

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 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 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 contenus multimédias publicitaires seront encodés dans des métadonnées minutées HLS à l'aide de la clé TXXX, réservée aux trames d'informations textuelles définies par l'utilisateur. Le contenu du frame n'est pas chiffré et commence toujours par le texte "google_".

L'intégralité du contenu textuel du frame doit être ajouté à l'URL de vérification des annonces avant d'effectuer chaque demande de validation d'annonce.

Méthode: metadata

Le point de terminaison des métadonnées à 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 balisage côté serveur, où le serveur est chargé de lancer la validation du mé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}

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 l'annonce breaks. Le point d'entrée dans les données est la section tags. À partir de là, itérez les tags et recherchez la première entrée dont le nom est un préfixe de l'ID d'élément multimédia d'annonce trouvé dans le flux vidéo. Par exemple, vous pouvez avoir un ID de média publicitaire semblable à celui-ci:

google_1234567890

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

Données de réponse

Flux

Le flux permet d'afficher une liste de ressources au format JSON pour un flux nouvellement créé.
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 de multivariantes dans HLS ou la description de la présentation du média dans DASH.
hls_master_playlist string

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

URL de validation multimédia utilisée comme point de terminaison de base pour suivre les événements de lecture.
metadata_url string

URL de métadonnées utilisée pour interroger des informations périodiques sur les événements d'annonces de flux à venir.
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 demande initiale de création du flux.
polling_frequency number

Fréquence d'interrogation, en secondes, lorsque vous demandez "metadata_url de" ou "Heartbeat_url".

PodMetadata

PodMetadata contient des informations de métadonnées sur les annonces, les coupures publicitaires et les tags d'identifiant multimédia.
Représentation JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
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.

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 pingué vers le point de terminaison Ad Media Verification.
Représentation JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Champs
ad string

ID de l'annonce associée à cette balise.
ad_break_id string

ID de la coupure publicitaire de cette balise.
type string

Type d'événement de cette balise.

AdBreak

Une coupure publicitaire décrit une seule coupure publicitaire dans le flux. Elle contient une durée, un type (milieu/avant/après) et le nombre d'annonces.
Représentation JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Champs
type string

Les types de coupures acceptés sont les suivants : "avant", "milieu" et "après".
duration number

Durée totale de l'annonce (en secondes) pour cette coupure publicitaire.
expected_duration number

Durée prévue de la coupure publicitaire (en secondes), incluant toutes les annonces et tous les écrans.
ads number

Nombre d'annonces dans la coupure publicitaire.
Une annonce désigne une annonce diffusée 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, à partir de 1.
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

ID d'annonce facultatif.
creative_id string

ID de création facultatif.
creative_ad_id string

ID de l'annonce de création facultatif.
deal_id string

ID d'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 validation Open Measurement facultatives qui listent les ressources et les métadonnées requises pour exécuter le code de mesure tierce afin de vérifier la lecture des créations.
slate boolean

Valeur booléenne facultative indiquant que l'entrée actuelle est un écran.
icons [object(Icon)]

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

Liste de wrappers, omis s'ils sont vides.
universal_ad_id object(UniversalAdID)

ID d'annonce universelle facultatif
extensions string

Liste facultative de tous les nœuds <Extension> dans la norme VAST.
companions [object(Companion)]

Créations associées facultatives qui peuvent être affichées avec cette annonce.
interactive_file object(InteractiveFile)

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

Icon

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 d'ID d'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 la 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, qui facilite la mesure tierce 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 validation
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 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 qui doivent être pinguées par le client 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 de création unique qui est géré dans tous les systèmes publicitaires.
Représentation JSON
{
  "id_value": string,
  "id_registry": string,
}
Champs
id_value string

Identifiant d'annonce universelle de la création sélectionnée.
id_registry string

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

Annonce associée

Companion contient des informations sur les annonces associées qui peuvent être affiché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

Attribut CreativeType sur le nœud <StaticResource> dans VAST s'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 créations associées statiques et iFrame, il s'agit de l'URL à charger et à afficher. Pour les créations HTML associées, il s'agit de l'extrait de code HTML qui doit s'afficher en tant que création associée.
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'espace publicitaire de cette annonce associée.
api_framework string

Framework d'API pour cette création associée.
tracking_events [object(TrackingEvent)]

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

InteractiveFile

InteractiveFile contient des informations sur 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

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

Valeur du nœud <AdParameters> dans la norme VAST.