Werbeunterbrechungen

Überblick

Das Web Receiver SDK bietet native Unterstützung für Werbeunterbrechungen und Companion-Anzeigen in einem bestimmten Mediastream. Sie bietet APIs zum Festlegen von Anzeigenposition, Anzeigenquelle und Verhalten von Werbeunterbrechungen und den zugehörigen Pausenclips. In diesem Leitfaden bezieht sich Break auf ein Wiedergabeintervall, das eine oder mehrere Anzeigen oder Bumper enthält. Jede Anzeige oder jeder Bumper wird als BreakClip bezeichnet. Diese Pausen sind mit den Medien verknüpft, die geladen oder wiedergegeben werden.

Anzeigentypen

Das Web Receiver SDK unterstützt die clientseitige Anzeigenbereitstellung (Client-Side Ad Inserting, CSAI) und die serverseitige Anzeigenbereitstellung (Server Stitched Ad Inserting, SSAI). Vom Kunden zusammengefügte Anzeigen können manuell von der Anwendung festgelegt oder aus VAST- und VMAP-Vorlagendateien extrahiert werden. Server-stitched-Anzeigen sollten vor dem Laden des Contents manuell als eingebettete Anzeigen oder dynamisch während der Content-Wiedergabe als eingebettete erweiterte Anzeigen angegeben werden. Die Implementierungen für jeden dieser Anzeigentypen werden unten ausführlich beschrieben.

manuell zusammengefügt

Bei einer manuell erstellten, vom Client erstellten Werbeunterbrechung handelt es sich um eine Art von Werbeunterbrechung, die vom Client zusammengefügt und manuell von der Anwendung mithilfe der SDK APIs angegeben wird. Dieser Anzeigentyp ist nicht in den Stream des Hauptcontents eingebettet. Der BreakClip muss die contentId, also eine URL, die auf den Anzeigeninhalt verweist, die contentType, die das Format des Anzeigeninhalts beschreibt, und die title enthalten.

Für Break muss isEmbedded und expanded auf den Standardwert false festgelegt sein. Für position kann eine Pre-Roll-, Mid-Roll- oder Post-Roll-Werbeunterbrechung festgelegt werden. Weitere Informationen dazu findest du im Abschnitt Positionierung der Werbeunterbrechung. Bei der Vorbereitung der Anzeige für die Wiedergabe generiert das Web Receiver SDK eine weitere Player-Instanz, um den Anzeigeninhalt zu laden und abzuspielen. Für diese Unterbrechungen ist ein stitched timeline erforderlich und sie müssen statisch hinzugefügt werden. Weitere Informationen finden Sie im Abschnitt Anzeigenbereitstellung. Im folgenden Beispiel sehen Sie eine grundlegende Implementierung einer manuell erstellten Anzeige:

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

VAST

Das Web Receiver SDK unterstützt das Hinzufügen von VAST (Video Ad Serving Template). Wenn diese angegeben ist, wird die XML-Vorlage geparst, um beim Eintreten der Unterbrechung einen nachfolgenden client-stitched-Pausenclip zu generieren.

Zum Erstellen einer VAST-Anzeige muss die Empfänger-App einen VastAdsRequest erstellen und im Attribut BreakClip vastAdsRequest angeben. Für das Objekt VastAdsRequest muss entweder die Eigenschaft adsResponse (eine Stringdarstellung der XML-Vorlage selbst) oder die Eigenschaft adTagUrl (die URL, unter der die XML-Vorlage gehostet wird) definiert sein. Wenn die URL angegeben ist, übernimmt das SDK das Abrufen der Vorlage. Das einschließende Break entspricht den Konventionen für vom Kunden zusammengefügte Anzeigen. Diese Anzeigen können zusammen mit anderen manuell erstellten Anzeigen in derselben Pause oder in separaten Pausen für denselben Inhalt hinzugefügt werden. Im folgenden Beispiel sehen Sie eine grundlegende Implementierung einer VAST-Anzeige:

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

