ผสานรวม SDK ของ Cast ลงในแอป Web Sender

คู่มือนักพัฒนาซอฟต์แวร์นี้จะอธิบายวิธีเพิ่มการสนับสนุน Google Cast ไปยังแอป Web Sender โดยใช้ Cast SDK

หมายเหตุ: เราขอแนะนำให้ลองทำตามขั้นตอนต่อไปนี้

• บทแนะนำ Cast Web Sender Codelab - เรียนรู้วิธีการแบบทีละขั้นตอนในการแก้ไขแอปวิดีโอบนเว็บที่มีอยู่เพื่อเล่นเนื้อหาในอุปกรณ์ Google Cast
• แอป CastVideos-chrome ตัวอย่าง (GitHub) - เรียกใช้ ไปยังส่วนต่างๆ และดูแอปตัวอย่างอ้างอิงนี้ซึ่งเป็นไปตาม หลักเกณฑ์ด้าน UX และ รายการตรวจสอบการออกแบบ

คำศัพท์

อุปกรณ์เคลื่อนที่หรือเบราว์เซอร์คือผู้ส่งซึ่งควบคุมการเล่น ส่วนอุปกรณ์ Google Cast จะเป็นตัวรับซึ่งจะแสดงเนื้อหาบนหน้าจอสำหรับเล่น

SDK สำหรับ Web Sender ประกอบด้วย 2 ส่วน ได้แก่ Framework API (cast.framework) และ Base API (chrome.cast) โดยทั่วไป คุณจะเรียกใช้ Framework API ระดับสูงกว่าที่ใช้งานง่ายขึ้น ซึ่งจะประมวลผลโดย Base API ระดับล่าง

เฟรมเวิร์กผู้ส่งหมายถึงเฟรมเวิร์ก API, โมดูล และทรัพยากรที่เกี่ยวข้องซึ่งมอบ Wrapper เกี่ยวกับฟังก์ชันการทำงานในระดับต่ำกว่า แอปของผู้ส่งหรือแอป Google Cast สำหรับ Chrome หมายถึงแอปเว็บ (HTML/JavaScript) ที่ทำงานในเบราว์เซอร์ Chrome บนอุปกรณ์ของผู้ส่ง แอปเว็บรีซีฟเวอร์หมายถึงแอป HTML/JavaScript ที่ทำงานบน Chromecast หรืออุปกรณ์ Google Cast

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

โหลดไลบรารี

เพื่อให้แอปของคุณใช้ฟีเจอร์ของ Google Cast แอปได้จำเป็นต้องทราบตำแหน่งของ SDK สำหรับ Google Cast Web Sender ดังที่แสดงด้านล่าง เพิ่มพารามิเตอร์การค้นหา URL loadCastFramework เพื่อโหลด Web Sender Framework API ด้วย ทุกหน้าของแอปต้องอ้างอิงถึงไลบรารีดังนี้

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

เฟรมเวิร์ก

SDK สำหรับ Web Sender ใช้ cast.framework.* และมีเนมสเปซ เนมสเปซจะมีดังนี้

• เมธอดหรือฟังก์ชันที่เรียกใช้การดำเนินการบน API
• Listener เหตุการณ์สำหรับฟังก์ชัน Listener ใน API

เฟรมเวิร์กประกอบด้วยองค์ประกอบหลักต่อไปนี้

• CastContext เป็นออบเจ็กต์ Singleton ที่ให้ข้อมูลเกี่ยวกับสถานะการแคสต์ปัจจุบัน และทริกเกอร์เหตุการณ์สำหรับการเปลี่ยนแปลงสถานะการแคสต์และสถานะเซสชัน
• ออบเจ็กต์ CastSession จะจัดการเซสชัน โดยให้ข้อมูลสถานะและทริกเกอร์เหตุการณ์ เช่น การเปลี่ยนแปลงระดับเสียงของอุปกรณ์ สถานะปิดเสียง และข้อมูลเมตาของแอป
• องค์ประกอบปุ่ม "แคสต์" ซึ่งเป็นองค์ประกอบ HTML ที่กำหนดเองที่เรียบง่าย ซึ่งขยายปุ่ม HTML หากปุ่ม "แคสต์" ที่ให้มายังไม่เพียงพอ คุณสามารถใช้สถานะ "แคสต์" เพื่อใช้งานปุ่ม "แคสต์"
• RemotePlayerController มอบการเชื่อมโยงข้อมูลเพื่อทำให้การใช้งานโปรแกรมเล่นระยะไกลง่ายขึ้น

