Рекламные паузы

Обзор

SDK Web Receiver обеспечивает встроенную поддержку рекламных пауз и сопутствующих рекламных объявлений в данном медиапотоке. Он предоставляет API для установки позиции рекламы, источника рекламы и поведения рекламных пауз и связанных с ними клипов. В этом руководстве Break понимается интервал воспроизведения, содержащий одну или несколько рекламных объявлений или заставок, и каждое рекламное объявление или заставка называется BreakClip . Эти перерывы связаны с загружаемым или воспроизводимым носителем.

Типы объявлений

SDK веб-приемника поддерживает вставку рекламы на стороне клиента (CSAI) и вставку рекламы, привязанную к серверу (SSAI). Объявления, сшитые клиентом, можно настроить вручную с помощью приложения или извлечь из файлов шаблонов VAST и VMAP . Объявления , добавленные на сервер, следует указывать вручную перед загрузкой контента в виде встроенных объявлений или динамически во время воспроизведения контента в виде встроенных расширенных объявлений. Реализация каждого из этих типов объявлений подробно описана ниже.

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

Типы временной шкалы игрока

При создании экземпляра проигрывателя SDK Web Receiver выбирает тип временной шкалы для поддержки воспроизведения рекламы во время воспроизведения контента. Каждая временная шкала позволяет добавлять определенные типы рекламных пауз. Тип временной шкалы определяется типами объявлений , присутствующими во время загрузки в MediaInformation LoadRequestData . Если присутствуют встроенные рекламные паузы, выбирается embedded временная шкала. Если присутствуют рекламные паузы, сшитые клиентом , выбирается stitched временная шкала. В случае отсутствия рекламы SDK по умолчанию использует embedded временную шкалу. После выбора временной шкалы ее нельзя изменить для текущего элемента мультимедиа. В таблице ниже представлено подробное описание каждой временной шкалы.

На рисунках 1–3 ниже показан некоторый контент с различными типами объявлений и соответствующими временными значениями. Контент настроен с помощью паузы перед роликом , содержащей два клипа-паузы, а также пауз в середине и после ролика, содержащих один клип-паузу. Время настенных часов с момента начала воспроизведения контента, время мультимедиа основного контента и время воспроизводимого в данный момент клипа перерыва выровнены под каждой цифрой.

Разрыв позиционирования

SDK Web Receiver позволяет разработчикам указывать, где следует размещать рекламные паузы, устанавливая свойство position Break . Это значение соответствует времени воспроизведения основного контента и может использоваться для создания рекламных пауз pre-roll , mid-roll и post-roll . Они определяются следующим образом:

Матрица совместимости

В качестве справки в Таблице 1 представлен обзор типов объявлений и их совместимости с функциями, связанными с рекламой.

События

Когда происходят события разрыва ключа, Cast SDK отправляет события типа BreaksEvent . Приложение-получатель может подписаться на них с помощью API PlayerManager addEventListener .

Эти события можно использовать для аналитики и отслеживания воспроизведения рекламы. При использовании объявлений VMAP (список воспроизведения нескольких видеообъявлений) и VAST (шаблон показа видеорекламы) любые стандартные события отслеживания, представленные в ответах, автоматически отправляются SDK.

Типы событий перечислены в Таблице 2 вместе с подробным описанием того, когда они инициируются.

Вставка объявления

Cast SDK позволяет приложениям вставлять и удалять рекламу в разные моменты сеанса трансляции. Два типа вставки рекламы — статические и динамические . Для вставки статической рекламы необходимо, чтобы реклама была указана в LoadRequestData до создания игрока. Вставка динамической рекламы использует API-интерфейс BreakManager addBreak для вставки разрывов в уже загруженный контент. Каждый тип метода вставки совместим с определенными типами объявлений . Обзор совместимости представлен в матрице совместимости .

Статическая вставка рекламы

