API vidéo Cloud SSAI

Dans cette rubrique, vous apprendrez comment utiliser l'API d'insertion d'annonces côté serveur (SSAI) pour créer et gérer des configurations d'annonces.

Les configurations publicitaires définissent divers aspects de la lecture SSAI, y compris les appels publicitaires, les balises et d'autres options de configuration. Un compte peut avoir plusieurs configurations et actuellement les configurations ne peuvent pas être partagées entre les comptes.

Informations générales

Les informations suivantes concernent toutes les demandes d'API SSAI.

URL de base

L'URL de base de l'API SSAI est :

https://ssai.api.brightcove.com/v1

Chemin du compte

Dans tous les cas, des demandes seront faites pour un Nuage vidéo Compte. Par conséquent, vous allez toujours ajouter le terme accounts suivi de votre identifiant de compte à l'URL de base :

https://ssai.api.brightcove.com/v1/accounts/your account id

Authentification

L'authentification des demandes nécessite un en-tête d'autorisation :

Authorization: Bearer your access token

Le access_token est un jeton d'accès OAuth2 temporaire qui doit être obtenu à partir du service Brightcove OAuth. Pour plus de détails sur la façon d'obtenir les informations d'identification client et de les utiliser pour récupérer des jetons d'accès, consultez le Authentification pour les demandes d'API Brightcove.

Opérations

Lorsque vous demandez des informations d'identification du client, vous devez spécifier le type d'accès au compte ou d'opérations que vous souhaitez. Voici une liste des opérations actuellement prises en charge pour l'API SSAI :

  • Données SSAI :

    video-cloud/ssai/read
    video-cloud/ssai/all

Gérer les configurations d'annonces

L'API prend en charge les requêtes GET et PUT suivantes :

Répertorier les configurations d'annonces

Répertoriez les configurations d'annonces définies pour un compte.

Méthode AVOIR
URL https://ssai.api.brightcove.com/v1/accounts/votre identifiant de compte/ssai_configs
Headers Authorization: Porteur votre jeton d'accès
Type de contenu : application/json

Réponse de l'échantillon :

[
  {
    "name": "VMAP Ad Server",
    "vmap_response_namespace": "bc",
    "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
    "account_id": "57838016001",
    "created_timestamp": "2017-07-24T19:28:34.976878586Z",
    "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
    "ad_config": {
      "expected_ad_response": "dfp_ad_rules",
      "disable_server_beacons": false,
      "template_url": {
          "template": "https://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
      }
    }
  }
]

Pour les définitions des champs, voir la section Détails des champs de configuration .

Créer une configuration d'annonce

Créez une configuration d'annonce pour un compte.

Méthode POST
URL https://ssai.api.brightcove.com/v1/accounts/votre identifiant de compte/ssai_configs
Headers Authorization: Porteur votre jeton d'accès
Type de contenu : application/json

Exemple de corps :

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "ad_tracking_sample_percentage": 100,
  "ad_config": {
    "expected_ad_response": "vast_3_0",
    "disable_server_beacons": false,
    "round_up_cue_points": false,
    "template_url": {
      "template": "https://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
    }
  },
  "discontinuities": {
    "hls": [ "*" ]
  }
}

Pour les définitions des champs, voir la section Détails des champs de configuration .

Remarques

  • ad_tracking_sample_percentage détermine le pourcentage de sessions qui seront enregistrées. Il peut prendre une valeur comprise entre 0 (désactivation de l'enregistrement) et 100 (enregistrement de toutes les sessions).

Obtenir les détails de la configuration des annonces

Pour un compte, obtenez les détails de configuration de l'annonce par Id de configuration.

Méthode AVOIR
URL https://ssai.api.brightcove.com/v1/accounts/votre identifiant de compte/ssai_configs/votre identifiant de configuration d'annonce
Headers Authorization: Porteur votre jeton d'accès
Type de contenu : application/json
Réponse de l'échantillon : 
	{
		"name": "VMAP Ad Server",
		"vmap_response_namespace": "bc",
		"config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
		"account_id": "57838016001",
		"created_timestamp": "2017-07-24T19:28:34.976878586Z",
		"updated_timestamp": "2017-07-24T19:28:34.976878586Z",
    "ad_tracking_sample_percentage": 100,
		"ad_config": {
			"expected_ad_response": "dfp_ad_rules",
			"disable_server_beacons": false,
			"template_url": {
					"template": "https://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
			}
		},
		"beacon_templates": [
				{
					"type": "content_start",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				},
				{
					"type": "content_midpoint",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				},
				{
					"type": "ad_start",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				},
				{
					"type": "content_complete",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				}
			],
			"discontinuities": {
				"dash": [
					"*"
				],
				"hls": [
					"*"
				]
			},
			"extend_beacon_guard_ttl": true
		}
	}

