Dodanie obsługi interfejsu API przerw na reklamy do odbiornika internetowego

1. Omówienie

Te ćwiczenia w Codelabs pokazują, jak utworzyć niestandardową aplikację odbiornika internetowego, która korzysta z interfejsu Cast Ad Breaks API.

Co to jest Google Cast?

Google Cast umożliwia użytkownikom przesyłanie treści z urządzenia mobilnego na telewizor. Dzięki temu użytkownicy mogą używać swoich urządzeń mobilnych jako pilota do odtwarzania multimediów na telewizorze.

Pakiet Google Cast SDK umożliwia rozszerzenie aplikacji o sterowanie telewizorem lub systemem audio. SDK Cast pozwala dodać niezbędne komponenty interfejsu zgodnie z listą kontrolną projektu Google Cast.

Lista kontrolna Google Cast ułatwia ustandaryzowanie implementacji Cast i umożliwia korzystanie z nich intuicyjnie na wszystkich obsługiwanych platformach.

Co utworzymy?

Po ukończeniu tego ćwiczenia w programowaniu będziesz mieć odbiornik Cast, który będzie korzystać z interfejsu Break API.

Czego się nauczysz

• Jak uwzględnić przerwy VMAP i VAST w treściach, aby przesyłać treści
• Jak pomijać klipy z przerwami
• Jak dostosować domyślne działanie przerw podczas przewijania

Czego potrzebujesz

• Najnowsza przeglądarka Google Chrome
• Usługa hostingu HTTPS, np. Hosting Firebase lub ngrok.
• Urządzenie przesyłające Google Cast, takie jak Chromecast lub Android TV, skonfigurowane z dostępem do internetu.
• Telewizor lub monitor z wejściem HDMI albo Google Home Hub.

Doświadczenie

Zanim przejdziesz do kolejnych ćwiczeń z programowania, upewnij się, że korzystasz z poniższego środowiska.

• Ogólna wiedza na temat tworzenia stron internetowych.
• Tworzę aplikacje Cast Web Receiver.

> Masz problemy z siecią? > Jeśli jesteś w miejscu, w którym sieć Wi-Fi nie jest pewna, możesz podłączyć Chromecasta przewodowo, korzystając z adaptera Ethernetu

Chromecasta lub Chromecasta z Google TV,

Jak wykorzystasz ten samouczek?

Tylko do przeczytania Przeczytaj go i wykonaj ćwiczenia

Jak oceniasz swoje doświadczenia z tworzeniem aplikacji internetowych?

Początkujący Poziom średnio zaawansowany Biegły

2. Pobieranie przykładowego kodu

Pobierz cały przykładowy kod na swój komputer...

Pobieranie kodu źródłowego

i rozpakuj pobrany plik ZIP.

> Repozytorium cast-videos-cast Codelab zawiera 2 przykładowe projekty: > * app-start – kod początkowy, który opracujesz w ramach tego ćwiczenia z programowania. * app-done – pełny kod gotowej przykładowej aplikacji wideo.

3. Wdróż lokalnie odbiornik

Aby można było korzystać z odbiornika internetowego z urządzeniem przesyłającym, musi on być hostowany w miejscu, w którym urządzenie przesyłające ma do niego dostęp. Jeśli masz już dostępny serwer obsługujący protokół https, pomiń poniższe instrukcje i zanotuj adres URL, ponieważ będzie on potrzebny w następnej sekcji.

Jeśli nie masz serwera do użycia, możesz skorzystać z Hostingu Firebase lub ngrok.

Uruchamianie serwera

Po skonfigurowaniu wybranej usługi przejdź do app-start i uruchom serwer.

Zanotuj adres URL hostowanego odbiornika. Wykorzystasz go w następnej sekcji.

4. Rejestrowanie aplikacji w konsoli programisty Cast

> Nie masz konta programisty Cast? > Załóż konto w konsoli programisty Google Cast SDK i zapłać opłatę rejestracyjną.

Aby na urządzeniach Chromecast uruchamiać niestandardowy odbiornik (wbudowany w tym ćwiczeniu w Codelabs), musisz zarejestrować swoją aplikację. Po zarejestrowaniu aplikacji zostanie wygenerowany identyfikator aplikacji. Musisz skonfigurować aplikację nadawcy, aby uruchomić aplikację odbiornika internetowego.

Kliknij „Dodaj nową aplikację”

