เริ่มต้นใช้งาน IMA DAI SDK

IMA SDK ช่วยให้ผสานรวมโฆษณามัลติมีเดียลงในเว็บไซต์และแอปได้อย่างง่ายดาย IMA SDK สามารถ ส่งคำขอโฆษณาจาก เซิร์ฟเวอร์โฆษณาที่ปฏิบัติตามข้อกำหนดของ VAST และจัดการการเล่นโฆษณาในแอปของคุณ เมื่อใช้ IMA DAI SDK แอปจะส่งคําขอสตรีมสําหรับโฆษณาและวิดีโอเนื้อหา ไม่ว่าจะเป็น VOD หรือเนื้อหาสด จากนั้น SDK จะแสดงผลลัพธ์ สตรีมวิดีโอแบบรวม คุณจึงไม่ต้องคอยจัดการสลับเปลี่ยนระหว่างโฆษณากับเนื้อหาวิดีโอ ภายในแอป

เลือกโซลูชัน DAI ที่คุณสนใจ

DAI แบบครบวงจร

คู่มือนี้สาธิตวิธีผสานรวม IMA DAI SDK เข้ากับวิดีโอง่ายๆ แอปโปรแกรมเล่น หากคุณต้องการดูหรือติดตามไปพร้อมกับตัวอย่างที่สมบูรณ์ การผสานรวม ให้ดาวน์โหลด ตัวอย่างง่ายๆ จาก GitHub

ภาพรวม IMA DAI

การใช้ IMA DAI SDK ประกอบด้วยคอมโพเนนต์หลัก 2 อย่างตามที่แสดงในคู่มือนี้

  • StreamRequest— VODStreamRequest หรือ LiveStreamRequest: ออบเจ็กต์ที่กำหนดคำขอสตรีม คำขอสตรีมอาจเป็นคำขอสำหรับวิดีโอออนดีมานด์หรือสตรีมแบบสดก็ได้ คำขอระบุรหัสเนื้อหา รวมทั้งคีย์ API หรือโทเค็นการตรวจสอบสิทธิ์ และอื่นๆ พารามิเตอร์
  • StreamManager: ออบเจ็กต์ที่จัดการสตรีมการแทรกโฆษณาแบบไดนามิกและการโต้ตอบกับแบ็กเอนด์ DAI เครื่องมือจัดการสตรีมยังจัดการคําสั่ง ping ในการติดตาม รวมถึงส่งต่อเหตุการณ์ของสตรีมและโฆษณาไปยัง ผู้เผยแพร่โฆษณา

ข้อกำหนดเบื้องต้น

  • ไฟล์ว่าง 3 ไฟล์
    • dai.html
    • dai.css
    • dai.js
  • Python ที่ติดตั้งในคอมพิวเตอร์หรือเว็บเซิร์ฟเวอร์เพื่อใช้ทดสอบ

เริ่มเซิร์ฟเวอร์การพัฒนา

เนื่องจาก IMA DAI SDK จะโหลดไลบรารีที่ใช้ร่วมกันโดยใช้โปรโตคอลเดียวกับหน้าที่โหลด คุณจึงต้องใช้เว็บเซิร์ฟเวอร์เพื่อทดสอบแอป วิธีเริ่มต้นเซิร์ฟเวอร์การพัฒนาในเครื่องอย่างรวดเร็วคือการใช้เซิร์ฟเวอร์ในตัวของ Python

  1. ใช้บรรทัดคำสั่งจากไดเรกทอรีที่มีไฟล์ index.html เรียกใช้:

    python -m http.server 8000
    เท่านั้น

  2. ไปที่ http://localhost:8000/ ในเว็บเบราว์เซอร์

    คุณยังใช้เว็บเซิร์ฟเวอร์อื่นๆ ได้ เช่น Apache HTTP เซิร์ฟเวอร์

สร้างวิดีโอเพลเยอร์ง่ายๆ

