Menyiapkan dengan DAI layanan penuh

Pilih platform: HTML5 Android iOS tvOS Cast Roku

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 yang ditentukan, dan kode jaringan Google Ad Manager untuk IMA SDK guna 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 aliran juga menangani ping pelacakan serta meneruskan peristiwa aliran dan iklan ke penayang.

Prasyarat

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

Memulai server pengembangan

Karena IMA DAI SDK memuat dependensi menggunakan protokol yang sama dengan halaman tempatnya 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 Server HTTP Apache.

Membuat pemutar video

Pertama, ubah dai.html untuk membuat elemen video HTML5 dan div yang akan digunakan untuk klik-tayang. 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>


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

#adUi {
  cursor: pointer;
}

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

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

Untuk melanjutkan pemutaran selama jeda iklan yang dijeda, siapkan pemroses peristiwa untuk peristiwa pause dan start elemen video guna 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';
}

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>

Melakukan inisialisasi StreamManager

Untuk meminta kumpulan iklan, buat ima.dai.api.StreamManager, yang bertanggung jawab untuk meminta dan mengelola streaming DAI. Konstruktor menggunakan 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);
}

Membuat permintaan streaming

Tentukan fungsi untuk meminta streaming. Contoh ini mencakup fungsi untuk VOD dan livestream, 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);
}

Kedua metode permintaan streaming menggunakan kunci API opsional. Jika menggunakan streaming yang dilindungi, Anda harus 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 berjangka waktu dan meneruskan peristiwa ke class StreamManager agar IMA dapat 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);
      });
    }
  });
}

Panduan ini menggunakan pemutar hls.js untuk pemutaran streaming, tetapi implementasi 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 penonaktifan 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();
  });
}

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

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