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

ภาพรวม

SDK ของ Web Receiver รองรับโฆษณาเนทีฟสำหรับช่วงพักโฆษณาและโฆษณาที่แสดงร่วมภายในสตรีมสื่อหนึ่งๆ โดยมี API สำหรับกำหนดอันดับโฆษณา แหล่งที่มาของโฆษณา และลักษณะการทำงานของช่วงพักโฆษณาและคลิปพักที่เกี่ยวข้อง ในคู่มือนี้ Break หมายถึงช่วงเวลาในการเล่นที่มีโฆษณาหรือบัมเปอร์อย่างน้อย 1 รายการ และโฆษณาหรือบัมเปอร์แต่ละรายการเรียกว่า BreakClip ช่วงพักเหล่านี้จะเชื่อมโยงกับสื่อที่กําลังโหลดหรือเล่นอยู่

ประเภทโฆษณา

SDK ของ Web Receiver รองรับการแทรกโฆษณาฝั่งไคลเอ็นต์ (CSAI) และการแทรกโฆษณาแบบเย็บต่อกันของเซิร์ฟเวอร์ (SSAI) แอปพลิเคชันจะตั้งค่าโฆษณาที่เชื่อมต่อไคลเอ็นต์ด้วยตนเองหรือดึงข้อมูลมาจากไฟล์เทมเพลต VAST และ VMAP ก็ได้ คุณควรระบุโฆษณาที่เชื่อมต่อเซิร์ฟเวอร์ด้วยตนเองก่อนที่เนื้อหาจะโหลดเป็นโฆษณาแบบฝัง หรือแสดงแบบไดนามิกระหว่างการเล่นเนื้อหาเป็นโฆษณาแบบขยายแบบฝัง การใช้งานโฆษณาแต่ละประเภทมีคำอธิบายโดยละเอียดที่ด้านล่าง

เย็บด้วยไคลเอ็นต์

ช่วงพักโฆษณาที่ผูกโดยไคลเอ็นต์ด้วยตนเองคือช่วงพักโฆษณาประเภทหนึ่งที่ไคลเอ็นต์นำมาต่อเข้าด้วยกัน และมีการระบุด้วยตนเองโดยแอปพลิเคชันโดยใช้ SDK API โฆษณาประเภทนี้ไม่ได้ฝังในสตรีมของเนื้อหาหลัก BreakClip ต้องระบุ contentId ซึ่งเป็น URL ที่ชี้ไปยังเนื้อหาโฆษณา contentType ที่อธิบายรูปแบบของเนื้อหาโฆษณา และtitle

Break ต้องตั้งค่า isEmbedded และ expanded เป็นค่าเริ่มต้น false คุณจะกำหนดให้ position ตั้งค่าเป็นช่วงพักโฆษณาตอนต้น โฆษณาตอนกลาง หรือโฆษณาตอนท้ายได้ (ดูข้อมูลเพิ่มเติมในส่วนการกำหนดตำแหน่งช่วงพักโฆษณา) เมื่อเตรียมโฆษณาให้พร้อมสำหรับการเล่น SDK ตัวรับสัญญาณเว็บจะสร้างอินสแตนซ์ของโปรแกรมเล่นอื่นขึ้นมาเพื่อโหลดและเล่นเนื้อหาโฆษณา ช่วงพักโฆษณาเหล่านี้ต้องมี stitched timeline และต้องเพิ่มแบบคงที่ (ดูข้อมูลเพิ่มเติมในส่วนการแทรกโฆษณา) ตัวอย่างด้านล่างแสดงการใช้งานพื้นฐานของโฆษณาที่เย็บติดลูกค้าด้วยตนเอง

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

VAST

Web Receiver SDK รองรับการเพิ่มโฆษณา VAST (เทมเพลตการแสดงโฆษณาวิดีโอ) มาตรฐานของ IAB หากระบุ เทมเพลต XML จะได้รับการแยกวิเคราะห์เพื่อสร้างคลิปหยุดพักแบบ client-stitched ที่ตามมาเมื่อเข้าสู่ช่วงพัก

