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

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

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

DAI สำหรับบริการเต็มรูปแบบ

คู่มือนี้แสดงวิธีผสานรวม IMA 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 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 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 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 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 SDK หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับฟีเจอร์ SDK ขั้นสูง โปรดดูคำแนะนำอื่นๆ หรือตัวอย่างเกี่ยวกับ GitHub