ตั้งค่า IMA SDK สําหรับ DAI

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: ออบเจ็กต์ที่กําหนดคําขอสตรีม คำขอสตรีมอาจเป็นคำขอสำหรับวิดีโอออนดีมานด์หรือสตรีมแบบสดก็ได้ คำขอสตรีมแบบสดจะระบุคีย์เนื้อหา ส่วนคำขอ VOD จะระบุรหัส CMS และรหัสวิดีโอ คําขอทั้ง 2 ประเภทอาจระบุคีย์ API ที่จําเป็นสําหรับเข้าถึงสตรีมที่ระบุ และรหัสเครือข่าย Google Ad Manager สําหรับ IMA SDK เพื่อจัดการตัวระบุโฆษณาตามที่ระบุไว้ในการตั้งค่า Google Ad Manager
  • StreamManager: ออบเจ็กต์ที่จัดการสตรีมการแทรกโฆษณาแบบไดนามิกและการโต้ตอบกับแบ็กเอนด์ DAI นอกจากนี้ เครื่องมือจัดการสตรีมยังจัดการการติดตามพิง และส่งต่อสตรีมและเหตุการณ์โฆษณาไปยังผู้เผยแพร่โฆษณาด้วย

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

  • ไฟล์ว่าง 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 เพื่อใช้สำหรับการคลิกผ่าน ตัวอย่างต่อไปนี้จะนําเข้า IMA DAI SDK ดูรายละเอียดเพิ่มเติมได้ที่นําเข้า IMA DAI SDK

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

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>


dai.html
 
#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}

dai.css
 
// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}
dai.js

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

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}
dai.js

โหลด IMA DAI SDK

ถัดไป ให้เพิ่มเฟรมเวิร์ก IMA โดยใช้แท็กสคริปต์ใน dai.html ก่อนแท็กสำหรับ dai.js

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
dai.html

เริ่มต้น StreamManager

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

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}
dai.js

ส่งคำขอสตรีม

กำหนดฟังก์ชันเพื่อขอสตรีม ตัวอย่างนี้ประกอบด้วยฟังก์ชันสำหรับทั้ง VOD และสตรีมแบบสด ซึ่งสร้างอินสแตนซ์ของคลาส VODStreamRequest และคลาส LiveStreamRequest หลังจากมีอินสแตนซ์ streamRequest แล้ว ให้เรียกใช้เมธอด streamManager.requestStream() ด้วยอินสแตนซ์คำขอสตรีม

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}
dai.js

ทั้ง 2 วิธีในการขอสตรีมใช้คีย์ API ที่ไม่บังคับ หากใช้สตรีมที่ปกป้อง คุณต้องสร้างคีย์การตรวจสอบสิทธิ์ DAI ดูรายละเอียดเพิ่มเติมได้ที่ตรวจสอบสิทธิ์คำขอสตรีมวิดีโอ DAI สตรีมทั้ง 2 รายการในตัวอย่างนี้ไม่ได้ได้รับการปกป้องโดยใช้คีย์การตรวจสอบสิทธิ์ DAI จึงไม่มีการใช้ apiKey

แยกวิเคราะห์ข้อมูลเมตาของสตรีม (สตรีมแบบสดเท่านั้น)

สำหรับสตรีมแบบสด คุณยังต้องเพิ่มตัวแฮนเดิลเพื่อฟังเหตุการณ์เมตาข้อมูลที่กําหนดเวลาไว้ และส่งต่อเหตุการณ์ไปยังคลาส StreamManager เพื่อให้ IMA ส่งเหตุการณ์โฆษณาระหว่างช่วงพักโฆษณา

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Only used in LIVE streams. Timed metadata is handled differently
  // by different video players, and the IMA SDK provides two ways
  // to pass in metadata, StreamManager.processMetadata() and
  // StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we 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);
      });
    }
  });
}
dai.js

คู่มือนี้ใช้โปรแกรมเล่น hls.js สำหรับการสตรีม แต่การติดตั้งใช้งานข้อมูลเมตาจะขึ้นอยู่กับประเภทโปรแกรมเล่นที่คุณใช้

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

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

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
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');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
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();
  });
}
dai.js

เมื่อโหลดสตรีมแล้ว วิดีโอเพลเยอร์จะโหลดและเล่น URL ที่ระบุโดยใช้ฟังก์ชัน loadUrl()

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