Mulai menggunakan IMA DAI SDK

IMA SDK memudahkan pengintegrasian iklan multimedia ke dalam situs dan aplikasi Anda. IMA SDK dapat minta iklan dari mana pun 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 iklan dan video konten dalam aplikasi.

Pilih solusi DAI yang Anda minati

Layanan lengkap Penyaluran pod

Pod yang menyalurkan DAI

Panduan ini menunjukkan cara memutar streaming Penayangan Pod DAI untuk live streaming atau VOD konten, menggunakan IMA DAI SDK untuk HTML5 dengan pemutar video yang mengandalkan hls.js untuk pemutaran. Jika Anda ingin melihat atau mengikuti contoh integrasi yang telah selesai, dengan dukungan untuk HLS.js dan Pemutaran Safari, lihat contoh penayangan pod HLS. Untuk dukungan DASH.js, lihat contoh penayangan pod DASH. Anda dapat mendownload aplikasi contoh ini dari halaman rilis GitHub DAI HTML5.

Catatan: IMA DAI SDK untuk HTML5 mendukung streaming HLS dan DASH, tetapi pemutaran masing-masing memerlukan pemutar media atau ekstensi yang berbeda seperti HLS.js atau DASH.js, dengan penerapan yang bervariasi.

Panduan ini menjelaskan cara mengonfigurasi HLS.js dan IMA DAI SDK untuk memutar streaming HLS, dengan catatan penting tentang perbedaan implementasi untuk DASH.

Lihat IMA Aplikasi contoh DASH.js untuk titik awal menerapkan aliran data DAI DASH dengan IMA.

Poin Penting: Untuk menggunakan Penayangan Pod DAI, Anda harus bekerja dengan penayangan pod partner dan harus memiliki akun Ad Manager 360 Akun lanjutan. Jika Anda memiliki akun Ad Manager, hubungi Account Manager Anda untuk mengetahui detail selengkapnya. Untuk mengetahui informasi tentang cara mendaftar ke Ad Manager, buka Pusat Bantuan Ad Manager.

Catatan: Untuk informasi tentang integrasi dengan platform lain, atau tentang penggunaan SDK sisi klien IMA, lihat Interactive Media Ads SDK.

Ringkasan Penayangan Pod DAI

Menerapkan penayangan pod menggunakan IMA DAI SDK melibatkan dua komponen utama, yang ditunjukkan dalam panduan ini:

• PodStreamRequest / PodVodStreamRequest: Objek yang menentukan permintaan streaming untuk server iklan Google. Permintaan menentukan Kode Jaringan, dan PodStreamRequest juga memerlukan Kunci Aset Kustom, dan kunci API opsional. Keduanya menyertakan parameter opsional lainnya.

• StreamManager: Objek yang menangani komunikasi antara streaming video dan IMA DAI SDK, seperti mengaktifkan ping pelacakan dan meneruskan peristiwa streaming 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 atau lingkungan pengembangan yang dihosting lainnya untuk digunakan dalam pengujian

Mengonfigurasi lingkungan pengembangan

Karena SDK memuat dependensi menggunakan protokol yang sama dengan halaman dari yang dimuat, Anda perlu menggunakan server web untuk menguji aplikasi Anda. Singkat cara untuk memulai server pengembangan lokal adalah dengan menggunakan server bawaan Python.

1. Dengan menggunakan command line, dari direktori yang berisi file index.html, jalankan:

   python -m http.server 8000
   

   Catatan: http.server hanya tersedia di Python 3.x.

2. Di browser web, buka http://localhost:8000/

   Anda juga dapat menggunakan server web atau lingkungan pengembangan yang dihosting lainnya, seperti Apache HTTP Server.

Membuat pemutar video sederhana

Catatan: Panduan ini mengasumsikan bahwa Anda menggunakan library HLS.js untuk memutar HLS feed. IMA DAI SDK untuk HTML5 juga dapat mendukung streaming DASH, dengan library yang sesuai seperti pemutar Shaka atau DASH.js.

Pertama, ubah dai.html untuk membuat elemen video HTML5 sederhana dan div untuk untuk elemen UI Iklan. Tambahkan juga tag yang diperlukan untuk memuat class dai.css dan dai.js, serta 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.

Konstanta permintaan streaming adalah sebagai berikut:

• BACKUP_STREAM: URL untuk streaming cadangan yang akan diputar jika proses iklan mengalami error fatal.

• STREAM_URL: Hanya digunakan untuk live stream. URL streaming video yang disediakan oleh manipulator manifes atau partner pihak ketiga yang menggunakan inferensi pod. Anda harus memasukkan ID streaming yang disediakan oleh IMA DAI SDK sebelum membuat permintaan. Dalam hal ini, URL streaming menyertakan placeholder, [[STREAMID]], yang diganti dengan ID streaming sebelum membuat permintaan.

