Добавить поддержку API Ad Breaks в веб-приемник

1. Обзор

В этом практическом занятии описано, как создать пользовательское приложение Web Receiver, использующее API рекламных пауз Cast.

Что такое Google Cast?

Google Cast позволяет пользователям транслировать контент с мобильного устройства на телевизор. Затем пользователи могут использовать свое мобильное устройство в качестве пульта дистанционного управления для воспроизведения мультимедиа на телевизоре.

SDK Google Cast позволяет расширить функциональность вашего приложения для управления телевизором или звуковой системой. SDK Cast позволяет добавлять необходимые компоненты пользовательского интерфейса в соответствии с контрольным списком дизайна Google Cast .

Контрольный список Google Cast Design Checklist предназначен для стандартизации реализаций Cast и обеспечения интуитивно понятного пользовательского интерфейса на всех поддерживаемых платформах.

Что мы будем строить?

По завершении этого практического занятия вы создадите приемник Cast, использующий API Break.

Что вы узнаете

• Как добавить разрывы VMAP и VAST в контент для Cast
• Как пропускать паузы в видеороликах
• Как настроить поведение прерывания по умолчанию при перемотке

Что вам понадобится

• Последняя версия браузера Google Chrome .
• HTTPS-хостинг, например, Firebase Hosting или ngrok .
• Устройство Google Cast, такое как Chromecast или Android TV, с подключением к интернету.
• Телевизор или монитор с HDMI-входом, или Google Home Hub.

Опыт

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

• Общие знания в области веб-разработки.
• Создание приложений Cast Web Receiver.

> Возникли проблемы с сетью? > Если вы находитесь в месте, где сеть Wi-Fi нестабильна, устройство Chromecast можно подключить проводным способом с помощью адаптера Ethernet.

Chromecast или Chromecast с Google TV .

Как вы будете использовать этот учебный материал?

Прочитайте только от начала до конца. Прочитайте текст и выполните упражнения.

Как бы вы оценили свой опыт в разработке веб-приложений?

Новичок Средний Профессионал

2. Получите пример кода.

Загрузите весь примерный код на свой компьютер...

Скачать исходный код

и распакуйте загруженный zip-файл.

> Репозиторий cast-videos-cast codelab содержит два примера проектов: > * app-start — это исходный код, на основе которого вы будете строить свою работу в этом практическом занятии. * app-done — Полный код готового демонстрационного видеоприложения.

3. Разверните приемник локально.

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

Если у вас нет доступного сервера, вы можете использовать Firebase Hosting или ngrok .

Запустите сервер

После того, как вы настроили выбранную вами службу, перейдите в app-start и запустите сервер.

Запишите URL-адрес вашего размещенного ресивера. Он понадобится вам в следующем разделе.

4. Зарегистрируйте приложение в консоли разработчика Cast.

> Нет учетной записи разработчика Cast? > Зарегистрируйте учетную запись в консоли разработчика Google Cast SDK и оплатите регистрационный сбор.

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

Нажмите «Добавить новое приложение».

Выберите "Пользовательский приемник", именно его мы и создаем.

Введите данные вашего нового получателя. Обязательно используйте URL-адрес, указывающий на место, где вы планируете разместить ваше приложение Web Receiver. Запишите идентификатор приложения , сгенерированный консолью после регистрации приложения. Приложение-отправитель будет настроено на использование этого идентификатора в последующем разделе.

Перед публикацией приложения необходимо также зарегистрировать устройство Google Cast, чтобы оно могло получить к нему доступ. После публикации приложение станет доступно для всех устройств Google Cast. Для целей данного практического занятия рекомендуется работать с неопубликованным приложением.

Нажмите «Добавить новое устройство»

Введите серийный номер, напечатанный на задней панели вашего устройства Cast, и присвойте ему описательное имя. Вы также можете найти свой серийный номер, транслируя экран в Chrome через консоль разработчика Google Cast SDK.

