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ả về các tính năng có sẵn cho ứng dụng Trình nhận web tuỳ chỉnh.

Lưu ý: Bạn nên thử làm như sau:

• Hướng dẫn trong lớp học lập trình về Trình thu nhận web của Cast – Tìm hiểu từng bước về cách tạo một ứng dụng Trình thu nhận web hỗ trợ Cast bằng SDK Google Cast có thể nhận video truyền.
• Ứng dụng mẫu CastReceiver (GitHub) – Chạy, điều hướng và xem ứng dụng mẫu tham khảo này tuân thủ Nguyên tắc về trải nghiệm người dùng và Danh sách kiểm tra thiết kế.

1. Phần tử 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 cùng với Trình thu web.
2. Kiểu tuỳ chỉnh giống CSS cho phần tử cast-media-player để tạo kiểu cho nhiều phần tử trên giao diện người dùng, chẳng hạn như background-image, splash-image và font-family.
3. 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. Hàng đợi để tự động phát.
6. Các lựa chọn để định cấu hình chế độ phát.
7. Các lựa chọn để đặt bối cảnh của Trình thu nhận web.
8. Các lựa chọn để đặt lệnh mà ứng dụng Trình thu nhận web hỗ trợ.
9. Lệnh gọi JavaScript để khởi động ứng dụng Trình nhận web.

Lưu ý: Bạn rất nên sử dụng phần tử HTML cast-media-player vì phần tử này xử lý tất cả trạng thái giao diện người dùng của trình phát cùng với kiểu của trình phát.

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

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

CastReceiverContext là lớp ngoài cùng mà nhà phát triển có thể thấy, đồng thời 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 Web Receiver. SDK này 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 cho mỗi lần 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 thấy cách ghi đè hành vi mặc định để phát hiện xem kết nối của người gửi có còn hoạt động hay không. Khi Trình thu nhận web không thể giao tiếp với người gửi trong maxInactivity giây, thì một sự kiện SENDER_DISCONNECTED sẽ được gửi đ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 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ó người gửi nào được kết nối ở trạng thái IDLE.

Lưu ý: Ứng dụng Trình nhận web production nên tránh đặt maxInactivity và thay vào đó, hãy dựa vào giá trị mặc định.

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 Trình nhận web cung cấp một cách để định cấu hình các biến phát, chẳng hạn như thông tin DRM, cấu hình thử lại và trình xử lý yêu cầu bằ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. Trình phát được tạo mỗi khi một lượt tải mới được chuyển đến SDK Trình nhận web. 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 chạy 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ả lần tải tiếp theo hoặc cho đến khi bị 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 trình phát. Những 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 các truy vấn đến getPlaybackConfig(). Khi mục nội dung nghe nhìn tiếp theo được tải, trình xử lý này sẽ được gọi lại.

Ví dụ dưới đây cho thấy cách đặt PlaybackConfig khi khởi chạy 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ụ dưới đây cho thấy cách ghi đè PlaybackConfig bằ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 xong 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ụ dưới đây cho thấy cách ghi đè PlaybackConfig cho một yêu cầu tải cụ thể bằ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 getLicenseUrlForMedia do ứng dụng triển khai để 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 Trình nhận web cho phép ứng dụng Trình nhận web xử lý các sự kiện của trình phát. Trình nghe sự kiện nhận một tham số cast.framework.events.EventType (hoặc một mảng các tham 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 được định cấu hình trước của cast.framework.events.EventType (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 được truyền phát, 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
});

Lưu ý: Khung Trình nhận web tự động theo dõi thời điểm người gửi kết nối hoặc ngắt kết nối khỏi khung đó và không yêu cầu trình nghe sự kiện SENDER_DISCONNECTED rõ ràng trong logic Trình nhận web của riêng bạn.

Chặn tin nhắn

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

Trình chặn phải trả về yêu cầu đã sửa đổi hoặc một Lời hứa phân giải bằng 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 đó:

Thận trọng: Đừng thêm hoặc sửa đổi thuộc tính queueData của LoadRequestData trong trình chặn LOAD. Việc này sẽ không ảnh hưởng đến quá trình phát vì queueData đã được đọc và áp dụng cho hàng đợi. Để biết thêm thông tin, hãy xem hướng dẫn về hàng đợi.

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 xảy ra lỗi 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ề cast.framework.messages.ErrorType và cast.framework.messages.ErrorReason phù 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;
        });
    });

Chặn tin nhắn 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 chặn tin nhắn 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 phù hợp nhất để kích hoạt số liệu phân tích hoặc một hàm tuỳ chỉnh.

