Menyiapkan IMA SDK untuk DAI

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 IMA DAI SDK, aplikasi membuat permintaan streaming untuk video iklan dan konten—baik konten VOD maupun live. Kemudian, SDK akan menampilkan streaming video gabungan, sehingga Anda tidak perlu mengelola peralihan antara video iklan dan konten dalam aplikasi Anda.

Pilih solusi DAI yang Anda minati

DAI layanan lengkap

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

Ringkasan IMA DAI

Penerapan IMA DAI SDK melibatkan dua komponen utama seperti yang ditunjukkan dalam panduan ini:

  • StreamRequest— VODStreamRequest atau LiveStreamRequest: Objek yang menentukan permintaan streaming. Permintaan streaming dapat berupa video-on-demand atau live stream. Permintaan live stream menentukan kunci aset, sedangkan permintaan VOD menentukan ID CMS dan ID video. Kedua jenis permintaan dapat secara opsional menyertakan kunci API yang diperlukan untuk mengakses streaming tertentu, dan kode jaringan Google Ad Manager agar IMA SDK menangani ID iklan seperti yang ditentukan dalam setelan Google Ad Manager.
  • StreamManager: Objek yang menangani streaming penyisipan iklan dinamis dan interaksi dengan backend DAI. Pengelola streaming juga menangani pelacakan ping dan meneruskan peristiwa streaming dan iklan ke penayang.

Prasyarat

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

Mulai server pengembangan

Karena IMA DAI SDK memuat dependensi menggunakan protokol yang sama dengan halaman tempat SDK dimuat, Anda harus menggunakan server web untuk menguji aplikasi. Cara cepat 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.

Membuat pemutar video

Pertama, ubah dai.html untuk membuat elemen video HTML5 dan div yang akan digunakan untuk click-through. Contoh berikut mengimpor IMA DAI SDK. Untuk mengetahui detail selengkapnya, lihat Mengimpor IMA DAI SDK.

Selain itu, tambahkan 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, fungsi initPlayer() yang akan dijalankan saat halaman dimuat, dan siapkan tombol putar untuk meminta streaming saat diklik.

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>


dai.html
 
#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}

dai.css
 
// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}
dai.js

Untuk melanjutkan pemutaran selama jeda iklan yang dijeda, siapkan pemroses peristiwa untuk peristiwa pause dan start elemen video untuk menampilkan dan menyembunyikan kontrol pemutar.

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}
dai.js

Memuat IMA DAI SDK

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

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
dai.html

Menginisialisasi StreamManager

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

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}
dai.js

Membuat permintaan streaming

Tentukan fungsi untuk meminta streaming. Contoh ini mencakup fungsi untuk VOD dan live stream, yang membuat instance class VODStreamRequest dan class LiveStreamRequest. Setelah memiliki instance streamRequest, panggil metode streamManager.requestStream() dengan instance permintaan streaming.

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}
dai.js

Kedua metode permintaan streaming mengambil kunci API opsional. Jika menggunakan streaming yang dilindungi, Anda perlu membuat kunci autentikasi DAI. Untuk mengetahui detail selengkapnya, lihat Mengautentikasi permintaan streaming video DAI. Tidak ada streaming dalam contoh ini yang dilindungi menggunakan kunci autentikasi DAI, sehingga apiKey tidak digunakan.

Mengurai metadata streaming

Anda juga perlu menambahkan pengendali untuk memproses peristiwa metadata berwaktu dan meneruskan peristiwa ke class StreamManager agar IMA memunculkan peristiwa iklan selama jeda iklan:

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Timed metadata is handled differently by different video players, and the
  // IMA SDK provides two ways to pass in metadata,
  // StreamManager.processMetadata() and StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we 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);
      });
    }
  });
}
dai.js

Panduan ini menggunakan pemutar hls.js untuk pemutaran streaming, tetapi penerapan metadata Anda bergantung pada jenis pemutar yang Anda gunakan.

Menangani peristiwa streaming

Terapkan pemroses peristiwa untuk peristiwa video utama. Contoh ini menangani peristiwa LOADED, ERROR, AD_BREAK_STARTED, dan AD_BREAK_ENDED dengan memanggil fungsi onStreamEvent(). Fungsi ini menangani pemuatan streaming, error streaming, dan menonaktifkan kontrol pemutar selama pemutaran iklan, yang diperlukan oleh IMA SDK.

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
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');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
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();
  });
}
dai.js

Saat streaming dimuat, pemutar video memuat dan memutar URL yang diberikan menggunakan fungsi loadUrl().

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