Pour les définitions des champs, voir la section Détails des champs de configuration .

Mettre à jour une configuration d'annonce

Mettre à jour une configuration d'annonce par l'ID de configuration.

Méthode METTRE
URL https://ssai.api.brightcove.com/v1/accounts/votre identifiant de compte/ssai_configs/votre identifiant de configuration d'annonce
Headers Authorization: Porteur votre jeton d'accès
Type de contenu : application/json
Corps de l'échantillon 
{
    "name": "VMAP Ad Server - updated"
}
Réponse de l'échantillon : 
	{
		"name": "VMAP Ad Server - updated",
		"vmap_response_namespace": "bc",
		"config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
		"account_id": "57838016001",
		"created_timestamp": "2017-07-24T19:28:34.976878586Z",
		"updated_timestamp": "2017-07-24T19:28:34.976878586Z",
		"ad_config": {
			"expected_ad_response": "dfp_ad_rules",
			"disable_server_beacons": false,
			"template_url": {
				"template": "https://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
			}
		}
	}

Pour les définitions des champs, voir la section Détails des champs de configuration .

Détails du champ de configuration

Ce tableau définit les champs de configuration d'annonce utilisés dans la section corps d'une demande.

Champ Type Description
name Chaîne Nom lisible par l'homme
vmap_response_namespace Chaîne Ajuste la sortie VMAP pour utiliser l'ancien format d'espace de noms Unicorn Once ou pour utiliser le nouveau format d'espace de noms Brightcove.

Valeurs : uo, bc Par défaut : bc
description Chaîne Description lisible par l'homme
ad_config.expected_ad_response Chaîne Quelle technologie utiliser pour analyser la réponse. [ 1]

Valeurs :
  • dfp_ad_rules
  • dfp_vmap
  • smart_xml
  • vast_3_0
Pour plus de détails, voir la section Types de réponses publicitaires .
ad_config.disable_server_beacons Booléen Indique si le déclenchement côté serveur des impressions/balises publicitaires doit être désactivé.

Lorsqu'il est défini sur true, SSAI ne déclenche pas de balises côté serveur et inclura toutes les balises dans la sortie VMAP

Lorsqu'il est défini sur false, SSAI déclenche les balises qu'il est capable de côté serveur et inclut tout ce qu'il n'est pas en mesure de faire dans la sortie VMAP
ad_config.round_up_cue_points Booléen Indique s'il faut arrondir à l'image clé suivante lors du choix d'une position à proximité pour l'insertion d'annonces.

Par défaut : false, qui choisit l'image-clé la plus proche de la position d'annonce souhaitée.
ad_config.template_url.template Chaîne Modèle de tag d'emplacement publicitaire. Variables disponibles décrites dans une section ultérieure.
ad_config.template_url.defaults Objet Mappage de String à String définissant la valeur par défaut à utiliser dans le cas où un paramètre d'URL n'est pas fourni.

Peut être un littéral { "url.foo": "SomeString" }

Ou référencer une autre variable { "url.foo": "{{ metadata.title_id }}" }
ad_tracking_sample_percentage entier Cette valeur détermine le pourcentage de sessions qui seront enregistrées. Il peut avoir une valeur comprise entre 0(désactiver la journalisation) et 100(enregistrer toutes les sessions). La valeur 0 désactive complètement les journaux.

Par défaut : 0

Valeurs : [ 0 .. 100 ]
beacon_templates baie Un tableau de balises à tirer (exemple : balises tierces)
beacon_templates[].type Chaîne

Type de balise à tirer. Valeurs:

  • content_start
  • content_first_quartile
  • content_midpoint
  • content_third_quartile
  • content_complete
  • content_quartiles
  • content_interval
  • ad_start
  • ad_first_quartile
  • ad_midpoint
  • ad_third_quartile
  • ad_complete
  • ad_quartiles
  • ad_break_start
  • ad_break_end
  • segment_start
  • segment_end
  • on_load
