API active de diffusion de séries d'annonces pour l'insertion dynamique d'annonces

L'API d'insertion dynamique d'annonces vous permet de demander des diffusions en direct pour l'insertion dynamique d'annonce et d'en effectuer le suivi.

Service: dai.google.com

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

Méthode: stream

Méthodes
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Enregistre une session de diffusion en direct de diffusion de séries d'annonces pour l'insertion dynamique d'annonces dynamiques.

Requête HTTP

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Paramètres de chemin

Paramètres
network_code string

Le code de réseau Google Ad Manager de l'éditeur

custom_asset_key string

Identifiant personnalisé associé à cet événement dans Google Ad Manager.

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
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 un nouvel objet Stream.

Open Measurement

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

Méthode: segment de série d'annonces

Méthodes
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

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

Requête HTTP

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Paramètres de chemin

Paramètres
network_code string

Le code de réseau Google Ad Manager de l'éditeur

custom_asset_key string

Identifiant personnalisé associé à cet événement dans Google Ad Manager.

pod_id integer

Identifiant numérique de la coupure publicitaire en cours. Les ID de séries d'annonces sont est attribué de manière incrémentielle à chaque événement, à partir de 1.

<ph type="x-smartling-placeholder">
profile_name string

La nom de la valeur demandée Profil d'encodage pour l'insertion dynamique d'annonce Google Ad Manager. Le profil d'encodage doit être l'un des profils d'encodage configurés pour l'événement sélectionné.

segment_number integer

Index du segment demandé dans la série d'annonces actuelle, à partir du à zéro.

<ph type="x-smartling-placeholder">
segment_format string

Extension de fichier associée au format de segment demandé. Les extensions acceptées sont les suivantes: ts, mp4, vtt, aac, ac3 ou eac3

Paramètres de requête

Paramètres
stream_id obligatoire string

ID de flux de la session de l'utilisateur actuel. Cette valeur est renvoyée par une requête réussie au point de terminaison stream.
sd required1 integer

Durée du segment demandé, en millisecondes.
so facultatif

Décalage du segment demandé dans la série d'annonces, en millisecondes. Si vous omettez le paramètre so, il sera calculé comme suit : en multipliant la durée du segment par le numéro du segment.
pd obligatoire2 integer

Durée de la série d'annonces, en millisecondes.
auth-token obligatoire string

Une clé-valeur signée, encodée au format URL Jeton HMAC pour la série d'annonces actuelle.
last facultatif boolean

Indique le dernier segment de la coupure publicitaire. Omettez ce paramètre pour tous d'autres segments.
scte35 facultatif string

Signal SCTE-35 encodé en base64 pour cette coupure publicitaire.
cust_params facultatif string

Ensemble de paires clé-valeur utilisé pour le ciblage des campagnes Ad Manager. Ces doivent être représentées par une chaîne de requête encodée au format URL.

Exemple :
Paramètres
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Notes de bas de page

  1. sd n'est pas requis pour les segments d'initialisation. ↩
  2. pd n'est pas obligatoire pour les événements comportant une annonce sans durée sauts de page activés. ↩

Corps de la réponse

Si la requête aboutit, le corps de la réponse sera un segment de flux lisible correspondant à et les paramètres spécifiés dans la requête.

Méthode: modèle de période de série d'annonces DASH

Méthodes
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Demande un modèle de période DASH à partir de Google Ad Manager. Ce modèle contient des macros que vous devez renseigner avec vos paramètres de flux. Une fois ces macros sont insérées, le modèle devient la période de coupure publicitaire et peuvent être intégrées à votre fichier manifeste DASH.

<ph type="x-smartling-placeholder">

Requête HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Paramètres de chemin

Paramètres
network_code string

Le code de réseau Google Ad Manager de l'éditeur

custom_asset_key string

Identifiant personnalisé associé à cet événement dans Google Ad Manager.

Paramètres de requête

Paramètres
stream_id obligatoire string

ID de flux de la session de l'utilisateur actuel. Cette valeur est renvoyée par une requête réussie au point de terminaison stream.

