Video Cloud SSAI-API

In diesem Thema erfahren Sie, wie Sie mit der Server-Side Ad Insertion (SSAI) API Anzeigenkonfigurationen erstellen und verwalten.

Anzeigenkonfigurationen definieren verschiedene Aspekte der SSAI-Wiedergabe, einschließlich Anzeigenaufruf(en), Beacons und andere Konfigurationsoptionen. Ein Konto kann mehrere Konfigurationen haben und Konfigurationen können derzeit nicht zwischen Konten geteilt werden.

Allgemeine Informationen

Die folgenden Informationen beziehen sich auf alle SSAI-API-Anfragen.

Basis-URL

Die Basis-URL für die SSAI-API lautet:

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

Account-Pfad

In allen Fällen werden Anfragen für ein bestimmtes Video Cloud-Konto gestellt. Sie fügen also immer den Begriff accounts gefolgt von Ihrer Konto-ID zur Basis-URL hinzu:

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

Authentifizierung

Die Authentifizierung für Anfragen erfordert einen Authorization-Header:

Authorization: Bearer your access token

Die access_token ist ein temporäres OAuth2-Zugriffstoken, das vom Brightcove OAuth-Dienst abgerufen werden muss. Ausführliche Informationen zum Abrufen von Client-Anmeldeinformationen und deren Verwendung zum Abrufen von Zugriffstoken finden Sie im Authentifizierung für Brightcove-API-Anforderungen.

Betrieb

Wenn Sie Client-Anmeldeinformationen anfordern, müssen Sie die Art des Kontozugriffs oder der gewünschten Vorgänge angeben. Im Folgenden finden Sie eine Liste der derzeit unterstützten Operationen für die SSAI-API:

  • SSAI-Daten:

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

Anzeigenkonfigurationen verwalten

Die API unterstützt die folgenden GET- und PUT-Anfragen:

Anzeigenkonfigurationen auflisten

Listen Sie die für ein Konto definierten Anzeigenkonfigurationen auf.

Methode WERDEN
URL https://ssai.api.brightcove.com/v1/accounts/deine Konto-ID/ssai_configs
Header Autorisierung: Träger Ihr Zugangstoken
Inhaltstyp: application/json

Beispielantwort:

[
  {
    "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 }}"
      }
    }
  }
]

Für Felddefinitionen siehe die Konfigurationsfelddetails Abschnitt.

Erstellen Sie eine Anzeigenkonfiguration

Erstellen Sie eine Anzeigenkonfiguration für ein Konto.

Methode BEITRAG
URL https://ssai.api.brightcove.com/v1/accounts/deine Konto-ID/ssai_configs
Header Autorisierung: Träger Ihr Zugangstoken
Inhaltstyp: application/json

Probenkörper:

{
  "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": [ "*" ]
  }
}

Für Felddefinitionen siehe die Konfigurationsfelddetails Abschnitt.

Anmerkungen

  • ad_tracking_sample_percentage bestimmt den Prozentsatz der Sitzungen, die protokolliert werden. Er kann einen Wert zwischen 0 (Protokollierung deaktivieren) und 100 (alle Sitzungen protokollieren) annehmen.

Details zur Anzeigenkonfiguration abrufen

Rufen Sie für ein Konto die Anzeigenkonfigurationsdetails nach Konfigurations-ID ab.

Methode WERDEN
URL https://ssai.api.brightcove.com/v1/accounts/deine Konto-ID/ssai_configs/deine Anzeigenkonfig-ID
Header Autorisierung: Träger Ihr Zugangstoken
Inhaltstyp: application/json
Beispielantwort: 
	{
		"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
		}
	}

Für Felddefinitionen siehe die Konfigurationsfelddetails Abschnitt.

Aktualisieren einer Anzeigenkonfiguration

Aktualisieren Sie eine Anzeigenkonfiguration anhand der Konfigurations-ID.

Methode STELLEN
URL https://ssai.api.brightcove.com/v1/accounts/deine Konto-ID/ssai_configs/deine Anzeigenkonfig-ID
Header Autorisierung: Träger Ihr Zugangstoken
Inhaltstyp: application/json
Proben-Körper 
{
    "name": "VMAP Ad Server - updated"
}
Beispielantwort: 
	{
		"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 }}"
			}
		}
	}

