Memulai

IMA SDK memudahkan pengintegrasian iklan multimedia ke dalam situs dan aplikasi Anda. IMA SDK dapat minta iklan dari semua server iklan yang sesuai dengan VAST dan mengelola pemutaran iklan di aplikasi Anda. Dengan SDK sisi klien IMA, Anda mempertahankan kontrol atas pemutaran video konten, sedangkan 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 yang ingin melihat atau mengikuti integrasi contoh yang telah selesai, unduh contoh sederhana dari GitHub. Jika Anda tertarik pada pemutar HTML5 dengan SDK pra-integrasi, lihat Plugin IMA SDK untuk Video.js.

Ringkasan sisi klien IMA

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

  • AdDisplayContainer: Objek penampung tempat iklan dirender.
  • AdsLoader: Objek yang meminta iklan dan menangani peristiwa dari respons permintaan iklan. Anda hanya boleh membuat instance satu loader iklan, yang dapat digunakan kembali selama masa pakai 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 iklan yang diaktifkan oleh SDK.

Prasyarat

Sebelum memulai, Anda memerlukan hal berikut:

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

1. Memulai server pengembangan

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

  1. Menggunakan baris perintah, dari direktori yang berisi file index.html Anda akan dijalankan: 
      python -m http.server 8000
  2. Di browser web, buka http://localhost:8000/

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

2. Membuat pemutar video sederhana

Pertama, ubah index.html untuk membuat elemen video HTML5 sederhana, yang dimuat dalam wrapper dan tombol untuk memicu pemutaran. Tambahkan juga tag yang diperlukan untuk memuat style.css dan ads.js. Kemudian, ubah styles.css untuk membuat pemutar video responsif untuk perangkat seluler. Terakhir, di ads.js, picu pemutaran video saat pemutaran diklik.

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

Setelah menyelesaikan langkah ini, saat Anda membuka index.html di browser (melalui proses pengembangan server) Anda akan dapat melihat elemen video dan video akan dimulai saat Anda mengklik tombol putar.

3. Mengimpor IMA SDK

Selanjutnya, tambahkan framework IMA menggunakan tag skrip di index.html, sebelum tag untuk 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. Lampirkan pengendali pemutar video dan halaman

Untuk mengubah perilaku pemutar video dengan JavaScript, tambahkan pengendali peristiwa yang memicu tindakan berikut:

  • Saat halaman selesai dimuat, lakukan inisialisasi IMA SDK.
  • Saat tombol putar video diklik, muat iklan (kecuali jika sudah ada iklan yang dimuat).
  • Saat ukuran jendela browser diubah, perbarui elemen video dan adsManager dimensi untuk membuat halaman responsif di perangkat seluler
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. Membuat penampung iklan

Di sebagian besar browser, IMA SDK menggunakan elemen penampung iklan khusus untuk menampilkan iklan dan yang terkait dengan iklan. Penampung ini harus berukuran agar dapat menempatkan elemen video dari di pojok kiri atas. Tinggi dan lebar iklan yang ditempatkan di penampung ini ditetapkan oleh 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 kiri atas sudut video-element. Terakhir, tentukan variabel untuk penampung di dalam Fungsi initializeIMA() yang berjalan saat halaman dimuat.

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. Melakukan inisialisasi AdsLoader dan membuat permintaan iklan

Untuk meminta kumpulan iklan, buat instance ima.AdsLoader. Instance ini mengambil objek AdDisplayContainer sebagai input dan dapat digunakan untuk memproses ima.AdsRequest objek yang terkait dengan URL tag iklan yang ditentukan. Tag iklan yang digunakan di contoh ini berisi iklan pre-roll 10 detik. Anda dapat menguji URL tag iklan ini atau URL tag iklan apa pun menggunakan IMA Video Suite Inspector.

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

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. Memproses peristiwa AdsLoader

Saat iklan berhasil dimuat, ima.AdsLoader akan memunculkan Peristiwa ADS_MANAGER_LOADED. Mengurai peristiwa yang diteruskan ke callback untuk melakukan inisialisasi Objek AdsManager. AdsManager memuat masing-masing iklan seperti yang ditentukan oleh respons terhadap iklan URL tag.

Selain itu, pastikan Anda menangani error yang mungkin terjadi selama proses pemuatan. Jika iklan tidak memuat, pastikan pemutaran media berlanjut, tanpa iklan, agar tidak mengganggu pengalaman pengguna.

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

Untuk memulai pemutaran iklan, Anda harus memulai AdsManager. Untuk mendukung perangkat seluler sepenuhnya {i>browser<i}, hal ini harus dipicu oleh interaksi pengguna.

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. Membuat AdsManager menjadi responsif

Untuk memastikan bahwa ukuran iklan diubah secara dinamis agar sesuai dengan ukuran pemutar video, jika layar mengubah ukuran atau orientasi, peristiwa pengubahan ukuran jendela harus memanggil 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. Memproses peristiwa AdsManager

AdsManager juga mengaktifkan beberapa peristiwa yang harus ditangani. Peristiwa ini digunakan untuk melacak perubahan status, memicu pemutaran dan jeda pada video konten, serta mencatat error.

Menangani error

Pengendali error yang dibuat untuk AdsLoader dapat berfungsi sebagai pengendali error untuk AdsManager dengan menambahkan pengendali peristiwa baru dengan fungsi callback yang sama.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

Memicu peristiwa putar dan jeda

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

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

Memicu klik untuk menjeda pada perangkat seluler

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

Untuk menerapkan klik untuk menjeda, tambahkan pengendali klik ke AdContainer dan picu pemutaran atau menjeda peristiwa pada video yang mendasarinya.

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

...

Memicu pemutaran pada iklan non-linear

AdsManager menjeda video konten saat iklan siap diputar, tetapi perilaku ini tidak memperhitungkan iklan non-linear, yang mana konten seharusnya terus diputar yang ditampilkan. Untuk mendukung iklan non-linear, proses AdsManager untuk memunculkan Peristiwa LOADED. Kemudian, periksa apakah iklan tersebut linear, dan jika tidak, lanjutkan pemutaran pada elemen video.

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

Selesai. Sekarang Anda meminta dan menampilkan iklan dengan IMA SDK. Untuk mempelajari lebih lanjut yang lebih canggih, lihat panduan lainnya atau sampel di GitHub.