Lưu ý: Bạn cũng có thể dùng trình nghe sự kiện để nghe một nhóm sự kiện bằng cách sử dụng enum CORE, DEBUG hoặc FINE.

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 tin nhắn, chặn tin nhắn và sửa đổi chính dữ liệu yêu cầu.
• Tốt nhất là bạn nên sử dụng tính năng chặn tin nhắn để 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 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 vào í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 một 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 riêng biệt cho nội dung hoặc danh sách phát đang được tải. Nếu sử dụng thuộc tính này làm giá trị nhận dạng, thì ứng dụng của bạn phải điền một URL có thể phát vào contentUrl.

Bạn nên sử dụng entity để lưu trữ mã nhận dạng thực hoặc tham số khoá, đồng thời 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, 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 thiết bị trên thiết bị truyền đã kết nối và thiết bị video hoặc thiết bị âm thanh được gắn vào thiết bị đó. Phương thức getDeviceCapabilities cung cấp thông tin hỗ trợ cho Trợ lý Google, Bluetooth, màn hình và thiết bị âm thanh được 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 phím IS_HDR_SUPPORTED và IS_DV_SUPPORTED tương ứng 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 Trình nhận web thông qua các ứng dụng của người gửi (Web, Android và iOS), lệnh thoại trên các thiết bị có Trợ lý, đ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 thiết bị Android TV. SDK Truyền cung cấp nhiều API để cho phép ứng dụng Trình nhận web xử lý các hoạt động 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 điều khiển nội dung nghe nhìn được hỗ trợ

Trạng thái của các thành phần điều khiển trên giao diện người dùng được điều khiển bằng MediaStatus.supportedMediaCommands cho bộ đ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 bitwise cụ thể được bật trong thuộc tính, các nút liên quan đến hành động đó sẽ được bật. Nếu bạn không đặt giá trị, thì nút này sẽ bị tắt. Bạn có thể thay đổi các giá trị này trên Trình thu nhận 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á 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 người nhận chuẩn bị MediaStatus đã cập nhật, này sẽ bao gồm các thay đổi trong thuộc tính supportedMediaCommands. Khi trạng thái được truyền phát, các ứng dụng của người 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.

Lưu ý: Việc thay đổi supportedMediaCommands sẽ không làm thay đổi loại nút hiển thị. Các giá trị này được đặt trực tiếp trong ứng dụng của người gửi (iOS, Android) và API Controls của người nhận. Trường hợp ngoại lệ duy nhất sử dụng supportedMediaCommands để thúc đẩy những thay đổi này là thẻ phát nội dung nghe nhìn trên màn hình chính của thiết bị màn hình thông minh.

Để 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 Accessing UI controls.

Quản lý trạng thái hành động 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ể điều khiển quá trình 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 điều khiển chế độ phát. Các yêu cầu sửa đổi thuộc tính cho mục hiện đ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 thực hiện những việc 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.

Lưu ý: Nếu cần, bạn có thể POST hành động này cho bất kỳ phần phụ trợ nào có liên quan để duy trì lựa chọn ưu tiên của người dùng.

Đoạn mã sau đây 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 được 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 chặn thông báo USER_ACTION và xử lý lệnh gọi phần phụ trợ bằng thay đổi được yêu cầu. Sau đó, ứng dụng sẽ thực hiện lệnh gọi để cập nhật UserActionState trên thiết bị 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 hành động đó được phần phụ trợ hỗ trợ.

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 của các nút điều khiển trê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 của Android TV. Trạng thái này cũng được truyền phát thông qua các thông báo MediaStatus gửi đi để cập nhật giao diện người dùng của trình điều khiển mở rộng cho người 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 Web Receiver cho thiết bị có Trợ lý. Bạn có thể tìm thấy các phương thức triển khai mặc định của những lệnh này trong cast.framework.PlayerManager.