Wybierz „Niestandardowy odbiornik”, czyli właśnie to tworzymy.

Wpisz dane nowego odbiornika. Pamiętaj, aby użyć adresu URL wskazującego miejsce, w którym planujesz hostować aplikację odbiornika internetowego. Zanotuj identyfikator aplikacji wygenerowany przez konsolę po zarejestrowaniu aplikacji. Aplikacja nadawcy zostanie skonfigurowana do używania tego identyfikatora w kolejnej sekcji.

Musisz też zarejestrować urządzenie Google Cast, by mogło ono uzyskiwać dostęp do aplikacji odbiornika przed jej opublikowaniem. Po opublikowaniu aplikacja odbiornika będzie dostępna dla wszystkich urządzeń Google Cast. Na potrzeby tego ćwiczenia z programowania zaleca się korzystanie z nieopublikowanej aplikacji odbierającej.

Kliknij „Dodaj nowe urządzenie”.

Wpisz numer seryjny wydrukowany z tyłu urządzenia przesyłającego i nadaj mu opisową nazwę. Numer seryjny możesz też znaleźć, przesyłając ekran w Chrome po otwarciu konsoli programisty Google Cast SDK.

Przygotowanie odbiornika i urządzenia do testów może potrwać 5–15 minut. Po odczekaniu 5–15 minut musisz zrestartować urządzenie przesyłające.

5. Przygotowywanie projektu początkowego

Przed rozpoczęciem tych ćwiczeń w programie warto zapoznać się z przewodnikiem dla programistów reklam, w którym znajdziesz omówienie interfejsów API przerw na reklamę.

Do pobranej aplikacji startowej musisz dodać obsługę Google Cast. Oto terminologia dotycząca Google Cast, której używasz w tym ćwiczeniu z programowania:

• aplikacja nadawca działa na urządzeniu mobilnym lub laptopie,
• aplikacja odbiornika na urządzeniu Google Cast).

Teraz możesz zacząć tworzyć projekt początkowy za pomocą ulubionego edytora tekstu:

1. Wybierz katalog app-start z pobranego przykładowego kodu.
2. Otwórz plik js/receiver.js i index.html

Uwaga: w miarę pracy z programem wybrane dla Ciebie rozwiązanie hostingowe powinno zostać zaktualizowane o wprowadzone zmiany. Pamiętaj o przekazywaniu zmian do witryny hosta podczas ich sprawdzania i testowania.

Projektowanie aplikacji

Jak już wspomnieliśmy, ćwiczenia w Codelabs korzystają z aplikacji nadawcy do zainicjowania sesji przesyłania oraz aplikacji odbierającej, która zostanie zmodyfikowana pod kątem korzystania z interfejsów API przerw na reklamę.

W ramach tego ćwiczenia w Codelabs narzędzie Cast and Command Tool będzie pełnić funkcję nadawcy internetowego, aby uruchomić aplikację odbierającą. Aby rozpocząć, otwórz narzędzie w przeglądarce Chrome. Wpisz identyfikator aplikacji odbiornika podany w konsoli programisty pakietu SDK Cast i kliknij Ustaw, aby skonfigurować aplikację wysyłającą do testowania.

Uwaga: jeśli ikona przesyłania się nie pojawia, upewnij się, że odbiornik internetowy i urządzenia przesyłające są prawidłowo zarejestrowane w konsoli programisty Cast. Wyłącz i ponownie włącz wszystkie zarejestrowane urządzenia przesyłające.

To ćwiczenie w Codelabs zawiera aplikację odbiornikową, która składa się z 1 widoku głównego zdefiniowanego w index.html i 1 pliku JavaScript o nazwie js/receiver.js. Zostały one opisane poniżej.

index.html

Ten plik HTML zawiera interfejs użytkownika aplikacji odbiornika dostarczanego przez element cast-media-player. Wczytuje też pakiet SDK CAF i biblioteki Cast Debug Logger.

receiver.js

Ten skrypt zarządza całą logiką naszej aplikacji odbiornika. Obecnie zawiera podstawowy odbiornik CAF, który inicjuje kontekst przesyłania i wczytuje zasób wideo przy inicjowaniu. Dodaliśmy też niektóre funkcje rejestrowania debugowania, które umożliwiają rejestrowanie danych z powrotem do narzędzia Cast i polecenia.