อ่าน ข้อมูลอ้างอิง API ของ Google Cast Web Sender เพื่อดูคำอธิบายแบบเต็มของเนมสเปซ

ปุ่ม "แคสต์"

คอมโพเนนต์ปุ่ม "แคสต์" ในแอปของคุณได้รับการจัดการโดยเฟรมเวิร์กทั้งหมด ซึ่งรวมถึงการจัดการระดับการเข้าถึง ตลอดจนการจัดการกิจกรรมการคลิก

<google-cast-launcher></google-cast-launcher>

อีกวิธีหนึ่งคือ คุณสามารถสร้างปุ่มแบบเป็นโปรแกรมได้ดังนี้

document.createElement("google-cast-launcher");

คุณสามารถนำการจัดรูปแบบเพิ่มเติม เช่น ขนาดหรือการวางตำแหน่ง ไปใช้กับองค์ประกอบได้ตามต้องการ ใช้แอตทริบิวต์ --connected-color เพื่อเลือกสีสำหรับสถานะของ Web Receiver ที่เชื่อมต่อและ --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
  });
};

ก่อนอื่น แอปจะเรียกอินสแตนซ์ Singleton ของออบเจ็กต์ CastContext ที่เฟรมเวิร์กระบุไว้ จากนั้นจะใช้ setOptions(options) โดยใช้ออบเจ็กต์ CastOptions เพื่อตั้งค่า applicationID

หากคุณใช้รีซีฟเวอร์สื่อเริ่มต้นซึ่งไม่ต้องมีการลงทะเบียน คุณสามารถใช้ SDK สำหรับ Web Sender ที่กำหนดไว้ล่วงหน้าตามที่แสดงด้านล่างแทนการใช้ 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 ที่นำไปใช้ดําเนินการที่จําเป็นเพื่อให้ได้ผลลัพธ์ที่ประสบความสำเร็จได้ หาก Promise ถูกปฏิเสธ อาร์กิวเมนต์ของฟังก์ชันจะเป็น chrome.cast.ErrorCode

คุณเข้าถึงตัวแปรสถานะโปรแกรมเล่นได้ใน RemotePlayer การโต้ตอบทั้งหมดกับ RemotePlayer รวมถึงโค้ดเรียกกลับและคำสั่งของเหตุการณ์สื่อ จะจัดการด้วย RemotePlayerController

var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);

RemotePlayerController ช่วยให้แอปควบคุมสื่อได้อย่างเต็มรูปแบบ ทั้ง PLAY, หยุดชั่วคราว, STOP และ 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>

สถานะสื่อ

ระหว่างการเล่นสื่อ จะมีเหตุการณ์ต่างๆ เกิดขึ้นซึ่งบันทึกไว้ได้โดยการตั้งค่าตัวฟังเหตุการณ์ 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 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 ได้ ใน 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
    }
  });

แม้ว่าผู้ใช้จะควบคุมการสิ้นสุดของ Cast ได้โดยตรงผ่านปุ่ม "แคสต์" ที่เป็นเฟรมเวิร์ก แต่ตัวผู้ส่งจะหยุดการแคสต์ได้โดยใช้ออบเจ็กต์ 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 หรือ Smart Display สื่อจะหยุดเล่นในอุปกรณ์หนึ่ง (แหล่งที่มา) และเล่นต่อในอุปกรณ์อื่น (ปลายทาง) อุปกรณ์แคสต์ที่มีเฟิร์มแวร์เวอร์ชันล่าสุดจะใช้เป็นแหล่งที่มาหรือปลายทางในการโอนสตรีมได้

หากต้องการรับอุปกรณ์ปลายทางใหม่ระหว่างการโอนสตรีม ให้โทรหา CastSession#getCastDevice() เมื่อมีการเรียกเหตุการณ์ cast.framework.SessionState.SESSION_RESUMED

ดูการโอนสตรีมบนเว็บรีซีฟเวอร์สำหรับข้อมูลเพิ่มเติม