เพิ่มฟีเจอร์ขั้นสูงลงในแอป Web Sender

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

Web Sender SDK รองรับช่วงพักโฆษณาและโฆษณาที่แสดงร่วมภายในสตรีมสื่อที่กำหนด

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีการทำงานของช่วงพักโฆษณาได้ที่ภาพรวมช่วงพักโฆษณาของ Web Receiver

แม้ว่าจะระบุช่วงพักได้ทั้งในอุปกรณ์ที่ส่งและอุปกรณ์รับ แต่เราขอแนะนำให้ระบุช่วงพักใน Web Receiver และ Android TV Receiver เพื่อให้ลักษณะการทำงานสอดคล้องกันในทุกแพลตฟอร์ม

บนเว็บ ให้ระบุช่วงพักโฆษณาในคำสั่งโหลดโดยใช้ BreakClip และ Break ดังนี้

let breakClip1 = new BreakClip('bc0');
breakClip1.title = 'Clip title'
breakClip1.posterUrl = 'https://www.some.url';
breakClip1.duration = 60;
breakClip.whenSKippable = 5;

let breakClip2 = ...
let breakClip3 = ...

let break1 = new Break('b0', ['bc0', 'bc1', 'bc2'], 10);

let mediaInfo = new chrome.cast.media.MediaInfo(<contentId>, '<contentType');
...
mediaInfo.breakClips = [breakClip1, breakClip2, breakClip3];
mediaInfo.breaks = [break1];

let request = new chrome.cast.media.LoadRequest(mediaInfo);

cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request)

การใช้ API ของแทร็ก

แทร็กอาจเป็นออบเจ็กต์ข้อความ (คำบรรยายแทนเสียงหรือคำบรรยาย) หรือออบเจ็กต์สตรีมเสียงหรือวิดีโอ Tracks API ช่วยให้คุณทำงานกับออบเจ็กต์เหล่านี้ในแอปพลิเคชันได้

ออบเจ็กต์ Track แสดงถึงแทร็กใน SDK คุณกำหนดค่าแทร็กและกำหนดรหัสที่ไม่ซ้ำกัน ให้กับแทร็กได้ดังนี้

var englishSubtitle = new chrome.cast.media.Track(1, // track ID
  chrome.cast.media.TrackType.TEXT);
englishSubtitle.trackContentId = 'https://some-url/caption_en.vtt';
englishSubtitle.trackContentType = 'text/vtt';
englishSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
englishSubtitle.name = 'English Subtitles';
englishSubtitle.language = 'en-US';
englishSubtitle.customData = null;

var frenchSubtitle = new chrome.cast.media.Track(2, // track ID
  chrome.cast.media.TrackType.TEXT);
frenchSubtitle.trackContentId = 'https://some-url/caption_fr.vtt';
frenchSubtitle.trackContentType = 'text/vtt';
frenchSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
frenchSubtitle.name = 'French Subtitles';
frenchSubtitle.language = 'fr';
frenchSubtitle.customData = null;

var frenchAudio = new chrome.cast.media.Track(3, // track ID
  chrome.cast.media.TrackType.AUDIO);
frenchAudio.trackContentId = 'trk0001';
frenchAudio.trackContentType = 'audio/mp3';
frenchAudio.subtype = null;
frenchAudio.name = 'French Audio';
frenchAudio.language = 'fr';
frenchAudio.customData = null;

รายการสื่ออาจมีหลายแทร็ก เช่น อาจมีคำบรรยายแทนเสียงหลายรายการ (แต่ละรายการสำหรับภาษาที่ต่างกัน) หรือสตรีมเสียงสำรองหลายรายการ (สำหรับภาษาที่ต่างกัน)

