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

คู่มือนักพัฒนาแอปนี้อธิบายวิธีเพิ่มการรองรับ Google Cast ลงในแอป Web Sender โดยใช้ Cast SDK

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

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

คำศัพท์

อุปกรณ์เคลื่อนที่หรือเบราว์เซอร์คือ Sender ซึ่งควบคุมการเล่น ส่วนอุปกรณ์ Google Cast คือ Receiver ซึ่งแสดงเนื้อหาบน หน้าจอเพื่อเล่น

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

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

Sender Framework ใช้การออกแบบการเรียกกลับแบบไม่พร้อมกันเพื่อแจ้งให้แอป Sender ทราบถึงเหตุการณ์ต่างๆ และเปลี่ยนสถานะต่างๆ ในวงจรชีวิตของแอป 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.* เนมสเปซ เนมสเปซแสดงถึงสิ่งต่อไปนี้

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

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

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

โปรดดูคำอธิบายเนมสเปซฉบับสมบูรณ์ได้ที่เอกสารอ้างอิง Google Cast Web Sender API

ปุ่ม "แคสต์"

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

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

หรือคุณจะสร้างปุ่มแบบเป็นโปรแกรมก็ได้

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

คุณสามารถใช้สไตล์เพิ่มเติม เช่น ขนาดหรือตำแหน่ง กับองค์ประกอบได้ตามต้องการ ใช้แอตทริบิวต์ --connected-color เพื่อเลือกสีสำหรับสถานะ Web Receiver ที่เชื่อมต่อ และ --disconnected-color สำหรับสถานะที่ไม่ได้เชื่อมต่อ

การเริ่มต้น

หลังจากโหลด Framework API แล้ว แอปจะเรียกใช้แฮนเดิลอร์ window.__onGCastApiAvailable คุณควรตรวจสอบว่าแอปได้ตั้งค่าแฮนเดิลอร์นี้ ใน window ก่อนที่จะ โหลดไลบรารี Sender

ภายในตัวแฮนเดิลนี้ คุณจะเริ่มต้นการโต้ตอบ 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

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

คุณสามารถเข้าถึงตัวแปรสถานะของเครื่องเล่นได้ใน RemotePlayer `RemotePlayerController` จะจัดการการโต้ตอบทั้งหมดกับ RemotePlayer ซึ่งรวมถึงการเรียกกลับและ คำสั่งเหตุการณ์สื่อ ซึ่งจัดการด้วย 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>

สถานะสื่อ

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

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

วิธีการทำงานของการจัดการเซสชัน

Cast SDK นำเสนอแนวคิดเรื่องเซสชัน Cast ซึ่งการสร้างเซสชันจะรวมขั้นตอนต่างๆ ได้แก่ การเชื่อมต่อกับอุปกรณ์ การเปิด (หรือเข้าร่วม) แอป Web Receiver การเชื่อมต่อกับแอปนั้น และการเริ่มต้นช่องควบคุมสื่อ ดูข้อมูลเพิ่มเติมเกี่ยวกับเซสชัน Cast และวงจรชีวิตของ Web Receiver ได้ที่คู่มือวงจรชีวิตของแอปพลิเคชัน Web Receiver

คลาส CastContextเป็นผู้จัดการเซสชัน ซึ่งแอปของคุณสามารถดึงข้อมูลได้ผ่าน cast.framework.CastContext.getInstance() เซสชันแต่ละรายการจะแสดงด้วยคลาสย่อยของคลาส Session เช่น CastSession แสดงถึงเซสชันกับอุปกรณ์ Cast แอปของคุณสามารถเข้าถึงเซสชัน Cast ที่ใช้งานอยู่ในปัจจุบันได้ผ่าน 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;
    }
  })

สำหรับการยกเลิกการเชื่อมต่อ เช่น เมื่อผู้ใช้คลิกปุ่ม "หยุดแคสต์" จาก กล่องโต้ตอบ Cast คุณสามารถเพิ่ม 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 ของเฟรมเวิร์ก แต่ Sender เองก็สามารถหยุดการแคสต์ได้โดยใช้ออบเจ็กต์ 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

ดูข้อมูลเพิ่มเติมได้ที่ การถ่ายโอนสตรีมใน Web Receiver