คู่มือนักพัฒนาซอฟต์แวร์นี้อธิบายวิธีเพิ่มการรองรับ Google Cast ในแอป WebSender โดยใช้ Cast SDK
คำศัพท์
อุปกรณ์เคลื่อนที่หรือเบราว์เซอร์คือผู้ส่งซึ่งควบคุมการเล่น โดยอุปกรณ์ Google Cast คือตัวรับที่จะแสดงเนื้อหาบนหน้าจอสําหรับการเล่น
Web Sender SDK ประกอบด้วย 2 ส่วน ได้แก่ Framework API (cast.framework) และ Base API (chrome.cast) โดยทั่วไปคุณเรียกใช้เฟรมเวิร์ก API ระดับที่สูงกว่าและไม่ซับซ้อน ซึ่งประมวลผลโดย Base API ระดับล่าง
เฟรมเวิร์กผู้ส่งหมายถึง API เฟรมเวิร์ก โมดูล และทรัพยากรที่เกี่ยวข้องซึ่งมี Wrapper เกี่ยวกับฟังก์ชันระดับล่าง แอปผู้ส่งหรือแอป Google Cast ใน Chrome หมายถึงแอปเว็บ (HTML/JavaScript) ที่ทํางานภายในเบราว์เซอร์ Chrome ในอุปกรณ์ของผู้ส่ง แอปตัวรับเว็บหมายถึงแอป HTML/JavaScript ที่ทํางานใน Chromecast หรืออุปกรณ์ Google Cast
เฟรมเวิร์กผู้ส่งใช้การออกแบบการเรียกกลับแบบไม่พร้อมกันเพื่อแจ้งแอปของผู้ส่งเหตุการณ์และเพื่อสลับระหว่างสถานะต่างๆ ของวงจรแอปแคสต์
โหลดไลบรารี
เพื่อให้แอปนําฟีเจอร์ของ Google Cast ไปใช้งาน แอปจําเป็นต้องทราบตําแหน่งของ SDK เว็บ Google Cast ดังที่แสดงด้านล่าง เพิ่มพารามิเตอร์การค้นหาของ URL loadCastFramework เพื่อโหลด Web Sender Framework API ด้วย ทุกหน้าของแอปต้องอ้างอิงไลบรารีดังต่อไปนี้
<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
เฟรมเวิร์ก
Web Sender SDK ใช้ cast.framework* เนมสเปซ เนมสเปซแสดงถึงสิ่งต่อไปนี้
- เมธอดหรือฟังก์ชันที่เรียกใช้การดําเนินการบน API
- Listener เหตุการณ์สําหรับฟังก์ชัน Listener ใน API
เฟรมเวิร์กประกอบด้วยองค์ประกอบหลักต่อไปนี้
CastContext
เป็นออบเจ็กต์เดี่ยวที่มีข้อมูลเกี่ยวกับสถานะแคสต์ปัจจุบัน และทริกเกอร์เหตุการณ์สําหรับสถานะแคสต์และสถานะของเซสชันการแคสต์- ออบเจ็กต์
CastSession
จะจัดการเซสชัน โดยมีข้อมูลสถานะและทริกเกอร์เหตุการณ์ เช่น การเปลี่ยนแปลงระดับเสียงของอุปกรณ์ สถานะปิดเสียง และข้อมูลเมตาของแอป - องค์ประกอบปุ่ม "แคสต์" ซึ่งเป็นองค์ประกอบที่กําหนดเองของ HTML ที่เรียบง่ายซึ่งขยายจากปุ่ม HTML หากปุ่ม "แคสต์" ที่ระบุไม่เพียงพอ คุณสามารถใช้สถานะการแคสต์เพื่อใช้ปุ่ม "แคสต์"
RemotePlayerController
ให้การเชื่อมโยงข้อมูลเพื่อให้ใช้งานโปรแกรมเล่นระยะไกลได้ง่ายขึ้น
อ่านเอกสารอ้างอิง Google Cast Web Sender API เพื่อดูคําอธิบายที่สมบูรณ์ของเนมสเปซ
ปุ่ม "แคสต์"
เฟรมเวิร์กของปุ่ม "แคสต์" ในแอปจะได้รับการจัดการโดยเฟรมเวิร์กทั้งหมด ซึ่งรวมถึงการจัดการระดับการเข้าถึงและการจัดการเหตุการณ์คลิก
<google-cast-launcher></google-cast-launcher>
หรือจะสร้างปุ่มโดยใช้วิธีต่อไปนี้ก็ได้
document.createElement("google-cast-launcher");
คุณใช้การจัดรูปแบบเพิ่มเติม เช่น ขนาดหรือตําแหน่งได้กับองค์ประกอบตามที่จําเป็น ใช้แอตทริบิวต์ --connected-color
เพื่อเลือกสีสําหรับสถานะ Web Receiver ที่เชื่อมต่อ และ
--disconnected-color
สําหรับสถานะยกเลิกการเชื่อมต่อแล้ว
การเริ่มต้น
หลังจากโหลด API เฟรมเวิร์กแล้ว แอปจะเรียกเครื่องจัดการ
window.__onGCastApiAvailable
คุณควรตรวจสอบว่าแอปตั้งค่าเครื่องจัดการนี้ใน window
ก่อนที่จะโหลดไลบรารีของผู้ส่ง
ในเครื่องจัดการนี้ คุณเริ่มต้นการโต้ตอบของ Cast ได้โดยเรียกใช้เมธอด setOptions(options)
ของ CastContext
เช่น
<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
if (isAvailable) {
initializeCastApi();
}
};
</script>
จากนั้นจึงเริ่มต้น API ดังนี้
initializeCastApi = function() {
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: applicationId,
autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
});
};
ขั้นแรก แอปจะเรียกอินสแตนซ์ Singleton ของออบเจ็กต์ CastContext
ที่เฟรมเวิร์กระบุไว้ จากนั้นจะใช้
setOptions(options)
โดยใช้ออบเจ็กต์ CastOptions
เพื่อตั้งค่า applicationID
หากคุณใช้ตัวรับสื่อเริ่มต้นซึ่งไม่ต้องลงทะเบียน คุณจะใช้ Web Sender SDK ที่กําหนดไว้ล่วงหน้าตามที่แสดงด้านล่างด้านล่าง applicationID
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});
ส่วนควบคุมสื่อ
เมื่อเริ่มต้น CastContext
แล้ว แอปสามารถเรียกข้อมูล CastSession
ปัจจุบันได้ทุกเมื่อโดยใช้ getCurrentSession()
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
CastSession
สามารถใช้โหลดสื่อไปยังอุปกรณ์แคสต์ที่เชื่อมต่อได้โดยใช้ loadMedia(loadRequest)
ขั้นแรก ให้สร้าง MediaInfo
โดยใช้ contentId
และ contentType
รวมถึงข้อมูลอื่นๆ ที่เกี่ยวข้องกับเนื้อหา จากนั้นสร้าง
LoadRequest
จากต้นทางดังกล่าว แล้วตั้งค่าข้อมูลที่เกี่ยวข้องทั้งหมดสําหรับคําขอ สุดท้ายนี้ ให้โทรหา loadMedia(loadRequest)
ในCastSession
ของคุณ
var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL, contentType);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
function() { console.log('Load succeed'); },
function(errorCode) { console.log('Error code: ' + errorCode); });
เมธอด loadMedia
จะส่งคืนคํามั่นสัญญาที่สามารถใช้เพื่อดําเนินการที่จําเป็นเพื่อให้ได้ผลลัพธ์ที่สําเร็จ
หาก Promise ถูกปฏิเสธ อาร์กิวเมนต์ของฟังก์ชันจะเป็น chrome.cast.ErrorCode
คุณเข้าถึงตัวแปรสถานะผู้เล่นได้ใน RemotePlayer
การโต้ตอบทั้งหมดกับ RemotePlayer
รวมถึงการเรียกกลับและกิจกรรมสื่อจะจัดการกับ RemotePlayerController
var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);
RemotePlayerController
ให้แอปควบคุมสื่อทั้งหมดของ
Play, หยุดชั่วคราว, หยุด และ SeeK สําหรับสื่อที่โหลด
- เล่น/หยุดชั่วคราว:
playerController.playOrPause();
- หยุด:
playerController.stop();
- กรอ:
playerController.seek();
RemotePlayer
และ RemotePlayerController
ใช้กับเฟรมเวิร์กการเชื่อมโยงข้อมูล เช่น Polymer หรือ Angular เพื่อนําโปรแกรมเล่นระยะไกลไปใช้ได้
ข้อมูลโค้ดสําหรับ Angular มีดังนี้
<button id="playPauseButton" class="playerButton" ng-disabled="!player.canPause" ng-click="controller.playOrPause()"> {{player.isPaused ? 'Play' : 'Pause'}} </button> <script> var player = new cast.framework.RemotePlayer(); var controller = new cast.framework.RemotePlayerController(player); // Listen to any player update, and trigger angular data binding update.controller.addEventListener( cast.framework.RemotePlayerEventType.ANY_CHANGE, function(event) { if (!$scope.$$phase) $scope.$apply(); }); </script>
สถานะสื่อ
ในระหว่างการเล่นสื่อ เหตุการณ์ต่างๆ จะเกิดขึ้นได้โดยการตั้งค่า Listener สําหรับเหตุการณ์ cast.framework.RemotePlayerEventType
ต่างๆ ในออบเจ็กต์ RemotePlayerController
หากต้องการรับข้อมูลสถานะสื่อ ให้ใช้เหตุการณ์
cast.framework.RemotePlayerEventType
.MEDIA_INFO_CHANGED
ซึ่งจะทริกเกอร์เมื่อมีการเปลี่ยนแปลงการเล่นและเมื่อ
CastSession.getMediaSession().media
มีการเปลี่ยนแปลง
playerController.addEventListener(
cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, function() {
// Use the current session to get an up to date media status.
let session = cast.framework.CastContext.getInstance().getCurrentSession();
if (!session) {
return;
}
// Contains information about the playing media including currentTime.
let mediaStatus = session.getMediaSession();
if (!mediaStatus) {
return;
}
// mediaStatus also contains the mediaInfo containing metadata and other
// information about the in progress content.
let mediaInfo = mediaStatus.media;
});
เมื่อมีเหตุการณ์อย่างเช่นการหยุดชั่วคราว เล่น เล่นต่อ หรือกรอวิดีโอ แอปจะต้องดําเนินการกับกิจกรรมเหล่านั้นและซิงค์ข้อมูลระหว่างแอปกับแอปตัวรับสัญญาณของอุปกรณ์ Cast ดูข้อมูลเพิ่มเติมในการอัปเดตสถานะ
วิธีการทํางานของการจัดการเซสชัน
Cast SDK แนะนําแนวคิดของเซสชันการแคสต์ ซึ่งเป็นการรวมขั้นตอนการเชื่อมต่อเข้ากับอุปกรณ์ การเปิด (หรือเข้าร่วม) แอป Web Receiver การเชื่อมต่อกับแอปดังกล่าว และเริ่มต้นช่องทางการควบคุมสื่อ ดูข้อมูลเพิ่มเติมเกี่ยวกับเซสชันการแคสต์และอายุการใช้งานของตัวรับสัญญาณบนเว็บได้ในตัวรับข้อมูลเว็บ
เซสชันจะจัดการโดยชั้นเรียน
CastContext
ซึ่งแอปของคุณเรียกดูได้ผ่าน
cast.framework.CastContext.getInstance()
เซสชันแต่ละรายการจะแสดงโดยชั้นเรียนย่อยของชั้นเรียน
Session
ตัวอย่างเช่น
CastSession
เป็นตัวแทนเซสชันที่มีอุปกรณ์แคสต์ แอปของคุณเข้าถึงเซสชันการแคสต์ที่กําลังดําเนินอยู่ผ่าน CastContext.getCurrentSession()
หากต้องการตรวจสอบสถานะของเซสชัน ให้เพิ่ม Listener ลงใน CastContext
สําหรับประเภทเหตุการณ์ CastContextEventType
.SESSION_STATE_CHANGED
var context = cast.framework.CastContext.getInstance();
context.addEventListener(
cast.framework.CastContextEventType.SESSION_STATE_CHANGED,
function(event) {
switch (event.sessionState) {
case cast.framework.SessionState.SESSION_STARTED:
case cast.framework.SessionState.SESSION_RESUMED:
break;
case cast.framework.SessionState.SESSION_ENDED:
console.log('CastContext: CastSession disconnected');
// Update locally as necessary
break;
}
})
สําหรับการยกเลิกการเชื่อมต่อ เช่น เมื่อผู้ใช้คลิกปุ่ม "หยุดแคสต์" จากกล่องโต้ตอบแคสต์ คุณจะเพิ่ม Listener ประเภทเหตุการณ์ RemotePlayerEventType
.IS_CONNECTED_CHANGED
ใน Listener ได้ ในการตรวจสอบผู้ฟังว่า
RemotePlayer
ถูกตัดการเชื่อมต่อหรือไม่ หากเป็นเช่นนั้น ให้อัปเดตสถานะโปรแกรมเล่นวิดีโอในเครื่องตามที่จําเป็น เช่น
playerController.addEventListener(
cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
if (!player.isConnected) {
console.log('RemotePlayerController: Player disconnected');
// Update local player to disconnected state
}
});
แม้ว่าผู้ใช้จะควบคุมการสิ้นสุดการแคสต์ได้โดยตรงผ่านปุ่ม "แคสต์" เฟรมเวิร์ก แต่ผู้ส่งเองสามารถหยุดแคสต์ได้โดยใช้ออบเจ็กต์ CastSession
ปัจจุบัน
function stopCasting() {
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
// End the session and pass 'true' to indicate
// that Web Receiver app should be stopped.
castSession.endSession(true);
}
การโอนสตรีม
การคงเซสชันเซสชันไว้คือพื้นฐานของการโอนสตรีม ซึ่งผู้ใช้สามารถย้ายสตรีมเสียงและวิดีโอที่มีอยู่ในอุปกรณ์ต่างๆ โดยใช้คําสั่งเสียง, แอป Google Home หรือจออัจฉริยะ สื่อจะหยุดเล่นในอุปกรณ์หนึ่ง (แหล่งที่มา) และเล่นต่อในอุปกรณ์อื่น (ปลายทาง) อุปกรณ์แคสต์ที่มีเฟิร์มแวร์ล่าสุดจะใช้เป็นต้นทางหรือปลายทางในการโอนสตรีมได้
หากต้องการรับอุปกรณ์ปลายทางใหม่ในระหว่างการโอนสตรีม ให้เรียก CastSession#getCastDevice()
เมื่อมีการเรียกเหตุการณ์ cast.framework.SessionState
.SESSION_RESUMED
ดูข้อมูลเพิ่มเติมที่หัวข้อการโอนสตรีมบนตัวรับสัญญาณเว็บ