เริ่มต้นใช้งาน IMA SDK สำหรับ DAI

เลือกแพลตฟอร์ม: HTML5 Android iOS tvOS Cast Roku

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

เลือกโซลูชัน DAI ที่ต้องการ ดังนี้

เล่นไลฟ์สดที่ลงทะเบียนกับ Google Cloud Video Stitcher API

คู่มือนี้สาธิตวิธีใช้ IMA DAI SDK สำหรับ HTML5 เพื่อขอและเล่นไลฟ์สดสำหรับกิจกรรมที่ลงทะเบียนกับ Google Cloud Video Stitcher API และวิธีแทรกช่วงพักโฆษณาระหว่างการเล่น

คู่มือนี้จะขยายความตัวอย่างพื้นฐานจากคู่มือเริ่มต้นใช้งานสำหรับ IMA DAI

ดูข้อมูลเกี่ยวกับการผสานรวมกับแพลตฟอร์มอื่นๆ หรือการใช้ SDK ฝั่งไคลเอ็นต์ของ IMA ได้ที่ SDK โฆษณาสื่ออินเทอร์แอกทีฟ

หากต้องการดูหรือทำตามการผสานรวมตัวอย่างที่เสร็จสมบูรณ์แล้ว ให้ดาวน์โหลดตัวอย่างเครื่องมือเชื่อมวิดีโอในระบบคลาวด์สำหรับ HLS หรือ DASH

ตั้งค่าโปรเจ็กต์ Google Cloud

ตั้งค่าโปรเจ็กต์ Google Cloud และกำหนดค่าบัญชีบริการเพื่อเข้าถึงโปรเจ็กต์

สร้างการกำหนดค่าสำหรับกิจกรรมไลฟ์สดโดยใช้ไลฟ์สดเนื้อหาของคุณเองหรือไลฟ์สดทดสอบ คู่มือนี้คาดหวังให้ใช้สตรีม HLS

ป้อนตัวแปรต่อไปนี้เพื่อใช้ใน IMA SDK

ตำแหน่ง
ภูมิภาค Google Cloud ที่สร้างการกำหนดค่าแบบเรียลไทม์: LOCATION
หมายเลขโปรเจ็กต์
หมายเลขโปรเจ็กต์ Google Cloud ที่ใช้ Video Stitcher API: PROJECT_NUMBER
โทเค็น OAuth

โทเค็น OAuth ที่มีอายุสั้นของบัญชีบริการที่มีบทบาทผู้ใช้ Video Stitcher: 

OAUTH_TOKEN

อ่านเพิ่มเติมเกี่ยวกับการสร้างข้อมูลเข้าสู่ระบบที่มีอายุสั้นสำหรับบัญชีบริการ คุณสามารถใช้โทเค็น OAuth ซ้ำในคำขอหลายรายการได้ตราบใดที่โทเค็นยังไม่หมดอายุ

รหัสเครือข่าย

รหัสเครือข่าย Ad Manager สำหรับการขอโฆษณา: NETWORK_CODE

รหัสการกำหนดค่าไลฟ์สด
รหัสการกำหนดค่าไลฟ์สดที่คุณระบุเมื่อสร้างกิจกรรมไลฟ์สด LIVE_CONFIG_ID
คีย์ของชิ้นงานที่กำหนดเอง
คีย์ชิ้นงานที่กำหนดเองของ Ad Manager ที่สร้างขึ้นระหว่างกระบวนการสร้างการกำหนดค่าสำหรับกิจกรรมไลฟ์สดด้วย Video Stitcher API: CUSTOM_ASSET_KEY

กำหนดค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์

แอปตัวอย่าง IMA จะสาธิตเฉพาะคำขอสตรีม HLS เท่านั้น คุณยังคงใช้สตรีม DASH ได้เมื่อสร้างคลาส VideoStitcherLiveStreamRequest เมื่อตั้งค่าเพลเยอร์ที่เข้ากันได้กับ DASH คุณต้องตั้งค่า Listener สำหรับเหตุการณ์ความคืบหน้าของวิดีโอเพลเยอร์ที่สามารถให้ข้อมูลเมตาของวิดีโอแก่ StreamManager.processMetadata() ฟังก์ชันนี้ใช้พารามิเตอร์ 3 รายการ ได้แก่

  1. type: สตริงที่ต้องตั้งค่าเป็น 'ID3' สำหรับสตรีม HLS และ 'urn:google:dai:2018' สำหรับสตรีม DASH

  2. data: สำหรับข้อความเหตุการณ์ DASH นี่คือสตริงข้อมูลข้อความ

  3. timestamp: ตัวเลขที่เป็นเวลาเริ่มต้นของข้อความเหตุการณ์สำหรับสตรีม DASH

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

ดาวน์โหลดตัวอย่าง IMA DAI สำหรับ HTML5 และแตกตัวอย่าง HLS.js Simple ลงในโฟลเดอร์ใหม่ ตัวอย่างนี้เป็นเว็บแอปที่คุณสามารถโฮสต์ในเครื่องเพื่อวัตถุประสงค์ในการทดสอบ

หากต้องการโฮสต์ตัวอย่างในเครื่อง ให้ไปที่โฟลเดอร์ใหม่ แล้วเรียกใช้คำสั่ง python ต่อไปนี้เพื่อเริ่มเว็บเซิร์ฟเวอร์

python3 -m http.server 8000

