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ó trong ứng dụng Custom Web Receiver.

1. Một phần tử cast-media-player đại diện cho giao diện người dùng trình phát tích hợp đi kèm với Web Receiver.
2. Kiểu tuỳ chỉnh tương tự như CSS cho phần tử cast-media-player để tạo kiểu cho nhiều phần tử giao diện người dùng, chẳng hạn như background-image, splash-image và font-family.
3. Một phần tử tập lệnh để tải khung Web Receiver.
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 lựa chọn để định cấu hình chế độ phát.
7. Các lựa chọn để đặt ngữ cảnh Web Receiver.
8. Các lựa chọn để đặt lệnh mà ứng dụng Web Receiver hỗ trợ.
9. Một lệnh gọi JavaScript để khởi động ứng dụng Web Receiver.

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

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

CastReceiverContext là lớp ngoài cùng được cung cấp cho nhà phát triển, đồng thời quản lý việc tải các thư viện cơ bản và xử lý quá trình khởi chạy Web Receiver SDK. 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 bạn đặ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 đang hoạt động hay không. Khi Web Receiver không thể giao tiếp với người gửi trong maxInactivity giây, 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 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.

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, Web Receiver SDK 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 cast.framework.PlaybackConfig. Thông tin này được xử lý bởi PlayerManager và được đánh giá tại thời điểm người chơi được tạo. Trình phát được tạo mỗi khi một tải mới được truyền đến Web Receiver SDK. Các điểm 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 lựa 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 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 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. 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 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 tạo CastReceiverContext. Cấu hình này sẽ ghi đè các yêu cầu đi để lấy tệp kê khai. Trình xử lý chỉ định rằng các yêu cầu Access-Control của CORS phải được thực hiện bằng thông tin đăng nhập, chẳng hạn 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 cách sử dụng phương thức truy xuất và phương thức thiết lập đượ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 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 xử lý sự kiện

Web Receiver SDK cho phép ứng dụng Web Receiver xử lý các sự kiện của trình phát. Trình nghe sự kiện sẽ lấy 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 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 một thay đổi mediaStatus đang được phát, bạn có thể 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

Web Receiver SDK cho phép ứng dụng Web Receiver chặn các thông báo và thực thi mã tuỳ chỉnh trên những thông báo đó. Trình chặn thông báo 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 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 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.

Ví dụ: nếu muốn thay đổi dữ liệu yêu cầu tải, bạn có thể 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 xảy ra lỗi trong trình chặn thông báo, ứng dụng Web Receiver 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;
        });
    });

Chặn thông báo so với trình xử lý 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.
• Bạn nên dùng trình nghe sự kiện để kích hoạt số liệu phân tích hoặc một hàm tuỳ chỉnh.

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

• Tính năng chặn thông báo cho phép bạn theo dõi một thông báo, chặn thông báo đó và sửa đổi chính dữ liệu yêu cầu.
• Bạn nên 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 người 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à một 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ẽ 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 duy nhấ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, ứng dụng của bạn phải điền một URL có thể phát trong contentUrl.

Bạn nên dùng entity để lưu trữ mã nhận dạng hoặc các tham số khoá thực, đồng thời dùng contentUrl cho URL của nội dung nghe nhìn. Ví dụ về trường hợp này được minh hoạ 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 âm thanh được đính kèm vào 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 một trong các enum được chỉ định để lấy khả 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 người gửi (Web, Android và iOS), lệnh thoại trên các thiết bị có Trợ lý, chế độ đ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ý những hoạt động tương tác này, cập nhật giao diện người dùng ứng dụng thông qua các 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 được hỗ trợ cho nội dung nghe nhìn

Các trạng thái của chế độ điều khiển giao diện người dùng được điều khiển bởi MediaStatus.supportedMediaCommands cho bộ điều khiển mở rộng của người gửi iOS và Android, ứng dụng nhận và điều khiển từ xa chạy trên thiết bị cảm ứng, cũng như ứng dụng nhận trên thiết bị Android TV. Khi một Command theo từng 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út sẽ bị vô hiệu hoá. Bạn có thể thay đổi các giá trị này trên Web Receiver 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 chuẩn bị MediaStatus đã cập nhật, bên nhận sẽ đưa các thay đổi vào thuộc tính supportedMediaCommands. Khi trạng thái được truyền đi, các ứng dụng 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 của chúng cho phù hợp.