Для подготовки ресивера и устройства к тестированию требуется от 5 до 15 минут. После ожидания в течение 5-15 минут необходимо перезагрузить устройство Cast.

5. Подготовьте стартовый проект.

Перед началом этого практического занятия полезно ознакомиться с руководством для разработчиков по рекламе , в котором представлен обзор API для создания рекламных пауз.

Необходимо добавить поддержку Google Cast в загруженное вами стартовое приложение. Вот некоторые термины, используемые в этом практическом задании:

• Приложение отправителя работает на мобильном устройстве или ноутбуке.
• Приложение- приемник работает на устройстве Google Cast.

Теперь вы готовы продолжить работу над стартовым проектом, используя свой любимый текстовый редактор:

1. Выберите Каталог app-start из загруженного вами примера кода.
2. Откройте js/receiver.js и index.html.

Обратите внимание, что во время выполнения этого практического задания необходимо обновить выбранное вами решение для веб-хостинга в соответствии с внесенными изменениями. Убедитесь, что вы отправляете изменения на хостинг-сайт при дальнейшей проверке и тестировании.

Дизайн приложений

Как уже упоминалось, в практическом задании используется приложение-отправитель для инициирования сессии Cast и приложение-получатель, которое будет модифицировано для использования API рекламных пауз.

В этом практическом занятии инструмент Cast and Command Tool будет выступать в качестве веб-отправителя для запуска приложения-приемника. Для начала откройте инструмент в браузере Chrome. Введите идентификатор приложения-приемника , который вам был предоставлен в консоли разработчика Cast SDK, и нажмите «Установить», чтобы настроить приложение-отправитель для тестирования.

Примечание: Если значок трансляции не отображается, убедитесь, что веб-приемник и устройство(а) трансляции правильно зарегистрированы в консоли разработчика Cast. Если вы еще этого не сделали, перезагрузите все только что зарегистрированные устройства трансляции.

Основное внимание в этом практическом занятии уделяется приложению-приемнику, которое состоит из одного основного представления, определенного в index.html , и одного файла JavaScript под названием js/receiver.js . Более подробно они описаны ниже.

index.html

Этот HTML-файл содержит пользовательский интерфейс нашего приложения-приемника, предоставляемый элементом cast-media-player . Он также загружает библиотеки CAF SDK и Cast Debug Logger.

receiver.js

Этот скрипт управляет всей логикой нашего приложения-приемника. В настоящее время он содержит базовый CAF-приемник для инициализации контекста трансляции и загрузки видеофайла при инициализации. Также добавлены возможности отладочного логирования для передачи логов обратно в инструмент Cast and Command.

> Документация по Cast? > У нас есть подробная документация для приемника, а также для отправителей на iOS, Android и Chrome.

6. Добавьте VMAP в свой контент.

SDK Cast Web Receiver обеспечивает поддержку рекламы, заданной с помощью многоканальных списков воспроизведения цифрового видео (Digital Video Multiple Ad Playlists , VMAP). XML-структура определяет рекламные паузы медиафайла и связанные с ними метаданные клипов пауз. Для вставки такой рекламы SDK предоставляет свойство vmapAdsRequest в объекте MediaInformation .

В файле js/receiver.js создайте объект VastAdsRequest . Найдите функцию перехвата запроса LOAD и замените её следующим кодом. Он содержит пример URL-адреса тега VMAP из DoubleClick и предоставляет случайное значение коррелятора , чтобы гарантировать, что последующие запросы к тому же URL-адресу будут генерировать XML-шаблон с рекламными паузами, которые ещё не были просмотрены.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      const vmapUrl =
          'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
          Math.floor(Math.random() * Math.pow(10, 10));
      let vmapRequest = new cast.framework.messages.VastAdsRequest();
      vmapRequest.adTagUrl = vmapUrl;
      loadRequestData.media.vmapAdsRequest = vmapRequest;

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