Wenn ein Break-Objekt eingegeben wird, das ein VAST-BreakClip enthält, ruft das Web Receiver SDK optional die Vorlage ab und parst sie dann. Beim Parsen generiert das SDK ein neues BreakClip und füllt dieses mit den aus der Vorlage extrahierten Werten wie contentId, contentType, title, duration, whenSkippable und clickThroughUrl aus. id für den generierten Pausenclip ist auf GENERATED:N gesetzt, wobei N eine Ganzzahl ist, die für jeden neuen VAST-Pausenclip ab 0 um 1 erhöht wird. Die generierte Anzeige wird dann dem Array BreakClip hinzugefügt. Die id jedes VAST im aktuellen Break werden dann durch die id des entsprechenden generierten Pausenclips ersetzt. Die Snippets unten veranschaulichen die Änderungen in den MEDIA_STATUS-Mitteilungen im Zusammenhang mit Anzeigen vor und nach einer solchen Unterbrechung.

Break- und BreakClip-Informationen, bevor eine Pause mit VAST-Anzeigen eintritt.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

Informationen zu Break und BreakClip nach einer Unterbrechung mit VAST-Anzeigen

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

VMAP

Das Web Receiver SDK unterstützt den IAB-Standard VMAP (Video Multiple Ad Playlists). Wenn ein VMAP bereitgestellt wird, parst das Web Receiver SDK die VMAP-Antwort und generiert client-stitched Break-Objekte für alle <AdBreak>-Einträge in der Antwort. Außerdem wird das entsprechende BreakClips mit einem vastAdsRequest-Objekt für jeden <AdSource>-Eintrag im VMAP generiert. Damit über VMAP Anzeigen in Ihre Inhalte eingefügt werden können, muss die Anwendung ein VastAdsRequest-Objekt erstellen und es der Property vmapAdsRequest von MediaInformation in der LoadRequestData zuweisen. Diese Anzeigen müssen statisch eingefügt werden. Weitere Informationen finden Sie im Abschnitt Anzeigenbereitstellung. Das folgende Snippet zeigt das Erstellen einer VMAP-Anfrage.

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

eingebettet

Eine eingebettete Werbeunterbrechung ist eine Art von Werbeunterbrechung, die serverseitig in den Stream des Hauptcontents eingefügt wird. Bei der Berechnung der Medienzeit wird die Dauer von Break von der Dauer des Hauptinhalts subtrahiert.

BreakClip muss den duration des Anzeigeninhalts und den title bereitstellen. Für Break muss isEmbedded auf true und expanded auf false festgelegt sein. Für position kann eine Pre-Roll- oder Mid-Roll-Werbeunterbrechung festgelegt werden. Post-Roll-Werbeunterbrechungen werden mit genau positiven position-Werten unterstützt. Weitere Informationen finden Sie im Abschnitt zur Positionierung von Unterbrechungen. Wenn die Wiedergabe der Anzeige ausgelöst wird, setzt das Web Receiver SDK die Wiedergabe des Streams fort, während die Anzeigensegmente darin eingebettet sind. Für diesen Anzeigentyp gibt es keinen zusätzlichen Lademechanismus. Die relevanten Anzeigenmetadaten werden dem Nutzer angezeigt, sobald sich der Abspielkopf innerhalb des Zeitraums für die Pause befindet. Für diese Unterbrechungen ist ein embedded timeline erforderlich und sie müssen statisch hinzugefügt werden. Weitere Informationen finden Sie im Abschnitt Anzeigenbereitstellung. Im Beispiel unten sehen Sie eine grundlegende Implementierung einer embedded-Anzeige.

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

eingebettete erweiterte Anzeigen

Die eingebettete erweiterte Werbeunterbrechung ist eine Art von Werbeunterbrechung, die serverseitig in den Stream des Hauptcontents eingefügt wird. Die Dauer von Break wird bei der Berechnung der Medienzeit in die Dauer des Hauptinhalts eingeschlossen.

