Diese Seite ist umgezogen - Sie werden weitergeleitet zum neuen Ort in 3 Sekunden. Bitte aktualisiere deine Lesezeichen!

Video Cloud SSAI-Anzeigenkonfigurations-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 Information

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 Übersicht über Brightcove OAuth.

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": "http://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 }}"
      }
    }
  }
]

Erstellen Sie eine Anzeigenkonfiguration

Erstellen Sie eine Anzeigenkonfiguration für ein Konto.

Methode POST
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_config": {
  	"expected_ad_response": "vast_3_0",
  	"disable_server_beacons": false,
    "round_up_cue_points": false,
  	"template_url": {
  		"template": "http://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": [ "*" ]
  }
}

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_config": {
    "expected_ad_response": "dfp_ad_rules",
    "disable_server_beacons": false,
    "template_url": {
        "template": "http://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
  }
}

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": "http://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 }}"
    }
  }
}

Details zum Konfigurationsfeld

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

Feld Typ Beschreibung
name String Für Menschen lesbarer Name
vmap_response_namespace String 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 String Für Menschen lesbare Beschreibung
ad_config.expected_ad_response String Welche Technologie soll zum Analysieren der Antwort verwendet werden? [1]

Werte:
  • dfp_ad_rules
  • dfp_vmap
  • smart_xml
  • vast_3_0
ad_config.disable_server_beacons Boolescher Wert Markiert, ob das serverseitige Auslösen von Anzeigenimpressionen / Beacons deaktiviert werden soll

Bei Einstellung auf true SSAI löst keine Beacons serverseitig aus und schließt alle Beacons in die VMAP-Ausgabe ein

Bei Einstellung auf false , SSAI löst die Beacons aus, die es serverseitig ausführen kann, und nimmt alle Beacons, die es nicht kann, in die VMAP-Ausgabe auf
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 Hiermit wird der Keyframe ausgewählt, der der gewünschten Anzeigenposition am nächsten kommt.
ad_config.template_url.template String 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 }}" }
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
beacon_templates Array Eine Reihe von Beacons, die ausgelöst werden sollen (Beispiel: Beacons von Drittanbietern)
beacon_templates[].type String

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 String Beacon-URL-Vorlage
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.

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
ip_address IP-Adresse des Endbenutzers
random_number_32 Zufällige 32-Bit-Ganzzahl
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.*}}

Metadatenvariablen

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

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

Feld Beschreibung
ad_keys Freiform-Textzeichenfolge, die im Video Cloud Studio-Medienmodul hinzugefügt und bearbeitet werden kann
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.