Thêm các tính năng cốt lõi vào trình thu nhận web tuỳ chỉnh

Trang này chứa các đoạn mã và nội dung mô tả các tính năng có sẵn cho ứng dụng Trình thu web tuỳ chỉnh.

1. Thành phần cast-media-player đại diện cho giao diện người dùng của trình phát tích hợp sẵn được cung cấp bằng Web Receiver.
2. Định kiểu CSS tuỳ chỉnh cho phần tử cast-media-player để định kiểu cho nhiều phần tử giao diện người dùng như background-image, splash-image và font-family.
3. Một phần tử tập lệnh để tải khung Bộ thu web.
4. Mã JavaScript để chặn thông báo và xử lý sự kiện.
5. Thêm vào hàng đợi để tự động phát.
6. Các tuỳ chọn để định cấu hình chế độ phát.
7. Các tuỳ chọn để đặt ngữ cảnh Trình nhận web.
8. Các tuỳ chọn để đặt các lệnh mà ứng dụng Web Receiver hỗ trợ.
9. Lệnh gọi JavaScript để khởi động ứng dụng Web Receiver.

Cấu hình và tuỳ chọn ứng dụng

Định cấu hình ứng dụng

CastReceiverContext là lớp ngoài cùng hiển thị cho nhà phát triển, đồng thời lớp này quản lý việc tải các thư viện cơ bản và xử lý việc khởi chạy SDK Bộ thu web. SDK cung cấp các API cho phép nhà phát triển ứng dụng định cấu hình SDK thông qua CastReceiverOptions. Các cấu hình này được đánh giá một lần mỗi khi khởi chạy ứng dụng và được chuyển đến SDK khi đặt tham số không bắt buộc trong lệnh gọi đến start.

Ví dụ dưới đây cho biết cách ghi đè hành vi mặc định để phát hiện xem kết nối của trình gửi có còn đang kết nối hay không. Khi Trình nhận web không thể giao tiếp với trình gửi trong maxInactivity giây, một sự kiện SENDER_DISCONNECTED sẽ được gửi. Cấu hình bên dưới sẽ ghi đè thời gian chờ này. Điều này có thể hữu ích khi gỡ lỗi các vấn đề vì nó ngăn ứng dụng Web Receiver đóng phiên Trình gỡ lỗi từ xa của Chrome khi không có trình gửi nào được kết nối ở trạng thái IDLE.

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);

Định cấu hình trình phát

Khi tải nội dung, SDK Bộ thu web cung cấp một cách để định cấu hình các biến phát như thông tin DRM, cấu hình thử lại và trình xử lý yêu cầu bằng cách sử dụng cast.framework.PlaybackConfig. Thông tin này do PlayerManager xử lý và được đánh giá tại thời điểm tạo người chơi. Người chơi được tạo mỗi khi một tải mới được truyền đến SDK Bộ thu web. Các nội dung sửa đổi đối với PlaybackConfig sau khi trình phát được tạo sẽ được đánh giá trong lần tải nội dung tiếp theo. SDK cung cấp các phương thức sau để sửa đổi PlaybackConfig.

• CastReceiverOptions.playbackConfig để ghi đè các tuỳ chọn cấu hình mặc định khi khởi tạo CastReceiverContext.
• PlayerManager.getPlaybackConfig() để lấy cấu hình hiện tại.
• PlayerManager.setPlaybackConfig() để ghi đè cấu hình hiện tại. Chế độ cài đặt này được áp dụng cho tất cả các lần tải tiếp theo hoặc cho đến khi chế độ cài đặt này được ghi đè lại.
• PlayerManager.setMediaPlaybackInfoHandler() để chỉ áp dụng các cấu hình bổ sung cho mục nội dung nghe nhìn đang được tải lên trên các cấu hình hiện tại. Trình xử lý được gọi ngay trước khi tạo người chơi. Các thay đổi được thực hiện tại đây không phải là vĩnh viễn và không được đưa vào truy vấn đến getPlaybackConfig(). Khi tải mục nội dung đa phương tiện tiếp theo, trình xử lý này sẽ được gọi lại.

Ví dụ dưới đây cho thấy cách thiết lập PlaybackConfig khi khởi tạo CastReceiverContext. Cấu hình này ghi đè các yêu cầu gửi đi để lấy tệp kê khai. Trình xử lý chỉ định rằng các yêu cầu Kiểm soát quyền truy cập CORS phải được thực hiện bằng thông tin xác thực như cookie hoặc tiêu đề uỷ quyền.

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

