Tích hợp Cast SDK vào ứng dụng Web Sender

Hướng dẫn dành cho nhà phát triển này mô tả cách thêm tính năng hỗ trợ Google Cast vào ứng dụng Trình gửi web bằng SDK Truyền.

Thuật ngữ

Thiết bị di động hoặc trình duyệt là thiết bị gửi, điều khiển quá trình phát; thiết bị Google Cast là thiết bị nhận, hiển thị nội dung trên màn hình để phát.

SDK Web Sender bao gồm hai phần: API Khung (cast.framework) và API Cơ sở (chrome.cast). Nhìn chung, bạn thực hiện lệnh gọi trên API Khung cấp cao hơn, đơn giản hơn, sau đó được xử lý bằng API Cơ sở cấp thấp hơn.

Khung người gửi là API khung, mô-đun và các tài nguyên liên quan cung cấp một trình bao bọc cho chức năng cấp thấp hơn. Ứng dụng của người gửi hoặc ứng dụng Google Cast cho Chrome là một ứng dụng web (HTML/JavaScript) chạy trong trình duyệt Chrome trên thiết bị của người gửi. Ứng dụng Trình nhận web là một ứng dụng HTML/JavaScript chạy trên Chromecast hoặc thiết bị Google Cast.

Khung người gửi sử dụng thiết kế lệnh gọi lại không đồng bộ để thông báo cho ứng dụng người gửi về các sự kiện và chuyển đổi giữa nhiều trạng thái trong vòng đời của ứng dụng Truyền.

Tải thư viện

Để triển khai các tính năng của Google Cast, ứng dụng của bạn cần biết vị trí của SDK Trình gửi web Google Cast, như minh hoạ dưới đây. Thêm tham số truy vấn URL loadCastFramework để tải cả API Web Sender Framework. Tất cả các trang trong ứng dụng của bạn phải tham chiếu đến thư viện như sau:

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

Khung

SDK Trình gửi web sử dụng không gian tên cast.framework.*. Không gian tên đại diện cho những thông tin sau:

  • Các phương thức hoặc hàm gọi thao tác trên API
  • Trình nghe sự kiện cho các hàm trình nghe trong API

Khung này bao gồm các thành phần chính sau:

  • CastContext là một đối tượng singleton cung cấp thông tin về trạng thái Truyền hiện tại, đồng thời kích hoạt các sự kiện cho trạng thái Truyền và các thay đổi về trạng thái phiên Truyền.
  • Đối tượng CastSession quản lý phiên hoạt động – đối tượng này cung cấp thông tin về trạng thái và kích hoạt các sự kiện, chẳng hạn như thay đổi về âm lượng thiết bị, trạng thái tắt tiếng và siêu dữ liệu của ứng dụng.
  • Phần tử nút Truyền, là một phần tử tuỳ chỉnh HTML đơn giản giúp mở rộng nút HTML. Nếu nút Truyền được cung cấp không đủ, bạn có thể sử dụng trạng thái Truyền để triển khai nút Truyền.
  • RemotePlayerController cung cấp tính năng liên kết dữ liệu để đơn giản hoá việc triển khai trình phát từ xa.

Xem Tài liệu tham khảo API Trình gửi web của Google Cast để biết nội dung mô tả đầy đủ về không gian tên.

Nút truyền

Thành phần nút Truyền trong ứng dụng của bạn hoàn toàn do khung xử lý. Điều này bao gồm việc quản lý chế độ hiển thị cũng như xử lý sự kiện nhấp chuột.

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

Ngoài ra, bạn có thể tạo nút theo phương thức lập trình:

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

Bạn có thể áp dụng mọi kiểu bổ sung (chẳng hạn như kích thước hoặc vị trí) cho phần tử nếu cần. Sử dụng thuộc tính --connected-color để chọn màu cho trạng thái Trình thu nhận web đã kết nối và --disconnected-color cho trạng thái đã ngắt kết nối.

Khởi chạy

Sau khi tải API khung, ứng dụng sẽ gọi trình xử lý window.__onGCastApiAvailable. Bạn nên đảm bảo rằng ứng dụng đặt trình xử lý này trên window trước khi tải thư viện người gửi.

Trong trình xử lý này, bạn khởi động hoạt động tương tác Cast bằng cách gọi phương thức setOptions(options) của CastContext.

Ví dụ:

<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
  if (isAvailable) {
    initializeCastApi();
  }
};
</script>

Sau đó, bạn khởi chạy API như sau:

initializeCastApi = function() {
  cast.framework.CastContext.getInstance().setOptions({
    receiverApplicationId: applicationId,
    autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
  });
};

Trước tiên, ứng dụng sẽ truy xuất thực thể singleton của đối tượng CastContext do khung cung cấp. Sau đó, hệ thống sẽ sử dụng setOptions(options) bằng cách dùng đối tượng CastOptions để đặt applicationID.

Nếu đang sử dụng Trình nhận nội dung nghe nhìn mặc định (không yêu cầu đăng ký), bạn sẽ sử dụng một hằng số được xác định trước bằng SDK Web Sender (như minh hoạ bên dưới) thay vì applicationID:

cast.framework.CastContext.getInstance().setOptions({
  receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});

Điều khiển phương tiện

Sau khi CastContext được khởi chạy, ứng dụng có thể truy xuất CastSession hiện tại bất cứ lúc nào bằng cách sử dụng getCurrentSession().

var castSession = cast.framework.CastContext.getInstance().getCurrentSession();

