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: "YWJjZGVmZ2g=",	// 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:

Nur avail_in Cue-Punkte vom Typ 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

Mit dem können Sie sofortige Cue-Points erstellen Live API durch Senden eines POST Anfrage:

Methode	`POST`
URL	`https://api.bcovlive.io/v1/jobs/Job_ID/cuepoint`
Header	`X-API-KEY: your API KEY`

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

Feld	Typ	Beschreibung
`duration`	Ganze Zahl	Dauer der Pause in Sekunden. Die Dauer des eingefügten Cue-Points muss sein mindestens doppelt so lang wie die Segmente in der Arbeit. Siehe die Dauer Beispiel.
`timecode`	SMPTE-Format	OPTIONAL: Ein Timecode im SMPTE-Format, HH:MM:SS:FF (FF = Frames), um anzugeben, wann ein Satz von Variablen (Schlüssel/Wert-Paare) an den AdServer übergeben werden soll. Wenn nicht angegeben, wird der Cue-Point sofort eingefügt. Wenn Sie die Timecode-Eigenschaft verwenden, muss der Encoder SMPTE-formatiert senden (`HH:MM:SS:FF` ) Timecode gespeichert in der `tc` Eigentum über `OnFI`. Timecodes sind vom Beginn des Livestreams an.
`ad_server_data`	Objekt	OPTIONAL: Welche Schlüssel/Wert-Paare Sie übergeben, hängt vom verwendeten Ad-Server ab. Weitere Informationen finden Sie in Ihrer Ad-Server-Dokumentation und in der Targeting von Anzeigen mithilfe von Anzeigenmakros Sektion.

Dauerbeispiel

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

Beispiel: Einfügen von a 10 Sekunden Cue-Punkt in einem Job mit "segment_seconds"=4 , wird gut funktionieren. 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

Software-Encoder wie Wirecast und OBS unterstützen das Senden von Timecode über . nicht OnFI Pakete im RTMP-Stream
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]
    },
  }

Beacons

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-Typen
Beacon-Typ	Beschreibung
`Load`	Wird einmal pro Sitzung ausgelöst und wird nur ausgelöst, wenn das Manifest der obersten Ebene angefordert wird
`Play`	Inhalt wurde angefordert und das erste Segment zurückgegeben
`Heartbeat`	Zieldauer (Segmentsekunden)
`AdStart`	Einzelanzeige gestartet
`AdFirstQuartile`	Erstes Anzeigenquartil (25 %)
`AdMidpoint`	Zweites Anzeigenquartil (50 %)
`AdThirdQuartile`	Drittes Anzeigenquartil (75 %)
`AdComplete`	Einzelanzeige abgeschlossen
`AdBreakStart`	Werbepause hat begonnen
`AdBreakComplete`	Werbeunterbrechung ist beendet

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.

Variablen für die Anzeigenkonfiguration
Variable	Beschreibung
`session.session_id`	eindeutige Sitzungs-ID
`job.job_id`	einzigartige Job-ID
`videocloud.video_id`	Nur verfügbar für Jobs, die mit einem VideoCloud-Video erstellt wurden.
`application_ad_configuration.description`	Wert der Anwendung bei der Session-Erstellung
`random.int32`	zufällige 32-Bit-Ganzzahl mit Vorzeichen
`random.int64`	zufällige 64-Bit-Ganzzahl mit Vorzeichen
`random.uint32`	zufällige 32-Bit-Ganzzahl ohne Vorzeichen
`random.uint64`	zufällige 64-Bit-Ganzzahl ohne Vorzeichen
`random.uuid`	zufällige uuid
`server.timestamputc`	Epochenzeit in Millisekunden, wenn der Aufruf von der ads-API getätigt wurde
`client.useragent`	HTTP-User-Agent-Header-Wert bei Sitzungserstellung
`client.ipaddress`	http x-forwarded-for Header-Wert bei Sitzungserstellung, falls angegeben, andernfalls die Remote-Adresse
`client.referrer`	HTTP-Referer-Header-Wert bei der Sitzungserstellung (Hinweis: das ist die richtige Schreibweise)
`client.referer`	HTTP-Referer-Header-Wert bei Sitzungserstellung (http-Rechtschreibung)
`client.ipuaid`	Hashwert von client.ipaddress und client.useragent
`live.adbreak`	(derzeit unbenutzt)
`live.adbreakdurationms`	Dauer der Werbeunterbrechung in Millisekunden
`live.adbreakduration`	Dauer der Werbeunterbrechung in Gleitkomma-Sekunden mit doppelter Genauigkeit
`live.adbreakdurationint`	Dauer der Werbeunterbrechung in ganzzahligen Sekunden
`live.adbreak.timestamputc.wallclock`	Epochenzeit in Millisekunden, wenn der Anruf beim Ads-Server getätigt wurde
`live.adbreak.timestamputc.origin`	Epochenzeit in Millisekunden von der Ursprungs-Chunklist. Dieser Wert gibt die Zeit an, zu der der Cue Out Chunk in der Ursprungs-Chunklist erstellt wurde.
`live.adbreak.timestamputc.session`	Epochenzeit in Millisekunden von der ssai-Chunklist. Dieser Wert gibt die Zeit des Cue-Out-Chunks in der ssai-Chunkliste an. Da der Adbreak-Inhalt und die Adbreak-Lücke normalerweise NICHT gleich sind, unterscheidet `live.adbreak.timestamputc.origin` sich das nach dem 1. Adbreak von `live.adbreak.timestamputc.session` . Dieser Wert berücksichtigt die Zeitanpassungen, die in der vorgenommen wurden SSAI Chunklist.