Ví dụ bên dưới cho thấy cách ghi đè PlaybackConfig bằng cách sử dụng phương thức getter và setter được cung cấp trong PlayerManager. Chế độ cài đặt này định cấu hình trình phát để tiếp tục phát nội dung sau khi tải 1 phân đoạn.

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

Ví dụ bên dưới cho thấy cách ghi đè PlaybackConfig cho một yêu cầu tải cụ thể bằng cách sử dụng trình xử lý thông tin phát nội dung nghe nhìn. Trình xử lý gọi một phương thức triển khai ứng dụng getLicenseUrlForMedia để lấy licenseUrl từ contentId của mục hiện tại.

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

Trình nghe sự kiện

SDK Bộ thu web cho phép ứng dụng Bộ thu web xử lý các sự kiện của người chơi. Trình nghe sự kiện sẽ lấy thông số cast.framework.events.EventType (hoặc một mảng các thông số này) để chỉ định(các) sự kiện sẽ kích hoạt trình nghe. Bạn có thể tìm thấy các mảng cast.framework.events.EventType được định cấu hình sẵn hữu ích cho việc gỡ lỗi trong cast.framework.events.category. Thông số sự kiện cung cấp thêm thông tin về sự kiện.

Ví dụ: nếu muốn biết thời điểm thay đổi mediaStatus đang được truyền tin, bạn có thể sử dụng logic sau để xử lý sự kiện:

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
    cast.framework.events.EventType.MEDIA_STATUS, (event) => {
      // Write your own event handling code, for example
      // using the event.mediaStatus value
});

Chặn tin nhắn

SDK Trình thu nhận web cho phép ứng dụng Trình thu nhận web của bạn chặn tin nhắn và thực thi mã tuỳ chỉnh trên các tin nhắn đó. Trình chặn thông báo sẽ lấy một tham số cast.framework.messages.MessageType chỉ định loại thông báo cần chặn.

Trình chặn sẽ trả về yêu cầu đã sửa đổi hoặc một Lời hứa phân giải với giá trị yêu cầu đã sửa đổi. Việc trả về null sẽ ngăn việc gọi trình xử lý thông báo mặc định. Hãy xem phần Tải nội dung nghe nhìn để biết thêm thông tin chi tiết.

Ví dụ: nếu muốn thay đổi dữ liệu yêu cầu tải, bạn có thể sử dụng logic sau để chặn và sửa đổi dữ liệu đó:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_FAILED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      if (!loadRequestData.media.entity) {
        return loadRequestData;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          if (!asset) {
            throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
          }

          loadRequestData.media.contentUrl = asset.url;
          loadRequestData.media.metadata = asset.metadata;
          loadRequestData.media.tracks = asset.tracks;
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

context.start();

Xử lý lỗi

Khi lỗi xảy ra trong trình chặn thông báo, ứng dụng Trình thu nhận web của bạn sẽ trả về một cast.framework.messages.ErrorType và cast.framework.messages.ErrorReason thích hợp.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_CANCELLED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      ...

      return fetchAssetAndAuth(loadRequestData.media.entity,
                               loadRequestData.credentials)
        .then(asset => {
          ...
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

Tính năng chặn thông báo so với trình nghe sự kiện

Sau đây là một số điểm khác biệt chính giữa tính năng chặn thông báo và trình nghe sự kiện:

• Trình nghe sự kiện không cho phép bạn sửa đổi dữ liệu yêu cầu.
• Trình nghe sự kiện được dùng tốt nhất để kích hoạt số liệu phân tích hoặc hàm tuỳ chỉnh.

playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });

• Tính năng chặn tin nhắn cho phép bạn nghe, chặn và chỉnh sửa chính dữ liệu yêu cầu.
• Bạn nên sử dụng tính năng chặn thông báo để xử lý logic tuỳ chỉnh liên quan đến dữ liệu yêu cầu.

Đang tải nội dung nghe nhìn

MediaInformation cung cấp nhiều thuộc tính để tải nội dung nghe nhìn trong thông báo cast.framework.messages.MessageType.LOAD, bao gồm entity, contentUrl và contentId.

• entity là thuộc tính được đề xuất để sử dụng trong quá trình triển khai cho cả ứng dụng gửi và ứng dụng nhận. Thuộc tính này là một URL đường liên kết sâu có thể là danh sách phát hoặc nội dung nghe nhìn. Ứng dụng của bạn phải phân tích cú pháp URL này và điền ít nhất một trong hai trường còn lại.
• contentUrl tương ứng với URL có thể phát mà trình phát sẽ sử dụng để tải nội dung. Ví dụ: URL này có thể trỏ đến tệp kê khai DASH.
• contentId có thể là URL nội dung có thể phát (tương tự như URL của thuộc tính contentUrl) hoặc giá trị nhận dạng duy nhất cho nội dung hoặc danh sách phát đang tải. Nếu sử dụng thuộc tính này làm giá trị nhận dạng, ứng dụng của bạn sẽ điền sẵn một URL có thể phát trong contentUrl.

Bạn nên sử dụng entity để lưu trữ mã nhận dạng thực hoặc các tham số khoá và sử dụng contentUrl cho URL của nội dung nghe nhìn. Ví dụ về điều này được thể hiện trong đoạn mã sau đây, trong đó entity có trong yêu cầu LOAD và contentUrl có thể phát được truy xuất:

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      ...

      if (!loadRequestData.media.entity) {
        // Copy the value from contentId for legacy reasons if needed
        loadRequestData.media.entity = loadRequestData.media.contentId;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          loadRequestData.media.contentUrl = asset.url;
          ...
          return loadRequestData;
        });
    });

