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

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