Menyiapkan IMA SDK

Pilih platform: HTML5 Android iOS tvOS

IMA SDK mempermudah integrasi iklan multimedia ke dalam situs dan aplikasi Anda. IMA SDK dapat meminta iklan dari server iklan yang kompatibel dengan VAST dan mengelola pemutaran iklan di aplikasi Anda. Dengan SDK sisi klien IMA, Anda tetap memegang kontrol pemutaran video konten, sementara SDK menangani pemutaran iklan. Iklan diputar di pemutar video terpisah yang diposisikan di atas pemutar video konten aplikasi.

Panduan ini menunjukkan cara mengintegrasikan IMA SDK ke dalam aplikasi pemutar video sederhana. Jika Anda ingin melihat atau mengikuti contoh integrasi yang telah selesai, download contoh sederhana dari GitHub. Jika Anda tertarik dengan pemutar HTML5 yang telah mengintegrasikan SDK, lihat Plugin IMA SDK untuk Video.js.

Ringkasan sisi klien IMA

Penerapan sisi klien IMA melibatkan empat komponen SDK utama, yang ditunjukkan dalam panduan ini:

  • AdDisplayContainer: Objek penampung yang menentukan tempat IMA merender elemen UI iklan dan mengukur visibilitas, termasuk Tampilan Aktif dan Open Measurement.
  • AdsLoader: Objek yang meminta iklan dan menangani peristiwa dari respons permintaan iklan. Anda hanya boleh meng-instance satu pemuat iklan, yang dapat digunakan kembali selama masa aktif aplikasi.
  • AdsRequest: Objek yang menentukan permintaan iklan. Permintaan iklan menentukan URL untuk tag iklan VAST, serta parameter tambahan, seperti dimensi iklan.
  • AdsManager: Objek yang berisi respons terhadap permintaan iklan, mengontrol pemutaran iklan, dan memproses peristiwa iklan yang diaktifkan oleh SDK.

Prasyarat

Sebelum memulai, Anda memerlukan hal berikut:

  • Tiga file kosong:
    • index.html
    • style.css
    • ads.js
  • Python diinstal di komputer Anda, atau server web untuk digunakan dalam pengujian

1. Mulai server pengembangan

Karena IMA SDK memuat dependensi menggunakan protokol yang sama dengan halaman tempat SDK dimuat, Anda harus menggunakan server web untuk menguji aplikasi. Cara paling sederhana untuk memulai server pengembangan lokal adalah dengan menggunakan server bawaan Python.

  1. Dengan menggunakan command line, dari direktori yang berisi file index.html Anda, jalankan: 
      python -m http.server 8000
  2. Di browser web, buka http://localhost:8000/

Anda juga dapat menggunakan server web lain, seperti Apache HTTP Server.

2. Membuat pemutar video sederhana

Pertama, ubah index.html untuk membuat elemen video HTML5 sederhana, yang ada dalam elemen pembungkus, dan tombol untuk memicu pemutaran. Contoh berikut mengimpor IMA SDK dan menyiapkan elemen penampung AdDisplayContainer. Untuk mengetahui detail selengkapnya, lihat langkah-langkah Mengimpor IMA SDK dan Membuat penampung iklan . 

<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

Tambahkan tag yang diperlukan untuk memuat file style.css dan ads.js. Kemudian, ubah styles.css untuk membuat pemutar video responsif untuk perangkat seluler. Terakhir, di ads.js, deklarasikan variabel dan picu pemutaran video saat Anda mengklik tombol putar.

Perhatikan bahwa cuplikan kode ads.js berisi panggilan ke setUpIMA(), yang ditentukan di bagian Initialize the AdsLoader and make an ads request .

3. Mengimpor IMA SDK

Selanjutnya, tambahkan framework IMA menggunakan tag skrip di index.html, sebelum tag untuk ads.js. 

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

4. Membuat penampung iklan

Di sebagian besar browser, IMA SDK menggunakan elemen penampung iklan khusus untuk menampilkan iklan dan elemen UI terkait iklan. Penampung ini harus berukuran untuk menempatkan elemen video dari sudut kiri atas. Tinggi dan lebar iklan yang ditempatkan di penampung ini ditetapkan oleh objek adsManager, sehingga Anda tidak perlu menetapkan nilai ini secara manual.

Untuk menerapkan elemen penampung iklan ini, buat div baru terlebih dahulu dalam elemen video-container. Kemudian, perbarui CSS untuk memosisikan elemen di pojok kiri atas video-element. Terakhir, tambahkan fungsi createAdDisplayContainer() untuk membuat objek AdDisplayContainer menggunakan div penampung iklan baru. 

<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. Lakukan inisialisasi AdsLoader dan buat permintaan iklan