หากต้องการสร้างโฆษณา VAST แอปฝั่งผู้รับต้องสร้าง VastAdsRequest และระบุโฆษณาในพร็อพเพอร์ตี้ BreakClip vastAdsRequest ออบเจ็กต์ VastAdsRequest ต้องมีการกำหนดพร็อพเพอร์ตี้ adsResponse (การแสดงสตริงของเทมเพลต XML) หรือพร็อพเพอร์ตี้ adTagUrl (URL ที่โฮสต์เทมเพลต XML) หากมีการระบุ URL แล้ว SDK จะจัดการการดึงข้อมูลเทมเพลตให้ การห่อหุ้ม Break เป็นไปตามแบบแผนสำหรับโฆษณาที่เชื่อมถึงกันโดยลูกค้า สามารถเพิ่มโฆษณาเหล่านี้ร่วมกับโฆษณาที่ติดลูกค้าด้วยตนเองอื่นๆ ในช่วงพักเดียวกัน หรือในช่วงพักที่แยกกันสำหรับเนื้อหาเดียวกัน ตัวอย่างด้านล่างแสดงการติดตั้งใช้งานโฆษณา VAST ขั้นพื้นฐาน

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

เมื่อมีการป้อน Break ที่มี VAST BreakClip แล้ว SDK ตัวรับสัญญาณเว็บจะเลือกดึงข้อมูลแล้วแยกวิเคราะห์เทมเพลตได้ ขณะแยกวิเคราะห์ SDK จะสร้าง BreakClip ใหม่และป้อนข้อมูลด้วยค่าที่ดึงมาจากเทมเพลต เช่น contentId, contentType, title, duration, whenSkippable และ clickThroughUrl id สำหรับคลิปหยุดพักที่สร้างขึ้นจะได้รับการตั้งค่าเป็น GENERATED:N โดยที่ N เป็นจำนวนเต็มซึ่งเพิ่มขึ้นทีละ 1 สำหรับคลิปเบรก VAST ใหม่แต่ละคลิปที่สร้างขึ้นเริ่มตั้งแต่ 0 จากนั้นโฆษณาที่สร้างขึ้นจะเพิ่มลงใน อาร์เรย์ BreakClip ระบบจะแทนที่ id ของคลิปพัก VAST แต่ละรายการใน Break ปัจจุบันด้วย id ของคลิปหยุดพักที่สร้างขึ้นที่เกี่ยวข้อง ตัวอย่างข้อมูลด้านล่างแสดงให้เห็นการเปลี่ยนแปลงในข้อความ MEDIA_STATUS ที่เกี่ยวข้องกับโฆษณาก่อนและหลังการเข้าสู่ช่วงพักดังกล่าว

Break และ BreakClip ก่อนเข้าสู่ช่วงพักด้วยโฆษณา VAST

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

Break และ BreakClip หลังเข้าสู่ช่วงพักโฆษณาด้วยโฆษณา VAST

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

VMAP

SDK ของ Web Receiver รองรับมาตรฐาน VMAP (เพลย์ลิสต์โฆษณาหลายรายการของวิดีโอ) ของ IAB เมื่อระบุ VMAP แล้ว Web Receiver SDK จะแยกวิเคราะห์การตอบสนองของ VMAP และสร้างออบเจ็กต์ Break ที่ไคลเอ็นต์ สำหรับรายการ <AdBreak> ในการตอบสนอง และจะสร้าง BreakClips ที่เหมาะสมโดยมีออบเจ็กต์ vastAdsRequest สำหรับแต่ละรายการ <AdSource> ที่ระบุใน VMAP ด้วย หากต้องการเปิดใช้ VMAP สำหรับการแทรกโฆษณาลงในเนื้อหา แอปพลิเคชันจะต้องสร้างออบเจ็กต์ VastAdsRequest และกำหนดให้กับพร็อพเพอร์ตี้ vmapAdsRequest ของ MediaInformation ใน LoadRequestData โฆษณาเหล่านี้ต้องแทรกแบบคงที่ (ดูเพิ่มเติมในส่วนการแทรกโฆษณา) ด้านล่างนี้คือตัวอย่างที่สรุปการสร้างคำขอ VMAP

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

ฝังแล้ว

ช่วงพักโฆษณาที่ฝังคือช่วงพักโฆษณาประเภทหนึ่งที่ต่อฝั่งเซิร์ฟเวอร์ลงในสตรีมของเนื้อหาหลัก ระยะเวลาของ Break จะหักออกจากระยะเวลาของเนื้อหาหลักเมื่อคำนวณเวลาของสื่อ