Вставка статической рекламы характеризуется добавлением соответствующих метаданных рекламы до создания проигрывателя. Эта информация предоставляется в MediaInformation LoadRequestData . Например, это может быть установлено в исходном запросе загрузки подключенного отправителя или может быть вставлено приложением веб-приемника путем перехвата запроса LOAD . Как только LoadRequestData возвращается в SDK веб-приемника для обработки, проигрыватель создается. Подробнее о загрузке мультимедиа см. В приведенном ниже примере показано , как вручную добавленное клиентом объявление в перехватчик запроса LOAD .

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

Динамическая вставка рекламы

Динамическая вставка рекламы характеризуется установкой рекламной паузы во время воспроизведения контента. Это делается путем получения экземпляра BreakManager и вызова API addBreak . Для этого требуется как минимум два параметра: встроенный расширенный Break и массив BreakClip . Включено необязательное третье свойство, которое принудительно отправляет изменения подключенным отправителям через широковещательную рассылку MediaStatus , если для него установлено true . При добавлении разрывов и клипов соответствующие идентификаторы должны быть уникальными. Эти объявления можно добавить только после создания игрока. SDK веб-приемника запускает событие PLAYER_LOADING после создания проигрывателя. См. пример ниже, демонстрирующий использование в обработчике событий, который реагирует на изменения в метаданных ID3 потока и создает объекты Break и BreakClip для вставки их на временную шкалу.

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

Удаление динамической рекламы

Чтобы удалить динамические разрывы, приложение должно вызывать removeBreakById во время воспроизведения. Функция принимает строковый идентификатор перерыва, который необходимо удалить с временной шкалы. Указанный идентификатор breakId должен указывать на встроенную расширенную рекламную паузу. Если обнаружен какой-либо другой тип рекламной паузы, она останется на временной шкале. См. пример ниже, в котором удаляется разрыв.

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

breakManager.removeBreakById('break_midroll_embedded_expanded');

Поведение перерывов

SDK определяет поведение по умолчанию, когда игрок входит и выходит из перерывов, и предоставляет возможность дальнейшей настройки с помощью некоторых API-интерфейсов, предоставляемых в BreakManager .

Поведение прерывания по умолчанию

Когда Break вводится посредством обычного воспроизведения или поиска по Break , SDK оценит, видел ли его уже пользователь, проверяя свойство isWatched . При создании значением по умолчанию для этого свойства разрыва является false . Если свойство имеет true , при вводе пауза не будет воспроизводиться, а основной контент продолжит воспроизведение. Если свойство имеет значение false , при вводе будет воспроизведен перерыв.

При поиске прошлых разрывов реализация по умолчанию получает все элементы Break , position которых находится между значениями seekFrom и seekTo операции поиска. Из этого списка разрывов SDK будет воспроизводить Break , position которого ближе всего к значению seekTo и чье свойство isWatched имеет значение false . Свойству isWatched этой паузы будет присвоено значение true , и проигрыватель начнет воспроизводить клипы паузы. После просмотра перерыва воспроизведение основного контента возобновится с позиции seekTo . Если такого разрыва не существует, то перерыв воспроизводиться не будет, и воспроизведение основного контента возобновится с позиции seekTo .

Во время воспроизведения с перерывом SDK будет транслировать любые соответствующие обновления подключенным приложениям-отправителям в MediaStatus . Эти приложения будут использовать трансляции для обновления своего пользовательского интерфейса для рекламы, считывая свойство breakStatus . Это свойство определяется только во время воспроизведения с перерывом.

Приложения-приемники также могут напрямую запрашивать информацию, относящуюся к положению точки воспроизведения относительно текущего времени отображаемого BreakClip , путем вызова PlayerManager getBreakClipCurrentTimeSec . Аналогично, приложения могут запрашивать продолжительность текущего BreakClip , вызывая getBreakClipDurationSec .

Пользовательское поведение при перерыве

Поведение по умолчанию для разрывов и клипов разрывов можно изменить с помощью методов setBreakClipLoadInterceptor и setBreakSeekInterceptor , предоставляемых в BreakManager .

Перехватчик поиска перерыва

