Konfigurowanie pakietu IMA SDK

Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą wysyłać żądania reklam do 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ą odtwarzane w osobnym odtwarzaczu wideo umieszczonym nad odtwarzaczem wideo z treściami aplikacji.

W tym przewodniku pokazujemy, jak zintegrować pakiet IMA SDK z prostą aplikacją odtwarzacza wideo. Jeśli chcesz wyświetlić gotową przykładową integrację lub z niej skorzystać, pobierz prosty przykład z GitHub. Jeśli interesuje Cię odtwarzacz HTML5 z wstępnie zintegrowanym pakietem SDK, zapoznaj się z wtyczką IMA SDK do odtwarzacza Video.js.

Omówienie IMA po stronie klienta

Wdrażanie pakietu IMA SDK po stronie klienta obejmuje 4 główne komponenty SDK, które zostały przedstawione w tym przewodniku:

  • AdDisplayContainer: obiekt kontenera, który określa, 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 obsługuje zdarzenia z odpowiedzi na żądania reklam. Powinieneś utworzyć tylko jeden moduł wczytywania reklam, którego można używać przez cały okres działania aplikacji.
  • AdsRequest: obiekt, który definiuje żądanie reklamy. Żądania reklam określają adres URL tagu reklamy VAST, a także dodatkowe parametry, takie jak wymiary reklamy.
  • AdsManager: obiekt, który zawiera odpowiedź na żądanie reklamy, kontroluje odtwarzanie reklam i nasłuchuje zdarzeń reklamowych wywoływanych 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żywać serwera WWW. Najprostszym sposobem na uruchomienie lokalnego serwera deweloperskiego jest użycie wbudowanego serwera Pythona.

  1. W wierszu poleceń w katalogu zawierającym plik index.html uruchom: 
      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 zawarty w elemencie opakowującym i przycisk uruchamiający odtwarzanie. W tym przykładzie importowany jest pakiet IMA SDK i konfigurowany jest element kontenera AdDisplayContainer. Więcej informacji znajdziesz w krokach Importowanie pakietu IMA SDK i  Tworzenie kontenera reklamy . 

<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 niezbędne tagi, aby wczytać pliki 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 uruchom 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 obiektu AdsLoader i wysyłanie żądania reklamy .

3. Zaimportuj pakiet IMA SDK

Następnie dodaj platformę IMA za pomocą tagu skryptu w pliku index.html przed tagiem dla elementu 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 specjalnego elementu kontenera reklamy do wyświetlania zarówno reklam, jak i elementów interfejsu związanych z reklamami. Ten kontener musi mieć rozmiar umożliwiający nałożenie go na element wideo od lewego górnego rogu. Wysokość i szerokość reklam umieszczanych w tym kontenerze są ustawiane przez obiekt adsManager, więc nie musisz ręcznie określać tych wartości.

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 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. Zainicjuj obiekt AdsLoader i wyślij żądanie reklamy

Aby wysyłać prośby o reklamy, utwórz instancję AdsLoader. Konstruktor AdsLoader przyjmuje jako dane wejściowe 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 wideo IMA.

Zgodnie ze sprawdzoną metodą przez cały cykl życia strony należy utrzymywać tylko 1 instancję AdsLoader. Aby wysłać dodatkowe żądania reklamy, utwórz nowy obiekt AdsRequest, ale użyj tego samego obiektu AdsLoader. Więcej informacji znajdziesz w odpowiedziach na najczęstsze pytania dotyczące pakietu IMA SDK.

Nasłuchiwanie zdarzeń wczytania reklam i błędów oraz reagowanie na nie za pomocą AdsLoader.addEventListener. Nasłuchuj tych zdarzeń:

  • 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&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 załaduje reklamy, wyemituje zdarzenie ADS_MANAGER_LOADED. Przeanalizuj zdarzenie przekazane do wywołania zwrotnego, aby zainicjować obiekt AdsManager. AdsManager wczytuje poszczególne reklamy zgodnie z odpowiedzią na adres URL tagu reklamy.

Zadbaj o obsługę błędów, które mogą wystąpić podczas wczytywania. Jeśli reklamy się nie wczytują, upewnij się, że odtwarzanie multimediów jest kontynuowane bez reklam, aby nie zakłócać oglądania treści przez użytkownika. 

/**
 * 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 ustawionych w funkcji onAdsManagerLoaded() znajdziesz w tych podsekcjach:

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 procedurę obsługi zdarzeń ponownie wykorzystującą funkcję 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łuż to zdarzenie, wywołując wstrzymanie odtwarzania w odtwarzaczu wideo. Podobnie po zakończeniu wyświetlania reklamy komponent AdsManager uruchamia zdarzenie CONTENT_RESUME_REQUESTED. Obsłuż to zdarzenie, ponownie uruchamiając odtwarzanie podstawowego filmu z treścią. 

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 wyświetlania reklam nielinearnych

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

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

Aby obsługiwać reklamy nieliniowe, nasłuchuj zdarzenia AdsManager emitowanego przez LOADED. Sprawdź, czy reklama jest linearna, a jeśli nie, wznow odtwarzanie w elemencie 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. Wywoływanie 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ć zamieszanie wśród użytkowników urządzeń mobilnych, którzy oczekują, że będą mogli kliknąć odtwarzacz wideo, aby wstrzymać odtwarzanie. 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 na urządzeniach innych niż mobilne, ponieważ kliknięcie reklamy otwiera link prowadzący do niej.

Aby wdrożyć funkcję kliknij, aby wstrzymać, dodaj funkcję obsługi kliknięć adContainerClick() o nazwie w detektorze wczytywania 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. Uruchamianie usługi AdsManager

Aby rozpocząć odtwarzanie reklamy, zainicjuj i uruchom AdsManager. Aby w pełni obsługiwać przeglądarki mobilne, w których nie można automatycznie odtwarzać reklam, uruchamiaj odtwarzanie reklam w odpowiedzi na interakcje użytkownika ze stroną, np. kliknięcie 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 zmieniały rozmiar i dopasowywały się 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. Żądania reklam i ich wyświetlanie odbywa się teraz za pomocą pakietu IMA SDK. Więcej informacji o zaawansowanych funkcjach pakietu SDK znajdziesz w innych przewodnikach lub w przykładach na GitHubie.