Rozpocznij

Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą żądać reklam z dowolnego serwera reklam zgodnego z VAST i zarządzać odtwarzaniem reklam 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 są wyświetlane w oddzielnym odtwarzaczu wideo umieszczonym nad odtwarzaczem treści aplikacji.

Ten przewodnik pokazuje, jak zintegrować pakiet IMA SDK z prostą aplikacją odtwarzacza wideo. Jeśli chcesz zobaczyć lub prześledzić przykładową integrację, pobierz prosty przykład z GitHuba. Jeśli interesuje Cię odtwarzacz HTML5 z wstępnie zintegrowanym pakietem SDK, zapoznaj się z wtyczką IMA SDK dla Video.js.

Omówienie IMA po stronie klienta

Wdrożenie IMA po stronie klienta obejmuje 4 główne komponenty pakietu SDK, które są opisane w tym przewodniku:

  • AdDisplayContainer: obiekt kontenera określający, gdzie IMA renderuje elementy interfejsu reklamy i mierzy widoczność, w tym Widok aktywny i Open Measurement.
  • AdsLoader: obiekt, który wysyła żądania reklam i przetwarza zdarzenia z odpowiedzi na żądania reklam. Powinieneś utworzyć tylko 1 ładowarkę reklam, którą można używać wielokrotnie przez cały czas działania aplikacji.
  • AdsRequest: obiekt definiujący żądanie reklamy. Żądania reklamy określają adres URL tagu reklamy VAST oraz dodatkowe parametry, takie jak wymiary reklamy.
  • AdsManager: obiekt zawierający odpowiedź na żądanie reklamy, który kontroluje odtwarzanie reklam i odbiera zdarzenia reklamowe wywołane przez pakiet SDK.

Wymagania wstępne

Zanim zaczniesz, musisz mieć:

  • 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 za pomocą tego samego protokołu co strona, z której jest wczytywany, dlatego do testowania aplikacji musisz użyć serwera WWW. Najprostszym sposobem uruchomienia lokalnego serwera programistycznego jest użycie wbudowanego serwera Pythona.

  1. W katalogu zawierającym plik index.html uruchom w wierszu poleceń: 
      python -m http.server 8000
  2. W przeglądarce otwórz stronę http://localhost:8000/

Możesz też użyć dowolnego innego serwera WWW, np. serwera HTTP Apache.

2. Tworzenie prostego odtwarzacza wideo

Najpierw zmodyfikuj plik index.html, aby utworzyć prosty element wideo HTML5 ujęty w element opakowujący oraz przycisk uruchamiający odtwarzanie. Dodaj też tagi niezbędne do wczytania plików style.css i ads.js. Następnie zmodyfikuj plik styles.css, aby odtwarzacz wideo był responsywny na urządzeniach mobilnych. Na koniec w pliku ads.js wywołaj odtwarzanie filmu 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, gdy otworzysz plik index.html w przeglądarce (za pomocą serwera programistycznego), powinieneś zobaczyć element wideo, który rozpocznie się odtwarzanie po kliknięciu przycisku odtwarzania.

3. Importowanie pakietu IMA SDK

Następnie dodaj platformę IMA, używając tagu skryptu w pliku index.html przed tagiem 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 obsługi stron i odtwarzacza

Aby zmodyfikować działanie odtwarzacza wideo za pomocą kodu JavaScript, dodaj przetwarzacze zdarzeń, które wywołują te działania:

  • Po załadowaniu strony zainicjuj pakiet IMA SDK.
  • Po kliknięciu przycisku odtwarzania filmu wczytuj reklamy (chyba że są już wczytane).
  • Gdy rozmiar okna przeglądarki się zmieni, zaktualizuj wymiary elementu wideo i elementu 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 reklamy do wyświetlania reklam i elementów interfejsu użytkownika związanych z reklamami. Rozmiar kontenera musi umożliwiać nakładanie elementu filmu na lewy górny róg. Wysokość i szerokość reklam umieszczonych w tym kontenerze są ustawiane przez obiekt adsManager, więc nie musisz ich ustawiać ręcznie.

Aby zaimplementować ten element kontenera reklamy, utwórz najpierw nowy element div w elemencie video-container. Następnie zaktualizuj plik CSS, aby ustawić element w lewym górnym rogu video-element. Na koniec zdefiniuj zmienną dla kontenera w ramach funkcji initializeIMA(), która jest wykonywana po załadowaniu 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. Inicjalizacja AdsLoadera i wysłanie żądania reklamy