• NETWORK_CODE: Kode jaringan untuk akun Ad Manager 360 Anda.

• CUSTOM_ASSET_KEY: Hanya digunakan untuk live stream. Kunci aset kustom yang mengidentifikasi peristiwa penayangan pod di Ad Manager 360. Ini dapat dibuat oleh manipulator manifes atau partner penayangan pod pihak ketiga.

• API_KEY: Hanya digunakan untuk live stream. Kunci API opsional yang dapat untuk mengambil ID streaming dari IMA DAI SDK.

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 DAI SDK 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'

// Stream Config.
const STREAM_URL = "https://encodersim.sandbox.google.com/masterPlaylist/...&stream_id=[[STREAMID]]";
const NETWORK_CODE = "51636543";
const CUSTOM_ASSET_KEY = "google-sample";
const API_KEY = "";

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

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

Memuat IMA DAI SDK

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

Catatan: Untuk menerima log konsol yang lebih panjang, Anda dapat mengganti ima3_dai.js dengan ima3_dai_debug.js. Namun, ima3_dai_debug.js tidak boleh digunakan dalam aplikasi produksi.

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

Melakukan inisialisasi StreamManager dan membuat permintaan streaming live atau VOD

Penayangan pod livestream

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 iklan interaksi.

Kemudian, tentukan fungsi untuk meminta livestream yang menyalurkan pod. Fungsi ini pertama-tama membuat PodStreamRequest, mengonfigurasinya dengan parameter streamRequest yang disediakan pada langkah 2, lalu memanggil streamManager.requestStream() dengan objek permintaan tersebut.

Poin Penting: Tidak ada aliran data dalam contoh ini yang dilindungi, sehingga apiKey tidak digunakan. Jika streaming Anda memerlukan Kunci API, lihat Mengautentikasi permintaan streaming video DAI.

dai.js

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

  requestLivePodStream(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
}

function requestLivePodStream(networkCode, customAssetKey, apiKey) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving live Stream Request
  const streamRequest = new google.ima.dai.api.PodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.customAssetKey = customAssetKey;
  streamRequest.apiKey = apiKey;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

Penayangan pod VOD

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 interaksi iklan.

Kemudian, tentukan fungsi untuk meminta pod yang menayangkan streaming VOD. Fungsi ini membuat PodVodStreamRequest terlebih dahulu, mengonfigurasinya dengan streamRequest yang diberikan pada langkah 2, lalu memanggil streamManager.requestStream() dengan objek permintaan tersebut.

dai.js

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

  requestVodPodStream(NETWORK_CODE);
}

function requestVodPodStream(networkCode) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving VOD Stream Request
  const streamRequest = new google.ima.dai.api.PodVodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

Menangani peristiwa streaming

Penayangan pod livestream

Selanjutnya, terapkan pemroses peristiwa untuk peristiwa video utama. Contoh ini menangani peristiwa STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED, dan AD_BREAK_ENDED dengan memanggil fungsi onStreamEvent(). Fungsi ini menangani pemuatan dan error streaming, serta menonaktifkan kontrol pemutar saat iklan diputar, yang diperlukan oleh SDK. Saat streaming dimuat, pemutar video akan memuat dan memutar URL yang disediakan menggunakan fungsi loadStream().

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    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.STREAM_INITIALIZED:
      console.log('Stream initialized');
      loadStream(e.getStreamData().streamId);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream('');
      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 loadStream(streamID) {
  var url;
  if(streamID) {
    url = STREAM_URL.replace('[[STREAMID]]', streamID);
  } else {
    console.log('Stream Initialization Failed');
    url = BACKUP_STREAM;
  }
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
}

Penayangan pod VOD

Selanjutnya, terapkan pemroses peristiwa untuk peristiwa video besar. Contoh ini menangani peristiwa STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED, dan AD_BREAK_ENDED dengan memanggil fungsi onStreamEvent(). Fungsi ini menangani pemuatan dan error streaming, serta menonaktifkan kontrol pemutar saat iklan diputar, yang diperlukan oleh SDK.

Selain itu, streaming penayangan pod VOD memerlukan panggilan StreamManager.loadStreamMetadata() sebagai respons terhadap peristiwa STREAM_INITIALIZED. Anda juga perlu meminta URL streaming dari, partner teknologi video (VTP). Setelah panggilan loadStreamMetadata() berhasil tindakan ini memicu peristiwa LOADED, tempat Anda harus memanggil fungsi loadStream() dengan URL streaming Anda untuk memuat dan memutar streaming.

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    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.STREAM_INITIALIZED:
      const streamId = e.getStreamData().streamId;
      // 'vtpInterface' is a place holder for your own video technology
      //  partner (VTP) API calls.
      vtpInterface.requestStreamURL({
        'streamId': streamId,
      })
      .then( (vtpStreamUrl) => {
        streamUrl = vtpStreamUrl;
        streamManager.loadStreamMetadata();
      }, (error) => {
        // Handle the error.
      });
      break;
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      loadStream(streamUrl);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream();
      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 loadStream(url) {
  if(url) {
    console.log('Loading:' + url);
    hls.loadSource(url);
  } else {
    console.log('Stream Initialization Failed');
    hls.loadSource(BACKUP_STREAM);
  }
  hls.attachMedia(videoElement);
}

