ผสานรวม Cast SDK เข้ากับแอป Web Sender

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

หมายเหตุ: เราขอแนะนําให้คุณลองทําสิ่งต่อไปนี้

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

คำศัพท์

อุปกรณ์เคลื่อนที่หรือเบราว์เซอร์คือผู้ส่งซึ่งควบคุมการเล่น โดยอุปกรณ์ 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

ดูข้อมูลเพิ่มเติมที่หัวข้อการโอนสตรีมบนตัวรับสัญญาณเว็บ