Khả năng của thiết bị

Phương thức getDeviceCapabilities cung cấp thông tin về thiết bị trên thiết bị Cast đã kết nối và thiết bị video hoặc âm thanh được đính kèm với thiết bị đó. Phương thức getDeviceCapabilities cung cấp thông tin hỗ trợ cho Trợ lý Google, Bluetooth cũng như màn hình và thiết bị âm thanh đã kết nối.

Phương thức này trả về một đối tượng mà bạn có thể truy vấn bằng cách truyền vào một trong các enum được chỉ định để lấy chức năng của thiết bị cho enum đó. Các enum được xác định trong cast.framework.system.DeviceCapabilities.

Ví dụ này kiểm tra xem thiết bị Web Receiver có thể phát HDR và DolbyVision (DV) bằng các khoá IS_HDR_SUPPORTED và IS_DV_SUPPORTED hay không.

const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
  const deviceCapabilities = context.getDeviceCapabilities();
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
  }
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
  }
});
context.start();

Xử lý hoạt động tương tác của người dùng

Người dùng có thể tương tác với ứng dụng Web Receiver thông qua các ứng dụng gửi (Web, Android và iOS), lệnh thoại trên các thiết bị có Trợ lý, các nút điều khiển cảm ứng trên màn hình thông minh và điều khiển từ xa trên các thiết bị Android TV. Cast SDK cung cấp nhiều API để cho phép ứng dụng Web Receiver xử lý các lượt tương tác này, cập nhật giao diện người dùng của ứng dụng thông qua trạng thái hành động của người dùng và tuỳ ý gửi các thay đổi để cập nhật mọi dịch vụ phụ trợ.

Các lệnh đa phương tiện được hỗ trợ

Các trạng thái điều khiển giao diện người dùng được điều khiển bởi MediaStatus.supportedMediaCommands cho trình điều khiển mở rộng của trình gửi iOS và Android, ứng dụng điều khiển từ xa và trình nhận chạy trên thiết bị cảm ứng, cũng như ứng dụng trình nhận trên thiết bị Android TV. Khi một Command bit cụ thể được bật trong thuộc tính, các nút liên quan đến thao tác đó sẽ được bật. Nếu bạn không đặt giá trị này, nút sẽ bị vô hiệu hoá. Bạn có thể thay đổi các giá trị này trên Trình thu web bằng cách:

1. Sử dụng PlayerManager.setSupportedMediaCommands để đặt Commands cụ thể
2. Thêm lệnh mới bằng cách sử dụng addSupportedMediaCommands
3. Xoá một lệnh hiện có bằng cách sử dụng removeSupportedMediaCommands.

playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

Khi trình nhận chuẩn bị MediaStatus đã cập nhật, trình nhận sẽ bao gồm các thay đổi trong thuộc tính supportedMediaCommands. Khi trạng thái được truyền tin, các ứng dụng trình gửi đã kết nối sẽ cập nhật các nút trong giao diện người dùng tương ứng.