MediaInfo คือคลาสที่สร้างโมเดลรายการสื่อ หากต้องการเชื่อมโยงคอลเล็กชันของ Track ออบเจ็กต์กับรายการสื่อ ให้อัปเดตพร็อพเพอร์ตี้ tracks ของรายการสื่อนั้น คุณต้องทำการเชื่อมโยงนี้ก่อนที่จะโหลดสื่อไปยังเครื่องรับ

var tracks = [englishSubtitle, frenchSubtitle, frenchAudio];
var mediaInfo = new chrome.cast.media.MediaInfo(mediaURL);
mediaInfo.contentType = 'video/mp4';
mediaInfo.metadata = new chrome.cast.media.GenericMediaMetadata();
mediaInfo.customData = null;
mediaInfo.streamType = chrome.cast.media.StreamType.BUFFERED;
mediaInfo.textTrackStyle = new chrome.cast.media.TextTrackStyle();
mediaInfo.duration = null;
mediaInfo.tracks = tracks;

คุณตั้งค่าแทร็กที่ใช้งานอยู่ได้ในคำขอสื่อ activeTrackIds

นอกจากนี้ คุณยังเปิดใช้งานแทร็กอย่างน้อย 1 แทร็กที่เชื่อมโยงกับรายการสื่อได้หลังจากโหลดสื่อแล้ว โดยเรียกใช้ EditTracksInfoRequest(opt_activeTrackIds, opt_textTrackStyle) และส่งรหัสของแทร็กที่จะเปิดใช้งานใน opt_activeTrackIds โปรดทราบว่า พารามิเตอร์ทั้ง 2 รายการเป็นพารามิเตอร์ที่ไม่บังคับ และคุณสามารถเลือกแทร็กหรือสไตล์ที่ใช้งานอยู่ เพื่อตั้งค่าได้ตามต้องการ ตัวอย่างเช่น วิธี เปิดใช้คำบรรยายภาษาฝรั่งเศส (2) และเสียงภาษาฝรั่งเศส (3) มีดังนี้

var activeTrackIds = [2, 3];
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(activeTrackIds);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

หากต้องการนำแทร็กเสียงหรือวิดีโอทั้งหมดออกจากสื่อปัจจุบัน เพียงตั้งค่า mediaInfo.tracks=null (อาร์เรย์ว่าง) แล้วโหลดสื่อซ้ำ

หากต้องการนำแทร็กข้อความทั้งหมดออกจากสื่อปัจจุบัน (เช่น การปิด คำบรรยายแทนเสียง) ให้ทำอย่างใดอย่างหนึ่งต่อไปนี้

• อัปเดต var activeTrackIds = [2, 3]; (แสดงก่อนหน้านี้) เพื่อให้มีเฉพาะ [3] ซึ่งเป็นแทร็กเสียง
• ตั้งค่า mediaInfo.tracks=null โปรดทราบว่าคุณไม่จำเป็นต้อง โหลดสื่อซ้ำเพื่อปิดคำบรรยายแทนเสียง (track.hidden) การส่งอาร์เรย์ activeTracksId ที่ไม่มีtrackId ที่เปิดใช้ก่อนหน้านี้จะปิดใช้แทร็กข้อความ

การจัดรูปแบบแทร็กข้อความ

TextTrackStyle คือออบเจ็กต์ที่ห่อหุ้มข้อมูลการจัดรูปแบบของแทร็กข้อความ หลังจากสร้างหรืออัปเดตออบเจ็กต์ TextTrackStyle ที่มีอยู่แล้ว คุณจะนำออบเจ็กต์นั้นไปใช้กับรายการสื่อที่กำลังเล่นอยู่ได้โดยเรียกใช้เมธอด editTrackInfo ของออบเจ็กต์นั้น ดังนี้

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(textTrackStyle);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

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

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

คุณจัดรูปแบบองค์ประกอบสไตล์แทร็กข้อความต่อไปนี้ได้

• สีและความทึบแสงของพื้นหน้า (ข้อความ)
• สีและความโปร่งแสงของพื้นหลัง
• ชนิดขอบ
• สีขอบ
• การปรับขนาดแบบอักษร
• ชุดแบบอักษร
• รูปแบบตัวอักษร