http.server พร้อมใช้งานใน Python 3.x เท่านั้น คุณสามารถใช้เว็บเซิร์ฟเวอร์อื่นๆ เช่น Apache HTTP Server หรือ Node JS

เปิดเว็บเบราว์เซอร์และไปที่ localhost:8000 เพื่อดูวิดีโอเพลเยอร์ เบราว์เซอร์ต้องรองรับไลบรารี HLS.js

หากทุกอย่างทำงานอย่างถูกต้อง การคลิกปุ่มเล่นในวิดีโอเพลเยอร์จะเริ่มเล่นภาพยนตร์สั้นเรื่อง "Tears of Steel" หลังจากโฆษณา Shorts เนื้อหานี้แสดงโดยใช้สตรีมวิดีโอออนดีมานด์ (VOD)

ขอไลฟ์สด

หากต้องการแทนที่สตรีม VOD ตัวอย่างด้วยไลฟ์สด ให้ใช้คลาส VideoStitcherLiveStreamRequest ที่สร้างเซสชันโฆษณาด้วย Google Ad Manager โดยอัตโนมัติ คุณสามารถใช้ UI ของ Google Ad Manager เพื่อค้นหาเซสชัน DAI ที่สร้างขึ้นเพื่อตรวจสอบและแก้ไขข้อบกพร่องได้

ในตัวอย่างที่มีอยู่ จะมีฟังก์ชันสำหรับการขอสตรีม VOD หรือไลฟ์สด หากต้องการให้ทำงานร่วมกับ Google Cloud Video Stitcher API คุณต้องเพิ่มฟังก์ชันใหม่เพื่อแสดงผลออบเจ็กต์ VideoStitcherLiveStreamRequest

เช่น

// StreamManager which will be used to request ad-enabled streams.
let streamManager;
...
function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(
    videoElement,
    adUiElement
  );
  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);

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

  videoElement.addEventListener('pause', () => {
    playButton.style.display = 'block';
  });

  playButton.addEventListener('click', initiatePlayback);
}

function initiatePlayback() {
  requestVideoStitcherStream();

  playButton.style.display = "none";
  playButton.removeEventListener('click', initiatePlayback);
  playButton.addEventListener('click', resumePlayback);
}
...

function requestVideoStitcherStream() {
  const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest();
  streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID';
  streamRequest.region = 'LOCATION';
  streamRequest.projectNumber = 'PROJECT_NUMBER';
  streamRequest.oAuthToken = 'OAUTH_TOKEN';
  streamRequest.networkCode = 'NETWORK_CODE';
  streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY';

  streamManager.requestStream(streamRequest);
}

สำหรับการทดสอบในเครื่อง หากไฟล์ไลฟ์สดอยู่ในที่เก็บข้อมูล Cloud Storage คุณต้องเปิดใช้ CORS สำหรับต้นทาง http://localhost:8000

โหลดหน้าซ้ำ จากนั้น คุณจะขอและเล่นไลฟ์สดที่กำหนดเองได้

(ไม่บังคับ) เพิ่มตัวเลือกเซสชันสตรีมมิง

ปรับแต่งคำขอสตรีมโดยเพิ่มตัวเลือกเซสชันเพื่อลบล้างการกำหนดค่า Cloud Video Stitcher API เริ่มต้นโดยใช้ VideoStitcherLiveStreamRequest.videoStitcherSessionOptions หากคุณระบุตัวเลือกที่ไม่รู้จัก Cloud Video Stitcher API จะตอบกลับด้วยข้อผิดพลาด HTTP 400 ดูคู่มือการแก้ปัญหาเพื่อรับความช่วยเหลือ

เช่น คุณสามารถลบล้างตัวเลือกไฟล์ Manifest ด้วยข้อมูลโค้ดต่อไปนี้ ซึ่งจะขอไฟล์ Manifest ของสตรีม 2 รายการที่มีการแสดงผลที่เรียงลำดับจากอัตราบิตต่ำสุดไปสูงสุด

...

// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
  "manifestOptions": {
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);

แทรกช่วงพักโฆษณา

Google Cloud Video Stitcher API จะแทรกโฆษณาที่ดึงมาจากแท็กโฆษณาสำหรับช่วงพักโฆษณาแต่ละช่วง ระบบจะระบุช่วงพักโฆษณาในไฟล์ Manifest โดยใช้เครื่องหมายโฆษณา ตัวทำเครื่องหมายโฆษณาจะแทรกโดยโปรแกรมเปลี่ยนไฟล์ไลฟ์สด

โฆษณาจะเล่นทันทีหลังจากแทรกช่วงพักโฆษณา

ล้างข้อมูล

เมื่อคุณโฮสต์ไลฟ์สดโดยใช้ Google Cloud Video Stitcher API และส่งคำขอโดยใช้ IMA DAI SDK สำหรับ HTML5 เรียบร้อยแล้ว คุณควรล้างทรัพยากรการแสดงโฆษณา

ทำตามคู่มือการล้างข้อมูลไลฟ์สดเพื่อนำทรัพยากรและชิ้นงานที่ไม่จำเป็นออก

สุดท้าย ในหน้าต่างเทอร์มินัลที่คุณเริ่มเว็บเซิร์ฟเวอร์ Python 3 ให้ใช้คำสั่ง ctrl+C เพื่อสิ้นสุดเซิร์ฟเวอร์ในเครื่อง