Để biết thêm thông tin về các lệnh đa phương tiện và thiết bị cảm ứng được hỗ trợ, hãy xem hướng dẫn về Accessing UI controls.

Quản lý trạng thái thao tác của người dùng

Khi tương tác với giao diện người dùng hoặc gửi lệnh thoại, người dùng có thể kiểm soát việc phát nội dung và các thuộc tính liên quan đến mục đang phát. SDK sẽ tự động xử lý các yêu cầu kiểm soát chế độ phát. Các yêu cầu chỉnh sửa thuộc tính cho mục đang phát, chẳng hạn như lệnh LIKE, yêu cầu ứng dụng nhận xử lý các yêu cầu đó. SDK cung cấp một loạt API để xử lý các loại yêu cầu này. Để hỗ trợ các yêu cầu này, bạn phải làm như sau:

• Đặt MediaInformation userActionStates theo lựa chọn ưu tiên của người dùng khi tải một mục nội dung nghe nhìn.
• Chặn thông báo USER_ACTION và xác định hành động được yêu cầu.
• Cập nhật MediaInformation UserActionState để cập nhật giao diện người dùng.

Đoạn mã sau đây sẽ chặn yêu cầu LOAD và điền sẵn MediaInformation của LoadRequestData. Trong trường hợp này, người dùng thích nội dung đang tải.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      const userActionLike = new cast.framework.messages.UserActionState(
          cast.framework.messages.UserAction.LIKE);
      loadRequestData.media.userActionStates = [userActionLike];

      return loadRequestData;
    });

Đoạn mã sau đây sẽ chặn thông báo USER_ACTION và xử lý việc gọi phần phụ trợ bằng thay đổi đã yêu cầu. Sau đó, lớp này sẽ thực hiện lệnh gọi để cập nhật UserActionState trên trình thu.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
  (userActionRequestData) => {
    // Obtain the media information of the current content to associate the action to.
    let mediaInfo = playerManager.getMediaInformation();

    // If there is no media info return an error and ignore the request.
    if (!mediaInfo) {
        console.error('Not playing media, user action is not supported');
        return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
    }

    // Reach out to backend services to store user action modifications. See sample below.
    return sendUserAction(userActionRequestData, mediaInfo)

    // Upon response from the backend, update the client's UserActionState.
    .then(backendResponse => updateUserActionStates(backendResponse))

    // If any errors occurred in the backend return them to the cast receiver.
    .catch((error) => {
      console.error(error);
      return error;
    });
});

Đoạn mã sau đây mô phỏng lệnh gọi đến một dịch vụ phụ trợ. Hàm này kiểm tra UserActionRequestData để xem loại thay đổi mà người dùng yêu cầu và chỉ thực hiện lệnh gọi mạng nếu phần phụ trợ hỗ trợ hành động đó.

function sendUserAction(userActionRequestData, mediaInfo) {
  return new Promise((resolve, reject) => {
    switch (userActionRequestData.userAction) {
      // Handle user action changes supported by the backend.
      case cast.framework.messages.UserAction.LIKE:
      case cast.framework.messages.UserAction.DISLIKE:
      case cast.framework.messages.UserAction.FOLLOW:
      case cast.framework.messages.UserAction.UNFOLLOW:
      case cast.framework.messages.UserAction.FLAG:
      case cast.framework.messages.UserAction.SKIP_AD:
        let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
        setTimeout(() => {resolve(backendResponse)}, 1000);
        break;
      // Reject all other user action changes.
      default:
        reject(
          new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
    }
  });
}

Đoạn mã sau đây lấy UserActionRequestData và thêm hoặc xoá UserActionState khỏi MediaInformation. Việc cập nhật UserActionState của MediaInformation sẽ thay đổi trạng thái của nút liên kết với hành động được yêu cầu. Thay đổi này được thể hiện trong giao diện người dùng điều khiển màn hình thông minh, ứng dụng điều khiển từ xa và giao diện người dùng Android TV. Thông báo này cũng được truyền qua các thông báo MediaStatus đi để cập nhật giao diện người dùng của trình điều khiển mở rộng cho trình gửi iOS và Android.

function updateUserActionStates(backendResponse) {
  // Unwrap the backend response.
  let mediaInfo = backendResponse.mediaInfo;
  let userActionRequestData = backendResponse.userActionRequestData;

  // If the current item playing has changed, don't update the UserActionState for the current item.
  if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
    return;
  }

  // Check for existing userActionStates in the MediaInformation.
  // If none, initialize a new array to populate states with.
  let userActionStates = mediaInfo.userActionStates || [];

  // Locate the index of the UserActionState that will be updated in the userActionStates array.
  let index = userActionStates.findIndex((currUserActionState) => {
    return currUserActionState.userAction == userActionRequestData.userAction;
  });

  if (userActionRequestData.clear) {
    // Remove the user action state from the array if cleared.
    if (index >= 0) {
      userActionStates.splice(index, 1);
    }
    else {
      console.warn("Could not find UserActionState to remove in MediaInformation");
    }
  } else {
    // Add the UserActionState to the array if enabled.
    userActionStates.push(
      new cast.framework.messages.UserActionState(userActionRequestData.userAction));
  }

  // Update the UserActionState array and set the new MediaInformation
  mediaInfo.userActionStates = userActionStates;
  playerManager.setMediaInformation(mediaInfo, true);
  return;
}