Für Felddefinitionen siehe die Konfigurationsfelddetails Abschnitt.

Details zum Konfigurationsfeld

Diese Tabelle definiert die Anzeigenkonfigurationsfelder, die im Hauptteil einer Anfrage verwendet werden.

Feld Typ Beschreibung
name Zeichenfolge Für Menschen lesbarer Name
vmap_response_namespace Zeichenfolge Passt die VMAP-Ausgabe an, um das alte Unicorn Once-Namespace-Format oder das neue Brightcove-Namespace-Format zu verwenden.

Werte: uo, bc Standard: bc
description Zeichenfolge Für Menschen lesbare Beschreibung
ad_config.expected_ad_response Zeichenfolge Welche Technologie soll zum Analysieren der Antwort verwendet werden? [1]

Werte:
  • dfp_ad_rules
  • dfp_vmap
  • smart_xml
  • vast_3_0
Einzelheiten finden Sie unter Arten von Anzeigenreaktionen Abschnitt.
ad_config.disable_server_beacons Boolescher Wert Gibt an, ob das serverseitige Auslösen von Anzeigenimpressionen/Beacons deaktiviert werden soll.

Wenn diese Option aktiviert ist true, löst SSAI serverseitig keine Beacons aus und schließt alle Beacons in die VMAP-Ausgabe ein.

Wenn auf gesetzt false, löst SSAI die Beacons aus, die es serverseitig kann, und schließt alle Beacons ein, die es nicht kann. in die VMAP-Ausgabe
ad_config.round_up_cue_points Boolescher Wert Gibt an, ob auf den nächsten Keyframe aufgerundet werden soll, wenn eine Position in der Nähe zum Einfügen von Anzeigen ausgewählt wird.

Standard: false, der den Keyframe auswählt, der der gewünschten Anzeigenposition am nächsten kommt.
ad_config.template_url.template Zeichenfolge Anzeigen-Tag-Vorlage. Verfügbare Variablen, die in einem späteren Abschnitt beschrieben werden.
ad_config.template_url.defaults Objekt Zuordnung von String zu String, der den Standardwert definiert, der verwendet werden soll, wenn kein URL-Parameter angegeben wird.

Kann wörtlich sein { "url.foo": "SomeString" }

Oder verweisen Sie auf eine andere Variable { "url.foo": "{{ metadata.title_id }}" }
ad_tracking_sample_percentage ganze Zahl Dieser Wert bestimmt den Prozentsatz der Sitzungen, die protokolliert werden. Es kann ein beliebiger Wert von 0(Protokollierung deaktivieren) bis 100(alle Sitzungen protokollieren) sein. Der Wert 0 deaktiviert Logs vollständig.

Standard: 0

Werte: [ 0 .. 100 ]
beacon_templates Reihe Eine Reihe von Beacons zum Abfeuern (Beispiel: Beacons von Drittanbietern)
beacon_templates[].type Zeichenfolge

Art des zu feuernden Leuchtfeuers. Werte:

  • 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 Zeichenfolge Beacon-URL-Vorlage
discontinuities.dash [2] []Zeichenfolge Steuert, welche Versionen von Dash Multi Period Dash-Manifeste liefern.

Einstellen ["*"] Mehrperioden-Dash für alle Versionen zu liefern

Leere Liste für nie

Beispiel: ["live-timeline"] für Live-Timeline zu liefern, aber nicht für hbbtv
discontinuities.hls [2] []Zeichenfolge Steuert, welche Versionen von hls mit Diskontinuitäten geliefert werden.

Einstellen ["*"] Lieferung mit Diskontinuitäten in allen Versionen von HLS

Leere Liste für nie

Beispiel: ["v4","v5"] für v4 & v5 zu liefern, aber nicht für v3
extend_beacon_guard_ttl Boolescher Wert Setzt die Länge der Beacon Guard TTL (Time to live) auf die Länge der Sitzungs-TTL des Inhalts. Andernfalls ist der Standardwert 1 Minute.

Arten von Anzeigenantworten

Hier finden Sie einige zusätzliche Informationen zum Arbeiten mit ad_config.expected_ad_response Typen aus der obigen Tabelle. Werte:

Prozessablauf

VOD SSAI-Konfigurationen
VOD SSAI-Konfigurationen