> Dokumentacja przesyłania? > Udostępniamy obszerną dokumentację dla nadawców oraz nadawców w systemach iOS i Android oraz w Chrome.

6. Dodawanie VMAP do treści

Pakiet Cast Web Receiver SDK zapewnia obsługę reklam określonych za pomocą cyfrowych playlist wideo z wieloma reklamami (nazywanych też VMAP). Struktura XML określa przerwy na reklamę w multimediach i powiązane z nimi metadane klipów. Aby można było wstawiać te reklamy, pakiet SDK udostępnia właściwość vmapAdsRequest w obiekcie MediaInformation.

W pliku js/receiver.js utwórz obiekt VastAdsRequest. Znajdź funkcję przechwytującego żądania LOAD i zastąp ją poniższym kodem. Zawiera on przykładowy adres URL tagu VMAP z usługi DoubleClick i podaje losową wartość parametru correlator, dzięki czemu kolejne żądania wysyłane do tego samego adresu URL generują szablon XML z przerwami na reklamy, które nie zostały jeszcze obejrzane.

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

Zapisz zmiany w usłudze js/receiver.js i prześlij plik na swój serwer WWW. Aby rozpocząć sesję przesyłania w narzędziu Cast and Command Tool, kliknij ikonę Cast. Reklamy VMAP powinny być odtwarzane, a po nich powinny wyświetlać się główne treści.

7. Dodawanie VAST do treści

Jak już wspomnieliśmy, pakiet Web Receiver SDK obsługuje wiele typów reklam. W tej sekcji opisujemy interfejsy API, które umożliwiają integrację reklam Digital Video Ad Serving Template, nazywane też VAST. Jeśli masz zaimplementowany kod VMAP z poprzedniej sekcji, umieść go w komentarzu.

Skopiuj poniższy kod do pliku js/receiver.js po przechwyceniu żądania wczytywania. Zawiera sześć klipów VAST oznaczających przerwę z DoubleClick i losową wartość correlator. Ten fragment jest przypisany do 5 przerw. Wartość position każdej przerwy jest ustawiona na czas w sekundach w stosunku do głównej treści, z uwzględnieniem reklam przed filmem (wartość position ustawiona na 0) i po filmie (wartość position ustawiona na -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}
  ];
};

Uwaga: właściwość breakClipIds przerwy jest tablicą, co oznacza, że do każdego przerwy można przypisać kilka klipów podziału.

W js/receiver.js file znajdź przechwytujący komunikat LOAD i zastąp go poniższym kodem. Pamiętaj, że treści VMAP są komentowane, aby można było wyświetlać reklamy typu 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;
    });

Zapisz zmiany w usłudze js/receiver.js i prześlij plik na swój serwer WWW. Aby rozpocząć sesję przesyłania w narzędziu Cast and Command Tool, kliknij ikonę Cast. Reklamy VAST powinny być odtwarzane, a po nich powinny wyświetlać się główne treści.

8. Pomijanie przerwy na reklamę

CAF ma klasę o nazwie BreakManager, która ułatwia wdrażanie niestandardowych reguł biznesowych dotyczących zachowania reklam. Jedna z tych funkcji umożliwia aplikacjom automatyczne pomijanie przerw i przerwanie klipów na podstawie pewnych warunków. W tym przykładzie pokazujemy, jak pominąć przerwę na reklamę, która znajduje się w pierwszych 30 sekundach treści, ale nie w przerwach po filmie. Jeśli używasz reklam VAST skonfigurowanych w poprzedniej sekcji, zdefiniowano 5 przerw: 1 przerwę przed filmem, 3 przerwy w trakcie filmu (15, 60 i 100 sekund) oraz 1 przerwa po filmie. Po wykonaniu tych czynności pomijane są tylko te reklamy przed filmem i w trakcie filmu, których pozycja wynosi 15 sekund.

W tym celu aplikacja powinna wywoływać interfejsy API dostępne w BreakManager, aby ustawić przechwytywanie ładowania przerwy. Skopiuj poniższy wiersz do pliku js/receiver.js, po wierszach zawierających zmienne context i playerManager, aby uzyskać odniesienie do instancji.

const breakManager = playerManager.getBreakManager();