Lệnh thoại

Các lệnh đa phương tiện sau đây hiện được hỗ trợ trong SDK Bộ thu web cho các thiết bị có Trợ lý. Bạn có thể tìm thấy cách triển khai mặc định của các lệnh này trong cast.framework.PlayerManager.

Các lệnh đa phương tiện được hỗ trợ bằng giọng nói

Để ngăn lệnh thoại kích hoạt lệnh đa phương tiện trên thiết bị có Trợ lý, trước tiên, bạn phải thiết lập các lệnh đa phương tiện được hỗ trợ mà bạn dự định hỗ trợ. Sau đó, bạn phải thực thi các lệnh đó bằng cách bật thuộc tính CastReceiverOptions.enforceSupportedCommands. Giao diện người dùng trên trình gửi Cast SDK và thiết bị hỗ trợ cảm ứng sẽ thay đổi để phản ánh các cấu hình này. Nếu bạn không bật cờ này, các lệnh thoại đến sẽ được thực thi.

Ví dụ: nếu cho phép PAUSE từ các ứng dụng của trình gửi và thiết bị hỗ trợ cảm ứng, bạn cũng phải định cấu hình trình nhận để phản ánh các chế độ cài đặt đó. Khi được định cấu hình, mọi lệnh thoại đến sẽ bị loại bỏ nếu không nằm trong danh sách các lệnh được hỗ trợ.

Trong ví dụ bên dưới, chúng ta đang cung cấp CastReceiverOptions khi bắt đầu CastReceiverContext. Chúng tôi đã thêm tính năng hỗ trợ cho lệnh PAUSE và buộc trình phát chỉ hỗ trợ lệnh đó. Bây giờ, nếu một lệnh thoại yêu cầu một thao tác khác như SEEK, thì thao tác đó sẽ bị từ chối. Người dùng sẽ được thông báo rằng lệnh này chưa được hỗ trợ.

const context = cast.framework.CastReceiverContext.getInstance();

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

Bạn có thể áp dụng logic riêng cho từng lệnh mà bạn muốn hạn chế. Xoá cờ enforceSupportedCommands và đối với mỗi lệnh mà bạn muốn hạn chế, bạn có thể chặn thông báo đến. Tại đây, chúng ta sẽ chặn yêu cầu do SDK cung cấp để các lệnh SEEK được đưa ra cho các thiết bị có Trợ lý không kích hoạt tính năng tìm kiếm trong ứng dụng Web Receiver.

Đối với các lệnh đa phương tiện mà ứng dụng của bạn không hỗ trợ, hãy trả về lý do lỗi thích hợp, chẳng hạn như NOT_SUPPORTED.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
  seekData => {
    // Block seeking if the SEEK supported media command is disabled
    if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
      let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
      .INVALID_REQUEST);
      e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
      return e;
    }

    return seekData;
  });

Hoạt động ở chế độ nền từ hoạt động bằng giọng nói

Nếu nền tảng Cast phát âm thanh của ứng dụng do hoạt động của Trợ lý, chẳng hạn như nghe lời nói của người dùng hoặc phản hồi, thì thông báo FocusState của NOT_IN_FOCUS sẽ được gửi đến ứng dụng Web Receiver khi hoạt động bắt đầu. Một thông báo khác có IN_FOCUS sẽ được gửi khi hoạt động kết thúc. Tuỳ thuộc vào ứng dụng và nội dung đa phương tiện đang phát, bạn có thể muốn tạm dừng nội dung đa phương tiện khi FocusState là NOT_IN_FOCUS bằng cách chặn loại thông báo FOCUS_STATE.