BreakClip ต้องระบุ duration ของเนื้อหาโฆษณา และ title Break ต้องตั้งค่า isEmbedded เป็น true และ expanded ตั้งค่าเป็น false คุณจะตั้งค่าpositionเป็นช่วงพักโฆษณาตอนต้นหรือโฆษณาตอนกลางได้ ช่วงพักโฆษณาตอนท้ายรองรับค่า position ที่เป็นบวกทุกประการ ดูข้อมูลเพิ่มเติมเกี่ยวกับสิ่งนี้ในส่วนการกำหนดตำแหน่งช่วงพักโฆษณา เมื่อมีการเรียกให้โฆษณาแสดงให้เล่น SDK ตัวรับสัญญาณเว็บจะเล่นสตรีมต่อเนื่องจากกลุ่มโฆษณาฝังอยู่ในสตรีม ไม่มีกลไกการโหลดเพิ่มเติมสำหรับโฆษณาประเภทนี้ ข้อมูลเมตาของโฆษณาที่เกี่ยวข้องจะแสดงต่อผู้ใช้เมื่อส่วนหัวของตัวควบคุมการเล่นอยู่ภายในช่วงช่วงพัก ช่วงพักโฆษณาเหล่านี้ต้องมี embedded timeline และต้องเพิ่มแบบคงที่ (ดูเพิ่มเติมในส่วนการแทรกโฆษณา) ตัวอย่างด้านล่างแสดงการติดตั้งใช้งานโฆษณา embedded ขั้นพื้นฐาน

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

ฝังแบบขยายแล้ว

ช่วงพักโฆษณาที่ขยายที่ฝังคือช่วงพักโฆษณาประเภทหนึ่งที่เชื่อมฝั่งเซิร์ฟเวอร์เข้ากับสตรีมของเนื้อหาหลัก ระยะเวลาของ Break จะรวม อยู่ในระยะเวลาของเนื้อหาหลักเมื่อคำนวณเวลาของสื่อ

BreakClip ต้องระบุ duration ของเนื้อหาโฆษณา และ title Break ต้องตั้งค่า isEmbedded เป็น true และ expanded ตั้งค่าเป็น true คุณจะตั้งค่าpositionเป็นช่วงพักโฆษณาตอนต้นหรือโฆษณาตอนกลางได้ ช่วงพักโฆษณาตอนท้ายรองรับค่า position เป็นบวก ดูข้อมูลเพิ่มเติมเกี่ยวกับสิ่งนี้ในส่วนการกำหนดตำแหน่งช่วงพักโฆษณา เมื่อมีการเรียกให้โฆษณาแสดงให้เล่น SDK ตัวรับสัญญาณเว็บจะเล่นสตรีมต่อเนื่องจากกลุ่มโฆษณาฝังอยู่ในสตรีม ไม่มีกลไกการโหลดเพิ่มเติมสำหรับโฆษณาประเภทนี้ ข้อมูลเมตาของโฆษณาที่เกี่ยวข้องจะแสดงต่อผู้ใช้เมื่อส่วนหัวของตัวควบคุมการเล่นอยู่ภายในช่วงช่วงพัก ช่วงพักโฆษณาเหล่านี้ต้องใช้ embedded timeline และจะเพิ่มแบบคงที่หรือแบบไดนามิกก็ได้ (ดูรายละเอียดเพิ่มเติมในส่วนการแทรกโฆษณา) ตัวอย่างด้านล่างแสดงการติดตั้งใช้งานขั้นพื้นฐานของโฆษณา embedded expanded

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

ประเภทไทม์ไลน์ของโปรแกรมเล่น

เมื่อสร้างอินสแตนซ์โปรแกรมเล่น SDK ของเว็บรีซีฟเวอร์จะเลือกประเภทไทม์ไลน์เพื่อรองรับการเล่นโฆษณาระหว่างการเล่นเนื้อหา แต่ละไทม์ไลน์จะทำให้เพิ่มช่วงพักโฆษณาบางประเภทได้ ประเภทไทม์ไลน์จะกำหนดตามประเภทโฆษณาที่แสดงในเวลาที่ใช้ในการโหลดใน MediaInformation ของ LoadRequestData หากมีช่วงพักโฆษณาที่ฝังอยู่ ระบบจะเลือกไทม์ไลน์ embedded หากมีช่วงพักโฆษณาที่เย็บโดยลูกค้า ระบบจะเลือกไทม์ไลน์ stitched ในกรณีที่ไม่มีโฆษณาปรากฏ SDK จะใช้ไทม์ไลน์ embedded เป็นค่าเริ่มต้น เมื่อเลือกไทม์ไลน์แล้ว จะไม่สามารถเปลี่ยนแปลงรายการสื่อปัจจุบันได้ ตารางด้านล่างจะอธิบายรายละเอียดของแต่ละลำดับเวลา

