Konfigurowanie pakietu IMA SDK

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 GitHub. 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 reklam generowane 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, więc do testowania aplikacji musisz użyć serwera WWW. Najprostszym sposobem uruchomienia lokalnego serwera do programowania 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 w formacie HTML5, ujęty w element opakowujący, oraz przycisk uruchamiający odtwarzanie. W tym przykładzie importujemy pakiet IMA SDK i konfigurujemy element kontenera AdDisplayContainer. Więcej informacji znajdziesz w odpowiednich krokach: Importowanie pakietu IMA SDK i  Tworzenie kontenera reklamowego . 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

index.html
 
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
style.css
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});
ads.js

Dodaj 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 zadeklaruj zmienne i uaktywnij odtwarzanie filmu po kliknięciu przycisku odtwarzania.

Pamiętaj, że fragment kodu ads.js zawiera wywołanie funkcji setUpIMA(), która jest zdefiniowana w sekcji Inicjowanie funkcji AdsLoader i wysyłanie żądania reklam .

3. Importowanie pakietu IMA SDK

Następnie dodaj platformę IMA, używając tagu skryptu w pliku index.html przed tagiem ads.js. 

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
index.html

4. 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 dodaj funkcję createAdDisplayContainer(), aby utworzyć obiekt AdDisplayContainer za pomocą nowego kontenera reklamy div. 

<div id="adContainer"></div>
index.html
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
style.css
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}
ads.js

5. Inicjalizacja AdsLoadera i wysłanie żądania reklamy

Aby żądać reklam, utwórz instancję AdsLoader. Konstruktor AdsLoader otrzymuje jako argument obiekt AdDisplayContainer i może służyć do przetwarzania obiektów 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 AdsLoader. Aby wysyłać dodatkowe żądania reklam, utwórz nowy obiekt AdsRequest, ale używaj tego samego obiektu AdsLoader. Więcej informacji znajdziesz w odpowiedziach na najczęstsze pytania dotyczące pakietu IMA SDK.

Za pomocą AdsLoader.addEventListener możesz nasłuchiwać zdarzeń wczytywania reklam i błędów oraz na nie odpowiadać. Nasłuchuj te zdarzenia:

  • ADS_MANAGER_LOADED
  • AD_ERROR

Aby utworzyć odbiorniki onAdsManagerLoaded() i onAdError(), zapoznaj się z tym przykładem: 

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const 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 = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}
ads.js

6. Odpowiadanie na zdarzenia AdsLoader

Gdy AdsLoader wczyta reklamy, 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.

Zadbaj o to, aby wszystkie błędy występujące podczas wczytywania były obsługiwane. Jeśli reklamy się nie wczytują, upewnij się, że odtwarzanie multimediów będzie kontynuowane bez reklam, aby nie zakłócać użytkownikowi oglądania treści. 

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  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);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}
ads.js

Więcej informacji o odbiornikach skonfigurowanych w funkcji onAdsManagerLoaded() znajdziesz w tych sekcjach:

Obsługa błędów AdsManager

Obsługa błędów utworzona dla AdsLoader może też służyć jako obsługa błędów dla AdsManager. Zobacz, jak w obsługniku zdarzeń jest ponownie używana funkcja onAdError(). 

adsManager.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);
ads.js

Obsługa 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 odtwarzania 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. 

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);
ads.js

Definicje funkcji onContentPauseRequested() i onContentResumeRequested() znajdziesz w tym przykładzie: 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}
ads.js

Obsługa odtwarzania treści podczas reklam nieliniowych

AdsManager wstrzymuje odtwarzanie filmu, gdy reklama jest gotowa do wyświetlenia, ale to zachowanie nie dotyczy reklam nieliniowych, w których treści są nadal odtwarzane podczas wyświetlania reklamy. 

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
ads.js

Aby obsługiwać reklamy nieliniowe, nasłuchuj zdarzenie AdsManager, aby emitować zdarzenie LOADED. Sprawdź, czy reklama jest linearna, a jeśli nie, wznów odtwarzanie elementu wideo.

Definicję funkcji onAdLoaded() znajdziesz w poniższym przykładzie. 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}
ads.js

7. Włączanie funkcji kliknięcia w celu wstrzymania 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 można je obsłużyć. Nie dotyczy to reklam liniowych w przeglądarkach innych niż mobilne, ponieważ kliknięcie reklamy powoduje otwarcie linku prowadzącego do reklamy.

Aby wdrożyć funkcję kliknięcia w celu wstrzymania, dodaj funkcję obsługi kliknięć adContainerClick() wywoływaną w detektorze wczytania okna. 

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}
ads.js

8. Uruchom program AdsManager.

Aby rozpocząć odtwarzanie reklamy, uruchom i rozpocznij AdsManager. Aby w pełni obsługiwać przeglądarki mobilne, w których nie można automatycznie odtwarzać reklam, uruchamiaj odtwarzanie reklam po interakcji użytkownika ze stroną, np. po kliknięciu przycisku odtwarzania. 

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}
ads.js

9. Obsługa zmiany rozmiaru odtwarzacza

Aby reklamy dynamicznie dostosowywały swój rozmiar do rozmiaru odtwarzacza wideo lub do zmian orientacji ekranu, wywołuj funkcję adsManager.resize() w odpowiedzi na zdarzenia zmiany rozmiaru okna. 

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    let width = videoContent.clientWidth;
    let height = videoContent.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});
ads.js

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 w przykładach na GitHubie.