SCTE-35-Anzeigenvariablen

Die Society of Cable Telecommunications Engineers (SCTE) definiert einen Standard für die dynamische Anzeigeneinfügung für Livestreams. Die folgende Tabelle fasst die SCTE-35-Anzeigenkonfigurationsvariablen zusammen.

SCTE-35-Anzeigenkonfigurationsvariablen
Variable	Beschreibung
`scte35_eventID`	eine eindeutige Ereignis-ID, die mit einer SCTE35-Nachricht übergeben wurde.
`scte35_programID`	Eine eindeutige Programm-ID, die mit einer SCTE35-Nachricht übergeben wird.
`scte35_availNum`	Eine für Anzeigen verfügbare ID für eine bestimmte Spleißzeit, die über eine SCTE35-Nachricht gesendet wird.
`scte35_breakDuration`	Pausendauer für die Werbeunterbrechung, ausgedrückt in Ticks des 90-kHz-Takts des Programms, die mit einer SCTE35-Nachricht übergeben wird.
`scte35_spliceTime`	Die Spleißzeit für eine Werbeunterbrechung, ausgedrückt in Ticks des 90-kHz-Takts des Programms, wird mit einer SCTE35-Nachricht übergeben.

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:

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

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

Die account_id Feld ist die Live-Konto-ID. Wenn es weggelassen wird, wird die Konto-ID des anfragenden Benutzers verwendet.

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:

Methode	`PUT`
URL	`https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/beacon_set_id`
Header	`X-API-KEY: your API KEY`

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

Die account_id Feld ist die Live-Konto-ID. Wenn es weggelassen wird, wird die Konto-ID des anfragenden Benutzers verwendet.

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:

Methode	`GET`
URL	`https://api.bcovlive.io/v1/ssai/beaconsets/account/Account ID`
Header	`X-API-KEY: your API KEY`

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:

Methode	`GET`
URL	`https://api.bcovlive.io/v1/ssai/beaconsets`
Header	`X-API-KEY: your API KEY`

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:

Methode	`GET`
URL	`https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/beacon_set_id`
Header	`X-API-KEY: your API KEY`

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:

Methode	`DELETE`
URL	`https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/beacon_set_id`
Header	`X-API-KEY: your API KEY`

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.

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

Live-API: Cue-Points und Ad Beacons mit SSAI

Überblick

Cue-Punkte

Vom Encoder

Hinweise:

Manuelles Einfügen von Cue-Punkten

Dauerbeispiel

Beispielanfragetext

Hinweise

Beispielantwort

Beacons

Beacon-Typen

Beacon-/Anzeigenvariablen

SCTE-35-Anzeigenvariablen

Beacon-Sets verwalten

Erstellen Sie ein Beacon-Set

Beispielanfragetext

Beispielantwort

Aktualisieren Sie ein Beacon-Set

Beispielanfragetext

Beispielantwort

Beacon-Sets erhalten

Beispielantwort

Beacon-Sets für anfragende Benutzer abrufen

Beispielantwort

Holen Sie sich ein Beacon-Set von id

Beispielantwort

Beacon-Set löschen

Beispielantwort

Anhang