Сохраните изменения в файле js/receiver.js и загрузите его на свой веб-сервер. Запустите сеанс Cast в инструменте Cast and Command , нажав на значок Cast . Должна начаться показ рекламы VMAP, после чего начнется основной контент.

7. Добавьте величия вашему контенту.

Как уже упоминалось, в SDK Web Receiver поддерживается множество типов рекламы. В этом разделе рассматриваются API, доступные для интеграции шаблонов цифровой видеорекламы (VAST). Если вы реализовали код VMAP из предыдущего раздела, закомментируйте его.

Скопируйте следующий код в файл js/receiver.js после перехватчика запроса загрузки. Он содержит шесть VAST-клипов для пауз из DoubleClick и случайное значение коррелятора . Эти клипы назначены на 5 пауз. position каждой паузы устанавливается в секундах относительно основного контента, включая паузы перед началом воспроизведения ( position установлена ​​на 0 ) и после воспроизведения ( position установлена ​​на -1 ).

const addVASTBreaksToMedia = (mediaInformation) => {
  mediaInformation.breakClips = [
    {
      id: 'bc1',
      title: 'bc1 (Pre-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('preroll')
      }
    },
    {
      id: 'bc2',
      title: 'bc2 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc3',
      title: 'bc3 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc4',
      title: 'bc4 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc5',
      title: 'bc5 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc6',
      title: 'bc6 (Post-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('postroll')
      }
    }
  ];

  mediaInformation.breaks = [
    {id: 'b1', breakClipIds: ['bc1'], position: 0},
    {id: 'b2', breakClipIds: ['bc2'], position: 15},
    {id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
    {id: 'b4', breakClipIds: ['bc5'], position: 100},
    {id: 'b5', breakClipIds: ['bc6'], position: -1}
  ];
};

Примечание: Свойство breakClipIds элемента break представляет собой массив, что означает, что каждому элементу break можно назначить несколько клипов.

В js/receiver.js file найдите перехватчик сообщений LOAD и замените его следующим кодом. Обратите внимание, что работа с VMAP закомментирована для демонстрации рекламы типа VAST.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      // const vmapUrl =
      //     'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
      //     Math.floor(Math.random() * Math.pow(10, 10));
      // let vmapRequest = new cast.framework.messages.VastAdsRequest();
      // vmapRequest.adTagUrl = vmapUrl;
      // loadRequestData.media.vmapAdsRequest = vmapRequest;

      // Append VAST ad breaks to the MediaInformation.
      addVASTBreaksToMedia(loadRequestData.media);

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

Сохраните изменения в файле js/receiver.js и загрузите его на свой веб-сервер. Запустите сеанс Cast в инструменте Cast and Command , нажав на значок Cast . Должна начаться показ рекламы VAST, после чего начнется основной контент.

8. Пропуск рекламной паузы

В CAF есть класс BreakManager , который помогает реализовать пользовательские бизнес-правила для поведения рекламы. Одна из таких функций позволяет приложениям программно пропускать рекламные паузы и фрагменты рекламы на основе определенного условия. В этом примере показано, как пропустить рекламную паузу, позиция которой находится в пределах первых 30 секунд контента, но не паузы после показа . При использовании VAST-рекламы, настроенной в предыдущем разделе, определены 5 пауз: 1 пре-ролл, 3 мид-ролла (на 15, 60 и 100 секундах) и, наконец, один пост-ролл. После выполнения этих шагов пропускаются только пре-ролл и мид-ролл, позиция которых находится на 15 секунде.

Для этого приложению следует вызвать API, доступные через BreakManager , чтобы установить перехватчик для загрузки прерывания. Скопируйте следующую строку в файл js/receiver.js после строк, содержащих переменные context и playerManager , чтобы получить ссылку на экземпляр.

const breakManager = playerManager.getBreakManager();