เช่น ตั้งค่าสีข้อความเป็นสีแดงที่มีความทึบแสง 75% ดังนี้

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
textTrackStyle.foregroundColor = '#80FF0000';

การควบคุมระดับเสียง

คุณใช้ RemotePlayer และ RemotePlayerController เพื่อตั้งค่าระดับเสียงของตัวรับได้

function changeVolume(newVolume) {
  player.volumeLevel = newVolume;
  playerController.setVolumeLevel();
  // Update sender UI to reflect change
}

แอปผู้ส่งควรปฏิบัติตามหลักเกณฑ์ต่อไปนี้ในการควบคุมระดับเสียง

• แอปพลิเคชันผู้ส่งต้องซิงค์กับตัวรับเพื่อให้ UI ของผู้ส่งรายงานระดับเสียงตามตัวรับเสมอ ใช้แฮนเดิลการเรียกกลับ RemotePlayerEventType.VOLUME_LEVEL_CHANGED และ RemotePlayerEventType.IS_MUTED_CHANGED เพื่อรักษาระดับเสียงในผู้ส่ง ดูข้อมูลเพิ่มเติมได้ที่การอัปเดตสถานะ
• แอปผู้ส่งต้องไม่ตั้งค่าระดับเสียงที่ระดับใดระดับหนึ่งที่กำหนดไว้ล่วงหน้า หรือตั้งค่าระดับเสียงเป็นระดับเสียงเรียกเข้า/สื่อของอุปกรณ์ผู้ส่งเมื่อ แอปโหลดในเครื่องรับ

ดูการควบคุมระดับเสียงของผู้ส่ง ในรายการตรวจสอบการออกแบบ

การส่งข้อความสื่อไปยังผู้รับ

Media Messages สามารถส่งจากผู้ส่งไปยังผู้รับได้ ตัวอย่างเช่น หากต้องการส่งSKIP_ADข้อความถึงผู้รับ ให้ทำดังนี้

// Get a handle to the skip button element
const skipButton = document.getElementById('skip');
skipButton.addEventListener("click", function() {
  if (castSession) {
    const media = castSession.getMediaSession();
    castSession.sendMessage('urn:x-cast:com.google.cast.media', {
      type: 'SKIP_AD',
      requestId: 1,
      mediaSessionId: media.mediaSessionId
    });
  }
});

การอัปเดตสถานะ

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

ด้วยเหตุนี้ แอปพลิเคชันของคุณจึงควรลงทะเบียน Listener ที่จำเป็นทั้งหมดใน RemotePlayerController หาก TextTrackStyle ของสื่อปัจจุบันมีการเปลี่ยนแปลง ระบบจะแจ้งเตือนผู้ส่งที่เชื่อมต่อทั้งหมด และจะส่งพร็อพเพอร์ตี้ที่เกี่ยวข้องของเซสชันสื่อปัจจุบัน เช่น activeTrackIds และ textTrackStyle ของฟิลด์ MediaInfo ไปยังผู้ส่งในการเรียกกลับ ในกรณีนี้ SDK ของตัวรับ จะไม่ตรวจสอบว่าสไตล์ใหม่แตกต่างจากสไตล์ก่อนหน้าหรือไม่ และ จะแจ้งผู้ส่งที่เชื่อมต่อทั้งหมดโดยไม่คำนึงถึงความแตกต่าง

ตัวบอกสถานะความคืบหน้า