Ví dụ: người dùng sẽ có trải nghiệm tốt nếu bạn tạm dừng phát sách nói nếu Trợ lý đang phản hồi truy vấn của người dùng.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
  focusStateRequestData => {
    // Pause content when the app is out of focus. Resume when focus is restored.
    if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
      playerManager.pause();
    } else {
      playerManager.play();
    }

    return focusStateRequestData;
  });

Ngôn ngữ phụ đề do giọng nói chỉ định

Khi người dùng không nêu rõ ngôn ngữ cho phụ đề, ngôn ngữ dùng cho phụ đề sẽ giống với ngôn ngữ mà người dùng nói ra lệnh. Trong những trường hợp này, thông số isSuggestedLanguage của thông báo đến cho biết liệu người dùng có đề xuất hoặc yêu cầu rõ ràng ngôn ngữ được liên kết hay không.

Ví dụ: isSuggestedLanguage được đặt thành true cho lệnh "OK Google, bật phụ đề" vì ngôn ngữ được suy luận theo ngôn ngữ của lệnh được nói. Nếu ngôn ngữ được yêu cầu rõ ràng, chẳng hạn như trong câu lệnh "Ok Google, bật phụ đề tiếng Anh", thì isSuggestedLanguage sẽ được đặt thành false.

Siêu dữ liệu và tính năng truyền giọng nói

Mặc dù theo mặc định, Web Receiver sẽ xử lý các lệnh thoại, nhưng bạn nên đảm bảo siêu dữ liệu cho nội dung của mình là đầy đủ và chính xác. Điều này đảm bảo rằng Trợ lý xử lý đúng cách các lệnh thoại và siêu dữ liệu hiển thị đúng cách trên các loại giao diện mới như ứng dụng Google Home và màn hình thông minh như Google Home Hub.

Chuyển đổi luồng

Việc duy trì trạng thái phiên là cơ sở của quá trình chuyển luồng, 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 cách sử dụ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ẽ ngừ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). Mọi thiết bị Cast có phần mềm cơ sở mới nhất đều có thể đóng vai trò là nguồn hoặc đích đến trong quá trình truyền trực tuyến.

Quy trình sự kiện để chuyển luồng là:

1. Trên thiết bị nguồn:
   1. Nội dung nghe nhìn dừng phát.
   2. Ứng dụng Web Receiver nhận được lệnh để lưu trạng thái nội dung đa phương tiện hiện tại.
   3. Ứng dụng Web Receiver bị tắt.
2. Trên thiết bị đích:
   1. Ứng dụng Web Receiver (Trình thu web) được tải.
   2. Ứng dụng Web Receiver nhận được lệnh khôi phục trạng thái nội dung nghe nhìn đã lưu.
   3. Nội dung nghe nhìn tiếp tục phát.

Các phần tử của trạng thái nội dung nghe nhìn bao gồm:

• Vị trí hoặc dấu thời gian cụ thể của bài hát, video hoặc mục nội dung nghe nhìn.
• Vị trí của nội dung đó trong một hàng đợi rộng hơn (chẳng hạn như danh sách phát hoặc đài phát của nghệ sĩ).
• Người dùng đã được xác thực.
• Trạng thái phát (ví dụ: đang phát hoặc tạm dừng).

Bật tính năng chuyển đổi luồng

Cách triển khai tính năng chuyển luồng cho Trình nhận web:

1. Cập nhật supportedMediaCommands bằng lệnh STREAM_TRANSFER:

   playerManager.addSupportedMediaCommands(
   cast.framework.messages.Command.STREAM_TRANSFER, true);

2. Bạn có thể ghi đè trình chặn thông báo SESSION_STATE và RESUME_SESSION như mô tả trong phần Duy trì trạng thái phiên. Chỉ ghi đè các giá trị này nếu cần lưu trữ dữ liệu tuỳ chỉnh trong ảnh chụp nhanh phiên. Nếu không, phương thức triển khai mặc định để lưu giữ trạng thái phiên sẽ hỗ trợ chuyển luồng.

Duy trì trạng thái phiên

