Cette page a été traduite par l'API Cloud Translation.

Early ad break notification

Utiliser l'API de notification des coupures publicitaires précoces

Remarque: Cette API est encore en version bêta. Contactez votre responsable de compte si vous souhaitez demander l'accès au programme EABN.

L'API EABN (Early Ad Break Notification) vous permet d'informer Google Ad Manager de la prochaine coupure publicitaire avec ses métadonnées avant le début de la coupure. Vous pouvez envoyer une demande de notification jusqu'à une heure avant la coupure publicitaire. Ce guide explique comment activer et utiliser l'API EABN, et fournit des exemples de requêtes et de réponses.

Attention: Les requêtes EABN sont immuables. Dès lors qu'une interruption est créée, elle ne peut plus être modifiée. Les demandes ultérieures de création de coupures publicitaires pour le même événement sont refusées jusqu'à ce que la coupure apparaisse dans le fichier manifeste de l'événement.

Les appels passés à l'API EABN doivent inclure les informations suivantes:

Identifiant du flux en direct correspondant dans lequel la coupure publicitaire est créée. Il peut s'agir de l'un des types d'identifiants suivants:
"Clé d'élément" de la diffusion en direct.
La "clé d'élément personnalisée" de la diffusion en direct, qui vous permet de gérer votre propre espace de clés en spécifiant votre propre chaîne d'identifiant.
"Content ID" et "Content ID" de la diffusion en direct.

Remarque: Vous devez être activé pour utiliser ce type d'identifiant. Pour en savoir plus, contactez votre responsable de compte.

Durée prévue de la prochaine coupure publicitaire. La durée doit être aussi proche que possible de la durée réelle de la coupure publicitaire.

En plus de ces champs obligatoires, vous pouvez également envoyer des paramètres de ciblage personnalisés, le nom d'un modèle de série d'annonces à appliquer ou des données de point de sortie SCTE35, le cas échéant.

Prérequis

Pour utiliser l'API EABN, vous devez créer un compte de service et l'ajouter à votre réseau Google Ad Manager.

Créer un compte de service

Pour créer un compte de service permettant d'appeler l'API EABN, procédez comme suit: - Si vous possédez un compte Google Cloud, créez un compte de service à l'aide du module IAM. Pour en savoir plus, consultez la page Créer et gérer des comptes de service. - Si vous n'avez pas de compte Google Cloud, procédez comme suit pour en créer un depuis la console Google APIs:

Créez un projet ou sélectionnez un projet existant.
Sur la page Identifiants, cliquez sur Gérer les comptes de service.
Sur la page Comptes de service, cliquez sur CRÉER UN COMPTE DE SERVICE.
Sur la page Créer un compte de service, saisissez les détails du compte. Cliquez ensuite sur CRÉER.

Une fois que vous avez créé un compte de service, copiez la clé JSON du compte, qui sera utilisée pour l'authentification.

Ajouter votre compte de service à votre réseau Google Ad Manager

Pour ajouter votre compte de service à votre réseau, suivez la procédure décrite dans Ajouter un utilisateur de compte de service pour l'accès à l'API.

Activer l'API

Une fois le compte de service créé, fournissez les informations suivantes à votre responsable de compte afin qu'il active l'API pour votre compte:

Adresse e-mail de votre compte Google Cloud
Votre compte de service
Code de votre réseau Google Ad Manager.

Une fois l'API activée par votre responsable de compte, procédez comme suit:

Dans la bibliothèque d'API Google, recherchez "API vidéo Google Ad Manager".
Cliquez sur ENABLE (ACTIVER).

Remarque: Si l'API n'apparaît pas dans les résultats de recherche, contactez votre responsable de compte pour vérifier que l'API d'insertion dynamique d'annonce est activée dans votre compte.

Utilisation de l'API

Vous pouvez appeler l'API EABN à l'aide de requêtes JSON/REST.

Autorisation

Pour effectuer des appels autorisés vers l'API EABN, vous devez générer des identifiants de compte de service OAuth2 à l'aide de la clé JSON de votre compte de service et du champ d'application https://www.googleapis.com/auth/video-ads. Pour en savoir plus, consultez l'article Utiliser OAuth 2.0 pour l'authentification serveur à serveur.

Vous devez inclure le jeton d'autorisation obtenu en tant qu'en-tête Auth pour chaque appel à l'API EABN.

Envoyer une notification anticipée de coupure publicitaire

Pour envoyer une notification anticipée de coupure publicitaire, envoyez une demande POST à l'une des trois URL EABN valides, selon la manière dont vous souhaitez spécifier la diffusion en direct. Les sections suivantes décrivent les différences entre les URL et fournissent des exemples de requêtes et de réponses.

URL

Il existe trois URL valides pour les notifications anticipées de coupure publicitaire. Vous pouvez utiliser les trois types pour créer une coupure publicitaire (POST) ou obtenir la liste des coupures publicitaires attribuées (GET).

Pour utiliser la clé d'élément d'une diffusion en direct, utilisez:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

Pour utiliser la clé d'élément personnalisée d'une diffusion en direct, utilisez:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

Pour utiliser l'approche Content Source ID et Content ID, utilisez:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

Pour tous les paramètres:

network_code représente le code de votre réseau Google Ad Manager.
asset_key représente la clé d'élément affichée sur la page d'informations de votre diffusion en direct.
custom_asset_key représente la clé d'élément personnalisé de votre diffusion en direct.
content_source_id représente l'ID d'une source de contenu dans Google Ad Manager.
content_id représente l'ID d'un contenu dans Google Ad Manager.

Remarque: La paire content_source_id/content_id spécifiée doit être associée à un flux en direct dans Google Ad Manager.

Corps de la requête : utilisé uniquement pour créer une coupure publicitaire (POST)

Objet
`expectedDuration`	Obligatoire	Durée de cette coupure publicitaire, au format de durée standard de Google (xx,xxx s, où xx,xxx correspond au nombre de secondes)
`customParams`	Facultatif	Paires clé-valeur à inclure dans les demandes d'annonces pour cette coupure publicitaire pour le ciblage par critères personnalisés dans AM360, séparées par `=` et rejoint par `&` . Exemple: `key=value&key2=value2,value3` Pour en savoir plus sur le ciblage, consultez Fournir des paramètres de ciblage à votre flux.
`podTemplateName`	Facultatif	Nom du modèle de série d'annonces
`scte35CueOut`	Facultatif	Données encodées en base64 à partir du point de sortie scte35. Peut inclure les `splice_insert()` ou `time_signal()` en utilisant la commande gcloud, Exemples: time_signal(): `/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==` splice_insert(): `/DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=`

Exemples de requête

Créer une coupure publicitaire

POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}

Corps de la réponse

Le corps de la réponse contient tous les paramètres envoyés dans l'objet adBreak, ainsi qu'un champ name supplémentaire, qui contient l'ID standard Google de la coupure publicitaire créée. Ce champ est renvoyé au format suivant:

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}

Exemple de réponse

HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}

Répertorier les coupures publicitaires attribuées

GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …

Corps de la réponse

Le corps de la réponse contient les coupures publicitaires, avec un champ breakState supplémentaire pour chaque coupure publicitaire attribuée au flux. Le champ breakState accepte les valeurs suivantes:

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE

Exemple de réponse

HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}