Rozpocznij

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.

  1. Korzystając z wiersza poleceń, z katalogu zawierającego uruchomienie Twojego pliku index.html:
      python -m http.server 8000
    
  2. 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.

index.html
...

        </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
ads.js
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.

index.html
...

  <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.

ads.js
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.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 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.

ads.js
...

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().

ads.js
...

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.

ads.js
...

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.

ads.js
...

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.

ads.js
...

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.

ads.js
...

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.