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

Brightcove Live-API: Serverseitige Anzeigeneinfügung (SSAI)

In diesem Thema erfahren Sie, wie Sie die serverseitige Anzeigeneinfügung (SSAI) für Ihre Livestream-Jobs einrichten.

Überblick

SSAI Ermöglicht die Anzeige von Anzeigen während eines Live-Streaming-Ereignisses zu bestimmten Zeiten. Zu den Hauptmerkmalen gehören:

  • Fügen Sie Anzeigen mit Cue-Points ein, die Sie von Ihrem Encoder gesendet haben, oder erstellen Sie einen sofortigen Cue-Point mit dem Live API
  • Nehmen Sie "Slate"-Assets auf, um ungenutzte Anzeigenzeit zu füllen
  • Vermeiden Sie Werbeblocker mit Anzeigen, die serverseitig in den Livestream eingebunden werden

Gehen Sie wie folgt vor, um einen Livestream mit serverseitigen Anzeigen zu erstellen:

  1. Lesen Sie die allgemeinen Informationen zur Live-API
  2. Erstellen Sie eine Live-Anzeigenkonfiguration. Sie können dies auch in Video Cloud Studio. Weitere Informationen zur Verwaltung Ihrer Anzeigenkonfigurationen mit der Live-API finden Sie in den folgenden Abschnitten.
  3. Slate-Assets erstellen. Wenn Sie eine Benutzeroberfläche bevorzugen, können Sie Schiefertafeln in Studio verwalten.
  4. Optional: Cue-Points und Werbe-Beacons einfügen.
  5. Jetzt bist du bereit zu Erstellen Sie einen Live-Stream mit der Live-API. Wenn Sie Studio bevorzugen, können Sie serverseitige Anzeigen im Live-Modul implementieren

Weitere Informationen zu benutzerdefinierten Headern, Anzeigenkonfigurationsvariablen und der Verwendung von DFP und Anzeigenmakros finden Sie im Rest dieses Dokuments.

Allgemeine Information

Die folgenden Informationen beziehen sich auf alle Live-APIs mit SSAI-Anfragen.

Basis-URL

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

    https://api.bcovlive.io/v1/ssai

Authentifizierung

Die Authentifizierung für Anfragen erfordert einen Header mit einem API-Schlüssel:

    X-API-KEY: your API KEY

Wenden Sie sich an Ihren Account Manager, um einen mit Ihrem Account verknüpften API-Schlüssel zu erhalten.

Erstellen Sie eine Anzeigenkonfiguration

Um eine neue Anzeigenkonfiguration zu erstellen, senden Sie eine POST wie folgt anfordern:

Methode POST
URL https://api.bcovlive.io/v1/ssai/applications
Header X-API-KEY: your API KEY

Beispielanfragetext

    {
      "application_ad_configuration": {
        "ad_configuration_description": "Human readable description of the configuration",
        "ad_configuration_expected_response_type": "Dfp, Vast or SmartXML",
        "ad_configuration_headers": {
        "X-Custom-Header-Rand": "{{random.int32}}",
        "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
        },
        "ad_configuration_headers_for_impressions": false,
        "ad_configuration_strategy": "SingleAdResponse or MultipleAdResponse",
        "ad_configuration_transforms": [
          {
          "xpath": "/",
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
          }
        ],
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
      },
      "application_description": "Human readable description of the ad application",
      "account_id": "User's Account ID [Optional]"
    }

Beispielantwort

    {
      "application": {
        "account_id": "User Account ID",
        "application_description": "Human readable description of the ad application",
        "application_ad_configuration": {
          "ad_configuration_description": "Human readable description of the configuration",
          "ad_configuration_expected_response_type": "Dfp | Vast | SmartXML",
          "ad_configuration_headers": {
            "X-Custom-Header-Rand": "{{random.int32}}",
            "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
          },
          "ad_configuration_headers_for_impressions": false,
          "ad_configuration_strategy": "SingleAdResponse | MultipleAdResponse",
          "ad_configuration_transforms": [
            {
              "xpath": "/",
              "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
            }
          ],
          "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
        },
        "application_id": "Application ID"
      },
      "inserted": true
    }

Aktualisieren einer Anzeigenkonfiguration

Das Aktualisieren einer Anzeigenkonfiguration ist dem Erstellen einer Anzeigenkonfiguration sehr ähnlich. Mach ein PUT wie folgt anfordern:

Methode PUT
URL https://api.bcovlive.io/v1/ssai/applications/application/Application_ID
Header X-API-KEY: your API KEY