Перехватчик поиска перерывов позволяет приложению контролировать поведение поиска во время рекламных пауз. Функция срабатывает, когда запрашивается операция поиска, которая осуществляет поиск вперед или назад через один или несколько разрывов. При вызове BreakSeekData передается в качестве параметра функции обратного вызова. Объект BreakSeekData содержит массив объектов Break , свойство position которого установлено в число между текущим временем воспроизведения, определенным как seekFrom , и временем назначения поиска seekTo .

Этот перехватчик позволяет изменять объекты Break в соответствующих разрывах. При реализации перехватчик поиска перерывов должен указывать, какие рекламные паузы воспроизводиться, возвращая необязательно модифицированный объект BreakSeekData . Игрок продолжит играть все перерывы, включенные в возвращаемое значение. Если от перехватчика поиска разрыва возвращается значение null или ничего, разрыв пропускается.

В приведенном ниже примере показана простая реализация перехватчика, который переопределяет поведение по умолчанию для просмотра всех запрашиваемых рекламных пауз, за ​​исключением уже просмотренных рекламных пауз.

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

Перехватчик нагрузки разрывного зажима

Используя перехватчик загрузки клипа прерывания, объект BreakClip можно изменить до начала его воспроизведения.

Перехватчик загрузки клипа разрыва вызывается только для сшитых разрывов временной шкалы и может быть установлен с помощью setBreakClipLoadInterceptor . Перед входом в Break этот перехватчик вызывается один раз для каждого отдельного BreakClip определенного в этом разрыве. SDK передает исходный объект BreakClip в качестве параметра функции обратного вызова. Затем приложение может изменить этот BreakClip и вернуть его, чтобы SDK мог получить и отобразить BreakClip с обновленной конфигурацией. Если возвращается null или ничего не возвращается, клип разрыва пропускается.

Ниже приведен пример, который изменяет contentUrl клипов разрыва с помощью вызова служебной функции getUrlFromClipId где id BreakClip сопоставляется с 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;
});

Пропуск рекламы

SDK Web Receiver предоставляет API для пропуска рекламных пауз и отдельных рекламных роликов внутри рекламной паузы. SDK также позволяет пользователям при желании пропускать перерывы, взаимодействуя со своими приложениями-отправителями или интеллектуальными устройствами отображения.

Пропускаемые пользователем перерывы в клипах

Настройка клипов с возможностью пропуска позволяет пользователям взаимодействовать с подключенными приложениями-отправителями и интеллектуальными устройствами отображения, чтобы при желании пропустить остальную часть воспроизводимого в данный момент клипа. Установка для свойства whenSkippable неотрицательного числа секунд включит эту функцию для объекта BreakClip . Игрок будет считать, что перерыв можно пропустить, как только он проиграется в течение указанного количества секунд. Установка этого значения на 0 позволяет пользователям немедленно пропустить прерывающий клип.

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

Эту информацию можно указать в исходном запросе загрузки отправителя или в приложении-получателе. При пропуске рекламного ролика в сшитой временной шкале воспроизведение текущего клипа будет остановлено. Проигрыватель либо загрузит следующий клип-паузу, если он присутствует, либо загрузит основной контент. Если этот параметр пропущен, рекламный ролик на встроенной временной шкале будет искать конец рекламного ролика и продолжать воспроизведение потока с этого момента.

Программный пропуск рекламы

Рекламу также можно пропускать автоматически без какого-либо взаимодействия с пользователем.

Чтобы пропустить весь перерыв в воспроизведении, приложение должно установить для свойства isWatched Break значение true . Это можно сделать в любой момент во время загрузки или воспроизведения контента. Свойство isWatched оценивается игроком, когда position разрыва встречается в текущем времени основного контента. В этот момент игрок определит, следует ли вводить перерыв. См. пример ниже, в котором циклически перебираются все разрывы и изменяется значение при загрузке проигрывателя.

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

Чтобы программно пропустить определенный клип разрыва , следует использовать перехватчик загрузки клипа разрыва . Если вернуть null или не вернуть значение в функции обратного вызова, клип в этом разрыве будет пропущен.

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

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