Przerwy na reklamy

Omówienie

Pakiet Web Receiver SDK zapewnia natywną obsługę przerw na reklamy i reklam towarzyszących w ramach danego strumienia multimediów. Udostępnia interfejsy API do ustawiania pozycji reklamy, źródła reklam zachowanie przerw na reklamę i powiązanych z nimi przerw na reklamy. W tym przewodniku Break oznacza interwał odtwarzania zawierający co najmniej jedną reklamę lub bumpery oraz Wszystkie reklamy i przerywniki to tzw. BreakClip Przerwy te są powiązane z multimediami, które są ładowane lub odtwarzane.

Typy reklam

Pakiet Web Receiver SDK obsługuje wstawianie reklam po stronie klienta i serwer połączone wstawianie reklam (SSAI). Reklamy połączone przez klienta mogą być ustawiane ręcznie przez lub wyodrębniona z plików szablonów VAST i VMAP. Reklamy połączone z serwerem należy określić ręcznie przed załadowaniem treści jako osadzonych reklam lub dynamicznie podczas odtwarzania treści jako osadzonych rozwiniętych. reklam. Implementacje tych typów reklam znajdziesz poniżej.

// 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.

// 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.

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

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

// 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;

// 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.

// 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;

Typy osi czasu odtwarzacza

Podczas tworzenia instancji odtwarzacza pakiet SDK odbiornika internetowego wybiera typ osi czasu, umożliwiają odtwarzanie reklam podczas odtwarzania treści. Każda oś czasu umożliwia typy podziałów, które chcesz dodać. Typ osi czasu jest określany przez typy reklam występujących w czasie wczytywania w sekcji MediaInformation. z LoadRequestData Jeśli występują umieszczone przerwy na reklamę, wybrana zostanie oś czasu embedded. Jeśli jeśli występują przerwy na reklamę połączone z klientem, wybrana jest oś czasu stitched. W przypadku braku reklam pakiet SDK domyślnie używa interfejsu embedded osi czasu. Po wybraniu osi czasu nie można jej zmienić dla bieżącej element multimedialny. W tabeli poniżej znajdziesz szczegółowy opis każdego harmonogramu.

Rysunki 1–3 poniżej przedstawiają treści związane z różnymi typami reklam i ich odpowiednie wartości osi czasu. w treściach jest skonfigurowana przerwa przed filmem; składające się z dwóch klipów oraz przerw w trakcie filmu i po filmie, zawierających pojedynczy klip. Zegar ścienny od momentu rozpoczęcia odtwarzania treści, czas multimediów głównej treści oraz bieżący czas przerwy odtwarzanego klipu z przerwami są wyrównane pod każdą ilustracją.

Przerwanie pozycjonowania

Pakiet Web Receiver SDK pozwala programistom określić, gdzie powinny znaleźć się przerwy na reklamy. umieszczone przez ustawienie position właściwości Break. Ta wartość odpowiada czasowi odtwarzania treści głównej i można go użyć do tworzenia przerw na reklamy pre-roll, mid-roll i post-roll. Są to:

Macierz interoperacyjności

W tabeli 1 znajdziesz omówienie różnych typów reklam oraz ich zgodności z funkcjami związanymi z reklamami.

Wydarzenia

Gdy wystąpią kluczowe zdarzenia przerwy na reklamę, pakiet SDK Cast będzie wysyłać zdarzenia określonego typu. BreaksEvent Aplikacja odbiornika może je subskrybować za pomocą funkcji PlayerManager addEventListener. API.

Można je wykorzystać do analizy i śledzenia odtwarzania reklam. Gdy VMAP (Playlista wideo z wieloma reklamami) i reklamy VAST (Video Ad Serving Template) są wszystkie standardowe zdarzenia śledzenia podane w odpowiedziach są automatycznie wysyłane przez pakiet SDK.

Typy zdarzeń podano w tabeli 2 wraz ze szczegółowym opisem po zwolnieniu z pracy.

Wstawianie reklam

Pakiet SDK Cast umożliwia aplikacjom wstawianie i usuwanie reklam w różnych momentach sesji przesyłania. Wyróżniamy 2 typy wstawiania reklam: statyczne i dynamiczne. Statyczne wstawianie reklam wymaga, by reklamy były zdefiniowane w sekcji LoadRequestData. przed jego utworzeniem. Dynamiczne wstawianie reklam wykorzystuje BreakManager. addBreak. Interfejs API do wstawiania przerw w już załadowanej treści. Każdy typ wstawiania jest zgodna z określonymi typami reklam. Zgodność jest dostępne w tabeli interoperacyjności.

Statyczne wstawianie reklam

Statyczne wstawianie reklam polega na dodaniu odpowiednich metadanych reklamy przed w tworzeniu odtwarzacza. Te informacje są dostępne w MediaInformation LoadRequestData. Można ją na przykład ustawić w ustawieniach połączonego nadawcy lub może zostać wstawione przez aplikację Web Receiver przechwytywania żądania LOAD. Gdy LoadRequestData wrócą do SDK odbiornika internetowego do przetwarzania, tworzony jest odtwarzacz. Zobacz więcej na: pobieram multimedia. Przykład poniżej pokazuje reklamę ręcznie złączoną z klientem dodaną w żądaniu LOAD lub przechwytywanie.

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;
});