Aby poprosić o utworzenie zestawu reklam, utwórz instancję ima.AdsLoader. Ta instancja przyjmuje obiekt AdDisplayContainer jako dane wejściowe i może służyć 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 inny adres URL tagu reklamy za pomocą inspektora pakietu IMA Video.

Zgodnie ze sprawdzoną metodą przez cały cykl życia strony należy utrzymywać tylko 1 wystąpienie ima.AdsLoader. Aby wysyłać dodatkowe żądania reklam, utwórz nowy obiekt ima.AdsRequest, ale używaj tego samego obiektu ima.AdsLoader. Więcej informacji znajdziesz w odpowiedziach na najczęstsze pytania dotyczące 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. Nasłuchiwanie zdarzeń AdsLoader

Gdy reklamy zostaną wczytane, funkcja ima.AdsLoader wyemituje 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ż, aby obsłużyć wszelkie błędy, które mogą wystąpić podczas procesu wczytywania. Jeśli reklamy się nie wczytują, upewnij się, że odtwarzanie multimediów będzie kontynuowane bez reklam, aby nie zakłócać korzystania z aplikacji przez użytkownika.

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. Uruchom program AdsManager.

Aby rozpocząć odtwarzanie reklamy, musisz uruchomić AdsManager. Aby w pełni obsługiwać przeglądarki mobilne, należy to wywołać za pomocą interakcji 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. Sprawianie, że klasa AdsManager jest elastyczna

Aby zapewnić dynamiczne dostosowywanie rozmiaru reklam do rozmiaru odtwarzacza, w przypadku zmiany rozmiaru lub orientacji ekranu zdarzenie zmiany rozmiaru okna musi wywołać funkcję 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. Nasłuchiwanie zdarzeń AdsManager

AdsManager wywołuje też kilka zdarzeń, które należy obsłużyć. Zdarzenia te służą do śledzenia zmian stanu, uruchamiania odtwarzania i wstrzymywania filmu z treściami oraz rejestrowania błędów.

Obsługa błędów

Obsługa błędów utworzona dla AdsLoader może służyć jako obsługa błędów dla AdsManager, jeśli dodasz nową obsługę 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 jest gotowy do wstawienia reklamy do wyświetlenia, uruchamia zdarzenie CONTENT_PAUSE_REQUESTED. Obsługuj to zdarzenie, wywołując wstrzymanie w odtwarzaczu. Podobnie, gdy reklama się zakończy, komponent AdsManager uruchomi zdarzenie CONTENT_RESUME_REQUESTED. Obsługuj to zdarzenie, ponownie uruchamiając odtwarzanie filmu z treściami.

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();
}

Uruchamianie funkcji „kliknij, aby wstrzymać” na urządzeniach mobilnych

Ponieważ element AdContainer nakłada się na element wideo, użytkownicy nie mogą wchodzić w bezpośrednią interakcję z odtwarzaczem. Może to wprowadzać w błąd użytkowników urządzeń mobilnych, którzy oczekują, że kliknięcie odtwarzacza filmu spowoduje wstrzymanie odtwarzania. Aby rozwiązać ten problem, pakiet IMA SDK przekazuje wszystkie kliknięcia, które nie są obsługiwane przez IMA, z nakładki reklamy do elementu AdContainer, gdzie mogą być obsługiwane. Nie dotyczy to reklam liniowych w przeglądarkach innych niż mobilne, ponieważ kliknięcie reklamy powoduje otwarcie linku prowadzącego do reklamy.

Aby zaimplementować funkcję pauzy po kliknięciu, dodaj moduł obsługi kliknięć do AdContainer i wywołaj zdarzenia odtwarzania lub pauzy w filmie źródłowym.

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 reklam nieliniowych

AdsManagerwstrzymuje odtwarzanie filmu z treściami, gdy reklama jest gotowa do wyświetlenia, ale to zachowanie nie dotyczy reklam nieliniowych, w których przypadku treści powinny być nadal odtwarzane podczas wyświetlania reklamy. Aby obsługiwać reklamy nieliniowe, nasłuchuj zdarzenie AdsManager, aby emitować zdarzenie LOADED. Następnie sprawdź, czy reklama jest linearna, 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. Reklamy są teraz żądane i wyświetlane za pomocą pakietu IMA SDK. Więcej informacji o zaawansowanych funkcjach pakietu SDK znajdziesz w innych przewodnikach lub przykładach na GitHubie.