Để 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 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 sửa đổi thuộc tính cho mục đang phát hiện tại (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ợ những 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 các 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 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ý việc gọi phần phụ trợ bằng nội dung thay đổi được yêu cầu. Sau đó, nó sẽ gọi để cập nhật UserActionState trên receiver.

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 một lệnh gọi đến 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ụ 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 được liên kết với thao tác đượ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 chế độ đ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 bộ điều khiển mở rộng cho người gửi trên 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

Web Receiver SDK hiện hỗ trợ các lệnh về nội dung nghe nhìn sau đây cho các 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.

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 về nội dung nghe nhìn trên thiết bị có Trợ lý, trước tiên, bạn phải đặt các lệnh về 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 các thiết bị gửi Cast SDK và thiết bị có màn hình cảm ứng sẽ thay đổi để phản ánh những cấu hình này. Nếu cờ này không được bật, 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 bộ nhận để phản ánh những 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 các lệnh được hỗ trợ.

Trong ví dụ bên dưới, 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ì yêu cầu đó 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. Ở đây, chúng ta chặn yêu cầu do SDK cung cấp để các lệnh SEEK được gửi đến các thiết bị có Trợ lý không kích hoạt thao tác tìm kiếm trong ứng dụng Web Receiver.

Đối với các lệnh về nội dung nghe nhì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 bằng giọng nói

Nếu nền tảng Cast chuyển âm thanh của ứng dụng sang 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 chuyện trở lại), thì thông báo FocusState thuộc loại 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 nghe nhìn đang phát, bạn có thể muố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ụ: việc tạm dừng phát sách nói nếu Trợ lý đang phản hồi một câu hỏi của người dùng sẽ mang lại trải nghiệm tốt cho 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ụ đề được chỉ định bằng giọng nói

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ữ mà người dùng đã nói lệnh. Trong những trường hợp này, tham số isSuggestedLanguage của thông báo đến cho biết liệu ngôn ngữ được liên kết có phải do người dùng đề xuất hay 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 "OK Google, bật phụ đề tiếng Anh", thì isSuggestedLanguage sẽ được đặt thành false.

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

Mặc dù Trình nhận web xử lý các lệnh thoại theo mặc định, nhưng bạn nên đảm bảo siêu dữ liệu cho nội dung của bạn đầ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 xuất hiện đú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 (chẳng hạn như Google Home Hub).

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 luồng phát, trong đó người dùng có thể di chuyển các luồng âm thanh và video hiện có giữa 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 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ị truyền có phần mềm 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 dữ liệu 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 nghe nhì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 đượ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 bài hát trong một hàng đợi lớn hơn (chẳng hạn như danh sách phát hoặc đài phát nhạc 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 tạm dừng).

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

Cách triển khai tính năng chuyển luồng cho Web Receiver:

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 (không bắt buộc) như mô tả trong phần Duy trì trạng thái phiên. Chỉ ghi đè những dữ liệu 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, việc triển khai mặc định để duy trì trạng thái phiên sẽ hỗ trợ chuyển luồng.

Lưu giữ trạng thái phiên

Web Receiver SDK cung cấp một phương thức triển khai mặc định cho các ứng dụng Web Receiver để duy trì trạng thái phiên bằng cách chụp nhanh trạng thái hiện tại của nội dung nghe nhìn, chuyển đổi trạng thái đó thành một 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 Web Receiver 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 đặ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

Web Receiver hỗ trợ việc 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. Quy cách đượ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 gian 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 ngay khi có thể. Vì vậy, nếu chỉ định một giá trị rất lớn cho việc tải trước trên queueItem, thì người dùng có thể đạt được hiệu ứng 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 sẽ để nhà phát triển tự chọn và thiết lập chế độ 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 đối với nội dung HLS, DASH và Smooth Streaming.

Các tệp video và âm thanh MP4 thông thường (chẳng hạn như MP3) sẽ không được tải trước vì các thiết bị truyền nội dung 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 Web Receiver.

Người gửi phát thông báo đến Web Receiver 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 có 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 các thông báo trên một không gian tên cụ thể. Nhờ đó, ứng dụng Web Receiver được cho là hỗ trợ giao thức không gian tên đó. Sau đó, mọi người gửi được kết nối muốn giao tiếp trên không gian tên đó sẽ 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à bất kỳ chuỗi nào. Ví dụ: "urn:x-cast:com.example.cast.mynamespace".

Dưới đây là một đoạn mã để Web Receiver nhận thông báo tuỳ chỉnh từ những 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ự, các ứng dụng Web Receiver có thể thông báo cho người gửi về trạng thái của Web Receiver bằng cách gửi thông báo cho 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. Web Receiver có thể gửi thông báo cho từng người gửi, có thể 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 việc nhắn tin điểm-điểm (giới hạn 64 kb), Web Receiver cũng có thể truyền tin nhắn đến tất cả người gửi được kết nối.

Truyền đến các 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ề chế độ phát chỉ có â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 làm 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

Google Web Receiver chạy trên thiết bị Android TV sẽ dịch dữ liệu đầu vào từ các chế độ điều khiển đầu vào 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ợ những thông báo này để kiểm soát việc phát nội dung nghe nhìn của ứng dụng nhằm cho phép kiểm soát việc phát cơ bản từ các chế độ đầ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

Sau đây là một số đề xuất và sai lầm 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 một 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 đa phương tiện của Android có thể sử dụng GZIP trong suốt để tìm nạp dữ liệu. Đảm bảo dữ liệu đa phương tiện của bạn có thể phản hồi Accept-Encoding: gzip.
• Các sự kiện đa phương tiện HTML5 trên Android TV có thể được kích hoạt ở thời điểm khác với Chromecast. Điều này có thể cho thấy những 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ì những 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ý các sự kiện đa phương tiện trong receiver.
• 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 thử SSL Qualsys để xác minh: nếu đường dẫn chứng nhận đáng tin cậy cho trang web của bạn có một chứng chỉ CA được gắn nhãn "extra download" (tải xuống bổ sung), 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 nhận 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 này ở độ phân giải lên đến 1080p. Đảm bảo trang nhận của bạn điều chỉnh tỷ lệ một cách linh hoạt ở nhiều độ phân giải.