Konfigurowanie pakietu IMA SDK

Wybierz platformę: HTML5 Android iOS tvOS

Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą wysyłać żądania reklam z dowolnego serwera reklam zgodnego ze standardem 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 treści wideo aplikacji.

Z tego przewodnika dowiesz się, jak zintegrować pakiet IMA SDK z prostą aplikacją odtwarzacza wideo. Jeśli chcesz zobaczyć lub pobrać gotowy przykład integracji, 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 pakietu IMA SDK po stronie klienta

Implementacja pakietu IMA SDK po stronie klienta obejmuje 4 główne komponenty SDK, które zostały opisane w tym przewodniku:

  • AdDisplayContainer: Obiekt kontenera, który określa, gdzie IMA renderuje elementy interfejsu reklamowego 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. Należy utworzyć tylko jeden moduł wczytywania reklam, który można ponownie wykorzystać przez cały okres działania aplikacji.
  • AdsRequest: Obiekt, który definiuje żądanie reklamy. Żądania reklam określają adres URL tagu reklamy VAST oraz 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. Uruchom serwer programistyczny

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 na uruchomienie lokalnego serwera programistycznego 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 http://localhost:8000/.

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

2. Utwórz prosty odtwarzacz wideo

Najpierw zmodyfikuj plik index.html , aby utworzyć prosty element wideo HTML5 zawarty w elemencie opakowującym oraz przycisk uruchamiający odtwarzanie. Poniższy przykład importuje pakiet IMA SDK i konfiguruje element kontenera AdDisplayContainer. Więcej informacji znajdziesz w Importowanie pakietu IMA SDK i Tworzenie kontenera reklamy krokach. 

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

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

Dodaj niezbędne tagi, aby wczytać pliki style.css i ads.js. Następnie zmodyfikuj styles.css, aby odtwarzacz wideo był responsywny na urządzeniach mobilnych. Na koniec w pliku ads.js zadeklaruj zmienne i uruchom odtwarzanie wideo po kliknięciu przycisku odtwarzania.

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

3. Importowanie pakietu IMA SDK

Następnie dodaj platformę IMA za pomocą tagu skryptu w pliku index.html przed tagiem ads.js. 

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

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 nakładanie się na element wideo od lewego górnego 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 zaimplementować ten element kontenera reklamy, najpierw utwórz nowy div w elemencie video-container. Następnie zaktualizuj CSS, aby umieścić element w lewym górnym rogu elementu video-element. Na koniec dodaj funkcję createAdDisplayContainer(), aby utworzyć obiekt AdDisplayContainer za pomocą nowego kontenera reklamy div. 

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

5. Inicjowanie modułu AdsLoader i wysyłanie żądania reklamy

Aby wysłać żądanie reklamy, utwórz AdsLoader instancję. 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 adres URL tagu reklamy za pomocą narzędzia Inspektor pakietu wideo IMA.

Zalecamy, aby przez cały cykl życia strony utrzymywać tylko jedną instancję AdsLoader. Aby wysłać dodatkowe żądania reklam, utwórz nowy AdsRequest obiekt, ale użyj tego samego AdsLoader. Więcej informacji znajdziesz w najczęstszych pytaniach dotyczących pakietu IMA SDK.

Nasłuchuj zdarzeń wczytania reklam i błędów oraz reaguj na nie za pomocą funkcji 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);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);

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

6. Reagowanie na zdarzenia modułu AdsLoader

Gdy moduł AdsLoader pomyślnie wczyta reklamy, wyemituje zdarzenie ADS_MANAGER_LOADED. Przeanalizuj zdarzenie przekazane do wywołania zwrotnego, aby zainicjować obiekt AdsManager. Moduł AdsManager wczytuje poszczególne reklamy zgodnie z odpowiedzią na adres URL tagu reklamy.

Upewnij się, że obsługujesz wszystkie błędy, które wystąpią podczas procesu wczytywania. Jeśli reklamy się nie wczytają , upewnij się, że odtwarzanie multimediów będzie 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();
}

Więcej informacji o odbiornikach ustawionych w funkcji onAdsManagerLoaded() znajdziesz w tych podsekcjach:

Obsługa błędówAdsManager

Obsługa błędów utworzona dla modułu AdsLoader może też służyć jako obsługa błędów dla modułu AdsManager. Zobacz moduł obsługi zdarzeń ponownie wykorzystujący funkcję onAdError(). 

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

Obsługa zdarzeń odtwarzania i wstrzymywania

Gdy moduł AdsManager jest gotowy do wstawienia reklamy do wyświetlenia, wywołuje zdarzenie CONTENT_PAUSE_REQUESTED. Obsłuż to zdarzenie, wywołując wstrzymanie w podstawowym odtwarzaczu wideo. Podobnie, gdy reklama się zakończy, moduł AdsManager wywołuje zdarzenie CONTENT_RESUME_REQUESTED. Obsłuż to zdarzenie, ponownie uruchamiając odtwarzanie podstawowej treści wideo na 

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

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

Obsługa odtwarzania treści podczas wyświetlania reklam nielinearnych

Moduł AdsManager wstrzymuje odtwarzanie treści wideo, gdy reklama jest gotowa do odtworzenia, ale to zachowanie nie uwzględnia reklam nielinearnych, w przypadku których treść jest odtwarzana podczas wyświetlania reklamy. 

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

Aby obsługiwać reklamy nielinearne, nasłuchuj, czy moduł AdsManager emituje zdarzenie LOADED. Sprawdź, czy reklama jest liniowa, a jeśli nie, wznow odtwarzanie elementu wideo.

Definicję funkcji onAdLoaded() znajdziesz w tym 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();
  }
}

7. Wywoływanie wstrzymania po kliknięciu na urządzeniach mobilnych

Ponieważ element AdContainer nakłada się na element wideo, użytkownicy nie mogą bezpośrednio wchodzić w interakcję z podstawowym odtwarzaczem. Może to dezorientować użytkowników urządzeń mobilnych, którzy oczekują, że będą mogli wstrzymać odtwarzanie, dotykając a odtwarzacza wideo. Aby rozwiązać ten problem, pakiet IMA SDK przekazuje wszystkie kliknięcia, które nie są obsługiwane przez IMA, z nakładki na reklamie 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 otwiera link docelowy.

Aby zaimplementować wstrzymanie po kliknięciu, dodaj funkcję obsługi kliknięć adContainerClick() wywoływaną w odbiorniku 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();
  }
}

8. Uruchamianie modułu AdsManager

Aby rozpocząć odtwarzanie reklamy, zainicjuj i uruchom moduł AdsManager. Aby w pełni obsługiwać przeglądarki mobilne, w których nie można automatycznie odtwarzać reklam, wywołuj odtwarzanie reklam w wyniku interakcji użytkownika ze stroną, np. kliknięcia 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();
  }
}

9. Obsługa zmiany rozmiaru odtwarzacza

Aby reklamy zmieniały rozmiar dynamicznie 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);
  }
});

To wszystko. Teraz możesz wysyłać żądania reklam i wyświetlać reklamy za pomocą pakietu IMA SDK. Aby dowiedzieć się więcej o bardziej zaawansowanych funkcjach pakietu SDK, zapoznaj się z innymi przewodnikami lub przykładami na GitHub.