Untuk meminta iklan, buat instance AdsLoader. Konstruktor AdsLoader mengambil objek AdDisplayContainer sebagai input dan dapat digunakan untuk memproses objek AdsRequest yang terkait dengan URL tag iklan tertentu. Tag iklan yang digunakan dalam contoh ini berisi iklan pre-roll 10 detik. Anda dapat menguji URL tag iklan ini, atau URL tag iklan lainnya, menggunakan IMA Video Suite Inspector.

Sebagai praktik terbaik, pertahankan hanya satu instance AdsLoader untuk seluruh siklus proses halaman. Untuk membuat permintaan iklan tambahan, buat objek AdsRequest baru, tetapi gunakan kembali AdsLoader yang sama. Untuk mengetahui informasi selengkapnya, lihat FAQ IMA SDK.

Dengarkan dan tanggapi peristiwa error dan iklan yang dimuat menggunakan AdsLoader.addEventListener. Memproses peristiwa berikut:

  • ADS_MANAGER_LOADED
  • AD_ERROR

Untuk membuat pemroses onAdsManagerLoaded() dan onAdError(), lihat contoh berikut: 

/**
 * 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. Merespons peristiwa AdsLoader

Saat AdsLoader berhasil memuat iklan, AdsLoader akan memancarkan peristiwa ADS_MANAGER_LOADED. Parse peristiwa yang diteruskan ke callback untuk melakukan inisialisasi objek AdsManager. AdsManager memuat iklan satu per satu seperti yang ditentukan oleh respons terhadap URL tag iklan.

Pastikan Anda menangani error apa pun yang terjadi selama proses pemuatan. Jika iklan tidak dimuat, pastikan pemutaran media berlanjut tanpa iklan agar tidak mengganggu pengguna saat melihat konten. 

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

Untuk mengetahui detail selengkapnya tentang pemroses yang ditetapkan dalam fungsi onAdsManagerLoaded(), lihat sub-bagian berikut:

Menangani error AdsManager

Penangan error yang dibuat untuk AdsLoader juga dapat berfungsi sebagai penangan error untuk AdsManager. Lihat pengendali peristiwa yang menggunakan kembali fungsi onAdError(). 

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

Menangani peristiwa putar dan jeda

Saat AdsManager siap menyisipkan iklan untuk ditampilkan, AdsManager akan memicu peristiwa CONTENT_PAUSE_REQUESTED. Tangani peristiwa ini dengan memicu jeda pada pemutar video yang mendasarinya. Demikian pula, saat iklan selesai, AdsManager akan memicu peristiwa CONTENT_RESUME_REQUESTED. Tangani peristiwa ini dengan memulai ulang pemutaran di video konten yang mendasarinya. 

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

Untuk definisi fungsi onContentPauseRequested() dan onContentResumeRequested(), lihat contoh berikut: 

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

Menangani pemutaran konten selama iklan nonlinier

AdsManager menjeda video konten saat iklan siap diputar, tetapi perilaku ini tidak memperhitungkan iklan nonlinier, di mana konten terus diputar saat iklan ditampilkan. 

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

Untuk mendukung iklan non-linear, dengarkan AdsManager untuk memancarkan peristiwa LOADED. Periksa apakah iklan bersifat linear, dan jika tidak, lanjutkan pemutaran pada elemen video.

Untuk definisi fungsi onAdLoaded(), lihat contoh berikut. 

/**
 * 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. Memicu klik untuk menjeda di perangkat seluler

Karena AdContainer menutupi elemen video, pengguna tidak dapat berinteraksi langsung dengan pemutar yang mendasarinya. Hal ini dapat membingungkan pengguna di perangkat seluler, yang berharap dapat mengetuk pemutar video untuk menjeda pemutaran. Untuk mengatasi masalah ini, IMA SDK meneruskan semua klik yang tidak ditangani oleh IMA dari overlay iklan ke elemen AdContainer, tempat klik tersebut dapat ditangani. Hal ini tidak berlaku untuk iklan linear di browser non-seluler, karena mengklik iklan akan membuka link tayang iklan.

Untuk menerapkan fitur klik untuk menjeda, tambahkan fungsi pengendali klik adContainerClick() yang dipanggil di pemroses saat jendela dimuat. 

/**
 * 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. Mulai AdsManager

Untuk memulai pemutaran iklan, mulai dan jalankan AdsManager. Untuk mendukung sepenuhnya browser seluler, tempat Anda tidak dapat memutar iklan secara otomatis, picu pemutaran iklan dari interaksi pengguna dengan halaman, seperti mengklik tombol putar. 

/**
 * 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. Mendukung pengubahan ukuran pemutar

Agar iklan dapat diubah ukurannya secara dinamis dan sesuai dengan ukuran pemutar video, atau agar sesuai dengan perubahan orientasi layar, panggil adsManager.resize() sebagai respons terhadap peristiwa pengubahan ukuran jendela. 

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

Selesai. Sekarang Anda meminta dan menampilkan iklan dengan IMA SDK. Untuk mempelajari fitur SDK lanjutan lainnya, lihat panduan lainnya atau contoh di GitHub.