Live-API: Cue Points und Ad Beacons mit SSAI

Überblick

Serverseitige Anzeigeneinfügung (SSAI) Ermöglicht die Anzeige von Anzeigen während eines Live-Streaming-Ereignisses zu bestimmten Zeiten. Allgemeine Informationen finden Sie im Live-API: Serverseitige Anzeigeneinfügung (SSAI) Dokument.

Cue-Punkte

Werbeunterbrechungen werden durch Cue-Points ausgelöst, die auf zwei Arten angegeben werden können:

• Vom Encoder an Brightcove gesendet
• Sofortige Cue-Points, die über das erstellt wurden Live API

Vom Encoder

Das Brightcove-Live-Delivery-System kann vom Encoder übermittelte Cue-Punkte im AMF-Format interpretieren:

  AMFDataList
  [0]:onCuePoint
  [1]:{Obj[]:
    time: 1.9889, //Difference from PTS of THIS packet to the first PTS of the 1st video frame in the adbreak
    name: "scte35",
    type: "event",
    ad_server_data: "eyJrZXkiOiJ2YWx1ZSJ9",	// optional introduced by Brightcove. It is a base64 encoded json map of parameters e.g. {"key":"value"}
    parameters: {Obj[]:
      type: "avail_in",
      duration: 12.0
    }
  }

Hinweise:

• Da Timecodes in HH:MM:SS ausgedrückt werden, gibt es keine Vorstellung davon, welcher Tag gemeint ist. Dies kann zu Problemen führen, z. B. wenn ein Cue-Point um 23:55:00 Uhr gesendet wird, damit eine Werbeunterbrechung um 00:01:00 Uhr beginnt und der Server das so interpretiert, als wäre es fast 24 Stunden her. Brightcove hat eine Lösung für dieses Problem wie folgt implementiert: Für Cue-Points, die nur zwischen 23:50:00 und 00:00:00 Uhr ankommen, gehen wir davon aus, dass Sie eine Werbepause für den darauffolgenden Tag planen.
• Bis zu 128 Cue-Points können in einer einzigen Anfrage gestapelt werden, aber aufgrund der oben erläuterten "Rollover"-Regeln können Cue-Points nicht auf diese Weise für den nächsten Tag gesendet werden.
• Da SMPTE-Timecodes mit dem Stream verbunden sind, ist es möglich, dass ein Cue nach der geplanten Zeit im Stream ankommt. Brightcove lässt eine Toleranz von bis zu 5 Sekunden nach dem Cue-Punkt zu, um noch einen Cue-Punkt einzufügen.
• Nur avail_in Und avail_out Typ Cue-Punkte werden derzeit in der RTMP-Eingabe unterstützt.
• SCTE-35-Cue-Punkte werden in RTP- und SRT-Eingängen unterstützt.

Manuelles Einfügen von Cue-Punkten

Sie können sofortige Cue-Points für einen Job oder eine redundante Gruppe erstellen, Live API indem Sie eine POST Anfrage senden:

Fügen Sie einen Anfragetext ein, der Folgendes angibt:

Dauerbeispiel

Die Dauer des eingefügten Cue-Punkts muss mindestens die doppelte Länge der Segmente in der Arbeit.

Beispielsweise funktioniert das Einfügen eines 10-Sekunden-Cue-Points in einen Job mit "segment_seconds"=4, problemlos. Das Einfügen desselben Cue-Points in einen Job jedoch mit "segment_seconds"=6 führt zu folgendem Fehler:

  "error": "The parameter duration should be greater than
    or equal to (2 * target duration) of the job"
 

Beispielanfragetext

  {
    "duration": 30,
    "timecode": "15:50:49:16",
    "ad_server_data" : {
    "adbreakid": 12312
    "breaktheme": "fitness"
    }
  }

Hinweise

1. Software-Encoder wie Wirecast und OBS unterstützen das Senden von Timecode über OnFI Pakete im RTMP-Stream nicht
2. Elementale Hardware-Encoder unterstützen das Senden von Timecode über OnFI Pakete im RTMP-Stream

Beispielantwort

  {
    "id": "Job_ID",
    "cue_point": {
      "id": "adBreak-2f58393ada1442d98eca0817fa565ba4",
      "duration": 30,
      "accuracy": "segment", [Can be segment or frame ]
      "inserted_at": "2017-07-21T09:30:46.307Z" [ Time when the cue point was inserted in the stream]
    },
  }

Leuchtfeuer

Beacons sind Datenpunkte bei der Wiedergabe, die an Drittanbieter-Analysen gesendet werden, um zu verfolgen, ob und wie viele Anzeigen abgespielt wurden. In diesem Abschnitt werden wir uns die Beacon-Typen ansehen, die mit dem eingestellt werden können Live API und Variablen, die zur Bereitstellung der Daten verwendet werden können. Im nächsten Abschnitt werden die API-Anfragen beschrieben, die zum Erstellen und Verwalten von Beacon-Sets verwendet werden.

Beacon-Typen

Beacon-/Anzeigenvariablen

Die folgende Tabelle zeigt die Variablen, die Sie verwenden können, um Daten für die Beacon-URLs bereitzustellen. Um eine Variable einzuschließen, umgeben Sie mit doppelten geschweiften Klammern wie folgt: {{job.job_id}}. Vollständige Beispiele finden Sie im nächsten Abschnitt zum Verwalten von Beacon-Sets.

