1. Opis
Z tego ćwiczenia z programowania dowiesz się, jak utworzyć aplikację niestandardowego odbiornika internetowego, która korzysta z interfejsu Cast Ad Breaks API.
Co to jest Google Cast?
Google Cast pozwala użytkownikom przesyłać 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 SDK Google Cast pozwala rozszerzyć aplikację o sterowanie telewizorem lub systemem audio. Pakiet SDK Cast pozwala dodać niezbędne komponenty interfejsu zgodnie z listą kontrolną projektowania Google Cast.
Opracowaliśmy listę kontrolną projektowania Google Cast, by ustandaryzować implementacje przesyłania i sprawiać, że korzystanie z aplikacji na wszystkich obsługiwanych platformach jest intuicyjne.
Co będziemy tworzyć?
Po ukończeniu tego ćwiczenia z programowania utworzysz odbiornik przesyłania, który będzie wykorzystywać interfejs Break API.
Czego się nauczysz
- Jak uwzględniać przerwy VMAP i VAST w treści przy przesyłaniu
- Jak pomijać klipy przerwania
- Dostosowywanie domyślnego zachowania przerwy przy wyszukiwaniu
Czego potrzebujesz
- najnowszą przeglądarkę Google Chrome,
- usługa hostingu HTTPS, na przykład Firebase Hosting lub ngrok;
- Urządzenie przesyłające Google Cast, takie jak Chromecast czy Android TV, z dostępem do internetu.
- telewizor lub monitor z wejściem HDMI albo Google Home Hub;
Funkcja
Zanim przejdziesz dalej w ramach tego ćwiczenia z programowania, upewnij się, że spełniasz wymienione niżej warunki.
- Ogólna wiedza o tworzeniu stron internetowych.
- Tworzenie aplikacji odbiornika internetowego Cast
Jak będziesz korzystać z tego samouczka?
Jak oceniasz swoje doświadczenia z tworzeniem aplikacji internetowych?
2. Pobieranie przykładowego kodu
Pobierz cały przykładowy kod na komputer...
i rozpakuj pobrany plik ZIP.
3. Wdrażanie odbiornika lokalnie
Aby można było używać 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ż serwer obsługujący https, pomiń poniższe instrukcje i zanotuj adres URL, ponieważ będzie on potrzebny w następnej sekcji.
Jeśli nie masz serwera, którego można użyć, możesz użyć Hostingu Firebase lub ngrok.
Uruchamianie serwera
Po skonfigurowaniu wybranej usługi przejdź do app-start i uruchom serwer.
Zanotuj adres URL hostowanego odbiornika. Użyjesz go w następnej sekcji.
4. Rejestrowanie aplikacji w Konsoli programisty Cast
Aby móc uruchamiać niestandardowy odbiornik (wbudowany w te ćwiczenia z programowania) na urządzeniach Chromecast, musisz zarejestrować swoją aplikację. Po zarejestrowaniu aplikacji zostanie wygenerowany identyfikator aplikacji nadawcy, który musi zostać skonfigurowany pod kątem uruchamiania aplikacji Web Received.
Kliknij „Dodaj nową aplikację”
Wybierz „Odbiornik niestandardowy”. To właśnie nad tym pracujemy.
Wpisz dane nowego odbiornika. Pamiętaj, aby użyć adresu URL wskazującego miejsce, w którym zamierzasz hostować aplikację Web pickupa. Zanotuj identyfikator aplikacji wygenerowany przez konsolę po zarejestrowaniu aplikacji. W późniejszej sekcji aplikacja nadawcy zostanie skonfigurowana do używania tego identyfikatora.
Musisz też zarejestrować urządzenie Google Cast, by miało dostęp do aplikacji odbiorcy przed jej opublikowaniem. Po opublikowaniu aplikacji odbierającej będzie ona dostępna dla wszystkich urządzeń Google Cast. Na potrzeby tych ćwiczeń z programowania zalecamy pracę z nieopublikowaną aplikacją odbierającą.
Kliknij „Dodaj nowe urządzenie”.
Wpisz numer seryjny wydrukowany z tyłu urządzenia Cast i nadaj mu opisową nazwę. Numer seryjny możesz też znaleźć, przesyłając ekran w Chrome, gdy otworzysz Google Cast SDK Developer Console.
Przygotowanie odbiornika i urządzenia do testowania może potrwać 5–15 minut. Po 5–15 minutach musisz zrestartować urządzenie przesyłające.
5. Przygotuj projekt początkowy
Przed rozpoczęciem tego ćwiczenia z programowania 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 niektóre z terminologii związanej z Google Cast, które zostały użyte w tym ćwiczeniu z programowania:
- aplikacja nadawca działa na urządzeniu mobilnym lub laptopie,
- aplikacja odbiornika działa na urządzeniu Google Cast;
Możesz teraz zacząć pracować nad projektem początkowym za pomocą ulubionego edytora tekstu:
- Wybierz katalog
app-startz pobranego przykładowego kodu. - Otwórz plik
js/receiver.jsi index.html
Zwróć uwagę, że w trakcie tych ćwiczeń z programowania wybrane przez Ciebie rozwiązanie hostingu WWW powinno być aktualizowane o wprowadzone zmiany. W trakcie ich weryfikacji i testowania upewnij się, że wprowadzasz zmiany do witryny hosta.
Projektowanie aplikacji
Jak już wspomnieliśmy, ćwiczenia z programowania wykorzystują aplikację nadawcy do zainicjowania sesji przesyłania oraz aplikację odbierającą, która zostanie zmodyfikowana pod kątem interfejsów API przerwy na reklamę.
W tym ćwiczeniu z programowania Cast and Command Tool będzie działać jako Web Sender, aby uruchomić aplikację odbiorcy. Aby rozpocząć, otwórz narzędzie w przeglądarce Chrome. Wpisz Identyfikator aplikacji odbiorcy podany w konsoli programisty Cast SDK i kliknij Ustaw, aby skonfigurować aplikację nadawcy do testowania.
Uwaga: jeśli ikona przesyłania się nie pojawia, sprawdź, czy odbiornik internetowy i urządzenia przesyłające są prawidłowo zarejestrowane w Konsoli programisty Cast. Wyłącz i wyłącz ponownie wszystkie zarejestrowane urządzenia przesyłające.
W tym ćwiczeniu z programowania skupiamy się na aplikacji odbierającej. Składa się ona z 1 widoku głównego zdefiniowanego w index.html oraz 1 pliku JavaScript o nazwie js/receiver.js. Poniżej omawiamy dokładniej te kwestie.
index.html
Ten plik HTML zawiera interfejs aplikacji odbierającej, który jest dostarczany przez element cast-media-player. Wczytuje też biblioteki CAF SDK i biblioteki Cast Debug Logger.
receiver.js
Ten skrypt zarządza całą logiką naszej aplikacji odbierającej. Obecnie zawiera podstawowy odbiornik CAF, który inicjuje kontekst przesyłania i wczytuje zasób wideo przy zainicjowaniu. Dodaliśmy też funkcje rejestratora debugowania, które umożliwiają ponowne rejestrowanie w narzędziu Cast i polecenie.
6. Dodawanie VMAP do treści
Pakiet Cast Web pickupr SDK obsługuje reklamy określane za pomocą playlist w postaci wielu reklam cyfrowych wideo, nazywanych też VMAP. Struktura XML określa przerwy na reklamę w multimediach i powiązane z nimi metadane klipu przerwy na reklamę. Aby można było wstawić te reklamy, pakiet SDK udostępnia w obiekcie MediaInformation właściwość vmapAdsRequest.
W pliku js/receiver.js utwórz obiekt VastAdsRequest. Znajdź funkcję przechwytujący żądania LOAD i zastąp ją poniższym kodem. Zawiera on przykładowy adres URL tagu VMAP z DoubleClick i losową wartość correlator, dzięki czemu kolejne żądania wysyłane na ten sam adres URL generują 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 usłudze js/receiver.js i prześlij plik na swój serwer WWW. Zainicjuj sesję przesyłania w narzędziu Cast i polecenia, klikając ikonę przesyłania. Powinno się wyświetlić reklamy VMAP, a po nich główna treść.
7. Dodaj VAST do swoich treści
Jak już wspomnieliśmy, pakiet Web pickupr SDK obsługuje wiele typów reklam. W tej sekcji opisujemy interfejsy API, które pozwalają integrować reklamy VAST z szablonem wyświetlania cyfrowych reklam wideo. Jeśli masz zaimplementowany kod VMAP z poprzedniej sekcji, skomentuj go.
Skopiuj kod podany poniżej do pliku js/receiver.js po przechwyciejącym żądania wczytania. Zawiera 6 klipów przerwy VAST z DoubleClick i losową wartość correlator. Te klipy są przypisane do 5 przerw. Element position każdej przerwy jest ustawiony na czas wyrażony w sekundach względem treści głównej, łącznie z reklamami przed filmem (position w ustawieniu 0) i po filmie (position 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 to tablica, co oznacza, że do każdego przerwy można przypisać wiele klipów przerwania.
W js/receiver.js file znajdź moduł przechwytującego komunikaty wczytywania i zastąp go poniższym kodem. Pamiętaj, że VMAP jest komentowany, aby 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. Zainicjuj sesję przesyłania w narzędziu Cast i polecenia, klikając ikonę przesyłania. Powinno się wyświetlić reklamy VAST, a po nich główna treść.
8. Pominięcie przerwy na reklamę
CAF ma klasę o nazwie BreakManager, która pomaga we wdrażaniu niestandardowych reguł biznesowych dotyczących zachowania reklam. Jedna z tych funkcji pozwala aplikacjom automatycznie pomijać przerwy i dzielić klipy w zależności od określonych warunków. Z tego przykładu dowiesz się, jak pominąć przerwę na reklamę, której pozycja znajduje się w pierwszych 30 sekundach treści, ale nie reklama po filmie. W przypadku reklam VAST skonfigurowanych w poprzedniej sekcji definiuje się 5 przerw: 1 przerwa przed filmem, 3 przerwy na reklamy w trakcie filmu (15, 60 i 100 sekund) oraz 1 przerwa po filmie. Po wykonaniu tych czynności pomijane są tylko reklamy przed filmem i reklamy w trakcie filmu o pozycji 15 sekund.
W tym celu aplikacja powinna wywoływać interfejsy API dostępne w BreakManager w celu ustawienia obiektu przechwytującego na potrzeby ładowania przerw. Skopiuj poniższy wiersz do pliku js/receiver.js za wierszami zawierającymi 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 reklamę występujących przed 30 sekundami filmu, pamiętając o wszelkich przerwach po filmie (ich wartości position to -1). Ten element przechwytujący działa jak element przechwytujący LOAD w elemencie PlayerManager, z wyjątkiem tej, która dotyczy ładowania klipów przerwy na reklamę. Ustaw tę wartość za obiektem przechwytującym żądanie LOAD i przed deklaracją funkcji addVASTBreaksToMedia.
Skopiuj kod podany poniżej 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 w tym miejscu elementu null spowoduje pominięcie przetwarzania elementu BreakClip. Jeśli Break nie ma zdefiniowanych żadnych klipów, sama przerwa jest pomijana.
Zapisz zmiany w usłudze js/receiver.js i prześlij plik na swój serwer WWW. Zainicjuj sesję przesyłania w narzędziu Cast i polecenia, klikając ikonę przesyłania. Reklamy VAST powinny zostać przetworzone. Pamiętaj, że reklamy przed filmem i pierwsza reklama w trakcie filmu (której position trwa 15 sekund) nie są odtwarzane.
9. Dostosuj sposób wyszukiwania przerwy
Podczas wyszukiwania wcześniejszych przerw w działaniu domyślna implementacja uzyskuje wszystkie elementy Break, których pozycje znajdują się między wartościami seekFrom i seekTo operacji wyszukiwania. Z tej listy przerw pakiet SDK odtwarza element Break, którego position jest najbliższy wartości seekTo, a jego właściwość isWatched jest ustawiona na false. Właściwość isWatched tej przerwy zostanie ustawiona na true, a odtwarzacz rozpoczyna odtwarzanie jej klipów. Po obejrzeniu przerwy główny film zostanie wznowiony od pozycji seekTo. Jeśli przerwa nie występuje, nie jest odtwarzana żadna przerwa, a główna treść jest wznawiana od pozycji seekTo.
Aby określić, które przerwy są odtwarzane w wyniku wyszukiwania, pakiet SDK Cast udostępnia w BreakManager interfejs API setBreakSeekInterceptor API. Gdy aplikacja udostępnia własną logikę za pomocą tego interfejsu API, pakiet SDK wywołuje ją za każdym razem, gdy operacja wyszukiwania jest wykonywana w co najmniej 1 przerwach. Funkcja wywołania zwrotnego jest przekazywana obiektowi zawierający wszystkie przerwy między pozycją seekFrom a pozycją seekTo. Aplikacja musi następnie zmodyfikować i zwrócić BreakSeekData.
Aby pokazać jego użycie, poniższa próbka zastępuje działanie domyślne, uwzględniając wszystkie przeszukane przerwy i odtwarzając tylko pierwszą, która pojawi się na osi czasu.
Skopiuj podany niżej kod do pliku js/receiver.js z 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 zwróci wartości lub zwróci null, przerwy nie będą odtwarzane.
Zapisz zmiany w usłudze js/receiver.js i prześlij plik na swój serwer WWW. Zainicjuj sesję przesyłania w narzędziu Cast i polecenia, klikając ikonę przesyłania. Reklamy VAST powinny zostać przetworzone. Pamiętaj, że reklamy przed filmem i pierwsza reklama w trakcie filmu (której position trwa 15 sekund) nie są odtwarzane.
Poczekaj, aż czas odtwarzania osiągnie 30 sekund, aby pominąć wszystkie przerwy pominięte przez moduł przechwytujący załadowanie klipu przerwania. Następnie wyślij polecenie przewijania na karcie Sterowanie multimediami. W polu Seek Into Media (Przejdź do multimediów) wpisz 300 s i kliknij przycisk TO. Zwróć uwagę na dzienniki wydrukowane w module przechwytującego przerwę. Domyślne zachowanie powinno zostać zastąpione, aby można było odtworzyć przerwę bliżej czasu seekFrom.
10. Gratulacje
Wiesz już, jak dodawać reklamy do aplikacji odbierającej za pomocą najnowszego pakietu SDK Cast pickupr SDK.
Więcej informacji znajdziesz w przewodniku dla deweloperów dotyczącym przerw na reklamy.