SDK Trình thu phát trên web cung cấp phương thức triển khai mặc định cho các ứng dụng Trình thu phát trên web để bảo toàn trạng thái phiên bằng cách chụp nhanh trạng thái nội dung đa phương tiện hiện tại, chuyển đổi trạng thái thành yêu cầu tải và tiếp tục phiên bằng yêu cầu tải.

Bạn có thể ghi đè yêu cầu tải do Trình thu web tạo ra trong trình chặn thông báo SESSION_STATE nếu cần. Nếu muốn thêm dữ liệu tuỳ chỉnh vào yêu cầu tải, bạn nên đặt dữ liệu đó vào loadRequestData.customData.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.SESSION_STATE,
    function (sessionState) {
        // Override sessionState.loadRequestData if needed.
        const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
        sessionState.loadRequestData.credentials = newCredentials;

        // Add custom data if needed.
        sessionState.loadRequestData.customData = {
            'membership': 'PREMIUM'
        };

        return sessionState;
    });

Bạn có thể truy xuất dữ liệu tuỳ chỉnh từ loadRequestData.customData trong trình chặn thông báo RESUME_SESSION.

let cred_ = null;
let membership_ = null;

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.RESUME_SESSION,
    function (resumeSessionRequest) {
        let sessionState = resumeSessionRequest.sessionState;

        // Modify sessionState.loadRequestData if needed.
        cred_ = sessionState.loadRequestData.credentials;

        // Retrieve custom data.
        membership_ = sessionState.loadRequestData.customData.membership;

        return resumeSessionRequest;
    });

Tải trước nội dung

Trình thu phát trên web hỗ trợ tải trước các mục nội dung nghe nhìn sau mục phát hiện tại trong hàng đợi.

Thao tác tải trước sẽ tải trước một số phân đoạn của các mục sắp tới. Thông số kỹ thuật được thực hiện trên giá trị preloadTime trong đối tượng QueueItem (mặc định là 20 giây nếu không được cung cấp). Thời gian được biểu thị bằng giây, tương ứng với thời điểm kết thúc của mục đang phát . Chỉ giá trị dương mới hợp lệ. Ví dụ: nếu giá trị là 10 giây, thì mục này sẽ được tải trước 10 giây trước khi mục trước kết thúc. Nếu thời gian tải trước cao hơn thời gian còn lại trên currentItem, thì quá trình tải trước sẽ diễn ra sớm nhất có thể. Vì vậy, nếu chỉ định một giá trị tải trước rất lớn trên queueItem, thì bạn có thể đạt được hiệu quả là bất cứ khi nào chúng ta phát mục hiện tại, chúng ta đã tải trước mục tiếp theo. Tuy nhiên, chúng tôi để nhà phát triển tự thiết lập và lựa chọn giá trị này vì giá trị này có thể ảnh hưởng đến băng thông và hiệu suất phát trực tuyến của mục đang phát.

Theo mặc định, tính năng tải trước sẽ hoạt động cho nội dung phát trực tuyến HLS, DASH và Smooth.

Các tệp video và âm thanh MP4 thông thường như MP3 sẽ không được tải trước vì các thiết bị Cast chỉ hỗ trợ một phần tử nội dung đa phương tiện và không thể dùng để tải trước khi một mục nội dung hiện có vẫn đang phát.

Thông báo tuỳ chỉnh

Trao đổi thông báo là phương thức tương tác chính cho các ứng dụng Web Receiver.

Trình gửi phát đi thông báo đến Trình nhận web bằng cách sử dụng API trình gửi cho nền tảng mà trình gửi đang chạy (Android, iOS, Web). Đối tượng sự kiện (là biểu hiện của một thông báo) được truyền đến trình nghe sự kiện có một phần tử dữ liệu (event.data) trong đó dữ liệu sẽ nhận các thuộc tính của loại sự kiện cụ thể.

Ứng dụng Web Receiver có thể chọn nghe thông báo trên một không gian tên được chỉ định. Nhờ đó, ứng dụng Web Receiver được cho là hỗ trợ giao thức không gian tên đó. Sau đó, mọi trình gửi đã kết nối muốn giao tiếp trên không gian tên đó đều có thể sử dụng giao thức thích hợp.

Tất cả không gian tên được xác định bằng một chuỗi và phải bắt đầu bằng "urn:x-cast:", theo sau là bất kỳ chuỗi nào. Ví dụ: "urn:x-cast:com.example.cast.mynamespace".