SCTE-35-Anzeigenvariablen

Die Society of Cable Telecommunications Engineers (SCTE) definiert einen Standard für die dynamische Anzeigeneinfügung für Livestreams. Ein SCTE-35-Anzeigenmarker definiert den Zeitstempel und die Dauer, zu der eine Anzeige in den Stream eingefügt werden kann.

Wenn sie von SCTE-35 geparst werden, können die folgenden Konfigurationsvariablen auf Ihre Anzeigen-Tags angewendet werden:

Als Teil der HLS-Manifeste sind die SCTE-35-Nachrichten ebenfalls base64 mit den Variablen in JSON. Zum Beispiel:

{"scte35_eventID": somevalue, "scte35_programID": somevalue}

Beacon-Sets verwalten

Dieser Abschnitt enthält Details zu den API-Anfragen zum Verwalten von Beacon-Sets. Informationen zu Beacon-Typen und -Variablen finden Sie im vorherigen Abschnitt.

Um einem Live-Job ein Beacon-Set hinzuzufügen, erstellen Sie zuerst das Beacon-Set und fügen Sie dann die ID beim Erstellen des Jobs ein, wie folgt:

{
  "live_stream": true,
  "region": "us-west-2",
  "reconnect_time": 30,
  "ad_insertion": true,
  "beacon_set": "beacon_set_id", ...

Erstellen Sie ein Beacon-Set

Um ein Beacon-Set zu erstellen, senden Sie a POST Anfrage:

Beispielanfragetext

{
    "account_id": "User's Account ID [Optional]",
    "beacon_urls": [
      {
        "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/load?position=load&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
        "beacon_type": "Load"
      },
      {
        "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/play?position=play&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
        "beacon_type": "Play"
      }
    ]
  }

Beispielantwort

{
    "beacon_set": {
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/load?position=load&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
      "beacon_type": "Load"
    },
    {
      "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/play?position=play&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
      "beacon_type": "Play"
    }],
    "beacon_set_id": "Inserted Beacon Set ID",
    "account_id": "USER's ACCOUNT ID"
    }
    "inserted": true
  }

Aktualisieren Sie ein Beacon-Set

Das Aktualisieren eines Beacon-Sets ähnelt dem Erstellen eines Beacon-Sets. Sende ein PUT Anfrage:

Beispielanfragetext

{
    "account_id": "User's Account ID [Optional]",
    "beacon_urls": [
      {
      "beacon_url": "https://myserver.com/beaconRX/load",
      "beacon_type": "Load"
      },
      {
      "beacon_url": "https://myserver.com/beaconRX/play",
      "beacon_type": "Play"
      }
    ]
  }

Beispielantwort

{
    "beacon_set": {
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID",
      "beacon_urls": [{
        "beacon_url": "https://myserver.com/beaconRX/load",
        "beacon_type": "Load"
        },
        {
        "beacon_url": "https://myserver.com/beaconRX/play",
        "beacon_type": "Play"
      }],
      "updated_beacon_set": {
        "beacon_set_id": "Beacon set ID",
        "beacon_urls": [{
          "beacon_url": "https://myserver.com/beaconRX/load",
          "beacon_type": "Load"
        },
        {
          "beacon_url": "https://myserver.com/beaconRX/play",
          "beacon_type": "Play"
        }],
        "account_id": "User's Account ID"
      }
    }
  }

Beacon-Sets erhalten

Um die Beacon-Sets für ein Konto abzurufen, senden Sie a GET Anfrage:

Beispielantwort

[{
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID1",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX/load",
      "beacon_type": "Load"
    }]
    },
    {
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID2",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX2/load",
      "beacon_type": "Load"
      },
      {
      "beacon_url": "https://myserver.com/beaconRX2/play",
      "beacon_type": "Play"
      }]
  }]

Beacon-Sets für anfragende Benutzer abrufen

Sie können die Beacon-Sets auch für das Konto des anfordernden Benutzers abrufen, ohne die Konto-ID in die Anforderungs-URL aufzunehmen:

Beispielantwort

[{
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID1",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX/load",
      "beacon_type": "Load"
    }]
    },
    {
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID2",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX2/load",
      "beacon_type": "Load"
      },
      {
      "beacon_url": "https://myserver.com/beaconRX2/play",
      "beacon_type": "Play"
      }]
  }]

Holen Sie sich ein Beacon-Set von id

Um ein einzelnes Beacon-Set anhand seiner ID abzurufen, senden Sie a GET Anfrage:

Beispielantwort

{
      "account_id": "User account ID",
      "beacon_set_id": "Beacon set ID",
      "beacon_urls": [{
        "beacon_type": "Load",
        "beacon_url": "https://myserver.com/beaconRX2/load"
    },
    {
      "beacon_type": "Play",
      "beacon_url": "https://myserver.com/beaconRX2/play"
    }]
  }

Beacon-Set löschen

Um schließlich ein Beacon-Set zu löschen, senden Sie a DELETE Anfrage:

Beispielantwort

Die Antwort wird wie folgt aussehen:

{
    "beacon_set_id": "Beacon set ID",
    "deleted": true
  }

Anhang

Unten ist ein Screenshot, der ein Beispiel für ein Cue-Point-Setup für den Elemental-Encoder zeigt.