เริ่มต้นใช้งาน 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);
}

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

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

นอกจากนี้ คุณอาจต้องตั้งค่า Listeners เหตุการณ์สําหรับเหตุการณ์ 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