Ra lệnh	Mô tả
Play	Phát hoặc tiếp tục phát từ trạng thái tạm dừng.
Tạm dừng	Tạm dừng nội dung đang phát.
Trước	Chuyển đến mục nội dung nghe nhìn trước đó trong hàng đợi nội dung nghe nhìn.
Tiếp theo	Chuyển đến mục nội dung nghe nhìn tiếp theo trong hàng đợi nội dung nghe nhìn.
Dừng	Dừng nội dung nghe nhìn đang phát.
Không lặp lại	Tắt chế độ lặp lại các mục nội dung nghe nhìn trong hàng đợi sau khi mục cuối cùng trong hàng đợi phát xong.
Lặp lại một lần	Lặp lại vô thời hạn nội dung nghe nhìn đang phát.
Lặp lại tất cả	Lặp lại tất cả các mục trong hàng đợi sau khi phát xong mục cuối cùng trong hàng đợi.
Lặp lại tất cả và phát ngẫu nhiên	Sau khi phát xong mục cuối cùng trong hàng đợi, hãy phát ngẫu nhiên hàng đợi và lặp lại tất cả các mục trong hàng đợi.
Phát ngẫu nhiên	Xáo trộn các mục nội dung nghe nhìn trong hàng đợi nội dung nghe nhìn. Lưu ý: Bạn cũng có thể xáo trộn nội dung nghe nhìn trước khi phát bằng cờ shuffle, nếu cờ này được đặt trong loadRequestData của thông báo LOAD.
BẬT/TẮT phụ đề	Bật/Tắt phụ đề cho nội dung nghe nhìn. Bạn cũng có thể bật/tắt theo ngôn ngữ.
Tua đến thời gian tuyệt đối	Chuyển đến thời gian tuyệt đối được chỉ định.
Tua đến thời gian tương đối so với thời gian hiện tại	Tua đi hoặc tua lại theo khoảng thời gian đã chỉ định so với thời gian phát hiện tại.
Chơi lại	Phát lại nội dung nghe nhìn đang phát hoặc phát mục nội dung nghe nhìn được phát gần đây nhất nếu hiện không có nội dung nào đang phát.
Đặt tốc độ phát	Thay đổi tốc độ phát nội dung nghe nhìn. Việc này sẽ được xử lý theo mặc định. Bạn có thể sử dụng trình chặn thông báo SET_PLAYBACK_RATE để ghi đè các yêu cầu về giá phòng sắp tới.

Các lệnh thoại được hỗ trợ cho nội dung nghe nhìn

Để ngăn lệnh thoại kích hoạt lệnh nội dung nghe nhìn trên thiết bị có Trợ lý, trước tiên, bạn phải đặt lệnh nội dung nghe nhì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 thiết bị 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 gửi và thiết bị hỗ trợ cảm ứng, bạn cũng phải định cấu hình thiết bị 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 có trong danh sách lệnh được hỗ trợ.

Trong ví dụ dưới đây, chúng ta sẽ 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 đó. Giờ đây, nếu một lệnh thoại yêu cầu một thao tác khác, chẳng hạn như SEEK, thì lệnh đó 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 tin nhắn đến. Tại đây, chúng tôi chặn yêu cầu do SDK cung cấp để các lệnh SEEK được phát hành cho thiết bị có Trợ lý không kích hoạt thao tác tua trong ứng dụng Trình nhận web.

Đố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ề một 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;
  });

Chuyển sang chế độ nền từ hoạt động thoại

Nếu nền tảng Truyền phát đặt âm thanh của ứng dụng ở chế độ nền 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 nói lại), thì một thông báo FocusState của NOT_IN_FOCUS sẽ được gửi đến ứng dụng Trình thu nhận web khi hoạt động bắt đầu. Hệ thống sẽ gửi một thông báo khác có IN_FOCUS khi hoạt động kết thúc. Tuỳ thuộc vào ứng dụng và nội dung nghe nhìn đang phát, bạn nên tạm dừng nội dung nghe nhìn khi FocusState là NOT_IN_FOCUS bằng cách chặn loại thông báo FOCUS_STATE.

Ví dụ: bạn nên tạm dừng phát sách nói nếu Trợ lý đang phản hồi một 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ữ được dùng cho phụ đề sẽ là ngôn ngữ được dùng để nói lệnh. Trong những trường hợp này, tham số isSuggestedLanguage của tin nhắn đến cho biết ngôn ngữ liên quan được đề xuất hay do người dùng yêu cầu một cách rõ rà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ữ mà 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, hãy bật phụ đề tiếng Anh", thì isSuggestedLanguage sẽ được đặt thành false.

Siêu dữ liệu và lồng tiếng

Mặc dù lệnh thoại được Web Receiver xử lý theo mặc định, 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, chẳng hạn như ứng dụng Google Home và màn hình thông minh như Google Home Hub.

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

Lưu ý: Theo mặc định, Trình nhận web âm thanh hỗ trợ tính năng mở rộng luồng, trong đó các thiết bị hỗ trợ Cast khác được thêm vào phiên. Trình nhận web video cần thực hiện các bước trong phần này để hỗ trợ tính năng 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.

Luồng sự kiện để chuyển đổi phiên phát trực tuyến là:

