Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą żądania reklam z Serwer reklam zgodny i zarządzanie odtwarzaniem reklam w aplikacjach. W przypadku pakietów IMA SDK po stronie klienta Ty kontrolujesz odtwarzanie treści wideo, a pakiet SDK obsługuje odtwarzanie reklam. Reklamy są wyświetlane w osobnego odtwarzacza wideo umieszczonego nad odtwarzaczem wideo treści w aplikacji.
Ten przewodnik pokazuje, jak zintegrować pakiet IMA SDK z prostą aplikacją odtwarzacza wideo. Jeśli chcesz zobaczyć lub śledzić ukończoną przykładową integrację, pobierz prosty przykład z GitHuba. Jeśli zainteresowanym odtwarzaczem HTML5 ze wstępnie zintegrowanym pakietem SDK, Wtyczka IMA SDK do pliku Video.js
Przegląd po stronie klienta IMA
Implementacja IMA po stronie klienta obejmuje 4 główne komponenty SDK, które pokazano w tym artykule. przewodnik:
AdDisplayContainer: Obiekt kontenera, w którym są renderowane reklamy.AdsLoader: Obiekt, który wysyła żądania reklam i obsługuje zdarzenia z odpowiedzi na żądania reklam. Należy tylko Utworzenie jednego programu wczytującego reklamy, którego można używać wielokrotnie w całej aplikacji.AdsRequest: Obiekt definiujący żądanie reklamy. Żądania reklam określają URL tagu reklamy VAST oraz dodatkowych parametrów, takich jak wymiary reklam.AdsManager: obiekt zawierający odpowiedź na żądanie reklamy, steruje odtwarzaniem i nasłuchuje reklamy. zdarzeń wywoływanych przez pakiet SDK.
Wymagania wstępne
Zanim zaczniesz, musisz mieć:
- Trzy 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 wczytywany, dlatego musi użyć serwera WWW, aby przetestować aplikację. Najprostszy sposób na rozpoczęcie lokalnej działalności jest używanie wbudowanego serwera Pythona.
- Przy użyciu wiersza poleceń z katalogu zawierającego
uruchomienie pliku index.html:
python -m http.server 8000
- W przeglądarce otwórz stronę
http://localhost:8000/
Możesz również użyć dowolnego innego serwera WWW, takiego jak Serwer HTTP Apache
2. Utwórz prosty odtwarzacz wideo
Najpierw zmodyfikuj plik index.html, by utworzyć prosty element wideo HTML5 zawarty w pakiecie. oraz przycisk aktywujący odtwarzanie. Dodaj też tagi niezbędne do wczytywania sekcji style.css i ads.js. Następnie zmodyfikuj plik styles.css, by utworzyć elastycznych reklam w wyszukiwarce Google. Natomiast kod ads.js aktywuje odtwarzanie filmu, gdy kliknięty przycisk.
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 i po otwarciu pliku index.html w przeglądarce (w programie serwer), powinien być widoczny element wideo, a film powinien się rozpocząć po kliknięciu przycisku przycisk odtwarzania.
3. Importowanie pakietu IMA SDK
Następnie dodaj platformę IMA przy użyciu tagu skryptu w witrynie index.html przed tagiem komponentu
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 elementów obsługi strony i odtwarzacza wideo
Aby zmienić działanie odtwarzacza za pomocą JavaScriptu, dodaj moduły obsługi zdarzeń, które wywołują następujące działania:
- Po zakończeniu wczytywania strony zainicjuj pakiet IMA SDK.
- Po kliknięciu przycisku odtwarzania filmu wczytaj reklamy (chyba że są już wczytane).
- Gdy zmienisz rozmiar okna przeglądarki, zaktualizuj element wideo i
adsManager. wymiary strony elastyczne, które wyświetlają się 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 specjalnego elementu kontenera reklamy do wyświetlania zarówno reklam,
związane z reklamami. Ten kontener musi mieć taki rozmiar, aby nakładać się na element wideo z tagu
w lewym górnym rogu. Wysokość i szerokość reklam umieszczanych w tym kontenerze są określane przez
adsManager, więc nie musisz ustawiać tych wartości ręcznie.
Aby zaimplementować ten element kontenera reklamy, najpierw utwórz nowy element div w
video-container. Następnie zaktualizuj CSS, aby umieścić element w lewym górnym rogu
na rogu video-element. Na koniec zdefiniuj zmienną dla kontenera w tagu
Funkcja initializeIMA() uruchamiana 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. Zainicjuj komponent AdsLoader i wyślij żądanie reklamy
Aby zażądać zestawu reklam, utwórz wystąpienie ima.AdsLoader. Ta instancja
pobiera obiekt AdDisplayContainer jako dane wejściowe i może być używany do przetwarzania
ima.AdsRequest obiektów powiązanych z określonym adresem URL tagu reklamy. Tag reklamy używany w
Ten przykład zawiera 10-sekundową reklamę przed filmem. Możesz przetestować ten lub dowolny adres URL tagu reklamy, korzystając z metody
Inspektor pakietu IMA wideo.
Zalecamy przechowywanie tylko jednego wystąpienia instancji ima.AdsLoader przez cały okres
cyklu życia strony. Aby przesyłać dodatkowe żądania reklamy, utwórz nowy element ima.AdsRequest
, ale potem użyj ponownie tego samego obiektu ima.AdsLoader. Więcej informacji:
Najczęstsze pytania 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. Nasłuchuj zdarzeń AdsLoader
Gdy reklamy zostaną poprawnie wczytane, ima.AdsLoader emituje sygnał
ADS_MANAGER_LOADED. Przeanalizuj zdarzenie przekazane do wywołania zwrotnego, aby zainicjować
AdsManager obiekt. AdsManager wczytuje poszczególne reklamy zgodnie z odpowiedzią na nie
adresu URL tagu.
Pamiętaj też, by nie zapominać o wszelkich błędach, które mogą wystąpić podczas wczytywania. Jeśli reklamy się nie wyświetlają upewnij się, że multimedia będą odtwarzane, bez reklam, aby nie zakłócać odtwarzania użytkowników.
ads.js
var 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 narzędzia AdsManager
Aby rozpocząć odtwarzanie reklam, musisz uruchomić AdsManager. Aby w pełni obsługiwać urządzenia mobilne
w przeglądarkach, powinno to 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. Zadbaj o elastyczność narzędzia AdsManager
Aby reklamy dynamicznie dostosowywały się do rozmiaru odtwarzacza, jeśli ekran
zmieni rozmiar lub orientację okna, 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. Nasłuchuj zdarzeń AdsManager
AdsManager wywołuje też kilka zdarzeń, które muszą być obsługiwane. Te zdarzenia są używane
śledzić zmiany stanu, uruchamiać odtwarzanie i wstrzymywać odtwarzanie filmu oraz rejestrować błędy.
Obsługa błędów
Moduł obsługi błędów utworzony dla interfejsu AdsLoader może służyć jako moduł obsługi błędów
AdsManager, dodając nowy moduł 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 displayowej, uruchamia
CONTENT_PAUSE_REQUESTED. Aby obsłużyć to zdarzenie, aktywuj wstrzymanie na
danego odtwarzacza. I podobnie, gdy reklama się zakończy, AdsManager uruchamia tag
CONTENT_RESUME_REQUESTED. Wykonaj to zdarzenie, ponownie uruchamiając odtwarzanie na
film, który z nim odpowiada.
...
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();
}
Aktywowanie reklam typu „kliknij, aby wstrzymać” na urządzeniach mobilnych
Ponieważ AdContainer nakłada się na element wideo, użytkownicy nie mogą wchodzić w bezpośrednią interakcję
w której występują. Może to wprowadzać w błąd użytkowników urządzeń mobilnych, którzy oczekują, że będą mogli kliknąć
odtwarzacza wideo, aby wstrzymać odtwarzanie. Aby rozwiązać ten problem, pakiet IMA SDK przekazuje wszystkie kliknięcia, które nie są
obsługiwane przez IMA, od nakładki reklamy do elementu AdContainer, gdzie mogą być
obsługiwane. Nie dotyczy to reklam linearnych w przeglądarkach innych niż mobilne, ponieważ kliknięcie reklamy otwiera
który prowadzi do kliknięcia.
Aby zaimplementować reklamę typu „kliknij, aby wstrzymać”, dodaj do elementu AdContainer moduł obsługi kliknięć i uruchamiaj odtwarzanie
lub wstrzymaj zdarzenia związane z filmem.
...
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();
}
}
...
Włączanie odtwarzania w reklamach nielinearnych
AdsManager wstrzymuje odtwarzanie filmu, gdy reklama będzie gotowa do wyświetlenia, ale w tym przypadku
nie uwzględnia reklam nielinearnych, w których treść powinna być nadal odtwarzana,
reklama zostaje wyświetlona. Aby obsługiwać reklamy nielinearne, poczekaj, aż AdsManager wygeneruje
LOADED. Następnie sprawdź, czy reklama jest linearna. Jeśli nie, wznów odtwarzanie na
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. Zamawiasz i wyświetlasz reklamy za pomocą pakietu IMA SDK. Aby dowiedzieć się więcej zaawansowanych funkcji SDK znajdziesz w innych przewodnikach lub znajdziesz na GitHubie.