Bạn có thể dùng CastSession để tải nội dung nghe nhìn vào thiết bị Truyền đã kết nối bằng cách sử dụng loadMedia(loadRequest). Trước tiên, hãy tạo một MediaInfo bằng cách sử dụng contentId và contentType cũng như mọi thông tin khác liên quan đến nội dung. Sau đó, hãy tạo một LoadRequest từ đó, đặt tất cả thông tin liên quan cho yêu cầu. Cuối cùng, hãy gọi loadMedia(loadRequest) trên 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); });

Phương thức loadMedia sẽ trả về một Promise có thể dùng để thực hiện mọi thao tác cần thiết nhằm đạt được kết quả thành công. Nếu Lời hứa bị từ chối, đối số hàm sẽ là chrome.cast.ErrorCode.

Bạn có thể truy cập vào các biến trạng thái của trình phát trong RemotePlayer. Tất cả các hoạt động tương tác với RemotePlayer, bao gồm cả lệnh gọi lại và lệnh sự kiện đa phương tiện, đều được xử lý bằng RemotePlayerController.

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

RemotePlayerController cung cấp cho ứng dụng toàn quyền kiểm soát nội dung nghe nhìn đối với các thao tác PHÁT, TẠM DỪNG, DỪNG và TUA cho nội dung nghe nhìn đã tải.

  • PHÁT/TẠM DỪNG: playerController.playOrPause();
  • STOP: playerController.stop();
  • SEEK: playerController.seek();

Bạn có thể sử dụng RemotePlayer và RemotePlayerController với các khung liên kết dữ liệu, chẳng hạn như Polymer hoặc Angular, để triển khai trình phát từ xa.

Dưới đây là đoạn mã cho 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>

Trạng thái nội dung nghe nhìn

Trong quá trình phát nội dung nghe nhìn, nhiều sự kiện xảy ra có thể được ghi lại bằng cách đặt trình nghe cho nhiều sự kiện cast.framework.RemotePlayerEventType trên đối tượng RemotePlayerController.

Để lấy thông tin về trạng thái nội dung nghe nhìn, hãy sử dụng sự kiện cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED. Sự kiện này sẽ kích hoạt khi quá trình phát thay đổi và khi CastSession.getMediaSession().media thay đổi.

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

Khi các sự kiện như tạm dừng, phát, tiếp tục hoặc tua xảy ra, ứng dụng sẽ cần phải hành động trên các sự kiện đó và đồng bộ hoá giữa chính ứng dụng đó và ứng dụng Trình nhận web trên thiết bị Truyền. Xem phần Thông tin cập nhật về trạng thái để biết thêm thông tin.

Cách hoạt động của tính năng quản lý phiên

SDK Truyền giới thiệu khái niệm về phiên Truyền, việc thiết lập phiên này kết hợp các bước kết nối với thiết bị, khởi chạy (hoặc tham gia) ứng dụng Trình nhận web, kết nối với ứng dụng đó và khởi chạy kênh điều khiển nội dung nghe nhìn. Hãy xem Hướng dẫn về vòng đời ứng dụng của Trình thu nhận web để biết thêm thông tin về phiên truyền và vòng đời của Trình thu nhận web.

Phiên được quản lý bởi lớp CastContext, mà ứng dụng của bạn có thể truy xuất thông qua cast.framework.CastContext.getInstance(). Các phiên riêng lẻ được biểu thị bằng các lớp con của lớp Session. Ví dụ: CastSession đại diện cho các phiên hoạt động với thiết bị Truyền. Ứng dụng của bạn có thể truy cập vào phiên Truyền hiện đang hoạt động thông qua CastContext.getCurrentSession().

Để theo dõi trạng thái phiên, hãy thêm trình nghe vào CastContext cho loại sự kiện 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;
    }
  })

Để ngắt kết nối, chẳng hạn như khi người dùng nhấp vào nút "dừng truyền" trong hộp thoại Truyền, bạn có thể thêm trình nghe cho loại sự kiện RemotePlayerEventType.IS_CONNECTED_CHANGED trong trình nghe của mình. Trong trình nghe, hãy kiểm tra xem RemotePlayer có bị ngắt kết nối hay không. Nếu có, hãy cập nhật trạng thái người chơi cục bộ nếu cần. Ví dụ:

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
    if (!player.isConnected) {
      console.log('RemotePlayerController: Player disconnected');
      // Update local player to disconnected state
    }
  });

Mặc dù người dùng có thể trực tiếp kiểm soát việc chấm dứt Cast thông qua nút Cast của khung, nhưng chính người gửi có thể dừng truyền bằng đối tượng CastSession hiện tại.

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

Chuyển đổi phiên phát trực tuyến

Việc duy trì trạng thái phiên là cơ sở của tính năng chuyển đổi phiên phát trực tuyến, trong đó người dùng có thể di chuyển các luồng âm thanh và video hiện có trên các thiết bị bằng lệnh thoại, ứng dụng Google Home hoặc màn hình thông minh. Nội dung nghe nhìn sẽ dừng phát trên một thiết bị (nguồn) và tiếp tục phát trên một thiết bị khác (đích). Bất kỳ thiết bị Truyền nào có chương trình cơ sở mới nhất đều có thể đóng vai trò là nguồn hoặc đích đến trong quá trình chuyển đổi phiên phát trực tuyến.

Để lấy thiết bị đích mới trong quá trình chuyển đổi phiên phát trực tuyến, hãy gọi CastSession#getCastDevice() khi sự kiện cast.framework.SessionState.SESSION_RESUMED được gọi.

Hãy xem phần Chuyển đổi phiên phát trực tuyến trên Trình thu nhận web để biết thêm thông tin.

Trước
Thiết lập
Tiếp
Thêm các tính năng nâng cao