Приложение должно настроить перехватчик с правилом игнорирования любых рекламных пауз, происходящих до 30 секунд, при этом учитывая любые паузы после показа (поскольку их значения position равны -1 ). Этот перехватчик работает аналогично перехватчику LOAD в PlayerManager , за исключением того, что он предназначен специально для загрузки рекламных клипов. Установите его после перехватчика запроса LOAD и перед объявлением функции addVASTBreaksToMedia .

Скопируйте следующий код в файл js/receiver.js .

breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
  /**
   * The code will skip playback of break clips if the break position is within
   * the first 30 seconds.
   */
  let breakObj = breakContext.break;
  if (breakObj.position >= 0 && breakObj.position < 30) {
    castDebugLogger.debug(
        'MyAPP.LOG',
        'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
    return null;
  } else {
    return breakClip;
  }
});

Примечание: Возврат значения null в данном случае пропускает обрабатываемый BreakClip . Если для Break не определены клипы прерывания, сам Break пропускается.

Сохраните изменения в файле js/receiver.js и загрузите его на свой веб-сервер. Запустите сессию Cast в инструменте Cast and Command , нажав на значок Cast . Должна быть обработана реклама VAST. Обратите внимание, что пре-ролл и первый мид-ролл ( position 15 секунде) не воспроизводятся.

9. Настройка поведения поиска с перерывами

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

Для настройки того, какие паузы воспроизводятся при перемотке, SDK Cast предоставляет API setBreakSeekInterceptor в BreakManager . Когда приложение предоставляет свою пользовательскую логику через этот API, SDK вызывает его всякий раз, когда выполняется операция перемотки через одну или несколько пауз. В функцию обратного вызова передается объект, содержащий все паузы между позицией seekFrom и позицией seekTo . Затем приложению необходимо изменить и вернуть объект BreakSeekData .

Чтобы продемонстрировать его использование, в приведенном ниже примере поведение по умолчанию изменено: воспроизводятся все перехваченные фрагменты, и проигрывается только первый из них, появившийся на временной шкале.

Скопируйте следующий код в файл js/receiver.js в раздел определения метода setBreakClipLoadInterceptor .

breakManager.setBreakSeekInterceptor((breakSeekData) => {
  /**
   * The code will play an unwatched break between the seekFrom and seekTo
   * position. Note: If the position of a break is less than 30 then it will be
   * skipped due to the setBreakClipLoadInterceptor code.
   */
  castDebugLogger.debug(
      'MyAPP.LOG',
      'Break Seek Interceptor processing break ids ' +
          JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));

  // Remove all other breaks except for the first one.
  breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
  return breakSeekData;
});

Примечание: Если функция не возвращает значение или возвращает null , прерывания не выполняются.

Сохраните изменения в файле js/receiver.js и загрузите его на свой веб-сервер. Запустите сессию Cast в инструменте Cast and Command , нажав на значок Cast . Должна быть обработана реклама VAST. Обратите внимание, что пре-ролл и первый мид-ролл ( position 15 секунде) не воспроизводятся.

Дождитесь, пока время воспроизведения достигнет 30 секунд, чтобы обойти все паузы, пропущенные перехватчиком загрузки фрагментов пауз. После достижения этой отметки отправьте команду перемотки, перейдя на вкладку «Управление мультимедиа» . Установите значение поля «Перемотка в мультимедиа» равным 300 секундам и нажмите кнопку «В» . Обратите внимание на сообщения в журнале, выводимые перехватчиком перемотки пауз. Теперь поведение по умолчанию должно быть изменено, чтобы воспроизведение паузы происходило ближе ко времени seekFrom .

10. Поздравляем!

Теперь вы знаете, как добавлять рекламу в ваше приложение-приемник, используя последнюю версию SDK Cast Receiver.

Более подробную информацию см. в Руководстве разработчика по рекламным паузам .

> Хотите узнать больше о Cast? > Ознакомьтесь с другими примерами кода Cast и нашими приложениями на GitHub .