Beachten Sie bei der Erstellung von SSAI-Anzeigenkonfigurationen die folgenden Prozesshinweise:

VMAP

Wenn der Anzeigenantworttyp von SSAI Config DFP VMAP ist:

  • Alle Cue-Points, die mit einem Video konfiguriert wurden, werden ignoriert.
  • SSAI parst die VMAP-XML-Datei des Anzeigenanbieters, die alle Anzeigen mit ihren definierten Positionen enthält.

GROSS

Wenn der Anzeigenantwortstyp von SSAI Config VAST 3.0 ist:

  • Definieren Sie Cue-Points in Ihrem Video. Die SSAI wird für jeden Cue-Point im Video Anfragen stellen, um Werbeunterbrechungen zu konstruieren.
  • Wenn für ein Video kein Cue-Point konfiguriert ist, wird standardmäßig eine Preroll-Anzeige eingefügt.

Anzeigenvariablen

Variablen in der Vorlagen-URL werden durch doppelte geschweifte Klammern ({{ … }}) mit optionalem Leerzeichen vor und nach dem variablen Pfad identifiziert. Allen Variablen ist einer von drei Namensräumen vorangestellt:

Systemvariablen

Systemvariablen werden vom SSAI-System bereitgestellt und können Informationen über den Endbenutzer oder Hilfsvariablen zum Generieren von Zufallswerten sein. Die Werte müssen URI-codiert sein, bevor sie in die URL-Vorlagen eingefügt werden.

Systemvariablen werden wie folgt identifiziert: {{system.*}}

Feld Beschreibung
ad.position_time Die Zeit in Sekunden des Cue-Points, der die Anzeigenanfrage ausgelöst hat; Nur für den Anzeigenantworttyp VAST verfügbar
ip_address IP-Adresse des Endbenutzers
random_number_32 Zufällige 32-Bit-Ganzzahl
random_number_<min>_<max> Erzeugt eine Zufallszahl zwischen zwei Zahlen. Der akzeptierte Bereich reicht von 0 bis zum Maximalwert von UInt32. Es sind nur positive Zahlen erlaubt, und die min muss niedriger sein als max
random_guid Zufällige UUID
referer Wert der Referr-Kopfzeile des Endbenutzers
timestamp_utc Aktuelle Uhrzeit als Unix-Zeitstempel
unique_user_id MD5(ip_address + user_agent)
unix_timestamp Aktuelle Uhrzeit als Unix-Zeitstempel (Sekunden)
user_agent User-Agent-Header-Wert des Endbenutzers
uuid Zufällige uuid
x_forwarded_for X-Forwarded-For-Header-Wert des Endbenutzers
xfp.correlator Zufällige 64-Bit-Ganzzahl
xfp.ip_address IP-Adresse des Endbenutzers
xfp.unique_user_id MD5(ip_address + user_agent)
xfp.scor Zufällige 64-Bit-Ganzzahl

URL-Variablen

Abfrageparameter, die auf dem Einstiegspunkt VMAP/Manifest bereitgestellt werden, sind unter dem url Namensraum. Im Gegensatz zu Variablen unter anderen Namespaces werden diese Parameter beim Einfügen in die Vorlage nicht url-codiert. Wenn Variablenwerte für den Anzeigenanbieter URL-kodiert werden müssen, müssen sie auf der Einstiegspunkt-URL doppelt urlkodiert werden.

URL-Variablen werden identifiziert als: {{url.*}}

URL-Variablen müssen wie folgt durch benutzerdefinierte Integration ersetzt werden:

  1. Schreiben Sie Code, um eine Anfrage an die Playback-API zu stellen.
  2. Abfangen der von der API-Anforderung zurückgegebenen Daten.
  3. Ersetzen Sie alle {{url.*}} Token in Quell-URLs
  4. Laden Sie die Daten/Quelle in den Player (Brightcove Player für Web oder die nativen SDKs)

Metadatenvariablen

Metadatenvariablen sind diejenigen, die das Inhaltsvideo beschreiben und sowohl aus Video Cloud- als auch aus Dynamic Delivery-Datenquellen abgeleitet werden. Die Werte (außer ad_keys) werden URL-codiert, bevor sie in die URL-Vorlagen eingefügt werden.

Metadatenvariablen werden wie folgt identifiziert: {{metadata.*}}