BreakClip muss den duration des Anzeigeninhalts und den title bereitstellen. Für Break muss isEmbedded auf true und expanded auf true festgelegt sein. Für position kann eine Pre-Roll- oder Mid-Roll-Werbeunterbrechung festgelegt werden. Post-Roll-Werbeunterbrechungen werden mit positiven position-Werten unterstützt. Weitere Informationen finden Sie im Abschnitt zur Positionierung von Unterbrechungen. Wenn die Wiedergabe der Anzeige ausgelöst wird, setzt das Web Receiver SDK die Wiedergabe des Streams fort, während die Anzeigensegmente darin eingebettet sind. Für diesen Anzeigentyp gibt es keinen zusätzlichen Lademechanismus. Die relevanten Anzeigenmetadaten werden dem Nutzer angezeigt, sobald sich der Abspielkopf innerhalb des Zeitraums für die Pause befindet. Für diese Unterbrechungen ist ein embedded timeline erforderlich. Sie können entweder statisch oder dynamisch hinzugefügt werden. Weitere Informationen finden Sie im Abschnitt Anzeigenbereitstellung. Das folgende Beispiel zeigt eine grundlegende Implementierung einer embedded expanded-Anzeige:

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

Zeitachsentypen des Players

Beim Erstellen einer Player-Instanz wählt das Web Receiver SDK einen Zeitachsentyp aus, der die Wiedergabe von Anzeigen während der Contentwiedergabe unterstützt. Zu jeder Zeitachse können bestimmte Arten von Werbeunterbrechungen hinzugefügt werden. Der Zeitachsentyp wird durch die Anzeigentypen bestimmt, die während der Ladezeit im MediaInformation der LoadRequestData vorhanden sind. Wenn eingebettete Werbeunterbrechungen vorhanden sind, wird die Zeitachse embedded ausgewählt. Wenn vom Kunden erstellte Werbeunterbrechungen vorhanden sind, wird die Zeitachse stitched ausgewählt. Falls keine Anzeigen vorhanden sind, verwendet das SDK standardmäßig die Zeitachse embedded. Sobald die Zeitachse ausgewählt ist, kann sie für das aktuelle Medienelement nicht mehr geändert werden. Die folgende Tabelle enthält eine detaillierte Beschreibung der einzelnen Zeitachsen.

