คู่มือนักพัฒนาซอฟต์แวร์นี้จะอธิบายวิธีเพิ่มการสนับสนุน Google Cast บนเว็บ แอปผู้ส่งที่ใช้ Cast SDK
คำศัพท์
อุปกรณ์เคลื่อนที่หรือเบราว์เซอร์คือผู้ส่ง ซึ่งจะควบคุมการเล่น อุปกรณ์ Google Cast เป็นเครื่องรับ ซึ่งจะแสดงเนื้อหาบน หน้าจอสำหรับการเล่น
Web Sender SDK ประกอบด้วย 2 ส่วน ได้แก่ Framework API (cast.framework) และ Base API (chrome.cast) โดยทั่วไป คุณจะเรียกใช้ Framework API ระดับที่สูงกว่าและง่ายกว่า ซึ่งจะประมวลผลโดย Base API ระดับล่าง
เฟรมเวิร์กผู้ส่งหมายถึงเฟรมเวิร์ก API, โมดูล และที่เกี่ยวข้อง ทรัพยากรที่มี Wrapper เกี่ยวกับฟังก์ชันระดับล่าง แอปผู้ส่งหรือแอป Google Cast Chrome หมายถึงแอปเว็บ (HTML/JavaScript) ทำงานภายในเบราว์เซอร์ Chrome ในอุปกรณ์ผู้ส่ง แอป Web Receiver อ้างถึง ไปยังแอป HTML/JavaScript ที่ทำงานบน Chromecast หรืออุปกรณ์ Google Cast
เฟรมเวิร์กผู้ส่งใช้การออกแบบ Callback แบบไม่พร้อมกันเพื่อแจ้งผู้ส่ง แอปเหตุการณ์และการเปลี่ยนไปมาระหว่างสถานะต่างๆ ในชีวิตของแอป Cast
โหลดไลบรารี
ในการทำให้แอปนำฟีเจอร์ของ Google Cast ไปใช้งาน แอปจำเป็นต้องรู้ ตำแหน่งของ Google Cast Web Sender SDK ดังที่แสดงด้านล่าง เพิ่ม พารามิเตอร์การค้นหา 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.* Namespace Namespace จะแสดงข้อมูลต่อไปนี้
- เมธอดหรือฟังก์ชันที่เรียกใช้การดำเนินการใน API
- Listener เหตุการณ์สำหรับฟังก์ชัน Listener ใน API
เฟรมเวิร์กนี้มีส่วนประกอบหลักดังต่อไปนี้
CastContext
คือออบเจ็กต์ Singleton ที่ให้ข้อมูลเกี่ยวกับ สถานะการแคสต์ปัจจุบัน และทริกเกอร์เหตุการณ์สำหรับสถานะการแคสต์และเซสชันการแคสต์ การเปลี่ยนแปลงสถานะCastSession
จัดการเซสชัน -- ระบุสถานะ ข้อมูลและเหตุการณ์ทริกเกอร์ เช่น การเปลี่ยนแปลงระดับเสียงของอุปกรณ์ สถานะปิดเสียง และข้อมูลเมตาของแอป- องค์ประกอบปุ่ม "แคสต์" ซึ่งเป็นองค์ประกอบ HTML ที่กำหนดเองอย่างง่ายที่ ปุ่ม HTML จะขยายออก หากปุ่ม "แคสต์" ที่ให้มานั้นไม่เพียงพอ คุณสามารถใช้สถานะ Cast เพื่อนำปุ่ม "แคสต์" ไปใช้
RemotePlayerController
ให้การเชื่อมโยงข้อมูลเพื่อลดความซับซ้อนของการใช้งานโปรแกรมเล่นระยะไกล
ตรวจสอบ เอกสารอ้างอิง API ผู้ส่งเว็บ Google Cast สำหรับ คำอธิบายเนมสเปซที่สมบูรณ์
ปุ่ม "แคสต์"
คอมโพเนนต์ปุ่ม "แคสต์" ในแอปจะจัดการโดยเฟรมเวิร์กทั้งหมด ช่วงเวลานี้ ประกอบด้วยการจัดการระดับการเข้าถึง รวมถึงการจัดการเหตุการณ์การคลิก
<google-cast-launcher></google-cast-launcher>
นอกจากนี้ คุณสามารถสร้างปุ่มแบบเป็นโปรแกรมได้โดยทำดังนี้
document.createElement("google-cast-launcher");
คุณสามารถใช้การจัดรูปแบบเพิ่มเติม เช่น ขนาดหรือตำแหน่ง กับองค์ประกอบ
องค์ประกอบเท่าที่จำเป็น ใช้แอตทริบิวต์ --connected-color
เพื่อ
เลือกสีสำหรับสถานะของเว็บรีซีฟเวอร์ที่เชื่อมต่อ และ
--disconnected-color
สำหรับสถานะการยกเลิกการเชื่อมต่อ
การเริ่มต้น
หลังจากโหลด API เฟรมเวิร์ก แอปจะเรียกใช้เครื่องจัดการ
window.__onGCastApiAvailable
คุณควรตรวจสอบว่าแอปตั้งค่าเครื่องจัดการนี้
ใน window
ก่อนโหลดไลบรารีของผู้ส่ง
ภายในเครื่องจัดการนี้ คุณจะเริ่มต้นการโต้ตอบกับแคสต์ด้วยการเรียกใช้
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
});
};
ก่อนอื่น แอปต้องเรียกอินสแตนซ์เดี่ยวของ
ออบเจ็กต์ 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
รวมถึง Callback ของเหตุการณ์สื่อ และ
จะมีการจัดการกับคำสั่ง
RemotePlayerController
var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);
RemotePlayerController
มอบสิทธิ์ให้แอปควบคุมสื่ออย่างเต็มรูปแบบ
เล่น หยุดชั่วคราว หยุด และดูสื่อที่โหลด
- เล่น/หยุดชั่วคราว:
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>
สถานะสื่อ
ระหว่างการเล่นสื่อ จะมีเหตุการณ์หลายอย่างเกิดขึ้นซึ่งการตั้งค่าจะบันทึกได้โดยการตั้งค่า
ผู้ฟังที่หลากหลาย
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 นำเสนอแนวคิดของเซสชันการแคสต์ ซึ่งประกอบด้วยขั้นตอนการเชื่อมต่อกับอุปกรณ์ การเปิด (หรือการเข้าร่วม) เว็บ แอปตัวรับสัญญาณ การเชื่อมต่อกับแอปดังกล่าว และการเริ่มต้นใช้งานช่องทางควบคุมสื่อ ดูเว็บรีซีฟเวอร์ คำแนะนำเกี่ยวกับวงจรของแอปพลิเคชัน สำหรับข้อมูลเพิ่มเติมเกี่ยวกับเซสชันการแคสต์และวงจรชีวิตของตัวรับเว็บ
ชั้นเรียนเป็นผู้จัดการเซสชัน
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
กิจกรรมนี้เรียกว่ากิจกรรม
โปรดดู การโอนสตรีมใน Web Receiver เพื่อดูข้อมูลเพิ่มเติม