เริ่มต้นใช้งาน 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: ออบเจ็กต์ที่กำหนดคำขอสตรีม คำขอสตรีมอาจเป็นวิดีโอออนดีมานด์หรือสตรีมแบบสดก็ได้ คำขอจะระบุ Content ID รวมถึงคีย์ API หรือโทเค็นการตรวจสอบสิทธิ์ และพารามิเตอร์อื่นๆ
  • StreamManager: ออบเจ็กต์ที่จัดการสตรีมการแทรกโฆษณาแบบไดนามิกและการโต้ตอบกับแบ็กเอนด์ DAI นอกจากนี้ ตัวจัดการสตรีมยังจัดการคําสั่ง ping ของการติดตาม รวมถึงส่งต่อเหตุการณ์ของสตรีมและเหตุการณ์โฆษณาไปยังผู้เผยแพร่โฆษณาอีกด้วย

สิ่งที่ต้องดำเนินการก่อน

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

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

เนื่องจาก IMA DAI SDK โหลดทรัพยากร Dependency โดยใช้โปรโตคอลเดียวกับหน้าเว็บที่โหลดมา คุณจึงต้องใช้เว็บเซิร์ฟเวอร์เพื่อทดสอบแอป วิธีเริ่มต้นอย่างรวดเร็วในเซิร์ฟเวอร์การพัฒนาภายในคือการใช้เซิร์ฟเวอร์ในตัวของ 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