Dưới đây là đoạn mã cho Trình thu web để nghe thông báo tuỳ chỉnh từ các trình gửi đã kết nối:

const context = cast.framework.CastReceiverContext.getInstance();

const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
  // handle customEvent.
});

context.start();

Tương tự, các ứng dụng Trình nhận web có thể thông báo cho người gửi về trạng thái của Trình nhận web bằng cách gửi thông báo đến những người gửi đã kết nối. Ứng dụng Trình thu web có thể gửi thông báo bằng cách sử dụng sendCustomMessage(namespace, senderId, message) trên CastReceiverContext. Trình thu Web có thể gửi thông báo đến một người gửi riêng lẻ, để phản hồi một thông báo đã nhận được hoặc do trạng thái ứng dụng thay đổi. Ngoài tính năng nhắn tin điểm-đến-điểm (với giới hạn 64kb), Trình nhận web cũng có thể truyền tin nhắn đến tất cả người gửi đã kết nối.

Truyền cho thiết bị âm thanh

Hãy xem Hướng dẫn về Google Cast cho thiết bị âm thanh để được hỗ trợ về việc chỉ phát âm thanh.

Android TV

Phần này thảo luận về cách Google Web Receiver sử dụng dữ liệu đầu vào của bạn dưới dạng nội dung phát và khả năng tương thích với Android TV.

Tích hợp ứng dụng với điều khiển từ xa

Trình thu phát web của Google chạy trên thiết bị Android TV sẽ dịch dữ liệu đầu vào từ các đầu vào điều khiển của thiết bị (tức là điều khiển từ xa cầm tay) dưới dạng thông báo phát nội dung nghe nhìn được xác định cho không gian tên urn:x-cast:com.google.cast.media, như mô tả trong phần Thông báo phát nội dung nghe nhìn. Ứng dụng của bạn phải hỗ trợ các thông báo này để điều khiển chế độ phát nội dung nghe nhìn của ứng dụng nhằm cho phép điều khiển chế độ phát cơ bản từ các đầu vào điều khiển của Android TV.

Nguyên tắc về khả năng tương thích với Android TV

Dưới đây là một số đề xuất và sai lầm phổ biến cần tránh để đảm bảo ứng dụng của bạn tương thích với Android TV:

• Xin lưu ý rằng chuỗi tác nhân người dùng chứa cả "Android" và "CrKey"; một số trang web có thể chuyển hướng đến trang web chỉ dành cho thiết bị di động vì chúng phát hiện nhãn "Android". Đừng giả định rằng "Android" trong chuỗi tác nhân người dùng luôn cho biết người dùng thiết bị di động.
• Ngăn xếp nội dung nghe nhìn của Android có thể sử dụng GZIP minh bạch để tìm nạp dữ liệu. Đảm bảo dữ liệu phương tiện của bạn có thể phản hồi Accept-Encoding: gzip.
• Các sự kiện nội dung nghe nhìn HTML5 trên Android TV có thể được kích hoạt theo thời gian khác với Chromecast, điều này có thể làm lộ các vấn đề bị ẩn trên Chromecast.
• Khi cập nhật nội dung nghe nhìn, hãy sử dụng các sự kiện liên quan đến nội dung nghe nhìn do các phần tử <audio>/<video> kích hoạt, chẳng hạn như timeupdate, pause và waiting. Tránh sử dụng các sự kiện liên quan đến mạng như progress, suspend và stalled, vì các sự kiện này thường phụ thuộc vào nền tảng. Hãy xem phần Sự kiện đa phương tiện để biết thêm thông tin về cách xử lý sự kiện đa phương tiện trong trình thu nhận.
• Khi định cấu hình chứng chỉ HTTPS của trang web nhận, hãy nhớ thêm cả các chứng chỉ CA trung gian. Hãy xem trang kiểm tra SSL của Qualsys để xác minh: nếu đường dẫn chứng nhận đáng tin cậy cho trang web của bạn bao gồm một chứng chỉ CA có nhãn "tải xuống bổ sung", thì trang web đó có thể không tải được trên các nền tảng dựa trên Android.
• Mặc dù Chromecast hiển thị trang trình thu trên mặt phẳng đồ hoạ 720p, nhưng các nền tảng Cast khác (bao gồm cả Android TV) có thể hiển thị trang lên đến 1080p. Đảm bảo trang receiver của bạn điều chỉnh tỷ lệ linh hoạt ở nhiều độ phân giải.