1. Omówienie
W tym ćwiczeniu z programowania opisujemy, jak utworzyć aplikację internetową niestandardowego odbiornika, 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. Użytkownicy mogą wtedy używać urządzenia mobilnego jako pilota do odtwarzania multimediów na telewizorze.
Pakiet SDK Google Cast umożliwia rozszerzenie aplikacji o możliwość sterowania telewizorem lub systemem dźwiękowym. Pakiet SDK Cast umożliwia dodawanie niezbędnych komponentów interfejsu użytkownika na podstawie listy kontrolnej interfejsu Google Cast.
Lista kontrolna dotycząca projektu Google Cast została przygotowana w celu ujednolicenia implementacji Cast i uczynienia interfejsu użytkownika bardziej intuicyjnym na wszystkich obsługiwanych platformach.
Co będziemy budować?
Po zakończeniu tego ćwiczenia z programowania będziesz mieć gotowy odbiornik Cast, który korzysta z interfejsu Break API.
Czego się nauczysz
- Jak uwzględnić przerwy VMAP i VAST w treściach przesyłanych na urządzenie Cast
- Jak pomijać klipy z przerwami
- Jak dostosować domyślne zachowanie przerwy podczas przewijania
Czego potrzebujesz
- Najnowsza przeglądarka Google Chrome
- usługa hostingowa HTTPS, np. Hosting Firebase lub ngrok.
- Urządzenie Google Cast, takie jak Chromecast lub Android TV skonfigurowane z dostępem do internetu.
- telewizor lub monitor z wejściem HDMI albo urządzenie Google Home Hub.
Doświadczenie
Zanim przejdziesz dalej, sprawdź, czy masz:
- Ogólna wiedza na temat tworzenia stron internetowych.
- Tworzenie aplikacji odbiornika internetowego przesyłania.
Jak będziesz korzystać z tego samouczka?
Jak oceniasz tworzenie aplikacji internetowych?
2. Pobieranie przykładowego kodu
Pobierz cały przykładowy kod na swój komputer...
i rozpakuj pobrany plik ZIP.
3. Wdrażanie odbiornika lokalnie
Aby można było używać odbiornika internetowego z urządzeniem Google Cast, musi on być hostowany w miejscu, do którego może dotrzeć urządzenie Google Cast. Jeśli masz już serwer, który obsługuje protokół https, pomiń te instrukcje i zapisz adres URL, ponieważ będzie Ci on potrzebny w następnej sekcji.
Jeśli nie masz serwera, możesz użyć hostingu Firebase lub ngrok.
Uruchamianie serwera
Po skonfigurowaniu wybranej usługi przejdź do app-start i uruchom serwer.
Zapisz adres URL hostowanego odbiornika. Wykorzystasz go w następnej sekcji.
4. Rejestrowanie aplikacji w Konsoli programisty Cast
Aby móc uruchamiać niestandardowy odbiornik na urządzeniach Chromecast, musisz zarejestrować aplikację. Po zarejestrowaniu aplikacji zostanie wygenerowany identyfikator aplikacji, który musi być skonfigurowany w aplikacji nadawczej, aby można było uruchomić aplikację odbiornika internetowego.
Kliknij „Dodaj nową aplikację”.
Wybierz „Custom Receiver” (Niestandardowy odbiornik), który właśnie tworzymy.
Wpisz szczegóły nowego odbiorcy. Używaj adresu URL wskazującego na miejsce, w którym planujesz hostować aplikację Web Receiver. Zanotuj identyfikator aplikacji wygenerowany przez konsolę po zarejestrowaniu aplikacji. Aplikacja nadawcy zostanie skonfigurowana do używania tego identyfikatora w później sekcji.
Musisz też zarejestrować urządzenie Google Cast, aby mogło uzyskać dostęp do aplikacji odbiorczej przed jej opublikowaniem. Po opublikowaniu aplikacji odbiorczej będzie ona dostępna na wszystkich urządzeniach Google Cast. Na potrzeby tego ćwiczenia zalecamy korzystanie z nieopublikowanej aplikacji odbiorczej.
Kliknij „Dodaj nowe urządzenie”.
Wpisz numer seryjny wydrukowany z tyłu urządzenia Cast i nadaj mu nazwę. Numer seryjny możesz też znaleźć, przesyłając ekran w Chrome, gdy otwierasz konsolę dewelopera Google Cast SDK.
Przygotowanie odbiornika i urządzenia do testowania może zająć 5–15 minut. Po odczekaniu 5–15 minut musisz zrestartować urządzenie przesyłające.
5. Przygotowywanie projektu początkowego
Zanim zaczniesz korzystać z tego ćwiczenia, warto zapoznać się z przewodnikiem dla programistów dotyczącym reklam, który zawiera omówienie interfejsów API przerw na reklamę.
Do pobranej aplikacji startowej musisz dodać obsługę Google Cast. Poniżej znajdziesz terminologię używaną w tym ćwiczeniu z programowania w Google Cast:
- aplikacja nadawcy działa na urządzeniu mobilnym lub laptopie,
- na urządzeniu Google Cast działa aplikacja odbiornikowa.
Teraz możesz rozszerzyć projekt startowy za pomocą ulubionego edytora tekstu:
- Wybierz katalog
app-startz pobranego przykładowego kodu. - Otwórz
js/receiver.jsi index.html
Podczas pracy z tym laboratorium kodu należy zaktualizować wybrane rozwiązanie hostingu internetowego, uwzględniając wprowadzone zmiany. Pamiętaj o przekazywaniu zmian do witryny hostującej podczas ich sprawdzania i testowania.
Projektowanie aplikacji
Jak już wspomnieliśmy, w tym samouczku wykorzystujemy aplikację nadawczą do inicjowania sesji przesyłania i aplikację odbiorczą, która zostanie zmodyfikowana, aby korzystać z interfejsów reklamowych.
W tym ćwiczeniu narzędzie Cast and Command będzie pełnić rolę nadawcy internetowego, aby uruchomić aplikację odbiorczą. Aby rozpocząć, otwórz to narzędzie w przeglądarce Chrome. Wpisz identyfikator aplikacji odbiorczej podany w Konsoli programisty pakietu SDK Cast i kliknij Ustaw, aby skonfigurować aplikację nadawczą na potrzeby testów.
Uwaga: jeśli ikona przesyłania nie pojawia się, sprawdź, czy odbiornik internetowy i urządzenia do przesyłania są prawidłowo zarejestrowane w Konsoli dewelopera Google Cast. Jeśli jeszcze tego nie zrobiono, wyłącz i ponownie włącz wszystkie urządzenia Cast, które zostały właśnie zarejestrowane.
Aplikacja odbiornika jest głównym tematem tego Codelab. Składa się z 1 widoku głównego zdefiniowanego w index.html i 1 pliku JavaScript o nazwie js/receiver.js. Opis tych funkcji znajdziesz 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ą aplikacji odbiorczej. Obecnie zawiera on podstawowy odbiornik CAF, który inicjuje kontekst przesyłania i wczytuje zasób wideo po inicjalizacji. Dodaliśmy też niektóre funkcje dziennikowania debugowania, aby umożliwić logowanie w narzędziu Cast and Command.
6. Dodawanie VMAP do treści
Pakiet SDK odbiornika internetowego Cast obsługuje reklamy określone za pomocą list odtwarzania reklam wideo, czyli VMAP. Struktura XML określa przerwy na reklamę w multimediach i powiązane z nimi metadane klipów. Aby wstawić te reklamy, pakiet SDK udostępnia właściwość vmapAdsRequest w obiekcie MediaInformation.
W pliku js/receiver.js utwórz obiekt VastAdsRequest. Odszukaj funkcję LOAD request interceptor i zastąp ją podanym niżej kodem. Zawiera on przykładowy adres URL tagu VMAP z DoubleClicka i losową wartość korelatora, aby kolejne żądania tego samego adresu URL generowały szablon XML z przerwami na reklamę, 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 pliku js/receiver.js i prześlij go na serwer WWW. Aby rozpocząć sesję przesyłania w Narzędziu przesyłania i sterowania, kliknij ikonę przesyłania. Reklamy VMAP powinny się wyświetlić, a potem główna treść.
7. Dodawanie pliku VAST do treści
Jak już wspomnieliśmy, pakiet SDK Web Receiver obsługuje wiele typów reklam. W tej sekcji omówiliśmy interfejsy API umożliwiające integrację reklam szablonu wyświetlania reklam wideo (VAST). Jeśli masz zaimplementowany kod VMAP z poprzedniej sekcji, umieść go w komentarzu.
Skopiuj podany poniżej kod do pliku js/receiver.js po intercepcie żądania wczytania. Zawiera sześć klipów VAST oznaczających przerwę z DoubleClick i losową wartość correlator. Te klipy reklamowe przerw są przypisane do 5 przerwy. Dla każdej przerwy position ustawiono czas w sekundach w odniesieniu do głównej treści, w tym przerwy przed filmem (position ustawiona na 0) i przerwy po filmie (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żdej przerwy można przypisać wiele klipów przerwy.
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 pliku js/receiver.js i prześlij go na serwer WWW. Aby rozpocząć sesję przesyłania w narzędziu Cast and Command Tool, kliknij ikonę Cast. Reklamy VAST powinny się odtwarzać, a potem powinna pojawić się główna treść.
8. Pomijanie przerw na reklamę
CAF zawiera klasę o nazwie BreakManager, która pomaga w wdrażaniu niestandardowych zasad biznesowych dotyczących zachowań reklam. Jedna z nich pozwala aplikacjom na automatyczne pomijanie przerw i przerwanych klipów na podstawie określonych warunków. Ten przykład pokazuje, jak pominąć przerwę na reklamę, która pojawia się w pierwszych 30 sekundach filmu, ale nie w przerwie po filmie. W przypadku reklam VAST skonfigurowanych w poprzedniej sekcji zdefiniowano 5 przerwy: 1 przed filmem, 3 w trakcie filmu (w 15, 60 i 100 sekundach) oraz 1 po filmie. Po wykonaniu tych czynności pomijane są tylko te reklamy przed filmem i reklamy w trakcie filmu, których pozycja wynosi 15 sekund.
W tym celu aplikacja powinna wywoływać interfejsy API dostępne przez BreakManager, aby ustawić przechwytywanie w celu przerwania wczytywania. 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ć przechwytujący z regułą ignorowania przerw na reklamy, które występują przed 30 sekundami, z uwzględnieniem przerw po filmie (ich wartości position to -1). Ten przechwytujący działa jak przechwytujący LOAD w PlayerManager, z tą różnicą, że jest przeznaczony do przechwytywania klipów przerw na reklamy. Ustaw to po przechwytującym żądaniu LOAD i przed deklaracją funkcji addVASTBreaksToMedia.
Skopiuj podany poniżej 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: zwrócenie wartości null spowoduje pominięcie elementu BreakClip. Jeśli w Break nie ma zdefiniowanych klipów przerwy, 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 przesyłania i sterowania, kliknij ikonę przesyłania. Reklamy VAST powinny zostać przetworzone. Pamiętaj, że reklamy przed filmem i pierwsza reklama w trakcie filmu (której czas trwania position wynosi 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 Break, którego wartość position jest najbliższa wartości seekTo, a właściwość isWatched ma wartość false. Właściwość isWatched przerwy jest ustawiana na true, a odtwarzacz rozpoczyna odtwarzanie klipów. Gdy przerwa się skończy, odtwarzanie głównej treści zostanie wznowione od pozycji seekTo. Jeśli nie ma takiego przerwania, nie jest ono odtwarzane, a główna treść wznawia odtwarzanie w 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 logikę niestandardową za pomocą tego interfejsu API, pakiet SDK wywołuje ją za każdym razem, gdy operacja przesunięcia jest wykonywana w przypadku co najmniej 1 przerwy. Do funkcji wywołania zwrotnego jest przekazywany obiekt zawierający wszystkie przerwy między pozycją seekFrom a pozycją seekTo. Aplikacja musi wtedy zmodyfikować i zwrócić wartość BreakSeekData.
Aby pokazać sposób jego użycia, w tym przykładzie zastąpiono domyślne zachowanie, pomijając wszystkie przerwy, które zostały przewinięte, i odtworzono tylko pierwszą z nich, która pojawia się na osi czasu.
Skopiuj ten kod do pliku js/receiver.js pod definicją 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 przesyłania i sterowania, kliknij ikonę przesyłania. 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 to zrobisz, wyślij polecenie przesunięcia, przechodząc na kartę Sterowanie multimediami. W polu Seek Into Media (Przejdź do środka pliku multimedialnego) wpisz 300 s i kliknij przycisk TO (DO). Zapisz logi wydrukowane w Break Seek Interceptor. Działanie domyślne powinno teraz zostać zastąpione, aby przerwa była odtwarzana 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.