Beispielanfragetext

    {
      "application_ad_configuration": {
        "ad_configuration_description": "Some Updated Description Value",
        "ad_configuration_expected_response_type": "Dfp or Vast or SmartXML,
        "ad_configuration_headers": {
          "X-Custom-Header-Rand": "{{random.int32}}",
          "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
        },
        "ad_configuration_headers_for_impressions": false,
        "ad_configuration_strategy": "SingleAdResponse or MultipleAdResponse",
        "ad_configuration_transforms": [
          {
          "xpath": "/",
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
          }
        ],
        "ad_configuration_url_format": "https://updated-ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
      },
      "application_description": "Human readable description of the ad application",
      "account_id": "User's Account ID [Optional]"
    }

Beispielantwort

    {
      "account_id": "User Account ID",
      "application_description": "Human readable description of the ad application",
      "application_ad_configuration": {
        "ad_configuration_description": "Some Updated Description Value",
        "ad_configuration_expected_response_type": "Dfp | Vast | SmartXML",
        "ad_configuration_headers": {
        "X-Custom-Header-Rand": "{{random.int32}}",
        "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
        },
        "ad_configuration_headers_for_impressions": false,
        "ad_configuration_strategy": "SingleAdResponse | MultipleAdResponse",
        "ad_configuration_transforms": [
          {
          "xpath": "/",
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
          }
        ],
        "ad_configuration_url_format": "https://updated-ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
      },
      "application_id": "Application ID"
    }

Alle Anzeigenkonfigurationen abrufen

Um alle Anzeigenkonfigurationen für ein Konto abzurufen, senden Sie a GET wie folgt anfordern:

Methode GET
URL https://api.bcovlive.io/v1/ssai/applications/account/Account_ID
Header X-API-KEY: your API KEY

Beispielantwort

    [
      {
        "application_id": "Application_ID_1",
        "application_description": "DFP Single Midroll",
        "application_ad_configuration": {
        "ad_configuration_description": "DFP Test Config Single Midroll",
        "ad_configuration_strategy": "MultipleAdResponse",
        "ad_configuration_transforms": [],
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler",
        "ad_configuration_expected_response_type": "Dfp"
        },
        "account_id": "Account_ID"
      },
      {
        "application_id": "Application_ID_2",
        "application_description": "Test DFP Single Midroll"
        "application_ad_configuration": {
        "ad_configuration_description": "DFP Test Config Single Midroll",
        "ad_configuration_strategy": "MultipleAdResponse",
        "ad_configuration_transforms": [
        {
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>",
          "xpath": "/"
        }
        ],
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}",
        "ad_configuration_expected_response_type": "Dfp"
        },
        "account_id": "Account_ID"
      }
    ]

Anzeigenkonfiguration abrufen

Sie können eine bestimmte Anzeigenkonfiguration auch über ihre application_id durch Senden einer GET wie folgt anfordern:

Methode GET
URL https://api.bcovlive.io/v1/ssai/applications/application/Application_ID
Header X-API-KEY: your API KEY

Beispielantwort

    {
      "application_id": "Application_ID",
      "application_description": "Test DFP Single Midroll",
      "application_ad_configuration": {
        "ad_configuration_description": "DFP Test Config Single Midroll",
        "ad_configuration_strategy": "MultipleAdResponse",
        "ad_configuration_transforms": [
          {
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>",
          "xpath": "/"
          }
        ],
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}",
        "ad_configuration_expected_response_type": "Dfp"
      },
      "account_id": "Account_ID"
    }

Anzeigenkonfiguration löschen

Um eine Anzeigenkonfiguration zu löschen, senden Sie a DELETE wie folgt anfordern:

Methode DELETE
URL https://api.bcovlive.io/v1/ssai/applications/application/APPLICATION_ID
Header X-API-KEY: your API KEY

Beispielantwort

    {
    "application_id": "Application_ID",
    "deleted": true
    }

Schiefer verwalten

Slates sind Ihre eigenen Assets, mit denen ungenutzte Werbezeit gefüllt wird. Sie können Schiefertafeln verwenden, um eine Nachricht mit der Aufschrift "Bin gleich zurück" oder andere Inhalte bereitzustellen, die Ihnen gefallen.

Nachfolgend finden Sie Details zu den API-Anfragen zum Hinzufügen und Verwalten von Slate-Assets.

Slate-Asset hinzufügen

Um ein neues Slate-Medienquellen-Asset aufzunehmen, senden Sie a POST Anfrage:

Methode POST
URL https://api.bcovlive.io/v1/ssai/slates
Header X-API-KEY: your API KEY

Beispielanfragetext

    {
      "source_url": "https://somesourceasset.com/slate-to-ingest.mp4",
      "account_id": "Account_ID [Optional]",
      "source_description": "User identifiable description for the slate  [Optional]"
    }