Feld Beschreibung
ad_keys

Freiform-Textstring, der im Video Cloud Studio Media-Modul hinzugefügt und bearbeitet werden kann, indem eines der beiden folgenden Felder verwendet wird, je nach Art Ihrer Anzeigenantwort

  • Non Vast 3.0 - Videofeld „Ad Keys“
  • Vast 3.0 — Das Videofeld „Ad Keys“ ist mit dem Feld „Key/Value Pairs“ auf den Video-Cue-Points verknüpft. Informationen zum Arbeiten mit Cue-Punkten finden Sie unter Arbeiten mit Cue-Punkten im Medienmodul dokumentieren.
custom_fields.{field_name} Benutzerdefinierte Video Cloud-Felder
long_description Lange Beschreibung von Video Cloud
name Video Cloud-Videoname
reference_id Video Cloud-Referenz-ID
tags Kommagetrennte Liste der Video Cloud-Tags für das Video
title.duration Dauer des Inhalts in Sekunden
title.id Titel-ID für dynamische Lieferung
title.name Name des dynamischen Versandtitels
video_id Video Cloud-Video-ID
Andere Video Cloud-Schlüssel / Wert-Paare wären ebenfalls hier

Parameter der Einstiegspunkt-URL

Es gibt eine Handvoll Abfrageparameter, die der SSAI-Einstiegspunkt-URL (VMAP oder Manifest) hinzugefügt werden können, um einige Verhaltensweisen zu optimieren:

Parameter Beschreibung
?rule=sd-only Filtert alle Videowiedergaben heraus, deren Höhe unter dem in der Kontokonfiguration festgelegten Schwellenwert liegt
?rule=discos-enabled Aktivieren Sie die Wiedergabe mit Unterbrechungen in HLS und MultiPeriods in Dash. Hat Vorrang vor der Einstellung von Diskontinuitäten in Playback Config
?rule=discos-disabled Deaktivieren Sie die Wiedergabe mit Unterbrechungen in HLS und MultiPeriods in Dash. Hat Vorrang vor der Einstellung von Diskontinuitäten in Playback Config

Konfigurationshinweise

  1. Das Vorabladen von Anzeigen sollte nicht mit SSAI erfolgen. Der Grund dafür ist, dass der Player beim Vorabladen eine Anzeigenimpression und wahrscheinlich die ersten Quartil-Beacons meldet, bevor das Video abgespielt wird. Dies kann zu ungenauen Anzeigenanalysen führen. Wenn Sie SSAI in Studio konfigurieren, geschieht dies automatisch, aber wenn Sie SSAI manuell einrichten, müssen Sie sich dieses Problems bewusst sein.
  2. Wenn der Webplayer SSAI verwendet und einer Ihrer Beweggründe darin besteht, Werbeblocker zu umgehen, sollten Sie serverseitige Beacons verwenden. Clientseitige Beacons sollten nicht verwendet werden, da sie blockiert werden.

Clientseitige Makros

Verwenden Sie die page Präfix, wenn Sie clientseitige Anzeigenmakros verwenden möchten. Mit diesen Makros können Sie Variablen in den VMAP- und Server-URLs verwenden. Weitere Informationen zu Anzeigenmakros finden Sie im Anzeigenmakros und die ServerURL Abschnitt des Dokuments Werbung mit dem IMA3-Plug-in.

Clientseitigen Makros wird Folgendes vorangestellt: {{page.*}}

Um zum Beispiel die hinzuzufügen document.referrer und ein pageVariable DOM-Fenstervariable, würden Sie ihnen voranstellen page in der Anzeigenvorlage wie folgt:

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

Die Wiedergabe-API kehrt zurück document.referrer und pageVariable.whateverIwant an die VMAP- und SRC-URLs angehängt. Der Brightcove-Player durchläuft dann seine clientseitige Makroersetzungslogik, um die entsprechenden Werte zu ersetzen, bevor die Anforderung gesendet wird:

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

Beacons für Anzeigenfehler

VAST-Anzeigenfehler-Beacons bei der Verwendung von SSAI können hilfreich sein, um Probleme mit Ihrem Anzeigenworkflow proaktiv zu finden und zu beheben. Einzelheiten finden Sie im Beacons für Anzeigenfehler mit SSAI dokumentieren.