Dynamiczne wstawianie reklam

Dynamiczne wstawianie reklam polega na ustawieniu przerwy na reklamę w trakcie treści odtwarzania. W tym celu należy pozyskać instancję BreakManager i wywołać addBreak. API. Wymagane są co najmniej dwa parametry: osadzone rozwinięte Break i tablica BreakClip Dołączyliśmy opcjonalną właściwość trzecią, która wymusza wysłanie zmian do nadawców połączonych za pomocą transmisji MediaStatus, gdy jest ustawiona na true. Kiedy po dodaniu przerw i klipów przerywanych, odpowiadające im identyfikatory muszą być unikalne. Te reklamy można dodać dopiero po utworzeniu odtwarzacza. Uruchomi się pakiet SDK odbiornika internetowego PLAYER_LOADING po utworzeniu odtwarzacza. Poniżej znajdziesz przykład korzystania z narzędzia modułu obsługi zdarzeń, który reaguje na zmiany w metadanych ID3 strumienia. tworzy obiekty Break i BreakClip, aby wstawić je na osi czasu.

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]);
});

Dynamiczne usuwanie reklam

Aby usunąć przerwy dynamiczne, aplikacja powinna wywołać removeBreakById podczas odtwarzania. Funkcja przyjmuje identyfikator przerwy w ciągu znaków, aby usunięte z osi czasu. Podana wartość breakId musi wskazywać umieszczoną rozwiniętej przerwy na reklamę. Jeśli zostanie wykryty inny typ przerwy na reklamę, pozostanie na osi czasu. Zapoznaj się z poniższym przykładem, w którym usunięto przerwę.

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

breakManager.removeBreakById('break_midroll_embedded_expanded');

Zachowanie przerw

Pakiet SDK określa domyślne zachowanie, gdy odtwarzacz zaczyna odtwarzać treści i zostawia przerwy. i umożliwia jego dalsze dostosowanie za pomocą niektórych interfejsów API cale BreakManager

Domyślne działanie przerwy

Jeśli podczas zwykłego odtwarzania lub przewijania w elemencie Break pojawi się element Break, SDK oceni, czy użytkownik widział już ten film, isWatched. usłudze. Po utworzeniu przerwy domyślna wartość przerwy dla tej właściwości to false. Jeśli właściwość ma true, przerwa nie będzie odtwarzana po wpisaniu i głównym treści będą nadal odtwarzane. Jeśli właściwość to false, przerwa będzie miała postać odtwarzane po uruchomieniu.

W przypadku przeszukiwania wcześniejszych przerw domyślna implementacja pobiera wszystkie te parametry: Break. elementy, których wartość position znajduje się między funkcją przewijania seekFrom. oraz seekTo. . Z tej listy przerw pakiet SDK będzie odtwarzać ścieżkę Break, której position jest najbliższa wartości seekTo, a jego właściwość isWatched jest ustawiona na false. Właściwość isWatched tej przerwy zostanie ustawiona na true, a parametr odtwarzacz rozpocznie odtwarzanie klipów przerw. Po obejrzeniu przerwy odtwarzanie głównej treści zostanie wznowione od pozycji seekTo. Jeśli nie, przerwa, nie zostanie odtworzona przerwa i zostanie wznowiona główna treść odtwarzam w pozycji seekTo.

Podczas odtwarzania w przerwie pakiet SDK będzie przesyłać wszystkie istotne aktualizacje do połączonych aplikacji nadawców w MediaStatus Te aplikacje będą korzystać z transmisji, aby aktualizować interfejs reklam na podstawie breakStatus usłudze. Ta właściwość jest określana tylko podczas odtwarzania przerwy.

Mogą też bezpośrednio wysyłać zapytania dotyczące położenie suwaka odtwarzania względem aktualnego czasu BreakClip wyświetlane po wywołaniu numeru PlayerManager getBreakClipCurrentTimeSec. Podobnie aplikacje mogą wysyłać zapytania o czas trwania bieżącego BreakClip przez połączenia getBreakClipDurationSec

Niestandardowe działanie przerwy

Działanie domyślne przerwanych i przerw na klipy można modyfikować za pomocą setBreakClipLoadInterceptor. oraz setBreakSeekInterceptor. metod wymienionych w BreakManager.

Przerwanie przechwytującego przewijania

Element przechwytujący przerwy i przewijanie umożliwia aplikacji kontrolowanie działania przewijania w czasie przerw na reklamę. Funkcja jest wyzwalana po zażądaniu operacji przewijania. przewijanie do przodu lub do tyłu o jedną lub więcej przerw. Po wywołaniu funkcja BreakSeekData jest przekazywany jako parametr do funkcji wywołania zwrotnego. Obiekt BreakSeekData zawiera tablicę Break. obiekty, których właściwość position jest ustawiona na liczbę z przedziału od bieżącej wartości czas odtwarzania zdefiniowany jako seekFrom. oraz czas przejścia do miejsca docelowego. seekTo