ประเภทลำดับเวลา คำอธิบาย
ไทม์ไลน์ที่ฝัง การนำเสนอเวลาของสื่อที่รองรับโฆษณาที่ฝังอยู่ในเนื้อหาหลัก (ช่วงพักโฆษณาที่ฝังและโฆษณาแบบขยายที่ฝัง) เมื่อมีช่วงพักโฆษณาที่ยังไม่ขยาย ระบบจะหักระยะเวลาของช่วงพักโฆษณาออกจากระยะเวลารวมของเนื้อหา ในทางกลับกัน เมื่อมีช่วงพักโฆษณาที่ขยาย จะถือว่าเวลานั้นเป็นส่วนหนึ่งของเนื้อหาหลัก
เชื่อมต่อไทม์ไลน์ การแสดงเวลาสื่อซึ่งรองรับโฆษณาที่มาจากไฟล์สื่อภายนอก (ช่วงพักโฆษณาที่ติดอยู่กับไคลเอ็นต์, VAST และ VMAP) เมื่อเพิ่มแล้ว ระยะเวลาของช่วงพักโฆษณา ไม่ได้เป็นส่วนหนึ่งของระยะเวลาของเนื้อหาหลัก

รูปที่ 1 ถึง 3 ด้านล่างแสดงเนื้อหาบางส่วนที่มีประเภทโฆษณาแตกต่างกันและค่าลำดับเวลาที่เกี่ยวข้อง เนื้อหาจะได้รับการกำหนดค่าด้วยช่วงพักตอนต้นที่ประกอบด้วยคลิปช่วงพัก 2 คลิป และช่วงพักตอนกลางและโฆษณาตอนท้ายที่มีคลิปหยุดพัก 1 คลิป เวลาจริงนับตั้งแต่เวลาที่เริ่มเล่นเนื้อหา เวลาสื่อของเนื้อหาหลัก และเวลาที่คลิปพักการเล่นของช่วงพักที่เล่นอยู่จะเรียงชิดกันใต้ตัวเลขแต่ละรายการ

ไทม์ไลน์ของโฆษณาที่ติดลูกค้า
รูปที่ 1: ไทม์ไลน์ที่แสดงเนื้อหาบางส่วนและช่วงพักโฆษณาที่เย็บโดยลูกค้า 3 ช่วง


ไทม์ไลน์ของโฆษณาที่ฝังอยู่ในเซิร์ฟเวอร์
รูปที่ 2: ไทม์ไลน์ที่แสดงเนื้อหาบางส่วนและช่วงพักโฆษณาที่ฝังแบบเชื่อมต่อเซิร์ฟเวอร์ 3 ครั้ง


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

การกำหนดตำแหน่งช่วงพัก

Web Receiver SDK ช่วยให้นักพัฒนาซอฟต์แวร์ระบุตำแหน่งที่ควรวางช่วงพักโฆษณาได้โดยการตั้งค่าพร็อพเพอร์ตี้ position ของ Break ค่านี้สอดคล้องกับเวลาสื่อของเนื้อหาหลัก และสามารถใช้เพื่อสร้างช่วงพักโฆษณา pre-roll, mid-roll และ post-roll ซึ่งมีคำจำกัดความดังต่อไปนี้

ตำแหน่งช่วงพัก คำอธิบาย
ตอนต้น ช่วงพักโฆษณาที่เล่นก่อนเนื้อหาหลัก ซึ่งจะแสดงโดยการตั้งค่า breakPosition เป็น 0
โฆษณาตอนกลาง ช่วงพักโฆษณาที่เล่นระหว่างเนื้อหา ซึ่งจะแสดงโดยการตั้งค่า breakPosition เป็นเวลาที่จุดเริ่มต้นของช่วงพักมากกว่าจุดเริ่มต้นของเนื้อหาหลัก และเวลาสิ้นสุดของช่วงพักน้อยกว่าเวลาสิ้นสุดของเนื้อหาหลัก
โฆษณาตอนท้าย ช่วงพักโฆษณาที่เล่นหลังจากเนื้อหาหลัก ซึ่งจะแสดงโดยการตั้งค่า breakPosition เป็น -1 สำหรับไทม์ไลน์ที่ต่อกัน สำหรับไทม์ไลน์ที่ฝังไว้ คุณควรตั้งค่า breakPosition ตามระยะเวลาของเนื้อหาหลักหักด้วยระยะเวลาของช่วงพัก ไม่รองรับเนื้อหาสด

เมทริกซ์ความสามารถในการทำงานร่วมกัน

ตารางที่ 1 แสดงภาพรวมของประเภทโฆษณาและความเข้ากันได้กับฟีเจอร์ที่เกี่ยวข้องกับโฆษณาเพื่อใช้เป็นข้อมูลอ้างอิง