1. Trên thiết bị nguồn:
   1. Nội dung nghe nhìn dừng phát.
   2. Ứng dụng Trình thu nhận web nhận được lệnh lưu trạng thái nội dung nghe nhìn hiện tại.
   3. Ứng dụng Trình thu nhận web bị tắt.
2. Trên thiết bị đích:
   1. Ứng dụng Trình thu nhận 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 thành phần 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 bài hát trong một danh sách chờ lớn 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 đã xác thực.
• Trạng thái phát (ví dụ: đang phát hoặc đang tạm dừng).

Bật tính năng chuyển đổi phiên phát trực tuyến

Cách triển khai tính năng chuyển đổi phiên phát trực tuyến cho Bộ thu 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 đè các 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 dưới dạng một phần của ảnh chụp nhanh phiên. Nếu không, phương thức triển khai mặc định để duy trì trạng thái phiên sẽ hỗ trợ tính năng chuyển đổi phiên phát trực tuyến.

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

SDK Trình nhận web cung cấp một phương thức triển khai mặc định cho các ứng dụng Trình nhận web để duy trì trạng thái phiên bằng cách chụp nhanh trạng thái nội dung nghe nhì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 Bộ thu web tạo 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 đưa 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 nhậ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ỉ các 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 một giá trị tải trước rất lớn được chỉ định trên queueItem, thì người dùng có thể đạt được hiệu quả 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 truyền 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 âm thanh và video MP4 thông thường như MP3 sẽ không được tải trước vì thiết bị Truyền chỉ hỗ trợ một phần tử nội dung nghe nhìn và không thể dùng để tải trước trong 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 Trình thu nhận web.

Người gửi phát hành thông báo đến Bộ thu web bằng cách sử dụng API người gửi cho nền tảng mà người 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 nhận các thuộc tính của loại sự kiện cụ thể.

Ứng dụng Trình thu nhận web 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 Trình nhận web được cho là hỗ trợ giao thức không gian tên đó. Sau đó, bất kỳ người gửi nào đã kết nối muốn giao tiếp trên không gian tên đó đều phải sử dụng giao thức thích hợp.

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

Lưu ý: Không gian tên thông báo đa phương tiện "urn:x-cast:com.google.cast.media" được đặt trước. Theo quy ước, thông báo nội dung nghe nhìn được gửi bằng API Truyền trên cả người gửi và Bộ thu web đều sử dụng giao thức không gian tên nội dung nghe nhìn. Hãy xem phần Nội dung nghe nhìn và trình phát để biết thêm thông tin về thông báo nội dung nghe nhìn.

Dưới đây là đoạn mã để Trình nhận web nghe thông báo tuỳ chỉnh từ người 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ự, ứ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 người gửi đã kết nối. Ứng dụng Web Receiver có thể gửi thông báo bằng sendCustomMessage(namespace, senderId, message) trên CastReceiverContext. Bộ 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 hoặc do thay đổi trạng thái ứng dụng. Ngoài tính năng nhắn tin điểm-điểm (với giới hạn 64 kb), Trình thu web cũng có thể phát thông báo phát đi tới tất cả người gửi đã kết nối.

Cast cho thiết bị âm thanh

Xem hướng dẫn về Google Cast cho thiết bị âm thanh để được hỗ trợ về tính năng chỉ phát âm thanh.

Android TV

Phần này thảo luận về cách Trình thu nhận web của Google sử dụng dữ liệu đầu vào của bạn làm chế độ 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 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 dữ liệu đầ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 việc phát nội dung nghe nhìn của ứng dụng, nhằm cho phép điều khiển 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à lỗi thường gặp 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ì các trang web đó phát hiện nhãn "Android". Đừng cho 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 nội dung nghe nhìn của bạn có thể phản hồi Accept-Encoding: gzip.
• Sự kiện nội dung nghe nhìn HTML5 trên Android TV có thể được kích hoạt vào những thời điểm khác với Chromecast, điều này có thể cho thấy 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 có xu hướ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.
• Khi định cấu hình chứng chỉ HTTPS của trang web nhận, hãy nhớ thêm chứng chỉ CA trung gian. Hãy xem trang kiểm tra Qualsys SSL để xác minh: nếu đường dẫn chứng chỉ đáng tin cậy cho trang web của bạn có chứng chỉ CA được gắn nhãn "tải xuống thêm", thì chứng chỉ đó 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 của bộ thu trên mặt phẳng đồ hoạ 720p, nhưng các nền tảng Truyền khác (bao gồm cả Android TV) có thể hiển thị trang lên đến 1080p. Đảm bảo trang của trình thu của bạn điều chỉnh tỷ lệ một cách linh hoạt ở các độ phân giải khác nhau.