Mulai

IMA SDK memudahkan integrasi iklan multimedia ke situs dan aplikasi Anda. IMA SDK dapat meminta iklan dari server iklan yang sesuai dengan VAST dan mengelola pemutaran iklan di aplikasi Anda. Dengan IMA DAI SDK, aplikasi membuat permintaan streaming untuk iklan dan video konten, baik VOD maupun konten live. SDK kemudian menampilkan streaming video gabungan, sehingga Anda tidak perlu mengelola peralihan antara video iklan dan konten dalam aplikasi.

Panduan ini menunjukkan cara mengintegrasikan IMA SDK ke dalam aplikasi pemutar video sederhana. Jika Anda ingin melihat atau mengikuti integrasi contoh yang telah selesai, download contoh sederhana dari GitHub.

Ringkasan DAI DAI

Untuk menerapkan IMA DAI melibatkan dua komponen SDK utama, yang ditunjukkan dalam panduan ini:

  • StreamRequest VODStreamRequest atau LiveStreamRequest: Objek yang menentukan permintaan streaming. Permintaan streaming dapat berupa untuk video on demand atau live stream. Permintaan menentukan Content ID, serta kunci API atau token autentikasi dan parameter lainnya.
  • StreamManager: Objek yang menangani streaming penyisipan iklan dinamis dan interaksi dengan backend DAI. Pengelola streaming juga menangani pelacakan ping dan meneruskan streaming dan peristiwa iklan ke penayang.

Prasyarat

Sebelum memulai, Anda memerlukan hal berikut:

  • Tiga file kosong
    • dai.html
    • dai.css
    • dai.js
  • Python yang diinstal di komputer Anda, atau server web yang digunakan untuk pengujian

1. Memulai server pengembangan

Karena IMA SDK memuat dependensi melalui protokol yang sama dengan halaman tempatnya dimuat, Anda harus menggunakan server web untuk menguji aplikasi. Cara termudah 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 lainnya, seperti Server HTTP Apache.

2. Membuat pemutar video sederhana

Pertama, ubah dai.html untuk membuat elemen video HTML5 sederhana dan div yang akan digunakan untuk klik-tayang. Tambahkan juga tag yang diperlukan untuk memuat file dai.css dan dai.js, serta untuk mengimpor pemutar video hls.js. Kemudian, ubah dai.css untuk menentukan ukuran dan posisi elemen halaman. Terakhir, di dai.js, tentukan variabel untuk menyimpan informasi permintaan streaming dan fungsi initPlayer() yang akan dijalankan saat halaman dimuat.

dai.html


<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
    <video id="video"></video>
    <div id="ad-ui"></div>
</body>
</html>

dai.css

#video,
#ad-ui {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#ad-ui {
  cursor: pointer;
}

dai.js

var BACKUP_STREAM =
    'https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8'

// Live stream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2528370";
var TEST_VIDEO_ID = "tears-of-steel";

var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;
var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
}

3. Memuat IMA SDK

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

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>

...

4. Melakukan inisialisasi StreamManager dan membuat permintaan streaming

Untuk meminta kumpulan iklan, buat ima.dai.api.StreamManager, yang bertanggung jawab untuk meminta dan mengelola streaming DAI. Konstruktor mengambil elemen video dan instance yang dihasilkan mengambil elemen UI iklan untuk menangani klik iklan.

Kemudian, tentukan fungsi yang meminta streaming. Contoh ini menyertakan fungsi untuk VOD dan live stream, yang membuat instance VODStreamRequest dan LiveStreamRequest, lalu memanggil streamManager.requestStream() dengan parameter streamRequest. Untuk live stream, Anda juga perlu menambahkan pengendali untuk memproses peristiwa metadata dengan waktu dan meneruskan peristiwa ke StreamManager. Anda dapat mengomentari atau menghapus tanda komentar pada kode agar sesuai dengan kasus penggunaan Anda. Kedua metode mengambil kunci API opsional. Jika menggunakan streaming terenkripsi, Anda harus membuat kunci autentikasi DAI.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  // Timed metadata is only used for LIVE streams.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in the metadata, pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });

  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, null);
  // Uncomment the line below and comment out the one above to request a
  // LIVE stream instead of a VOD stream.
  //requestLiveStream(TEST_ASSET_KEY, null);
}

function requestVODStream(cmsId, videoId, apiKey) {
  var streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

function requestLiveStream(assetKey, apiKey) {
  var streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

5. Menangani peristiwa streaming

Terakhir, Anda perlu menerapkan pemroses peristiwa untuk peristiwa video utama. Contoh sederhana ini menangani peristiwa LOADED, ERROR, AD_BREAK_STARTED, dan AD_BREAK_ENDED dengan memanggil fungsi onStreamEvent(). Fungsi ini menangani pemuatan streaming dan error, serta menonaktifkan kontrol pemutar saat iklan diputar, yang diwajibkan oleh SDK. Saat streaming dimuat, pemutar video memuat dan memutar URL yang disediakan menggunakan fungsi loadUrl().

Sebaiknya Anda juga menyiapkan pemroses peristiwa untuk peristiwa pause dan start elemen video agar pengguna dapat melanjutkan pemutaran saat IMA dijeda selama jeda iklan.

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);

  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.LOADED,
     google.ima.dai.api.StreamEvent.Type.ERROR,
     google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
     google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);

...

function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      console.log('Stream loaded');
      loadUrl(e.getStreamData().url);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadUrl(BACKUP_STREAM);
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

function loadUrl(url) {
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  hls.on(Hls.Events.MANIFEST_PARSED, function() {
    console.log('Video Play');
    videoElement.play();
  });
}

function onStreamPause() {
  console.log('paused');
  if (isAdBreak) {
    videoElement.controls = true;
    adUiElement.style.display = 'none';
  }
}

function onStreamPlay() {
  console.log('played');
  if (isAdBreak) {
    videoElement.controls = false;
    adUiElement.style.display = 'block';
  }
}

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