ตารางที่ 1: เมทริกซ์การทำงานร่วมกันของโฆษณา
การสนับสนุนฟีเจอร์ โฆษณาที่ต่อเข้ากับลูกค้าด้วยตัวลูกค้าเอง VAST VMAP โฆษณาแบบฝัง โฆษณาแบบขยายที่ฝัง
ใช้ได้กับ VAST เย็บด้วยไคลเอ็นต์ ไม่มีข้อมูล ฝังแบบขยายแล้ว ฝังแล้ว
ไทม์ไลน์ แบบเย็บตะเข็บ แบบเย็บตะเข็บ แบบเย็บตะเข็บ ฝังแล้ว ฝังแล้ว
การแทรกโฆษณา คงที่ คงที่ คงที่ คงที่ คงที่, ไดนามิก
การลบโฆษณา
โฆษณาตอนต้น
โฆษณาตอนกลาง
โฆษณาตอนท้าย
การข้ามโฆษณา
ตัวสกัดกั้นการกรอวิดีโอ
เครื่องมือสลับการโหลดคลิปหยุด

กิจกรรม

เมื่อเกิดเหตุการณ์ช่วงพักโฆษณาที่สำคัญ SDK การแคสต์จะส่งเหตุการณ์ประเภท BreaksEvent แอปรีซีฟเวอร์จะสมัครรับข้อมูลได้โดยใช้ PlayerManager addEventListener API

เหตุการณ์เหล่านี้สามารถใช้สำหรับการวิเคราะห์และการติดตามการเล่นโฆษณา เมื่อใช้ VMAP (เพลย์ลิสต์โฆษณาหลายรายการสำหรับวิดีโอ) และโฆษณา VAST (เทมเพลตการแสดงโฆษณาวิดีโอ) SDK จะส่งเหตุการณ์การติดตามมาตรฐานใดก็ตามที่ระบุไว้ในการตอบกลับให้โดยอัตโนมัติ

ประเภทเหตุการณ์แสดงอยู่ในตารางที่ 2 พร้อมกับคำอธิบายโดยละเอียดเกี่ยวกับเวลาที่เริ่มทำงาน

วงจรเหตุการณ์ช่วงพักโฆษณา
รูปที่ 4: วงจรเหตุการณ์ช่วงพัก
ตารางที่ 2: เหตุการณ์ช่วงพักและคำอธิบาย
เหตุการณ์หยุดพัก คำอธิบาย
BREAK_STARTED เริ่มทำงานเมื่อเวลาสื่อปัจจุบันของเนื้อหาหลักเท่ากับ position ของช่วงพักที่ยังไม่ได้ดู
BREAK_CLIP_LOADING เริ่มทำงานเฉพาะเมื่อคลิปพักไทม์ไลน์ที่ต่อกันเริ่มโหลด
BREAK_CLIP_STARTED เริ่มทำงานเมื่อคลิปพักเริ่มเล่น
BREAK_CLIP_ENDED เริ่มทำงานเมื่อคลิปพักสิ้นสุดลง ระบบจะป้อนข้อมูล endedReason สำหรับกรณีต่อไปนี้
  • คลิปตัดเส้นแบ่งลำดับเวลาที่ต่อกันเล่นจนจบ
  • คลิปหยุดของไทม์ไลน์ที่ต่อกันมีการเปลี่ยนเป็นคลิปพักอีกคลิป
  • ระบบจะข้ามคลิปพัก
  • คลิปพักวิดีโอล่าสุดเล่นจนจบในช่วงพักโฆษณาตอนกลางแบบฝัง
  • มีข้อผิดพลาดเกิดขึ้น
BREAK_ENDED เริ่มทำงานเมื่อคลิปหยุดพักล่าสุดในช่วงพักสิ้นสุดลง

การแทรกโฆษณา

SDK การแคสต์ช่วยให้แอปพลิเคชันสามารถแทรกและนำโฆษณาออกในช่วงเวลาต่างๆ ของเซสชันการแคสต์ การแทรกโฆษณา 2 ประเภทคือแบบคงที่และแบบไดนามิก การแทรกโฆษณาแบบคงที่ต้องระบุโฆษณาไว้ใน LoadRequestData ก่อนการสร้างโปรแกรมเล่น การแทรกโฆษณาแบบไดนามิกใช้ประโยชน์จาก BreakManager addBreak API เพื่อแทรกช่วงพักในเนื้อหาที่โหลดแล้ว วิธีการแทรกแต่ละประเภทสามารถใช้งานร่วมกับโฆษณาบางประเภทได้ ภาพรวมความเข้ากันได้มีอยู่ในเมทริกซ์ความสามารถในการทำงานร่วมกัน