Aplikacja powinna skonfigurować element przechwytujący z regułą ignorowania wszystkich przerw na reklamy występujących przed 30 sekundami, pamiętając przy tym o wszelkich przerwach po filmie (ponieważ ich wartości position wynoszą -1). Ten element przechwytujący działa jak element przechwytujący LOAD na PlayerManager, z tym że dotyczy wyłącznie wczytywania klipów z przerwami. Ustaw ją po elemencie przechwytującym żądania LOAD i przed deklaracją funkcji addVASTBreaksToMedia.

Skopiuj poniższy kod do pliku 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;
  }
});

Uwaga: powrót null w tym miejscu powoduje pominięcie przetwarzania BreakClip. Jeśli Break nie ma zdefiniowanych żadnych klipów w przerwie, sama przerwa zostanie pominięta.

Zapisz zmiany w usłudze js/receiver.js i prześlij plik na swój serwer WWW. Aby rozpocząć sesję przesyłania w narzędziu Cast and Command Tool, kliknij ikonę Cast. Reklamy VAST powinny zostać przetworzone. Pamiętaj, że reklama przed filmem i pierwsza reklama w trakcie filmu (o której position ma 15 sekund) nie są odtwarzane.

9. Dostosuj zachowanie przewijania w przerwie

W przypadku przewijania wcześniejszych przerw domyślna implementacja pobiera wszystkie elementy Break, których pozycja znajduje się między wartościami seekFrom i seekTo operacji wyszukiwania. Z tej listy przerw pakiet SDK odtwarza element Break, którego parametr position jest najbliższy wartości seekTo, a właściwość isWatched jest ustawiona na false. Właściwość isWatched przerwy jest ustawiana na true, a odtwarzacz rozpoczyna odtwarzanie klipów. Po obejrzeniu przerwy główna treść wznawia odtwarzanie od pozycji seekTo. Jeśli przerwa nie istnieje, przerwa nie jest odtwarzana i odtwarzanie głównej treści zostanie wznowione od pozycji seekTo.

Aby określić, które przerwy mają być odtwarzane w przypadku przewijania, pakiet SDK Cast udostępnia interfejs API setBreakSeekInterceptor w narzędziu BreakManager. Gdy aplikacja udostępnia niestandardową logikę za pomocą tego interfejsu API, pakiet SDK wywołuje ją za każdym razem, gdy wykonywana jest operacja przewijania w ramach jednej lub kilku przerw. Funkcja wywołania zwrotnego jest przekazywana do obiektu zawierającego wszystkie przerwy między pozycją seekFrom a pozycją seekTo. Aplikacja musi następnie zmodyfikować i zwrócić BreakSeekData.

Aby pokazać użycie tego narzędzia, przykład poniżej zastępuje działanie domyślne, przyjmując wszystkie przewijane przerwy i odtwarzając tylko pierwszą z nich, która pojawi się na osi czasu.

Skopiuj poniższy kod do pliku js/receiver.js pod definicją do pliku 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;
});

Uwaga: jeśli funkcja nie zwraca wartości lub zwraca null, przerwy nie są odtwarzane.

Zapisz zmiany w usłudze js/receiver.js i prześlij plik na swój serwer WWW. Aby rozpocząć sesję przesyłania w narzędziu Cast and Command Tool, kliknij ikonę Cast. Reklamy VAST powinny zostać przetworzone. Pamiętaj, że reklama przed filmem i pierwsza reklama w trakcie filmu (o której position ma 15 sekund) nie są odtwarzane.

Zaczekaj, aż czas odtwarzania upłynie 30 sekund, aby pominąć wszystkie przerwy, które są pomijane przez komponent przechwytujący wczytanie klipu z przerwami. Gdy będzie dostępne, wyślij polecenie przewijania na karcie Sterowanie multimediami. Wypełnij pole Seek Into Media (Wyszukaj multimedia) przez 300 s i kliknij przycisk TO (Do). Zwróć uwagę na logi wydrukowane w narzędziu Break Seek Interceptor. Domyślne działanie powinno być teraz zastąpione, aby można było odtworzyć przerwę bliżej czasu seekFrom.

10. Gratulacje

Wiesz już, jak dodawać reklamy do aplikacji odbiornika, korzystając z najnowszego pakietu SDK Cast Receiver.

Więcej informacji znajdziesz w przewodniku dla programistów dotyczącym przerw na reklamy.

> Chcesz dodać więcej funkcji Cast? > Zapoznaj się z innymi ćwiczeniami z programowania dotyczącymi przesyłania i naszymi przykładowymi aplikacjami na GitHubie.