Zeitachsentyp Beschreibung
eingebettete Zeitachse Eine Darstellung der Medienzeit, die Anzeigen unterstützt, die in den Hauptinhalt eingebettet sind (eingebettete und eingebettete erweiterte Werbeunterbrechungen). Wenn eine nicht maximierte Werbeunterbrechung vorhanden ist, wird ihre Dauer von der Gesamtdauer des Contents abgezogen. Wenn andererseits eine erweiterte Werbeunterbrechung vorhanden ist, wird diese Zeit als Teil des Hauptinhalts betrachtet.
zusammengefügte Zeitachse Darstellung der Medienzeit, die Anzeigen unterstützt, die aus externen Mediendateien stammen (manuell mit Client-Stitched-, VAST- und VMAP-Werbeunterbrechungen. Wenn sie hinzugefügt wird, ist die Dauer der Werbeunterbrechung nicht Teil der Dauer des Hauptcontents.

In den Abbildungen 1 bis 3 unten sind einige Inhalte mit verschiedenen Anzeigentypen und deren jeweiligen Zeitachsenwerten dargestellt. Der Inhalt ist mit einer Pre-Roll-Pause konfiguriert, die zwei Pausenclips sowie Mid-Roll- und Post-Roll-Werbeunterbrechungen mit einem einzelnen Pausenclip enthält. Unter jeder Zahl sind die Zeitspanne seit Beginn der Inhaltswiedergabe, die Medienzeit des Hauptinhalts und die Zeit des aktuell wiedergegebenen Pausenclips der Pause angegeben.

Zeitplan für vom Kunden zusammengefügte Anzeigen
Abbildung 1: Zeitachse für einige Inhalte und die drei vom Kunden erstellten Werbeunterbrechungen.


Zeitachse für eingebettete Anzeigen mit Server-Stitching
Abbildung 2: Die Zeitachse, die einen Teil des Contents und die drei in Server eingebetteten Werbeunterbrechungen darstellt.


Zeitachse für eingebettete erweiterte Anzeigen mit Server-Stitching
Abbildung 3: Zeitachse, die einen Teil des Contents und die drei eingebetteten, eingebetteten erweiterten Werbeunterbrechungen in einem Server-Stitching darstellt.

Positionierung der Werbeunterbrechung

Mit dem Web Receiver SDK können Entwickler angeben, wo Werbeunterbrechungen platziert werden sollen. Dazu wird die Property position von Break festgelegt. Dieser Wert entspricht der Medienzeit des Hauptinhalts und kann zum Erstellen von pre-roll-, mid-roll- und post-roll-Werbeunterbrechungen verwendet werden. Diese sind wie folgt definiert:

Unterbrechungsposition Beschreibung
Pre-Roll Werbeunterbrechung, die vor dem Hauptcontent abgespielt wird Setzen Sie dazu breakPosition auf 0.
Mid-Roll Werbeunterbrechung, die mitten im Content abgespielt wird Dazu wird für breakPosition eine Zeit festgelegt, in der der Beginn der Unterbrechung größer als der Beginn des Hauptinhalts und das Ende der Unterbrechung kürzer als die Endzeit des Hauptinhalts ist.
Post-Roll Eine Werbeunterbrechung, die nach dem Hauptcontent wiedergegeben wird Setzen Sie dazu breakPosition für zusammengefügte Zeitachsen auf -1. Bei eingebetteten Zeitachsen sollte für breakPosition die Dauer des Hauptinhalts von der Dauer der Unterbrechung abgezogen werden. Wird für Liveinhalte nicht unterstützt.

Interoperabilitätsmatrix

Als Kurzübersicht finden Sie in Tabelle 1 einen Überblick über die Anzeigentypen und ihre Kompatibilität mit anzeigenbezogenen Funktionen.

Tabelle 1: Interoperabilitätsmatrix für Anzeigen
Funktionsunterstützung Manuell erstellte Client-Stitching-Anzeige VAST VMAP eingebettete Anzeige eingebettete erweiterte Anzeige
kompatibel mit VAST manuell zusammengefügt eingebettete erweiterte Anzeigen eingebettet
Zeitleiste Vernäht Vernäht Vernäht eingebettet eingebettet
Anzeigen einfügen Statisch Statisch Statisch Statisch statisch, dynamisch
Anzeigenentfernung
Pre-Roll-Anzeige
Mid-Roll-Anzeige
Post-Roll-Anzeige
Anzeigen überspringen
Break-Suche-Abfanggerät
Clip-Ladevorgang unterbrechen

Veranstaltungen

Wenn wichtige Pausenereignisse auftreten, löst das Cast SDK Ereignisse vom Typ BreaksEvent aus. Eine Empfängeranwendung kann sie mit der PlayerManager addEventListener API abonnieren.

Diese Ereignisse können für Analysen und das Tracking der Anzeigenwiedergabe verwendet werden. Wenn VMAP (Video Multiple Ad Playlist) und VMAP (Video Ad Serving Template) verwendet werden, werden alle standardmäßigen Tracking-Ereignisse in den Antworten automatisch vom SDK ausgelöst.

Die Ereignistypen sind in Tabelle 2 zusammen mit einer detaillierten Beschreibung dazu aufgeführt, wann sie ausgelöst werden.

Lebenszyklus von Unterbrechungsereignissen
Abbildung 4: Lebenszyklus von Unterbrechungsereignissen
Tabelle 2: Unterbrechungsereignisse und ihre Beschreibungen
Unterbrechungsereignis Beschreibung
BREAK_STARTED Wird ausgelöst, wenn die aktuelle Medienzeit des Hauptinhalts mit der position einer nicht angesehenen Pause übereinstimmt.
BREAK_CLIP_LOADING Wird nur ausgelöst, wenn der Ladevorgang einer zusammengefügten Zeitachse beginnt.
BREAK_CLIP_STARTED Wird ausgelöst, wenn die Wiedergabe eines Pausenclips beginnt
BREAK_CLIP_ENDED Wird ausgelöst, wenn ein Pausenclip endet Das Feld endedReason wird unter den folgenden Umständen ausgefüllt:
  • Bei einer zusammengefügten Zeitachse wird der Clip unterbrochen, der vollständig abgespielt wurde.
  • Eine zusammengefügte Zeitachse unterbricht den Übergang zu einem anderen Pausenclip.
  • Jeder Pausenclip wird übersprungen.
  • Der letzte Pausenclip, der vollständig in einer eingebetteten Post-Roll-Pause abgespielt wurde.
  • Ein Fehler ist aufgetreten.
BREAK_ENDED Wird ausgelöst, wenn der letzte Pausenclip in einer Unterbrechung endet.

Anzeigen einfügen

Mit dem Cast SDK können Apps zu verschiedenen Zeitpunkten einer Streamingsitzung Werbung einfügen und entfernen. Es gibt zwei Arten der Anzeigenbereitstellung: statisch und dynamisch. Für die statische Anzeigenbereitstellung müssen Anzeigen vor dem Erstellen des Players in der LoadRequestData angegeben werden. Bei der dynamischen Anzeigenbereitstellung werden mit der BreakManager addBreak API Pausen in bereits geladenen Inhalten eingefügt. Jede Art von Einfügemethode ist mit bestimmten Anzeigentypen kompatibel. Eine Kompatibilitätsübersicht finden Sie in der Interoperabilitätsmatrix.

Statische Anzeigenbereitstellung

Bei der statischen Anzeigenbereitstellung werden vor dem Erstellen des Players die relevanten Anzeigenmetadaten hinzugefügt. Diese Informationen finden Sie in der MediaInformation der LoadRequestData. Sie kann beispielsweise in der ursprünglichen Ladeanfrage eines verbundenen Senders festgelegt werden oder von der Web Receiver-Anwendung eingefügt werden, indem die LOAD-Anfrage abgefangen wird. Sobald die LoadRequestData zur Verarbeitung an das Web Receiver SDK zurückgegeben wird, wird der Player erstellt. Weitere Informationen zum Laden von Medien Im Beispiel unten sehen Sie eine manuell mit Client-Stitching erstellte Anzeige, die im Anfragen-Abfangprogramm LOAD hinzugefügt wird.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

Dynamische Anzeigenbereitstellung

Bei der dynamischen Anzeigenbereitstellung wird bei der Wiedergabe von Inhalten eine Werbeunterbrechung festgelegt. Dazu rufen Sie eine Instanz von BreakManager ab und rufen die addBreak API auf. Dafür sind mindestens zwei Parameter erforderlich: ein eingebettetes, erweitertes Break und ein Array von BreakClip. Ein optionales drittes Attribut ist enthalten, um das Senden der Änderungen an verbundene Absender über einen MediaStatus-Broadcast zu erzwingen, wenn true festgelegt ist. Beim Hinzufügen von Unterbrechungen und Pausenclips müssen die entsprechenden IDs eindeutig sein. Diese Anzeigen können erst hinzugefügt werden, nachdem der Player erstellt wurde. Das Web Receiver SDK löst das Ereignis PLAYER_LOADING aus, nachdem der Player erstellt wurde. Im folgenden Beispiel wird die Verwendung in einem Event-Handler veranschaulicht, der auf Änderungen in den ID3-Metadaten eines Streams reagiert und Break- und BreakClip-Objekte erstellt, um ihn in die Zeitachse einzufügen.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

Dynamische Anzeigen entfernen

Um dynamische Unterbrechungen zu entfernen, sollte die Anwendung während der Wiedergabe removeBreakById aufrufen. Die Funktion übernimmt eine String-ID der Unterbrechung, die von der Zeitachse entfernt werden soll. Die angegebene breakId muss auf eine eingebettete maximierte Werbeunterbrechung verweisen. Wenn eine andere Art von Werbeunterbrechung erkannt wird, bleibt sie auf der Zeitachse. Im folgenden Beispiel sehen Sie, wie eine Unterbrechung entfernt wird.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.removeBreakById('break_midroll_embedded_expanded');

Verhalten von Pausen

Das SDK definiert ein Standardverhalten für den Fall, dass der Spieler Pausen öffnet und wieder verlässt, und bietet die Möglichkeit, es mithilfe einiger der in BreakManager bereitgestellten APIs weiter anzupassen.

Standardverhalten für Werbeunterbrechung

Wenn ein Break über die reguläre Wiedergabe oder durch eine Suche in einem Break eingegeben wird, prüft das SDK anhand der Property isWatched, ob der Nutzer die Datei bereits gesehen hat. Der Standardwert einer Werbeunterbrechung für dieses Attribut beim Erstellen lautet false. Wenn das Attribut true ist, wird die Pause beim Aufrufen nicht abgespielt und der Hauptinhalt wird weiter abgespielt. Wenn das Attribut false ist, wird die Werbeunterbrechung bei Eingabe wiedergegeben.

Beim Durchsuchen vergangener Pausen werden bei der Standardimplementierung alle Break-Elemente abgerufen, deren position sich zwischen den seekFrom- und seekTo-Werten des Suchvorgangs befindet. Aus dieser Liste von Unterbrechungen gibt das SDK das Break wieder, dessen position dem Wert seekTo am nächsten ist und dessen Attribut isWatched auf false festgelegt ist. Die isWatched-Eigenschaft dieser Pause wird dann auf true gesetzt und der Player beginnt mit der Wiedergabe der Pausenclips. Nach der Wiedergabe der Pause wird die Wiedergabe des Hauptinhalts ab der Position seekTo fortgesetzt. Wenn keine solche Unterbrechung vorhanden ist, wird keine Unterbrechung ausgeführt und der Hauptinhalt wird an der Position seekTo fortgesetzt.

Während der Pausenwiedergabe sendet das SDK alle relevanten Aktualisierungen an verbundene Absenderanwendungen im MediaStatus. Diese Anwendungen verwenden die Broadcasts, um ihre Benutzeroberfläche für Anzeigen durch Lesen der breakStatus-Property zu aktualisieren. Diese Eigenschaft wird nur während der Unterbrechungswiedergabe definiert.

Empfängeranwendungen können auch direkt Informationen abfragen, die sich auf die Position des Abspielkopfs in Bezug auf die aktuelle Zeit des BreakClip beziehen, der durch Aufrufen von PlayerManager getBreakClipCurrentTimeSec angezeigt wird. Auf ähnliche Weise können Anwendungen die Dauer des aktuellen BreakClip durch Aufrufen von getBreakClipDurationSec abfragen.

Benutzerdefiniertes Verhalten für eine Werbeunterbrechung

Das Standardverhalten für Pausen und Pausenclips kann mit den Methoden setBreakClipLoadInterceptor und setBreakSeekInterceptor in BreakManager geändert werden.

Brechen, suchen und abfangen

Mit dem Interceptor der Werbeunterbrechung kann die App die Suche nach Werbeunterbrechungen steuern. Die Funktion wird ausgelöst, wenn ein Suchvorgang angefordert wird, der über eine oder mehrere Unterbrechungen vorwärts oder rückwärts springt. Beim Aufruf wird der BreakSeekData als Parameter an die Callback-Funktion übergeben. Das BreakSeekData-Objekt enthält ein Array von Break-Objekten, bei denen das Attribut position auf eine Zahl zwischen der aktuellen Abspielkopfzeit, definiert als seekFrom, und der Zielzeit für die Suche seekTo festgelegt ist.

Mit diesem Interceptor können die Break-Objekte in den jeweiligen Unterbrechungen geändert werden. Bei der Implementierung muss der Interceptor für die Pausensuche angeben, welche Werbeunterbrechungen abgespielt werden sollen. Dazu wird ein optional geändertes BreakSeekData-Objekt zurückgegeben. Der Player fährt mit der Wiedergabe aller im Rückgabewert enthaltenen Pausen fort. Wenn ein Wert von null oder nichts vom Interceptor der Pausensuche zurückgegeben wird, wird die Unterbrechung übersprungen.

Im folgenden Beispiel siehst du eine einfache Implementierung des Interceptor-Tools, das das Standardverhalten überschreibt, um alle Werbeunterbrechungen mit Ausnahme bereits angesehener Pausen zu beobachten.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

Abfangen des Clipladevorgangs unterbrechen

Mit dem Interceptor für das Laden von Pausenclips kann ein BreakClip-Objekt vor Beginn der Wiedergabe geändert werden.

Der Interceptor für das Laden eines Pausenclips wird nur für Bruchs in der zusammengefügten Zeitachse aufgerufen und kann mit setBreakClipLoadInterceptor festgelegt werden. Vor der Eingabe eines Break wird dieser Interceptor einmal für jede einzelne BreakClip aufgerufen, die in diesem Pause definiert ist. Das SDK übergibt das ursprüngliche BreakClip-Objekt als Parameter der Callback-Funktion. Die Anwendung kann dann diesen BreakClip ändern und ihn zurückgeben, sodass das SDK den Pausenclip mit der aktualisierten Konfiguration abrufen und anzeigen kann. Wenn null oder nichts zurückgegeben wird, wird der Unterbrechungsclip übersprungen.

Unten sehen Sie ein Beispiel, bei dem die contentUrl der Pausenclips mit dem Dienstprogrammfunktion getUrlFromClipId geändert werden, wobei die id der BreakClip einer URL zugeordnet ist.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

Überspringen von Anzeigen

Das Web Receiver SDK bietet APIs zum Überspringen von Werbeunterbrechungen und einzelnen Werbeunterbrechungen innerhalb einer Werbeunterbrechung. Mit dem SDK können Nutzer außerdem Pausenclips überspringen, indem sie mit ihren Senderanwendungen oder Smart Display-Geräten interagieren.

Nutzer – Überspringbare Pausenclips

Wenn Pausenclips überspringbar sind, können Nutzer mit verbundenen Senderanwendungen und Smart-Display-Geräten interagieren und optional den Rest eines aktuell wiedergegebenen Pausenclips überspringen. Wenn Sie das Attribut whenSkippable auf eine nicht negative Anzahl von Sekunden festlegen, wird diese Funktion für das Objekt BreakClip aktiviert. Der Pausenclip wird vom Player als überspringbar betrachtet, sobald er die entsprechende Anzahl von Sekunden abgespielt hat. Wenn Sie diesen Wert auf 0 setzen, können Nutzer den Pausenclip sofort überspringen.

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

Diese Informationen können in der ursprünglichen Ladeanfrage des Absenders oder in der Empfänger-App festgelegt werden. Wenn ein Pausenclip in einer zusammengefügten Zeitachse übersprungen wird, wird die Wiedergabe des aktuellen Pausenclips beendet. Der Player lädt entweder den nächsten Pausenclip (falls vorhanden) oder den Hauptinhalt. Wenn ein Pausenclip in einer eingebetteten Zeitachse übersprungen wird, springt er zum Ende des Pausenclips und setzt die Wiedergabe des Streams an dieser Stelle fort.

Anzeigen programmatisch überspringen

Anzeigen können auch automatisch ohne Nutzerinteraktion übersprungen werden.

Wenn eine gesamte Pause übersprungen werden soll, sollte eine App das Attribut isWatched einer Break auf true setzen. Dies kann jederzeit während der Ladesequenz oder der Inhaltswiedergabe erfolgen. Das Attribut isWatched wird vom Player ausgewertet, wenn die position einer Pause in der aktuellen Zeit des Hauptinhalts erreicht ist. An dieser Stelle entscheidet der Player, ob eine Pause eingegeben werden soll. Im folgenden Beispiel werden alle Unterbrechungen durchgegangen und der Wert wird geändert, wenn der Player geladen wird.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

Wenn Sie einen bestimmten Unterbrechungsclip programmatisch überspringen möchten, sollten Sie den Abfangvorgang für das Laden von Pausenclips verwenden. Wird null oder kein Wert in der Callback-Funktion zurückgegeben, wird der Clip in dieser Pause übersprungen.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});