beacon_templates[].template_url.template Chaîne Modèle d'URL de balise
discontinuities.dash [ 2] []Chaîne de caractères Contrôle les versions de Dash pour fournir des manifestes Multi Period Dash.

Définie ["*"] sur pour fournir un tiret multipériode pour toutes les versions Liste

vide pour jamais

Exemple : ["live-timeline"] à livrer pour live timeline mais pas pour hbbtv
discontinuities.hls [ 2] []Chaîne de caractères Contrôle les versions de hls à livrer avec des discontinuités.

["*"] Définir sur livraison avec discontinuités dans toutes les versions de HLS Liste

vide pour jamais

Exemple : ["v4","v5"] à livrer pour v4 et v5 mais pas pour v3
extend_beacon_guard_ttl Booléen Définit la durée de la durée de vie de Beacon Guard TTL (Time to live) à la durée de la session TTL du contenu. Sinon, la valeur par défaut est 1 minute.

Types de réponses publicitaires

Voici quelques informations supplémentaires sur l'utilisation des ad_config.expected_ad_response types figurant dans le tableau ci-dessus. Valeurs:

Flux de processus

Configurations VOD SSAI
Configurations VOD SSAI

Lorsque vous créez des configurations publicitaires SSAI, gardez à l'esprit les remarques suivantes :

VMAP

Si le type de réponse publicitaire de SSAI Config est DFP VMAP :

  • Tous les marqueurs configurés avec une vidéo seront ignorés.
  • Le SSAI analyse le fichier XML VMAP du fournisseur de publicité qui contient toutes les publicités avec leurs positions définies.

VASTE

Si le type de réponse publicitaire de SSAI Config est VAST 3.0 :

  • Définissez des points de repère dans votre vidéo. Le SSAI fera des demandes pour chaque point de repère dans la vidéo afin de construire des pauses publicitaires.
  • Si aucun marqueur temporel n'est configuré pour une vidéo, une publicité de type preroll est insérée par défaut.

Variables publicitaires

Les variables de l'URL du modèle sont identifiées par des accolades doubles ({{ … }}) avec des espaces blancs optionnels avant et après le chemin d'accès à la variable. Toutes les variables sont préfixées par l'un des trois espaces de noms :

Variables système

Les variables système sont fournies par le système SSAI et peuvent être des informations sur l'utilisateur final ou des variables auxiliaires pour générer des valeurs aléatoires. Les valeurs doivent être codées en URI avant d'être insérées dans les modèles d'URL.

Les variables système sont identifiées comme : {{system.*}}

Champ Description
ad.position_time Le temps en secondes du Cue Point qui a déclenché la demande d'annonce ; Uniquement disponible pour le type de réponse d'annonce VAST
ip_address Adresse IP de l'utilisateur final
random_number_32 Entier aléatoire de 32 bits
random_number_<min>_<max> Génère un nombre aléatoire entre deux nombres. La plage acceptée va de 0 à la valeur maximale de UInt32. Seuls les nombres positifs sont autorisés, et le min doit être inférieur au max
random_guid UUID aléatoire
referer Valeur de l'en-tête Référent de l'utilisateur final
timestamp_utc Heure actuelle sous forme d'horodatage Unix
unique_user_id MD5 (adresse_ip + agent_utilisateur)
unix_timestamp Heure actuelle sous forme d'horodatage Unix (secondes)
user_agent Valeur d'en-tête User-Agent de l'utilisateur final
uuid Uuid aléatoire
x_forwarded_for Valeur d'en-tête X-Forwarded-For de l'utilisateur final
xfp.correlator Entier aléatoire 64 bits
xfp.ip_address Adresse IP de l'utilisateur final
xfp.unique_user_id MD5 (adresse_ip + agent_utilisateur)
xfp.scor Entier aléatoire 64 bits

Variables d'URL

Les paramètres de requête fournis sur le point d'entrée VMAP/Manifest sont disponibles sous le url espace de noms. Contrairement aux variables sous d'autres espaces de noms, ces paramètres ne sont pas codés en URL lors de l'insertion dans le modèle. Si les valeurs des variables doivent être encodées en URL pour aller au fournisseur de publicité, elles devront être encodées en double sur l'url du point d'entrée.

Les variables d'URL sont identifiées comme : {{url.*}}

Les variables URL doivent être remplacées à l'aide d'une intégration personnalisée comme suit :

  1. Écrire du code pour faire une demande à l'API de lecture.
  2. Intercepte les données renvoyées par la requête API.
  3. Remplacez tous {{url.*}} les jetons dans les URL sources
  4. Chargement des données/sources dans le lecteur (Brightcove Player for web ou les SDK natifs)

