Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą wysyłać żądania reklam z dowolnego serwera reklam zgodnych z VAST i zarządzać ich odtwarzaniem w aplikacjach. Dzięki pakietom IMA SDK po stronie klienta zachowujesz kontrolę nad odtwarzaniem treści wideo, a pakiet SDK obsługuje odtwarzanie reklam. Reklamy wyświetlają się w osobnym odtwarzaczu nad odtwarzaczem wideo treści w aplikacji.
Z tego przewodnika dowiesz się, jak zintegrować pakiet IMA SDK z prostą aplikacją odtwarzacza wideo. Jeśli chcesz zapoznać się z przykładową integracją lub wykonać związane z nią instrukcje, pobierz prosty przykład z GitHuba. Jeśli interesuje Cię odtwarzacz HTML5 ze wstępnie zintegrowanym pakietem SDK, zajrzyj do wtyczki IMA SDK do Video.js.
Omówienie po stronie klienta IMA
Implementacja pakietu IMA po stronie klienta obejmuje 4 główne komponenty SDK, które opisujemy w tym przewodniku:
AdDisplayContainer
: obiekt kontenera, w którym są renderowane reklamy.AdsLoader
: obiekt, który wysyła żądania reklam i obsługuje zdarzenia z odpowiedzi żądań reklam. Inicjuj tylko 1 program wczytujący reklamy, którego można używać wielokrotnie w całym cyklu życia aplikacji.AdsRequest
: obiekt definiujący żądanie reklamy. Żądania reklam określają adres URL tagu reklamy VAST oraz dodatkowe parametry, np. wymiary reklamy.AdsManager
: obiekt, który zawiera odpowiedź na żądanie reklamy, steruje odtwarzaniem i nasłuchuje zdarzeń reklamowych wywoływanych przez pakiet SDK.
Wymagania wstępne
Zanim zaczniesz, będziesz potrzebować:
- 3 puste pliki:
- index.html
- style.css
- ads.js
- Python zainstalowany na komputerze lub serwer WWW do testowania
1. Uruchamianie serwera programistycznego
Pakiet IMA SDK wczytuje zależności przez ten sam protokół co strona, z której jest załadowana, dlatego do przetestowania aplikacji musisz użyć serwera WWW. Najprostszym sposobem uruchomienia lokalnego serwera programistycznego jest użycie wbudowanego serwera Pythona.
- Korzystając z wiersza poleceń, z katalogu zawierającego uruchomienie Twojego pliku index.html:
python -m http.server 8000
- W przeglądarce otwórz stronę
http://localhost:8000/
Możesz też użyć dowolnego innego serwera WWW, na przykład serwera HTTP Apache.
2. Utwórz prosty odtwarzacz wideo
Najpierw zmodyfikuj plik index.html tak, by utworzyć prosty element wideo HTML5 zawarty w elemencie paczki i przycisk uruchamiający odtwarzanie. Dodaj też tagi niezbędne do wczytywania plików style.css i ads.js. Następnie zmodyfikuj plik styles.css, by odtwarzacz wideo reagował na urządzenia mobilne. Na koniec kod ads.js uruchamia odtwarzanie wideo po kliknięciu przycisku odtwarzania.
index.html<!doctype html> <html lang="en"> <head> <title>IMA HTML5 Simple Demo</title> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> <link rel="stylesheet" href="style.css"> </head> <body> <div id="page-content"> <div id="video-container"> <video id="video-element"> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4"> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm"> </video> </div> <button id="play-button">Play</button> </div> <script src="ads.js"></script> </body> </html>style.css
#page-content { position: relative; /* this element's width controls the effective height */ /* of the video container's padding-bottom */ max-width: 640px; margin: 10px auto; } #video-container { position: relative; /* forces the container to match a 16x9 aspect ratio */ /* replace with 75% for a 4:3 aspect ratio, if needed */ padding-bottom: 56.25%; } #video-element { /* forces the contents to fill the container */ position: absolute; top: 0; left: 0; width: 100%; height: 100%; }ads.js
var videoElement; // On window load, attach an event to the play button click // that triggers playback on the video element window.addEventListener('load', function(event) { videoElement = document.getElementById('video-element'); var playButton = document.getElementById('play-button'); playButton.addEventListener('click', function(event) { videoElement.play(); }); });
Po wykonaniu tego kroku po otwarciu pliku index.html w przeglądarce (za pomocą serwera programistycznego) powinien być widoczny element wideo, a film powinien się rozpocząć po kliknięciu przycisku odtwarzania.
3. Importowanie pakietu IMA SDK
Następnie dodaj platformę IMA, korzystając z tagu skryptu w pliku index.html, przed tagiem witryny ads.js
.
... </video> </div> <button id="play-button">Play</button> </div> <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script> <script src="ads.js"></script> </body> </html>
4. Dołączanie modułów obsługi stron i odtwarzacza
Aby zmienić działanie odtwarzacza wideo za pomocą JavaScriptu, dodaj moduły obsługi zdarzeń, które wywołują te działania:
- Po zakończeniu wczytywania strony zainicjuj pakiet IMA SDK.
- Po kliknięciu przycisku odtwarzania filmu zostaną wczytane reklamy (chyba że zostały już wczytane).
- Po zmianie rozmiaru okna przeglądarki zaktualizuj element wideo i wymiary
adsManager
, aby strona była elastyczna na urządzeniach mobilnych
var videoElement; // Define a variable to track whether there are ads loaded and initially set it to false var adsLoaded = false; window.addEventListener('load', function(event) { videoElement = document.getElementById('video-element'); initializeIMA(); videoElement.addEventListener('play', function(event) { loadAds(event); }); var playButton = document.getElementById('play-button'); playButton.addEventListener('click', function(event) { videoElement.play(); }); }); window.addEventListener('resize', function(event) { console.log("window resized"); }); function initializeIMA() { console.log("initializing IMA"); } function loadAds(event) { // Prevent this function from running on if there are already ads loaded if(adsLoaded) { return; } adsLoaded = true; // Prevent triggering immediate playback when ads are loading event.preventDefault(); console.log("loading ads"); }
5. Tworzenie kontenera reklamy
W większości przeglądarek pakiet IMA SDK używa dedykowanego elementu kontenera reklam, który służy do wyświetlania zarówno reklam, jak i związanych z nimi elementów interfejsu. Rozmiar tego kontenera musi być dostosowany, aby nachodził na element wideo widoczny w lewym górnym rogu. Wysokość i szerokość reklam umieszczonych w tym kontenerze są ustawiane przez obiekt adsManager
, więc nie musisz ustawiać tych wartości ręcznie.
Aby wdrożyć ten element kontenera reklamy, najpierw utwórz nowy element div
w elemencie video-container
. Następnie zaktualizuj CSS, aby umieścić element w lewym górnym rogu interfejsu video-element
. Na koniec zdefiniuj zmienną dla kontenera w funkcji initializeIMA()
, która uruchamia się podczas wczytywania strony.
... <div id="video-container"> <video id="video-element" controls> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4"> <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm"> </video> <div id="ad-container"></div> </div> ...style.css
... #ad-container { position: absolute; top: 0; left: 0; width: 100%; }ads.js
var videoElement; var adsLoaded = false; var adContainer; ... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); }
6. Zainicjowanie klasy AdsLoader i wysłanie żądania reklamy
Aby zażądać zestawu reklam, utwórz wystąpienie ima.AdsLoader
. Ta instancja pobiera obiekt AdDisplayContainer
jako dane wejściowe i można jej używać do przetwarzania obiektów ima.AdsRequest
powiązanych z określonym adresem URL tagu reklamy. Tag reklamy użyty w tym przykładzie zawiera 10-sekundową reklamę przed filmem. Możesz przetestować ten lub dowolny adres URL tagu reklamy za pomocą narzędzia IMA Video Suite Inspector.
Sprawdzoną metodą jest utrzymywanie tylko 1 wystąpienia ima.AdsLoader
przez cały cykl życia strony. Aby wysłać dodatkowe żądania reklamy, utwórz nowy obiekt ima.AdsRequest
, ale ponownie użyj tego samego obiektu ima.AdsLoader
. Więcej informacji znajdziesz w Najczęstszych pytaniach na temat pakietu IMA SDK.
var videoElement; var adsLoaded = false; var adContainer; var adDisplayContainer; var adsLoader; ... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement); adsLoader = new google.ima.AdsLoader(adDisplayContainer); // Let the AdsLoader know when the video has ended videoElement.addEventListener('ended', function() { adsLoader.contentComplete(); }); var adsRequest = new google.ima.AdsRequest(); adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' + 'iu=/21775744923/external/single_ad_samples&sz=640x480&' + 'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&' + 'gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator='; // Specify the linear and nonlinear slot sizes. This helps the SDK to // select the correct creative if multiple are returned. adsRequest.linearAdSlotWidth = videoElement.clientWidth; adsRequest.linearAdSlotHeight = videoElement.clientHeight; adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth; adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3; // Pass the request to the adsLoader to request ads adsLoader.requestAds(adsRequest); }
7. Wykrywaj zdarzenia AdsLoader
Po pomyślnym wczytaniu reklam ima.AdsLoader
wysyła zdarzenie ADS_MANAGER_LOADED
. Przeanalizuj zdarzenie przekazane do wywołania zwrotnego, aby zainicjować obiekt AdsManager
. AdsManager
wczytuje poszczególne reklamy zgodnie z definicją w odpowiedzi na adres URL tagu reklamy.
Pamiętaj też o eliminowaniu wszelkich błędów, które mogą się pojawić podczas wczytywania. Jeśli reklamy się nie ładują, upewnij się, że odtwarzanie multimediów będzie kontynuowane, bez reklam, aby nie zakłócać korzystania z urządzenia.
ads.jsvar videoElement; var adsLoaded = false; var adContainer; var adDisplayContainer; var adsLoader; var adsManager; ... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement); adsLoader = new google.ima.AdsLoader(adDisplayContainer); adsLoader.addEventListener( google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED, onAdsManagerLoaded, false); adsLoader.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false); ... function onAdsManagerLoaded(adsManagerLoadedEvent) { // Instantiate the AdsManager from the adsLoader response and pass it the video element adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); } function onAdError(adErrorEvent) { // Handle the error logging. console.log(adErrorEvent.getError()); if(adsManager) { adsManager.destroy(); } }
8. Uruchamianie menedżera reklam
Aby rozpocząć odtwarzanie reklamy, musisz uruchomić AdsManager
. Aby w pełni obsługiwać przeglądarki mobilne, wywołanie powinno być wywoływane przez interakcję użytkownika.
... function loadAds(event) { // prevent this function from running on every play event if(adsLoaded) { return; } adsLoaded = true; // prevent triggering immediate playback when ads are loading event.preventDefault(); console.log("loading ads"); // Initialize the container. Must be done via a user action on mobile devices. videoElement.load(); adDisplayContainer.initialize(); var width = videoElement.clientWidth; var height = videoElement.clientHeight; try { adsManager.init(width, height, google.ima.ViewMode.NORMAL); adsManager.start(); } catch (adError) { // Play the video without ads, if an error occurs console.log("AdsManager could not be started"); videoElement.play(); } } ...
9. Ustawianie parametrów reklam elastycznych w usłudze AdsManager
Aby reklamy dynamicznie dostosowywały się do rozmiaru odtwarzacza wideo, przy zmianie rozmiaru lub orientacji ekranu zdarzenie zmiany rozmiaru okna musi wywołać adsManager.resize()
.
... window.addEventListener('resize', function(event) { console.log("window resized"); if(adsManager) { var width = videoElement.clientWidth; var height = videoElement.clientHeight; adsManager.resize(width, height, google.ima.ViewMode.NORMAL); } }); ...
10. Wykrywaj zdarzenia AdsManager
AdsManager
uruchamia też kilka zdarzeń, które muszą być obsługiwane. Zdarzenia te służą do śledzenia zmian stanu, uruchamiania i wstrzymywania odtwarzania treści wideo oraz rejestrowania błędów.
Obsługa błędów
Moduł obsługi błędów utworzony na potrzeby obiektu AdsLoader
może służyć jako moduł obsługi błędów w AdsManager
przez dodanie nowego modułu obsługi zdarzeń z tą samą funkcją wywołania zwrotnego.
... function onAdsManagerLoaded(adsManagerLoadedEvent) { adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); adsManager.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError); } ...
Aktywowanie zdarzeń odtwarzania i wstrzymywania
Gdy AdsManager
będzie gotowy do wstawienia reklamy do wyświetlenia, uruchamia zdarzenie CONTENT_PAUSE_REQUESTED
. Aby obsłużyć to zdarzenie, wstrzymaj odtwarzanie w odtwarzaczu. I podobnie, po zakończeniu wyświetlania reklamy AdsManager
wywołuje zdarzenie CONTENT_RESUME_REQUESTED
. Aby uporać się z tym zdarzeniem, ponownie uruchom odtwarzanie filmu, który aktualnie prowadzi.
... function onAdsManagerLoaded(adsManagerLoadedEvent) { adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); adsManager.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED, onContentResumeRequested); } ... function onContentPauseRequested() { videoElement.pause(); } function onContentResumeRequested() { videoElement.play(); }
Włączanie funkcji „kliknij, aby wstrzymać” na urządzeniach mobilnych
Element AdContainer
nakłada się na element wideo, dlatego użytkownicy nie mogą wchodzić w bezpośrednią interakcję z odtwarzaczem, który się na nim znajduje. Może to wprowadzać w błąd użytkowników urządzeń mobilnych, którzy oczekują możliwości wstrzymania odtwarzania poprzez dotknięcie odtwarzacza. Aby rozwiązać ten problem, pakiet IMA SDK przekazuje wszystkie kliknięcia, które nie są obsługiwane przez IMA, z nakładki na reklamy do elementu AdContainer
, gdzie są one obsługiwane. Nie dotyczy to reklam linearnych w przeglądarkach na inne urządzenia, ponieważ kliknięcie reklamy otwiera
link po kliknięciu.
Aby zaimplementować funkcję „kliknij, aby wstrzymać”, dodaj do parametru AdContainer
moduł obsługi kliknięć, który będzie wywoływać zdarzenia odtwarzania i wstrzymywania w przypadku odpowiedniego filmu.
... function initializeIMA() { console.log("initializing IMA"); adContainer = document.getElementById('ad-container'); adContainer.addEventListener('click', adContainerClick); adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement); adsLoader = new google.ima.AdsLoader(adDisplayContainer); ... function adContainerClick(event) { console.log("ad container clicked"); if(videoElement.paused) { videoElement.play(); } else { videoElement.pause(); } } ...
Uruchamianie odtwarzania w przypadku reklam nielinearnych
Element AdsManager
wstrzymuje film, gdy reklama jest gotowa do odtworzenia. Jednak to zachowanie nie uwzględnia reklam nielinearnych, w których przypadku zawartość powinna być nadal odtwarzana w trakcie wyświetlania. Aby obsługiwać reklamy nielinearne, czekaj na to, aż AdsManager
będzie emitować zdarzenie LOADED
. Następnie sprawdź, czy reklama jest liniowa, a jeśli nie, wznów odtwarzanie elementu wideo.
... function onAdsManagerLoaded(adsManagerLoadedEvent) { adsManager = adsManagerLoadedEvent.getAdsManager( videoElement); adsManager.addEventListener( google.ima.AdErrorEvent.Type.AD_ERROR, onAdError); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested); adsManager.addEventListener( google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED, onContentResumeRequested); adsManager.addEventListener( google.ima.AdEvent.Type.LOADED, onAdLoaded); } ... function onAdLoaded(adEvent) { var ad = adEvent.getAd(); if (!ad.isLinear()) { videoElement.play(); } }
Znakomicie. Wysyłajesz żądanie i wyświetlasz reklamy za pomocą pakietu IMA SDK. Informacje o bardziej zaawansowanych funkcjach pakietu SDK znajdziesz w innych przewodnikach i przykładach na GitHubie.