Beispielantwort

    {
      "media_source_asset_id": "New_UUID",
      "account_id": "Account_ID",
      "media_source_asset_default": false,
      "media_source_asset_type": "slate",
      "media_source_asset_url": "https://somesourceasset.com/slate-to-ingest.mp4",
      "media_source_asset_status": "transcoding"
      "media_source_asset_description": "User identifiable description for the slate"
    }

Slate-Asset löschen

Um ein Slate-Medienquellen-Asset zu löschen, senden Sie eine DELETE Anfrage:

Methode DELETE
URL https://api.bcovlive.io/v1/ssai/slates/slate/Slate_MSA_ID
Header X-API-KEY: your API KEY

Beispielantwort

    {
      "media_source_asset_id": "MSA_UUID",
      "media_source_asset_type": "slate",
      "media_source_asset_url": "http://someS3urlpath/media.mp4",
      "media_source_asset_default": false,
      "media_source_asset_status": "ready",
      "account_id": "ACCOUNT_ID"
    }

Holen Sie sich Slate-Assets

Sie können ein Array aller Slate-Medienquellen-Assets für ein Konto abrufen, indem Sie eine GET Anfrage:

Methode GET
URL https://api.bcovlive.io/v1/ssai/slates/account/Account_ID
Header X-API-KEY: your API KEY

Beispielantwort

    [
      {
      "media_source_asset_id": "MSA_UUID_1",
      "media_source_asset_type": "slate",
      "media_source_asset_default": false,
      "media_source_asset_url": "http://someS3urlpath.com/media.mp4",
      "account_id": "ACCOUNT_ID",
      "media_source_asset_status": "ready"
      },
      {
      "media_source_asset_id": "MSA_UUID_2",
      "media_source_asset_type": "slate",
      "media_source_asset_default": true,
      "media_source_asset_url": "http://someS3urlpath.com/media.mp4",
      "account_id": "ACCOUNT_ID",
      "media_source_asset_status": "ready"
      }
    ]

Hinweise zu DFP

Wenn Sie Anzeigen von DFP beziehen, sollten Sie Folgendes beachten, um Probleme zu vermeiden.

Anzeigen-Tag

Achten Sie beim Erstellen eines Anzeigen-Tags für Live darauf, dass Sie die richtigen Richtlinien befolgen und Folgendes einschließen: /live . Siehe das DFP-Dokument Erstellen Sie manuell ein Master-Video-Tag für alle Einzelheiten.

Gleichzeitigkeit

Wenn Sie ein hohes Maß an Parallelität erwarten, empfehlen wir Ihnen, mit Ihrem DFP-Kontoteam zu sprechen.

Einzelne/mehrere Anzeigenantworten

Das singleadresponse und multiadresponse Parameter werden derzeit nicht von verwendet SSAI.

Wohnen SSAI führt nur einen einzelnen Ad-Server-Aufruf durch und erwartet, dass die Antwort alle Anzeigen für die Unterbrechung enthält, mit der Ausnahme, dass alle erforderlichen Anzeigen-Wrapper mit einem Limit von 5 Weiterleitungen pro Anzeige folgen. Die folgenden Anzeigenantwortformate werden akzeptiert und wie folgt geparst:

  • VAST – Einzelantwort oder ein Anzeigen-Pod in einer einzigen Antwort
  • DFP-Anzeigenregeln – Fasst alle verfügbaren Anzeigen in der Antwort zusammen, einschließlich definierter Pre-, Mid- und Post-Roll-Anzeigen
  • Smart XML – Fasst alle verfügbaren Anzeigen in der Antwort zusammen, einschließlich Pre-, Mid- und Post-Roll-definierter Anzeigen

Benutzerdefinierte Header für Anzeigenanfragen

Das SSAI Die Plattform kann benutzerdefinierte Header mit den Anzeigenaufrufen und allen von der Backend-Plattform verwendeten Beacons übergeben. Einige Adserver wie VideoPlaza erfordern benutzerdefinierte Header.

Benutzerdefinierte Header werden als eine Reihe von Schlüssel-Wert-Paaren in einem . angegeben ad_configuration_headers Objekt, das Teil des application_ad_configuration (siehe die Erstellen Sie eine Anzeigenkonfiguration Sektion).

Hinweise

  • Standard-Header werden standardmäßig behandelt, wie zum Beispiel:
    • X-Forwarded-For
    • X-Device-User-Agent
  • Header-Werte können die Anzeigenkonfigurationsvariablen
  • Headerwerte können auch statische Strings sein

Targeting von Anzeigen mithilfe von Anzeigenmakros