การแสดงตำแหน่งการเล่นพร้อมตัวบ่งชี้ความคืบหน้าในอุปกรณ์ที่ส่งเป็น ข้อกำหนดสำหรับแอปส่วนใหญ่ Cast API ใช้โปรโตคอลสื่อ Cast ซึ่ง เพิ่มประสิทธิภาพการใช้แบนด์วิดท์สำหรับสถานการณ์นี้และสถานการณ์อื่นๆ ดังนั้นคุณจึงไม่ จำเป็นต้องใช้การซิงค์สถานะของคุณเอง ดูการติดตั้งใช้งานตัวบ่งชี้ความคืบหน้าสำหรับการเล่นสื่อโดยใช้ API อย่างเหมาะสมได้ในแอปตัวอย่าง CastVideos-chrome

ข้อกำหนดของ CORS

สำหรับการสตรีมสื่อแบบปรับอัตรา Google Cast กำหนดให้ต้องมีส่วนหัว CORS แต่แม้แต่สตรีมสื่อ mp4 อย่างง่ายก็ต้องใช้ CORS หากมีแทร็ก หากต้องการเปิดใช้แทร็กสำหรับสื่อใดก็ตาม คุณต้องเปิดใช้ CORS สำหรับทั้งสตรีมแทร็กและสตรีมสื่อ ดังนั้น หากไม่มีส่วนหัว CORS สำหรับสื่อ mp4 แบบธรรมดาในเซิร์ฟเวอร์ และคุณเพิ่มแทร็กคำบรรยายแทนเสียงแบบธรรมดา คุณจะสตรีมสื่อไม่ได้จนกว่าจะอัปเดตเซิร์ฟเวอร์ให้มีส่วนหัว CORS ที่เหมาะสม

คุณต้องมีส่วนหัวต่อไปนี้ Content-Type, Accept-Encoding และ Range โปรดทราบว่าส่วนหัว 2 รายการสุดท้าย Accept-Encoding และ Range เป็นส่วนหัวเพิ่มเติม ที่คุณอาจไม่จำเป็นต้องใช้ก่อนหน้านี้

ใช้ไวลด์การ์ด "*" สำหรับส่วนหัว Access-Control-Allow-Origin ไม่ได้ หากหน้าเว็บมีเนื้อหาสื่อที่ได้รับการคุ้มครอง หน้าเว็บจะต้องใช้โดเมนแทน ไวลด์การ์ด

การกลับมาใช้เซสชันต่อโดยไม่ต้องโหลดหน้าเว็บซ้ำ

หากต้องการกลับมาใช้ CastSession ที่มีอยู่ ให้ใช้ requestSessionById(sessionId) กับ sessionId ของเซสชันที่คุณพยายามเข้าร่วม

คุณจะดู sessionId ได้ใน CastSession ที่ใช้งานอยู่โดยใช้ getSessionId() หลังจากโทร loadMedia()

แนวทางที่แนะนำมีดังนี้

1. โทร loadMedia() เพื่อเริ่มเซสชัน
2. จัดเก็บ sessionId ไว้ในเครื่อง
3. เข้าร่วมเซสชันอีกครั้งโดยใช้ requestSessionById(sessionId) เมื่อจำเป็น

let sessionId;

function rejoinCastSession() {
  chrome.cast.requestSessionById(sessionId);

  // Add any business logic to load new content or only resume the session
}

document.getElementById('play-button').addEventListener(("click"), function() {
  if (sessionId == null) {
    let castSession = cast.framework.CastContext.getInstance().getCurrentSession();
    if (castSession) {
      let mediaInfo = createMediaInfo();
      let request = new chrome.cast.media.LoadRequest(mediaInfo);
      castSession.loadMedia(request)

      sessionId = CastSession.getSessionId();
    } else {
      console.log("Error: Attempting to play media without a Cast Session");
    }
  } else {
    rejoinCastSession();
  }
});

ขั้นตอนถัดไป

ตอนนี้คุณได้ทราบฟีเจอร์ที่เพิ่มลงในแอปตัวส่งบนเว็บได้แล้ว คุณสามารถสร้างแอปตัวส่งสำหรับแพลตฟอร์มอื่น (Android หรือ iOS) หรือ สร้างแอปตัวรับ