Umożliwia on obiektom Break w odpowiednich przerwach zmodyfikowane. Po zaimplementowaniu ten element przechwytujący przerwę podczas przewijania musi określać, która reklama powoduje zwrócenie opcjonalnie zmodyfikowanego obiektu BreakSeekData. odtwarzacz rozpocznie odtwarzanie wszystkich przerw zawartych w zwracanej wartości. Jeśli wartość null lub żaden element nie jest zwracany z funkcji przechwytywania przerwy i przewijania, przerwa jest przeskoczył mnie na bok.

Poniżej znajdziesz przykład prostej implementacji modułu zastępuje domyślne zachowanie polegające na oglądaniu wszystkich przerw na reklamy przeszukanych wraz z z wyjątkiem wcześniej obejrzanych przerw.

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;
});

Przerwij przechwytujący obciążenie wczytywania klipu

Za pomocą funkcji przechwytującej wczytywania klipu z przerwami można modyfikować obiekt BreakClip przed rozpoczęciem odtwarzania.

Funkcja przechwytująca wczytywanie klipu z przerwami jest wywoływana tylko dla połączone przerwy na osi czasu, i można ustawić za pomocą setBreakClipLoadInterceptor. Przed wprowadzeniem danych Break ten element przechwytujący jest wywoływany raz dla każdej osoby BreakClip zdefiniowane w tej przerwie. Pakiet SDK przekazuje pierwotną wersję BreakClip jako parametr funkcji wywołania zwrotnego. Aplikacja może następnie modyfikować ten element BreakClip i zwróci go, aby pakiet SDK mógł pobrać i wyświetlić przerwę ze zaktualizowaną konfiguracją. Jeśli zostanie zwrócona wartość null lub żadna, przerwa klip jest pomijany.

Poniżej znajdziesz przykład, który zmienia znak contentUrl w klipach przerwy na reklamę – wywołanie funkcji użytkowej getUrlFromClipId, gdzie id funkcji BreakClip jest mapowany na adres URL.

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;
});

Pomijanie reklam

Pakiet Web Receiver SDK udostępnia interfejsy API, które umożliwiają pomijanie przerw na reklamy i poszczególnych przerw na reklamy w trakcie przerwy na reklamę. Pakiet SDK umożliwia też użytkownikom opcjonalnie pomijanie klipów przerywanych według interakcji z aplikacjami wysyłającymi lub inteligentnymi ekranami.

Przerwane klipy użytkownika możliwe do pominięcia

Ustawienie klipów z przerwami jako możliwych do pominięcia umożliwia użytkownikom interakcję z połączonym nadawcą aplikacji i inteligentnych ekranów, aby opcjonalnie pominąć odtwarzam klip z przerwą. Ustawienie wartości whenSkippable na nieujemną liczbę sekund, dla funkcji BreakClip obiekt. Odtwarzacz uzna klip za możliwy do pominięcia, gdy został odtworzony przez taką liczbę sekund. Ustawiam tę wartość na 0 pozwala użytkownikom na natychmiastowe pominięcie klipu.

// 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.

Te informacje można ustawić w pierwotnym żądaniu wczytania nadawcy lub w w aplikacji odbiornika. Pominięty klip oznacza przerwę na reklamę w połączonej osi czasu. przerwie odtwarzanie bieżącego klipu. Odtwarzacz wczyta następne przerywać klip (jeśli jest dostępny) lub wczytać główną zawartość. Jeśli pominiesz ten krok, klip z przerwą umieszczona oś czasu przerwa na reklamę przejdzie do końca klipu z przerwami i od tego momentu będzie dalej odtwarzać strumień.

Automatyczne pomijanie reklam

Reklamy mogą być też pomijane automatycznie bez interakcji ze strony użytkownika.

Aby pominąć całą przerwę od odtwarzania, aplikacja powinna ustawić parametr isWatched. właściwości obiektu Break do true. Możesz to zrobić w dowolnym momencie wczytywania sekwencji lub odtwarzania treści. Właściwość isWatched jest oceniana przez odtwarzacz, w przypadku którego w bieżącym momencie treści głównej występuje osiągnięcie wartości position przerwy. Na w tym punkcie, odtwarzacz określi, czy należy zrobić przerwę. Zapoznaj się z poniższym przykładem, który zawiera zapętlone wszystkie przerwy i modyfikuje podczas wczytywania odtwarzacza.

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;
  });
});

Aby automatycznie pominąć konkretny klip przerwy, komponent Należy użyć mechanizmu przechwytującego wczytanie klipu. Według zwracający null lub nie zwraca wartości w funkcji wywołania zwrotnego, zostanie utworzony klip ta przerwa zostanie pominięta.

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

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