Rozpocznij

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.

  1. Przy użyciu wiersza poleceń z katalogu zawierającego uruchomienie pliku index.html: 
      python -m http.server 8000
  2. 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

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

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

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

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

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

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

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

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.

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

...

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.

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