Menangani metadata streaming

Pada langkah ini, Anda akan menerapkan pemroses peristiwa untuk metadata guna memberi tahu SDK saat peristiwa iklan terjadi. Pemrosesan peristiwa metadata dalam streaming dapat bervariasi, bergantung pada format streaming (HLS atau DASH), jenis streaming (streaming Live atau VOD), jenis pemutar, dan jenis backend DAI yang digunakan. Lihat Timed Metadata kami untuk informasi selengkapnya.

Format streaming HLS (streaming VOD dan Live, pemutar HLS.js)

Jika Anda menggunakan pemutar HLS.js, dengarkan peristiwa FRAG_PARSING_METADATA HLS.js untuk mendapatkan metadata ID3 dan meneruskannya ke SDK dengan StreamManager.processMetadata().

Untuk memutar video secara otomatis setelah semuanya dimuat dan siap, dengarkan peristiwa MANIFEST_PARSED HLS.js untuk memicu pemutaran.

function loadStream(streamID) {
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  
  // Timed metadata is passed HLS stream events to the streamManager.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
  hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}

function parseID3Events(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((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
}

function startPlayback() {
  console.log('Video Play');
  videoElement.play();
}

DASH.js (format streaming DASH, jenis streaming Live dan VOD)

Jika Anda menggunakan pemutar DASH.js, Anda harus menggunakan string yang berbeda untuk memproses metadata ID3 untuk Live atau VOD feed:

• Livestream: 'https://developer.apple.com/streaming/emsg-id3'
• Streaming VOD: 'urn:google:dai:2018'

Teruskan metadata ID3 ke SDK dengan StreamManager.processMetadata().

Untuk menampilkan kontrol video secara otomatis setelah semuanya dimuat dan siap, proses peristiwa MANIFEST_LOADED DASH.js.

const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);

function processMetadata(metadataEvent) {
  const messageData = metadataEvent.event.messageData;
  const timestamp = metadataEvent.event.calculatedPresentationTime;

  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with dash.js.
  streamManager.processMetadata('ID3', messageData, timestamp);
}

function loadlistener() {
  showControls();

  // This listener must be removed, otherwise it triggers as addional
  // manifests are loaded. The manifest is loaded once for the content,
  // but additional manifests are loaded for upcoming ad breaks.
  dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}

Shaka Player dengan livestream (format streaming DASH)

Jika Anda menggunakan pemutar Shaka untuk pemutaran live stream, gunakan string 'emsg' untuk memproses peristiwa metadata. Kemudian, gunakan data pesan peristiwa dalam panggilan Anda ke StreamManager.onTimedMetadata().

shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));

function onEmsgEvent(metadataEvent) {
  // Use StreamManager.onTimedMetadata() if your video player provides
  // processed metadata, as with Shaka player livestreams.
  streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}

Shaka Player dengan streaming VOD (format streaming DASH)

Jika Anda menggunakan pemutar Shaka untuk pemutaran streaming VOD, gunakan string 'timelineregionenter' untuk memproses peristiwa metadata. Kemudian, gunakan data pesan peristiwa dalam panggilan Anda untuk StreamManager.processMetadata() dengan string 'urn:google:dai:2018'.

shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));

function onTimelineEvent(metadataEvent) {
  const detail = metadataEvent.detail;
  if ( detail.eventElement.attributes &&
       detail.eventElement.attributes['messageData'] &&
       detail.eventElement.attributes['messageData'].value ) {
        const mediaId = detail.eventElement.attributes['messageData'].value;
        const pts = detail.startTime;
        // Use StreamManager.processMetadata() if your video player provides raw
        // ID3 tags, as with Shaka player VOD streams.
        streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
       }
}

Menangani peristiwa pemain

Tambahkan pemroses peristiwa ke peristiwa pause dan start elemen video untuk mengizinkan pengguna untuk melanjutkan pemutaran saat SDK dijeda selama jeda iklan.

function loadStream(streamUrl) {
  ...
  
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);
}

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 di streaming penayangan pod dengan IMA DAI SDK untuk HTML5. Untuk mempelajari fitur SDK lanjutan lainnya, lihat panduan lain atau contoh di GitHub.