Variables de métadonnées

Les variables de métadonnées sont celles qui décrivent le contenu vidéo, dérivées des sources de données Video Cloud et Dynamic Delivery. Les valeurs (à l'exception de ad_keys) sont codées en URL avant d'être insérées dans les modèles d'URL.

Les variables de métadonnées sont identifiées comme : {{metadata.*}}

Champ Description
ad_keys

Chaîne de texte libre qui peut être ajoutée et modifiée dans le module médias de Video Cloud Studio à l'aide de l'un des deux champs ci-dessous, en fonction du type de réponse à votre publicité

  • Non Vast 3.0 - Champ vidéo "Ad Keys
  • Vast 3.0 - Le champ vidéo "Ad Keys" est concaténé avec le champ "Key/Value Pairs" sur les marqueurs vidéo. Pour savoir comment travailler avec des marqueurs, voir le document Travailler avec des marqueurs dans le module Média .
custom_fields.{field_name} Champs personnalisés de Video Cloud
long_description Description longue de Video Cloud
name Nom de la vidéo Video Cloud
reference_id Identifiant de référence Video Cloud
tags Liste séparée par des virgules des balises Video Cloud pour la vidéo
title.duration Durée du contenu en secondes
title.id Identifiant du titre de la diffusion dynamique
title.name Nom du titre de la diffusion dynamique
video_id Identifiant vidéo Video Cloud
D' autres paires clé/valeur Video Cloud seraient également là

Paramètres d'URL du point d'entrée

Il existe une poignée de paramètres de requête qui peuvent être ajoutés à l'URL du point d'entrée SSAI (VMAP ou manifeste) afin de modifier certains comportements :

Paramètre Description
?rule=sd-only Filtre tout rendu vidéo dont la hauteur est inférieure au seuil défini dans la configuration du compte
?rule=discos-enabled Activez la lecture avec discontinuités dans HLS et multipériodes dans Dash. A la priorité sur le réglage des discontinuités dans la configuration de lecture
?rule=discos-disabled Désactivez la lecture avec discontinuités dans HLS et multipériodes dans Dash. A la priorité sur le réglage des discontinuités dans la configuration de lecture

Notes de configuration

  1. Le préchargement des annonces ne doit pas être effectué avec SSAI. La raison en est que si vous préchargez, le lecteur signalera une impression publicitaire et probablement les balises du premier quartile avant la lecture de la vidéo. Cela pourrait conduire à des analyses publicitaires inexactes. Si vous configurez SSAI dans Studio, cela se fera automatiquement, mais si vous configurez SSAI manuellement, vous devez être conscient de ce problème.
  2. Si le lecteur Web utilise SSAI et que l'une de vos motivations est de contourner les bloqueurs de publicités, vous devez utiliser des balises côté serveur. Les balises côté client ne doivent pas être utilisées car elles seront bloquées.

Macros côté client

Utilisez le page préfixe lorsque vous souhaitez utiliser des macros publicitaires côté client. Ces macros vous permettent d'utiliser des variables dans les URL de VMAP et de serveur. Pour plus de détails sur les macros publicitaires, reportez-vous à la section Macros Ad et ServerURL du document Advertising with the IMA3 Plugin.

Les macros côté client sont préfixées par : {{page.*}}

Par exemple, pour ajouter le document.referrer et un pageVariable variable de fenêtre DOM, vous les préfixeriez avec page dans le modèle d'annonce comme suit :

https://adserver.com/{{page.document.referrer}}/{{page.pageVariable.whateverIwant}}

L'API de lecture revient document.referrer et pageVariable.whateverIwant ajouté aux URL VMAP et SRC. Le lecteur Brightcove exécute ensuite sa logique de remplacement de macro côté client pour remplacer les valeurs appropriées, avant d'envoyer la demande :

https://bolt-prefix/blah.vmap?document.referrer={document.referrer}&pageVariable.whateverIwant={pageVariable.whateverIwant}

Balises d'erreur publicitaire

Les balises d'erreur publicitaire VAST lors de l'utilisation de SSAI peuvent être utiles pour rechercher et résoudre de manière proactive les problèmes liés à votre flux de travail publicitaire. Pour plus de détails, consultez le Balises d'erreur publicitaire avec SSAI document.