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

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

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

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

คำศัพท์

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

SDK ผู้ส่งเว็บประกอบด้วย 2 ส่วนคือ API ของเฟรมเวิร์ก (cast.framework) และ Base API (chrome.cast) โดยทั่วไป คุณจะเรียก API เฟรมเวิร์กระดับที่สูงกว่าและง่ายขึ้น ซึ่งมีการประมวลผลโดย Base API ระดับล่าง

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

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

โหลดไลบรารี

เพื่อให้แอปของคุณนําคุณลักษณะของ Google Cast ไปใช้ได้ แอปจําเป็นต้องทราบตําแหน่งของ SDK เว็บผู้ส่งของ Google Cast ดังที่แสดงด้านล่าง เพิ่มพารามิเตอร์การค้นหา loadCastFramework URL เพื่อโหลด 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 มีการเชื่อมโยงข้อมูลเพื่อให้ใช้งานโปรแกรมเล่นระยะไกลได้ง่ายขึ้น

อ่านข้อมูลอ้างอิง API ของผู้ส่งสําหรับเว็บของ Google Cast สําหรับคําอธิบายทั้งหมดของเนมสเปซ

ปุ่ม "แคสต์"

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

<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 เพื่อโหลดสื่อไปยังอุปกรณ์ Cast ที่เชื่อมต่อได้โดยใช้ 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, หยุดชั่วคราว, 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>

สถานะสื่อ

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

เซสชันจะจัดการโดยชั้นเรียน CastContext ซึ่งแอปของคุณเรียกดูได้ผ่านทาง cast.framework.CastContext.getInstance() และแต่ละเซสชันจะแสดงโดยคลาสย่อย Session ตัวอย่างเช่น CastSession จะเป็นตัวแทนเซสชันที่มีอุปกรณ์แคสต์ แอปของคุณเข้าถึงเซสชันแคสต์ที่กําลังดําเนินอยู่ผ่าน CastContext.getCurrentSession() ได้

หากต้องการตรวจสอบสถานะเซสชัน ให้เพิ่ม Listener ลงในประเภทเหตุการณ์ CastContextEventType.SESSION_STATE_CHANGED ของ CastContext

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
    }
  });

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

ดูการโอนสตรีมในเครื่องรับเว็บสําหรับข้อมูลเพิ่มเติม