ก่อนอื่น ให้แก้ไข dai.html เพื่อสร้างองค์ประกอบวิดีโอ HTML5 แบบง่ายและ div เพื่อใช้สำหรับการคลิกผ่าน นอกจากนี้ ให้เพิ่มแท็กที่จําเป็นเพื่อโหลดไฟล์ dai.css และ dai.js รวมถึงนําเข้าโปรแกรมเล่นวิดีโอ hls.js จากนั้นให้ทำดังนี้ แก้ไข dai.css เพื่อระบุขนาดและตำแหน่งขององค์ประกอบในหน้า สุดท้ายใน dai.js ให้กำหนดตัวแปรเพื่อเก็บคำขอสตรีม และฟังก์ชัน initPlayer() ที่จะเรียกใช้เมื่อโหลดหน้าเว็บ

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

// Livestream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2548831";
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');
}

โหลด IMA DAI SDK

ถัดไป ให้เพิ่มเฟรมเวิร์ก IMA โดยใช้แท็กสคริปต์ใน dai.html ก่อนแท็กสำหรับ 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>

เริ่มต้น StreamManager และส่งคำขอสตรีม

หากต้องการขอชุดโฆษณา ให้สร้าง ima.dai.api.StreamManager ซึ่งมีหน้าที่รับผิดชอบในการขอและจัดการสตรีม DAI เครื่องมือสร้างใช้เวลา และอินสแตนซ์ที่เป็นผลลัพธ์จะนำองค์ประกอบ UI โฆษณามาจัดการกับโฆษณา คลิก

จากนั้นกำหนดฟังก์ชันที่จะขอสตรีม ตัวอย่างนี้ประกอบด้วยฟังก์ชันสำหรับทั้ง VOD และสตรีมแบบสด ซึ่งสร้างอินสแตนซ์ของ VODStreamRequest และ LiveStreamRequest ตามลำดับ จากนั้นเรียกใช้ streamManager.requestStream() ด้วยพารามิเตอร์ streamRequest สำหรับสตรีมแบบสด คุณต้องเพิ่ม ตัวแฮนเดิลเพื่อฟังเหตุการณ์ข้อมูลเมตาตามกำหนดเวลา และส่งต่อเหตุการณ์ไปยัง StreamManager คุณสามารถใส่หมายเหตุหรือยกเลิกหมายเหตุโค้ดให้เหมาะกับกรณีการใช้งานของคุณได้ ทั้ง 2 วิธีจะใช้คีย์ API ที่ไม่บังคับ หากใช้สตรีมที่มีการป้องกัน คุณจะ จำเป็นต้อง สร้างคีย์การตรวจสอบสิทธิ์ DAI

สตรีมในตัวอย่างนี้ไม่มีการป้องกัน จึงไม่ใช้ apiKey

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

จัดการเหตุการณ์สตรีม

ขั้นตอนสุดท้าย คุณต้องใช้ Listener เหตุการณ์สำหรับเหตุการณ์วิดีโอที่สำคัญ ตัวอย่างที่เรียบง่ายนี้จัดการเหตุการณ์ LOADED, ERROR, AD_BREAK_STARTED และ AD_BREAK_ENDED โดยการเรียกใช้ฟังก์ชัน onStreamEvent() ฟังก์ชันนี้ จัดการการโหลดสตรีมและข้อผิดพลาด รวมถึงการปิดใช้ตัวควบคุมวิดีโอเพลเยอร์ ขณะที่โฆษณากำลังเล่น ซึ่ง SDK จำเป็นต้องใช้ เมื่อสตรีมกำลัง ที่โหลด วิดีโอเพลเยอร์จะโหลดและเล่น URL ที่ระบุโดยใช้ loadUrl()

คุณอาจต้องตั้งค่า Listener เหตุการณ์สำหรับ pause ขององค์ประกอบวิดีโอด้วย และ start เหตุการณ์เพื่ออนุญาตให้ผู้ใช้เล่นต่อเมื่อ IMA หยุดชั่วคราว ระหว่างช่วงพักโฆษณา

หากต้องการใช้ DAI โปรแกรมเล่นที่กำหนดเองต้องส่งเหตุการณ์ ID3 สำหรับสตรีมแบบสดไปยัง IMA DAI SDK ตามที่แสดงในโค้ดตัวอย่าง

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

เท่านี้ก็เรียบร้อย ตอนนี้คุณกำลังขอและแสดงโฆษณาด้วย IMA DAI SDK หากต้องการดูข้อมูลเกี่ยวกับฟีเจอร์ขั้นสูงเพิ่มเติมของ SDK โปรดดูคู่มืออื่นๆ หรือตัวอย่างใน GitHub