Corps de la réponse

Si la requête aboutit, le corps de la réponse contient une nouvelle objet PodTemplateResponse.

Méthode: vérification des supports

Lorsque l'identifiant d'un support publicitaire s'affiche pendant la lecture, effectuez immédiatement une à l'aide de l'élément media_verification_url obtenu dans le flux stream point de terminaison, comme indiqué ci-dessus. Ces requêtes ne sont pas nécessaires pour le balisage côté serveur flux, où le serveur lance la validation 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 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é.
  • HTTP/1.1 404 Not Found si la requête ne peut pas valider le contenu multimédia pour les raisons suivantes : Format d'URL incorrect ou expiration
  • HTTP/1.1 404 Not Found s'il s'agissait d'une précédente demande de validation pour cet ID réussi.
  • HTTP/1.1 409 Conflict si une autre demande envoie déjà des pings à ce stade en temps réel.

ID des supports publicitaires

Les identifiants des supports publicitaires sont codés dans une piste de métadonnées distincte (avec code temporel) Métadonnées pour le flux de transport HLS ou e-mail pour les fichiers MP4. Identifiants de supports publicitaires commence toujours par la chaîne google_.

L'intégralité du contenu textuel de l'entrée de métadonnées doit être ajouté à l'annonce l'URL de validation avant d'envoyer chaque demande de validation d'annonce.

Méthode: metadata

Le point de terminaison des métadonnées à metadata_url renvoie les informations utilisées pour créer une annonce UI. 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 vérification 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

Analyser les métadonnées

Les métadonnées comportent trois sections distinctes: tags, ads et l'annonce breaks. L'entrée point dans les données est la section tags. À partir de là, itérez les balises et rechercher la première entrée dont le nom est un préfixe identifiant du contenu multimédia de l'annonce détecté dans le flux vidéo. Par exemple : peut 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, elle correspond ID d'élément multimédia de l'annonce. Une fois que vous avez trouvé l'objet de préfixe de média d'annonce approprié, vous pouvez rechercher les identifiants des annonces, les identifiants des coupures publicitaires et le type d'événement. Les identifiants d'annonce sont ensuite utilisés pour indexer Les objets ads et les ID de coupure publicitaire permettent d'indexer les objets breaks.

Données de réponse

Flux

Le flux permet d'afficher la liste des ressources d'un nouveau flux dans JSON.
Représentation JSON
{
  "stream_id": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
Champs
stream_id string

Identifiant de flux GAM.
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 rechercher 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.
heartbeat_url string

L'URL de pulsation, utilisée pour maintenir actif le flux de balisage côté serveur, elle doit être pinguée toutes les {PollingFrequency} secondes. Valeur renseignée pour les flux de balisage côté serveur.
polling_frequency number

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

Le modèle d'URL du fichier manifeste du pod permet de générer l'URL permettant de récupérer le fichier manifeste du pod d'un flux. correspondant à l'URL de la playlist de multivariantes dans HLS ou de la description de la présentation du média dans DASH. Renseigné pour les événements de diffusion en direct du type d'insertion dynamique d'annonce POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

Le format du fichier manifeste est le format du fichier manifeste récupéré à partir du champ "pod_manifest_url", soit -, soit hls.

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 identifiant.
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 with type="progress" ne doivent pas être pingués vers le support publicitaire le point de terminaison de validation.
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, le 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 valides 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 facultative de l'annonce.
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.
click_tracking_urls string

URL de suivi des clics facultatives.
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.
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)

Identifiant d'annonce universel facultatif.
extensions string

Liste facultative de tous les éléments <Extension> dans le format VAST.
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.

PodTemplateResponse

PodTemplateResponse représente la charge utile JSON renvoyée à un VTP pour l'assemblage de pods.
Représentation JSON
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
Champs
dash_period_template string

DashPeriodTemplate est le modèle XML pour la période à renseigner avec les données appropriées avant l'assemblage.
segment_duration_ms int64

SegmentDurationMS est la durée des segments de période en millisecondes.

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

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.