การแทรกโฆษณาแบบคงที่

การแทรกโฆษณาแบบคงที่จะมีลักษณะเป็นการเพิ่มข้อมูลเมตาของโฆษณาที่เกี่ยวข้องก่อนการสร้างโปรแกรมเล่น ข้อมูลนี้มีอยู่ใน MediaInformation ของ LoadRequestData เช่น สามารถตั้งค่าในคำขอโหลดเดิมของผู้ส่งที่เชื่อมต่อ หรือแทรกโดยแอปพลิเคชันเว็บรีซีฟเวอร์ได้โดยสกัดกั้นคำขอ LOAD เมื่อมีการส่ง LoadRequestData กลับไปยัง SDK ของ Web Receiver เพื่อประมวลผลแล้ว ระบบจะสร้างโปรแกรมเล่นขึ้น ดูเพิ่มเติมเกี่ยวกับการโหลดสื่อ ตัวอย่างด้านล่างแสดงการเพิ่มโฆษณาที่เย็บติดลูกค้าด้วยตนเองซึ่งเพิ่มเข้ามาในเครื่องมือดักจับคำขอ LOAD

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

การแทรกโฆษณาแบบไดนามิก

การแทรกโฆษณาแบบไดนามิกมีลักษณะของการตั้งค่าช่วงพักโฆษณาระหว่างการเล่นเนื้อหา ซึ่งทำได้โดยการรับอินสแตนซ์ของ BreakManager และเรียก addBreak API การดำเนินการนี้จะใช้พารามิเตอร์อย่างน้อย 2 รายการ ซึ่งได้แก่ ส่วนขยายแบบขยาย Break และอาร์เรย์ของ BreakClip พร็อพเพอร์ตี้ที่ 3 ที่ไม่บังคับจะรวมอยู่เพื่อบังคับให้ส่งการเปลี่ยนแปลงไปยังผู้ส่งที่เชื่อมต่อผ่านการออกอากาศ MediaStatus เมื่อตั้งค่าเป็น true เมื่อเพิ่มช่วงพักและคลิปช่วงพัก รหัสที่เกี่ยวข้องจะต้องไม่ซ้ำกัน โดยจะเพิ่มโฆษณาเหล่านี้ได้ เมื่อสร้างโปรแกรมเล่นเรียบร้อยแล้ว Web Receiver SDK จะเริ่มการทำงานของเหตุการณ์ PLAYER_LOADING เมื่อสร้างโปรแกรมเล่นแล้ว ดูตัวอย่างด้านล่างที่แสดงการใช้งานในเครื่องจัดการเหตุการณ์ซึ่งตอบสนองต่อการเปลี่ยนแปลงในข้อมูลเมตา ID3 ของสตรีมและสร้างออบเจ็กต์ Break และ BreakClip เพื่อแทรกลงในไทม์ไลน์

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

การนำโฆษณาแบบไดนามิกออก

หากต้องการนำช่วงพักแบบไดนามิกออก แอปพลิเคชันควรเรียกใช้ removeBreakById ระหว่างการเล่น ฟังก์ชันนี้จะใช้ตัวระบุสตริงของช่วงพักซึ่งจะนำออกจากไทม์ไลน์ breakId ที่ระบุต้องชี้ไปยังช่วงพักโฆษณาที่ขยายที่ฝัง หากตรวจพบช่วงพักโฆษณาประเภทอื่นๆ ช่วงพักโฆษณาจะยังคงอยู่ในไทม์ไลน์ ดูตัวอย่างด้านล่างซึ่งจะลบช่วงพัก

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.removeBreakById('break_midroll_embedded_expanded');

ลักษณะการพัก

SDK กำหนดลักษณะการทำงานเริ่มต้นเมื่อโปรแกรมเล่นเข้าและออกจากช่วงพัก และมีวิธีปรับแต่งเพิ่มเติมโดยใช้ API บางรายการที่ให้ไว้ใน BreakManager

ลักษณะการทำงานเริ่มต้นของช่วงพักโฆษณา

เมื่อมีการป้อน Break ผ่านการเล่นตามปกติหรือโดยการกรอไปยัง Break SDK จะประเมินว่าผู้ใช้เคยเห็นแล้วหรือไม่โดยการตรวจสอบพร็อพเพอร์ตี้ isWatched เมื่อสร้างแล้ว ค่าเริ่มต้นของช่วงพักโฆษณาสำหรับพร็อพเพอร์ตี้นี้คือ false หากพร็อพเพอร์ตี้คือ true ระบบจะไม่เล่นช่วงพักเมื่อป้อน และเนื้อหาหลักจะยังคงเล่นต่อไป หากพร็อพเพอร์ตี้คือ false ระบบจะเล่นช่วงพักเมื่อป้อน