Wenn du Erstellen Sie eine Anzeigenkonfiguration , sieht Ihr Anzeigen-Tag normalerweise so aus:

      https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&
      num={{random.int32}}&ses={{session.session_id}}&IDFA={{deviceid}}&
      sitesection={{sitesection}}&breakid={{breakid}}&breaktheme={{breaktheme}}

Die Elemente innerhalb der doppelten geschweiften Klammern sind Variablen, auch Anzeigenmakros genannt, die Brightcove Live beim Senden der Anzeigenanfrage durch Werte ersetzt, falls vorhanden.

Anzeigenmakrowerte können auf folgende Weise bereitgestellt werden:

Header-Informationen verwenden

Header-Informationen, detailliert im Anzeigenkonfigurationsvariablen Abschnitt oben, steht für jede Anfrage zur Verfügung. Geben Sie einfach die gewünschten Variablen mit den entsprechenden Schlüsselnamen in Ihrer Anzeigenkonfiguration an.

Anhängen der URL

Zusätzliche Sitzungswerte können an die URL für den Livestream angehängt werden, etwa wie folgt:

      http://playback.bcovlive.io/e058d9f2737e18/us-west-2/NA/
      playlist.m3u8?deviceid=123456&sitesection=services"

URLs dynamisch hinzufügen

Sie können URLs dynamisch hinzufügen, indem Sie Javascript und die Brightcove Player API verwenden:

      <!DOCTYPE html>
      <body>
        <video
        id="myPlayerID"
        data-video-id="5975635167001"
        data-account="3737230870001"
        data-player="tIG7lVKBm"
        data-embed="default"
        data-application-id
        class="video-js"
        controls
        width="640"
        height="360"></video>
        <script src="//players.brightcove.net/3737230870001/tIG7lVKBm_default/index.min.js"></script>

        <script type="text/javascript">
        var player = videojs("myPlayerID");

        player.one("loadstart", function(){
          var sourceUrl = player.currentSource();
          console.log(sourceUrl);
          var liveUrlWithParams = sourceUrl.src + "?player_width={width}&player_height={height}&deviceid={deviceid}";

          player.src([{
            "type": "application/vnd.apple.mpegurl",
            "src": liveUrlWithParams
          }]);
        });
      </script>

      </body>

Beachten Sie, dass die Schlüsselnamen in diesem Beispiel den Variablennamen im oben gezeigten Anzeigen-Tag entsprechen.

Anzeigenkonfigurationsvariablen

Anzeigenkonfigurationsvariablen, auch als Beacons bezeichnet, können in Anfragen zur Verwaltung von Anzeigenkonfigurationen verwendet werden. Einzelheiten finden Sie im Live-API: Cue Points und Ad Beacons mit SSAI dokumentieren.

Verwenden von manuellen Cue-Punkten

Werte für bestimmte Werbeunterbrechungen können mit der manuellen Anforderung zum Einfügen von Cue-Punkten gesendet werden. Einzelheiten finden Sie im Live-API: Cue-Points und Ad-Beacons dokumentieren.

Bekannte Probleme

  • SSAI erfordert, dass das Live-Streaming-Video eine Audiospur hat.
  • Wenn die zurückgegebene VAST dieselbe Anzeigen-ID hat, fordert der Server den Anzeigeninhalt nicht an, obwohl die Anzeigen-URL dynamische Variablen verwendet, um sie zu einer eindeutigen URL zu machen. Das macht nicht gelten, wenn Sie DFP für Anzeigen verwenden.
  • Mit DFP können Sie zwar dieselbe Anzeigen-ID verwenden, es muss jedoch eine andere Motiv-ID vorhanden sein. Mit anderen Worten, Sie können die MediaFile nicht einfach austauschen.

  • Wenn eine Werbeunterbrechung kürzer als die MAX-Dauer der Anzeigen-URL ist (min_ad_duration=0&max_ad_duration=30000), wird die Anzeige nicht wiedergegeben, wenn die Anzeige länger als die Werbeunterbrechung ist.

  • VPAID- oder anklickbare Anzeigen werden für nicht unterstützt Brightcove Live SSAI.

  • Wenn eine Werbeunterbrechung eine kürzere Restzeit als die Segmentsekunden des Streams hat und eine Slate angezeigt wird, wird die Slate für die Segmentdauer angezeigt und die tatsächliche Werbeunterbrechung ist länger als erwartet.

  • Das Obige kann dazu führen, dass eine der folgenden Werbeunterbrechungen um die Latenzzeit verkürzt wird, um zu versuchen, die Sitzung wieder an den Live-Edge zu bringen.

  • Wenn die Anzeige zum ersten Mal von unserem System gesehen wird, wird sie erst abgespielt, wenn sie transcodiert und zur Auslieferung bereit ist.
  • VMAP for Live SSAI wird derzeit nicht unterstützt.