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

คู่มือนักพัฒนาซอฟต์แวร์นี้จะอธิบายวิธีเพิ่มการสนับสนุน Google Cast ไปยังแอป Web Sender โดยใช้ 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 ในอุปกรณ์ผู้ส่ง แอปตัวรับเว็บหมายถึงแอป HTML/JavaScript ที่ทำงานบน Chromecast หรืออุปกรณ์ Google Cast

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

โหลดไลบรารี

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

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

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

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

ตรวจสอบข้อมูลอ้างอิง API ผู้ส่งของ Google Cast Web เพื่อดูคำอธิบายทั้งหมดของเนมสเปซ

ปุ่ม "แคสต์"

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

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

ก่อนอื่นแอปจะดึงอินสแตนซ์ 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 ซึ่งรวมถึง Callback และคําสั่งเหตุการณ์ของสื่อจะจัดการด้วย RemotePlayerController

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

RemotePlayerController ให้แอปควบคุมสื่ออย่างเต็มรูปแบบ ระหว่าง "PLAY" "หยุดชั่วคราว" "หยุด" และ "ดู" สำหรับสื่อที่โหลด

  • เล่น/หยุดชั่วคราว: 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 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
    }
  });

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

ก่อนหน้า
ตั้งค่า
ถัดไป
เพิ่มฟีเจอร์ขั้นสูง