เมื่อค้นหาช่วงพักโฆษณาที่ผ่านไปแล้ว การติดตั้งใช้งานเริ่มต้นจะได้รับรายการ Break ทั้งหมดที่มี position อยู่ระหว่างค่าของการดำเนินการค้นหา seekFrom และ seekTo จากรายการช่วงพักนี้ SDK จะเล่น Break ซึ่งมี position ใกล้เคียงกับค่า seekTo มากที่สุด และมีการตั้งค่าพร็อพเพอร์ตี้ isWatched เป็น false ระบบจะตั้งค่าพร็อพเพอร์ตี้ isWatched ของช่วงพักนั้นเป็น true และโปรแกรมเล่นจะเริ่มเล่นคลิปพัก เมื่อดูช่วงพักแล้ว เนื้อหาหลักจะเล่นต่อจากตำแหน่ง seekTo ถ้าไม่มีช่วงพักดังกล่าว จะไม่มีการเล่นช่วงพักและเนื้อหาหลักจะเล่นต่อที่ตำแหน่ง seekTo

ระหว่างการเล่นช่วงพัก SDK จะเผยแพร่การอัปเดตที่เกี่ยวข้องไปยังแอปพลิเคชันผู้ส่งที่เชื่อมต่อใน MediaStatus แอปพลิเคชันเหล่านี้จะใช้การออกอากาศในการอัปเดต UI สำหรับโฆษณาโดยการอ่านพร็อพเพอร์ตี้ breakStatus คุณสมบัตินี้จะถูกกำหนดไว้ระหว่างการเล่นช่วงพักเท่านั้น

แอปพลิเคชันรีซีฟเวอร์ยังสามารถค้นหาข้อมูลที่เกี่ยวข้องกับตำแหน่งของส่วนหัวของตัวควบคุมการเล่นโดยตรง ตามเวลาปัจจุบันของ BreakClip ที่แสดงโดยการเรียกใช้ PlayerManager getBreakClipCurrentTimeSec ในทํานองเดียวกัน แอปพลิเคชันจะค้นหาระยะเวลาของ BreakClip ปัจจุบันได้โดยเรียกใช้ getBreakClipDurationSec

ลักษณะการทำงานของช่วงพักโฆษณาที่กำหนดเอง

ลักษณะการทำงานเริ่มต้นสำหรับช่วงพักและคลิปช่วงพักจะแก้ไขได้โดยใช้เมธอด setBreakClipLoadInterceptor และ setBreakSeekInterceptor ที่ระบุไว้ใน BreakManager

ผู้สกัดกั้นการกรอวิดีโอ

ตัวสกัดกั้นการกรอวิดีโอช่วยให้แอปควบคุมลักษณะการทำงานของการกรอวิดีโอผ่านช่วงพักโฆษณาได้ ฟังก์ชันจะทริกเกอร์เมื่อมีการขอการดำเนินการกรอไปข้างหน้าหรือย้อนกลับในช่วงช่วงพักอย่างน้อย 1 ครั้ง เมื่อเรียกใช้ ระบบจะส่งต่อ BreakSeekData ในรูปแบบพารามิเตอร์ไปยังฟังก์ชันเรียกกลับ ออบเจ็กต์ BreakSeekData มีอาร์เรย์ของออบเจ็กต์ Break ที่ตั้งค่าพร็อพเพอร์ตี้ position เป็นตัวเลขระหว่างเวลาส่วนหัวของตัวควบคุมการเล่นปัจจุบันที่กำหนดเป็น seekFrom กับเวลาปลายทางการค้นหา seekTo

ตัวตรวจจับนี้อนุญาตให้แก้ไขออบเจ็กต์ Break ในช่วงพักที่เกี่ยวข้อง เมื่อใช้งานตัวตรวจจับช่วงพักต้องระบุช่วงพักโฆษณาที่จะเล่นโดยแสดงผลออบเจ็กต์ BreakSeekData ที่แก้ไขแล้ว โปรแกรมเล่นวิดีโอจะเริ่มเล่นช่วงพักทั้งหมดที่รวมอยู่ในค่าที่ส่งคืน หากค่า null หรือไม่ส่งกลับมาจากตัวตรวจจับช่วงพัก ระบบจะข้ามช่วงพักนั้น

