1. Przegląd
W tym laboratorium dowiesz się, jak utworzyć niestandardową aplikację odbiornika internetowego, która korzysta z interfejsu Cast Ad Breaks API.
Co to jest Google Cast?
Google Cast umożliwia 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 Google Cast SDK umożliwia rozszerzenie aplikacji o możliwość sterowania telewizorem lub systemem dźwiękowym. Pakiet Cast SDK umożliwia dodawanie niezbędnych komponentów interfejsu na podstawie listy kontrolnej projektu Google Cast.
Lista kontrolna projektu Google Cast ma na celu ujednolicenie implementacji Cast, aby zapewnić użytkownikom intuicyjną obsługę na wszystkich obsługiwanych platformach.
Co będziemy tworzyć?
Po ukończeniu tego ćwiczenia z programowania będziesz mieć odbiornik Cast, który korzysta z interfejsu Break API.
Czego się nauczysz
- Jak uwzględniać w treściach przeznaczonych do przesyłania przerwy VMAP i VAST
- Jak pomijać klipy z przerwami
- Jak dostosować domyślne zachowanie przerw podczas przewijania
Czego potrzebujesz
- Najnowsza wersja przeglądarki Google Chrome.
- usługi hostingowej HTTPS, takiej jak Hosting Firebase lub ngrok;
- Urządzenie przesyłające, np. 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 dalej, upewnij się, że masz odpowiednie doświadczenie.
- Ogólna wiedza na temat tworzenia stron internetowych.
- tworzyć aplikacje odbiornika internetowego Cast;
Jak zamierzasz korzystać z tego samouczka?
Jak oceniasz swoje doświadczenie w tworzeniu 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, do którego urządzenie przesyłające ma dostęp. Jeśli masz już serwer obsługujący protokół HTTPS, pomiń poniższe instrukcje i zanotuj adres URL, ponieważ będzie Ci potrzebny w następnej sekcji.
Jeśli nie masz serwera, którego możesz użyć, możesz skorzystać z Hostingu Firebase lub ngrok.
Uruchamianie serwera
Po skonfigurowaniu wybranej usługi otwórz app-start i uruchom serwer.
Zanotuj adres URL hostowanego odbiornika. Będzie on potrzebny w następnej sekcji.
4. Rejestrowanie aplikacji w Konsoli programisty Cast
Aby móc uruchamiać na urządzeniach Chromecast niestandardowy odbiornik, taki jak w tym ćwiczeniu, musisz zarejestrować aplikację. Po zarejestrowaniu aplikacji zostanie wygenerowany identyfikator aplikacji, który musi być skonfigurowany w aplikacji wysyłającej, aby można było uruchomić aplikację odbiornika internetowego.
Kliknij „Dodaj nową aplikację”.
Wybierz „Custom Receiver” (Odbiornik niestandardowy) – to właśnie tworzymy.
Wpisz dane nowego odbiorcy. Użyj adresu URL wskazującego miejsce, w którym planujesz hostować aplikację Web Receiver. Zapisz identyfikator aplikacji wygenerowany przez konsolę po zarejestrowaniu aplikacji. W dalszej części skonfigurujemy aplikację wysyłającą, aby używała tego identyfikatora.
Musisz też zarejestrować urządzenie przesyłające Google Cast, aby miało dostęp do aplikacji odbiornika przed jej opublikowaniem. Po opublikowaniu aplikacji odbiornika będzie ona dostępna na wszystkich urządzeniach Google Cast. Na potrzeby tego modułu zalecamy pracę z nieopublikowaną aplikacją odbiorcy.
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 podczas korzystania z Konsoli programisty Google Cast SDK.
Przygotowanie odbiornika i urządzenia do testowania zajmuje 5–15 minut. Po odczekaniu 5–15 minut musisz ponownie uruchomić urządzenie przesyłające.
5. Przygotowywanie projektu startowego
Zanim zaczniesz korzystać z tego ćwiczenia, warto zapoznać się z przewodnikiem dla deweloperów dotyczącym reklam, w którym znajdziesz omówienie interfejsów API przerw na reklamy.
Obsługę Google Cast należy dodać do pobranej aplikacji startowej. Oto niektóre terminy związane z Google Cast, które są używane w tych ćwiczeniach z programowania:
- aplikacja nadawcy jest uruchomiona na urządzeniu mobilnym lub laptopie,
- na urządzeniu przesyłającym działa aplikacja odbiornika;
Teraz możesz rozbudowywać projekt początkowy za pomocą ulubionego edytora tekstu:
- W pobranych przykładowych kodach wybierz katalog
app-start. - Otwórz
js/receiver.jsi index.html.
Pamiętaj, że w trakcie wykonywania tego Codelabs wybrane rozwiązanie hostingu WWW powinno być aktualizowane o wprowadzone zmiany. Podczas dalszego sprawdzania i testowania zmian upewnij się, że przesyłasz je do witryny hosta.
Projektowanie aplikacji
Jak już wspomnieliśmy, w tym laboratorium wykorzystywana jest aplikacja nadawcy do inicjowania sesji Cast oraz aplikacja odbiorcy, która zostanie zmodyfikowana w celu używania interfejsów API przerw na reklamy.
W tym laboratorium narzędzie Cast and Command Tool będzie działać jako nadawca internetowy, który uruchomi aplikację odbiornika. Aby rozpocząć, otwórz narzędzie w przeglądarce Chrome. Wpisz identyfikator aplikacji odbiorcy, który został Ci przyznany w Konsoli programisty Cast SDK, i kliknij Ustaw, aby skonfigurować aplikację nadawcy do testowania.
Uwaga: jeśli ikona przesyłania nie jest widoczna, sprawdź, czy odbiornik internetowy i urządzenia przesyłające są prawidłowo zarejestrowane w Konsoli dewelopera Cast. Jeśli nie zostało to jeszcze zrobione, wyłącz i włącz wszystkie urządzenia do przesyłania, które zostały właśnie zarejestrowane.
Aplikacja odbiorcy jest głównym tematem tego laboratorium i składa się z jednego głównego widoku zdefiniowanego w pliku index.html oraz jednego pliku JavaScript o nazwie js/receiver.js. Opisujemy je poniżej.
index.html
Ten plik HTML zawiera interfejs aplikacji odbiornika udostępniany przez element cast-media-player. Wczytuje też biblioteki pakietu SDK CAF i Cast Debug Logger.
receiver.js
Ten skrypt zarządza całą logiką aplikacji odbiornika. Obecnie zawiera podstawowy odbiornik CAF, który inicjuje kontekst przesyłania i wczytuje zasób wideo po inicjowaniu. Dodaliśmy też niektóre funkcje rejestrowania debugowania, aby przesyłać logi z powrotem do narzędzia Cast and Command.
6. Dodawanie VMAP do treści
Pakiet Cast Web Receiver SDK obsługuje reklamy określone za pomocą cyfrowych list odtwarzania wielu reklam wideo, znanych też jako VMAP. Struktura XML określa przerwy na reklamę w treściach i powiązane z nimi metadane klipów z przerwami. Aby 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ę LOAD request interceptor i zastąp ją tym kodem: Zawiera on przykładowy URL tagu VMAP z DoubleClick i podaje losową wartość korelatora, aby zapewnić, że kolejne żądania tego samego adresu URL będą generować 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 pliku js/receiver.js i prześlij go na serwer WWW. Rozpocznij sesję przesyłania w narzędziu do przesyłania i sterowania, klikając ikonę przesyłania. Reklamy VMAP powinny być odtwarzane przed główną treścią.
7. Dodawanie VAST do treści
Jak wspomnieliśmy wcześniej, pakiet Web Receiver SDK obsługuje wiele typów reklam. W tej sekcji znajdziesz informacje o interfejsach API, które umożliwiają integrację reklam Digital Video Ad Serving Template, czyli VAST. Jeśli masz wdrożony kod VMAP z poprzedniej sekcji, umieść go w komentarzu.
Skopiuj poniższy kod do pliku js/receiver.js po przechwytywaniu żądania wczytania. Zawiera 6 klipów z przerwami na reklamy VAST z DoubleClick i losową wartość korelatora. Te klipy są przypisane do 5 przerw. Każda przerwa position jest ustawiona na czas w sekundach względem głównej treści, w tym przerwy na reklamę przed filmem (position ustawione na 0) i po filmie (position ustawione 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 pliku js/receiver.js file znajdź przechwytujący komunikat LOAD i zastąp go poniższym kodem. Pamiętaj, że kod VMAP jest wykomentowany, aby pokazać 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. Rozpocznij sesję przesyłania w narzędziu do przesyłania i sterowania, klikając ikonę przesyłania. Reklamy VAST powinny być odtwarzane przed główną treścią.
8. Pominięcie przerwy na reklamę
CAF ma klasę o nazwie BreakManager, która pomaga wdrażać niestandardowe reguły biznesowe dotyczące zachowań reklam. Jedna z tych funkcji umożliwia aplikacjom programowe pomijanie przerw i klipów reklamowych na podstawie określonego warunku. Ten przykład pokazuje, jak pominąć przerwę na reklamę, która znajduje się w pierwszych 30 sekundach treści, ale nie przerwę po filmie. W przypadku reklam VAST skonfigurowanych w poprzedniej sekcji zdefiniowano 5 przerw: 1 przerwę przed filmem, 3 przerwy w trakcie filmu (po 15, 60 i 100 sekundach) oraz 1 przerwę po filmie. Po wykonaniu tych czynności pomijane są tylko reklamy przed filmem i reklamy w trakcie filmu, których pozycja wynosi 15 sekund.
W tym celu aplikacja powinna wywołać interfejsy API dostępne w BreakManager, aby ustawić przechwytujący dla wstrzymywania ładowania. Skopiuj ten 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ć przechwytywacz z regułą ignorowania przerw na reklamy, które występują przed upływem 30 sekund, z uwzględnieniem reklam po filmie (ponieważ ich wartości position to -1). Ten przechwytywacz działa podobnie jak przechwytywacz LOAD na PlayerManager, z tym że jest on przeznaczony do wczytywania klipów z przerwami. Ustaw tę wartość po przechwytywaniu żądania 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 null tutaj powoduje pominięcie przetwarzania BreakClip. Jeśli Break nie ma zdefiniowanych klipów przerw, sama przerwa jest pomijana.
Zapisz zmiany w pliku js/receiver.js i prześlij go na serwer WWW. Rozpocznij sesję przesyłania w narzędziu do przesyłania i sterowania, 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 wynosi 15 sekund) nie są odtwarzane.
9. Dostosowywanie działania funkcji przeskakiwania przerw
Podczas wyszukiwania przerw w przeszłości domyślna implementacja pobiera wszystkie elementy Break, których pozycja mieści się między wartościami seekFrom i seekTo operacji wyszukiwania. Z tej listy przerw pakiet SDK odtwarza przerwę Break, której position jest najbliższe wartości seekTo, a właściwość isWatched ma wartość false. Właściwość isWatched tej przerwy jest ustawiana na true, a odtwarzacz rozpoczyna odtwarzanie klipów przerwy. Po obejrzeniu przerwy odtwarzanie głównej treści zostanie wznowione od pozycji seekTo. Jeśli nie ma takiego punktu, przerwa nie zostanie odtworzona, a główne treści będą odtwarzane dalej od pozycji seekTo.
Aby dostosować, które przerwy mają być odtwarzane podczas przewijania, pakiet Cast SDK udostępnia interfejs setBreakSeekInterceptor API w BreakManager. 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 przypadku co najmniej 1 przerwy. Funkcja wywołania zwrotnego otrzymuje obiekt zawierający wszystkie przerwy między pozycją seekFrom a pozycją seekTo. Aplikacja musi następnie zmodyfikować i zwrócić BreakSeekData.
Aby pokazać, jak to działa, w poniższym przykładzie zastąpiono domyślne zachowanie, wybierając wszystkie przerwy, do których użytkownik przewinął, i odtwarzając 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 wartość null, nie są odtwarzane żadne przerwy.
Zapisz zmiany w pliku js/receiver.js i prześlij go na serwer WWW. Rozpocznij sesję przesyłania w narzędziu do przesyłania i sterowania, 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 wynosi 15 sekund) nie są odtwarzane.
Poczekaj, aż czas odtwarzania osiągnie 30 sekund, aby pominąć wszystkie przerwy, które są pomijane przez przechwytywacz wczytywania klipu z przerwą. Gdy to zrobisz, wyślij polecenie wyszukiwania, przechodząc na kartę Sterowanie multimediami. W polu Seek Into Media wpisz 300 sekund i kliknij przycisk DO. Zwróć uwagę na logi wyświetlane w interceptorze Break Seek. Domyślne działanie powinno zostać zastąpione, aby odtwarzać przerwę bliżej godziny seekFrom.
10. Gratulacje
Wiesz już, jak dodawać reklamy do aplikacji odbiorcy za pomocą najnowszego pakietu Cast Receiver SDK.
Więcej informacji znajdziesz w przewodniku dla programistów dotyczącym przerw na reklamy.