ลองดูตัวอย่างด้านล่างสำหรับวิธีใช้ตัวตรวจจับอย่างง่ายๆ ซึ่งลบล้างลักษณะการทำงานเริ่มต้นในการดูช่วงพักโฆษณาทั้งหมดซึ่งยกเว้นช่วงพักที่ดูไปแล้ว

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

เครื่องมือสลับการโหลดคลิป

เมื่อใช้ตัวตรวจจับการโหลดคลิปช่วงพัก คุณจะแก้ไขออบเจ็กต์ BreakClip ก่อนที่องค์ประกอบจะเริ่มเล่นได้

ระบบจะเรียกใช้ตัวตรวจจับการโหลดคลิปช่วงพักสำหรับช่วงพักไทม์ไลน์ที่ต่อเข้าด้วยกันเท่านั้น และจะตั้งค่าโดยใช้ setBreakClipLoadInterceptor ได้ ก่อนป้อน Break ระบบจะเรียกใช้ตัวตรวจจับนี้ 1 ครั้งสำหรับแต่ละบุคคล BreakClip ที่กำหนดไว้ในช่วงพักนั้น SDK ส่งออบเจ็กต์ BreakClip ต้นฉบับเป็นพารามิเตอร์ของฟังก์ชันเรียกกลับ จากนั้นแอปพลิเคชันจะแก้ไข BreakClip นี้และส่งคืนเพื่อให้ SDK ดึงข้อมูลและแสดง Break Clip ด้วยการกำหนดค่าที่อัปเดตได้ หากส่ง null หรือไม่มีอะไรเลย ระบบจะข้ามคลิปหยุด

ดูตัวอย่างด้านล่างที่แก้ไข contentUrl ของคลิปพักด้วยการเรียกใช้ฟังก์ชันยูทิลิตี getUrlFromClipId โดยที่ id ของ BreakClip แมปกับ URL

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

การข้ามโฆษณา

Web Receiver SDK มี API ให้ข้ามช่วงพักโฆษณาและคลิปพักแต่ละคลิปภายในช่วงพักโฆษณา นอกจากนี้ SDK ยังอนุญาตให้ผู้ใช้เลือกข้ามการตัดคลิปโดยโต้ตอบกับแอปพลิเคชันของผู้ส่งหรืออุปกรณ์ Smart Display ได้ด้วย

คลิปหยุดพักที่ผู้ใช้ข้ามได้

การตั้งค่า Break Clip เป็นแบบข้ามได้ช่วยให้ผู้ใช้โต้ตอบกับแอปพลิเคชันผู้ส่งที่เชื่อมต่ออยู่และอุปกรณ์ Smart Display เพื่อเลือกข้ามส่วนที่เหลือของคลิปที่กำลังเล่นอยู่ได้ การตั้งค่าพร็อพเพอร์ตี้ whenSkippable เป็นจำนวนวินาทีที่ไม่ติดลบจะเป็นการเปิดใช้ฟีเจอร์นี้สำหรับออบเจ็กต์ BreakClip โปรแกรมเล่นจะถือว่าคลิปตัดข้ามได้เมื่อคลิปพักเล่นเป็นเวลาตามจำนวนวินาทีนั้น การตั้งค่านี้เป็น 0 ช่วยให้ผู้ใช้ข้ามคลิปพักได้ทันที

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

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

การข้ามโฆษณาแบบเป็นโปรแกรม

นอกจากนี้ ระบบยังอาจข้ามโฆษณาโดยอัตโนมัติโดยไม่ต้องมีการโต้ตอบจากผู้ใช้ด้วย

หากต้องการข้ามการเล่นทั้ง แอปพลิเคชันควรตั้งค่าพร็อพเพอร์ตี้ isWatched ของ Break เป็น true ซึ่งทำได้ทุกเมื่อระหว่างลำดับการโหลดหรือการเล่นเนื้อหา ผู้เล่นจะประเมินพร็อพเพอร์ตี้ isWatched เมื่อมีช่วงพักครบ position ในเวลาปัจจุบันของเนื้อหาหลัก เมื่อถึงเวลานั้น ผู้เล่นจะกำหนดว่าควรเข้าสู่ช่วงพักหรือไม่ ดูตัวอย่างด้านล่างซึ่งเล่นวนซ้ำไปเรื่อยๆ และแก้ไขค่าเมื่อโปรแกรมเล่นกำลังโหลด

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

หากต้องการข้ามคลิปหยุดพักที่เจาะจงแบบเป็นโปรแกรม ควรใช้ตัวตรวจจับการโหลดคลิปหยุด หากแสดง null หรือไม่แสดงผลค่าในฟังก์ชันเรียกกลับ ระบบจะข้ามคลิปในช่วงพักนั้น

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});