Trang này chứa các đoạn mã và nội dung mô tả về các tính năng dành cho ứng dụng Trình thu nhận web tuỳ chỉnh.
- 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 sẵn được cung cấp kèm theo Trình thu web. - Định kiểu tuỳ chỉnh giống CSS cho phần tử
cast-media-player
để tạo kiểu cho các thành phần trên giao diện người dùng khác nhau nhưbackground-image
,splash-image
vàfont-family
. - Phần tử tập lệnh để tải khung Web receiver.
- Mã JavaScript để chặn thông báo và xử lý sự kiện.
- Danh sách chờ tự động phát.
- Các tuỳ chọn định cấu hình tính năng phát.
- Các tuỳ chọn để đặt ngữ cảnh của Trình nhận web.
- Các tuỳ chọn để đặt lệnh được ứng dụng Trình thu nhận web hỗ trợ.
- Lệnh gọi JavaScript để khởi động ứng dụng Web receiver.
Cấu hình và các lựa chọn về ứ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 nhìn thấy, đồng thời quản lý việc tải các thư viện cơ sở cũng như xử lý hoạt động khởi chạy SDK Trình nhận web. 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 mỗi lần khởi chạy ứng dụng và được chuyển tới SDK khi đặt tham số không bắt buộc trong lệnh gọi đến start
.
Ví dụ bên dưới cho biết cách ghi đè hành vi mặc định để phát hiện xem một kết nối người gửi có đang vẫn đang kết nối hay không. Khi Trình nhận web 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. Thao tác này có thể hữu ích khi gỡ lỗi các sự cố vì nó ngăn ứng dụng Trình thu thập dữ liệu web đóng phiên Trình gỡ lỗi từ xa 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, SDK trình nhận web cung cấp một cách để định cấu hình các biến
phát lại, 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 trình phát. Trình phát được tạo mỗi khi có một lượt tải mới được truyền đến SDK Web receiver. Các nội dung sửa đổi đối với PlaybackConfig
sau khi tạo trình phát 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ạyCastReceiverContext
.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ượt 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 đa phương tiện đang được tải ở đầu 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 ở đây không vĩnh viễn và không được đưa vào truy vấn đối vớigetPlaybackConfig()
. Khi mục nội dung đa phương tiện tiếp theo được tải, trình xử lý này sẽ được gọi lại.
Ví dụ bên dưới 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 để nhận 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 của CORS phải được thực hiện bằng các 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 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 1 phân đoạn được tải xong.
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 về việc phát nội dung đa phương tiện. Trình xử lý này gọi một phương thức do ứng dụng triển khai 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 trình thu web trên web cho phép ứng dụng Trình thu nhận web của bạn xử lý các sự kiện của trình phát. Trình nghe sự kiện lấy thông số cast.framework.events.EventType
(hoặc một mảng gồm 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 rất 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 thông báo, 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
});
Tính năng chặn tin nhắn
SDK Web receiver cho phép ứng dụng Web receiver của bạn 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 tin nhắn sẽ lấy tham số cast.framework.messages.MessageType
chỉ định loại thông báo cần được giao cắt.
Trình chặn sẽ trả về yêu cầu đã sửa đổi hoặc một Promise sẽ giải quyết cùng 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ý tin nhắn mặc định. Xem phần Tải nội dung nghe nhìn để biết thêm 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 xảy ra lỗi trong trình chặn tin nhắn, ứ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;
});
});
Tính năng 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 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.
- Tốt nhất là bạn nên sử dụng trình nghe sự kiện để 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 tin nhắn và tự sửa đổi dữ liệu của 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 cả 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 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 nên 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à một URL nội dung có thể phát (tương tự như URL của thuộc tínhcontentUrl
) hoặc là 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 bạn dùng thuộc tính này làm giá trị nhận dạng, thì ứng dụng của bạn sẽ điền sẵn một URL có thể phát vàocontentUrl
.
Bạn nên dùng entity
để lưu trữ các tham số chính hoặc mã nhận dạng thực và dùng contentUrl
cho URL của nội dung nghe nhìn. Ví dụ về vấn đề này được thể hiện trong đoạn mã sau đây, trong đó entity
xuất hiện 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 đi 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ư các thiết bị âm thanh và màn hình đã 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 tính 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 sẽ 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 Web receiver của bạn thông qua ứng dụng gửi (Web, Android và iOS), lệnh thoại trên 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. Cast SDK cung cấp nhiều API khác nhau để cho phép ứng dụng Web receiver 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 bất kỳ dịch vụ phụ trợ nào.
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 thúc đẩy bởi MediaStatus.supportedMediaCommands
cho bộ điều khiển mở rộng dành cho người gửi iOS và Android, ứng dụng điều khiển từ xa và bộ thu trên thiết bị cảm ứng cũng như ứng dụng bộ thu 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 thao tác đó sẽ được bật. Nếu bạn không đặt giá trị thì nút này sẽ bị tắt. Có thể thay đổi các giá trị này trên Trình nhận trên web bằng cách:
- Sử dụng
PlayerManager.setSupportedMediaCommands
để đặtCommands
cụ thể - Thêm lệnh mới bằng
addSupportedMediaCommands
- Xoá một lệnh hiện có bằ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 này sẽ đưa các thay đổi vào thuộc tính supportedMediaCommands
. Khi trạng thái được thông báo, 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 tương ứng.
Để biết thêm thông tin về các lệnh đa phương tiện được hỗ trợ và thiết bị cảm ứng, 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 người dùng tương tác với giao diện người dùng hoặc gửi lệnh thoại, họ có thể điều khiển chế độ phát nội dung và các thuộc tính liên quan đến mục đang phát. Các yêu cầu điều khiển chế độ phát sẽ do SDK tự động xử lý. Các yêu cầu sửa đổi thuộc tính của mục đang phát, chẳng hạn như lệnh LIKE
, đòi hỏi ứng dụng của receiver phải xử lý các thuộc tính đó. 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ữ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 đa phương tiện. - Chặn
USER_ACTION
thông báo 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 MediaInformation
của LoadRequestData
. Trong trường hợp này, người dùng sẽ 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ợ với thay đổi được yêu cầu. Sau đó, hàm này sẽ thực hiện một lệnh 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 lệnh gọi đến một dịch vụ phụ trợ. Hàm này sẽ 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 sẽ lấy UserActionRequestData
, rồi 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 thao tác được yêu cầu. Thay đổi này được phản ánh 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 của Android TV. Thông báo này cũng được truyền qua các thông báo MediaStatus
gửi đ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
Các lệnh đa phương tiện sau đây hiện được hỗ trợ trong SDK trình nhận web dành 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
.
Lệnh | Nội dung mô tả |
---|---|
Chơi | 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 về 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. |
Ngừng | Dừng nội dung nghe nhìn đang phát. |
Không lặp lại | Tắt tính năng lặp lại mục nội dung nghe nhìn trong hàng đợi sau khi phát xong mục cuối cùng trong hàng đợi. |
Lặp lại đĩa đơn | Lặp lại nội dung nghe nhìn đang phát vô thời hạn. |
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 mục cuối cùng trong hàng đợi. |
Lặp lại tất cả và phát ngẫu nhiên | Khi mục cuối cùng trong hàng đợi phát xong, 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 | Trộn nội dung nghe nhìn trong hàng đợi nội dung nghe nhìn. |
BẬT / TẮT phụ đề | Bật / Tắt phụ đề cho nội dung nghe nhìn. Tính năng Bật / Tắt cũng được cung cấp theo ngôn ngữ. |
Tìm kiếm đến thời gian tuyệt đối | Chuyển đến thời gian tuyệt đối được chỉ định. |
Tìm kiếm đến thời gian liên quan 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 | Khởi động lại nội dung nghe nhìn đang phát hoặc phát mục nội dung nghe nhìn 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 đa phương tiện. Trạng thái này sẽ được xử lý theo mặc định. Bạn có thể sử dụng trình chặn tin nhắn SET_PLAYBACK_RATE để ghi đè các yêu cầu giá đến. |
Các lệnh 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 phát nội dung đ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 đị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 người gửi SDK Cast và thiết bị có hỗ trợ 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ẽ thực thi.
Ví dụ: nếu cho phép PAUSE
từ các ứng dụng dành cho người gửi và thiết bị có 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 các lệnh được hỗ trợ.
Trong ví dụ bên dưới, chúng tôi đang cung cấp CastReceiverOptions
khi khởi động 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, chẳng hạn như SEEK
, thì thao tác đó sẽ bị từ chối. Người dùng sẽ nhận đượ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 biệt cho mỗi lệnh mà bạn muốn hạn chế. Xoá cờ enforceSupportedCommands
và chặn thư đến đối với mỗi lệnh mà bạn muốn hạn chế. Ở đây, chúng tôi chặn yêu cầu do SDK cung cấp để các lệnh SEEK
gửi tới các thiết bị có Trợ lý không kích hoạt lệnh tìm kiếm trong ứng dụng Trình thu thập dữ liệu web của bạn.
Đố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;
});
Chạy ở chế độ nền từ hoạt động bằng giọng nói
Nếu nền tảng Truyền 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 nói lại, thì thông báo FocusState
của NOT_IN_FOCUS
sẽ được gửi đến ứng dụng Trình thu trên web khi hoạt động bắt đầu. Hệ thống sẽ gửi một tin nhắn 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 thông báo loại 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 truy vấn của người dùng sẽ mang lại một 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 chỉ định rõ ngôn ngữ cho phụ đề, ngôn ngữ dùng cho phụ đề sẽ chính là ngôn ngữ dùng để đọc lệnh.
Trong các trường hợp này, tham số isSuggestedLanguage
của tin nhắn đến cho biết liệu ngôn ngữ liên kết có được người dùng đề xuất hay yêu cầu rõ ràng hay không.
Ví dụ: isSuggestedLanguage
được đặt thành true
cho lệnh "Ok Google, bật phụ đề", vì ngôn ngữ này được suy ra theo ngôn ngữ của lệnh. Nếu ngôn ngữ được yêu cầu rõ ràng, chẳng hạn như trong "Ok Google, bật phụ đề tiếng Anh", thì isSuggestedLanguage
sẽ được đặt thành false
.
Truyền siêu dữ liệu và giọng nói
Mặc dù theo mặc định, Trình thu nhận web sẽ xử lý lệnh thoại, nhưng bạn phải đảm bảo siêu dữ liệu cho nội dung của mình đầy đủ và chính xác. Điều này đảm bảo rằng các lệnh thoại được Trợ lý xử lý đúng cách và siêu dữ liệu sẽ xuất hiện đú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à các màn hình thông minh như Google Home Hub.
Chuyển 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ó 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 dừng phát trên một thiết bị (nguồn) và tiếp tục trên một thiết bị khác (đích đến). Mọi thiết bị Truyền 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 luồng.
Quy trình chuyển sự kiện cho quá trình chuyển luồng như sau:
- Trên thiết bị nguồn:
- Nội dung nghe nhìn ngừng phát.
- Ứng dụng Web receiver nhận lệnh để lưu trạng thái của nội dung nghe nhìn hiện tại.
- Ứng dụng Trình nhận web đã tắt.
- Trên thiết bị đích:
- Ứng dụng Trình nhận web đã được tải.
- Ứng dụng Web receiver nhận lệnh để khôi phục trạng thái của nội dung nghe nhìn đã lưu.
- Nội dung nghe nhìn sẽ tiếp tục phát.
Các yếu tố của trạng thái nội dung đa phương tiệ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 đa phương tiện.
- Vị trí của video 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 đã 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 truyền luồng
Cách triển khai quá trình chuyển luồng cho Bộ thu web:
- Cập nhật
supportedMediaCommands
bằng lệnhSTREAM_TRANSFER
:playerManager.addSupportedMediaCommands( cast.framework.messages.Command.STREAM_TRANSFER, true);
- Ghi đè (không bắt buộc) trình chặn thông báo
SESSION_STATE
vàRESUME_SESSION
như mô tả trong phần Bảo tồn trạng thái phiên. Chỉ ghi đè các chế độ cài đặt 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 bản tổng quan nhanh về 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ợ chuyển luồng.
Bảo tồn trạng thái phiên
Web receiver SDK cung cấp 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 nội dung nghe nhìn hiện tại, chuyển đổi trạng thái thành một yêu cầu tải và tiếp tục phiên với yêu cầu tải đó.
Yêu cầu tải do Trình nhận web tạo ra có thể bị ghi đè 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ợ tải trước các mục nội dung đa phương tiệ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. Việc đặc tả 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 là hợp lệ. Ví dụ: nếu giá trị là 10 giây, mục này sẽ được tải trước 10 giây trước khi mục trước đó hoàn tất. Nếu thời gian tải trước lâu hơn thời gian còn lại của mục hiện tại, thì việc 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ênqueueItem, thì bạn có thể đạt được hiệu quả bất cứ khi nào chúng ta đang 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 cài đặt và lựa chọn phương án 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 phát trực tuyến HLS, DASH và mượt mà.
Các tệp video và âm thanh 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 thành phần 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 nhận web.
Người gửi gửi tin nhắn cho một Người nhận trên 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 thị của một thông báo) được chuyển đến trình nghe sự kiện có một phần tử dữ liệu (event.data
), trong đó dữ liệu lấy 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 đã chỉ định. Do đó, ứng dụng Web receiver được cho là hỗ trợ giao thức không gian tên đó. Sau đó, tuỳ thuộc vào việc bất kỳ người gửi đã kết nối nào muốn giao tiếp trên không gian tên đó để sử dụng giao thức phù 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 thập dữ liệu web để nghe thư tuỳ chỉnh từ những người gửi được 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 thu web có thể thông báo cho người gửi về trạng thái của Bộ thu trên web bằng cách gửi thông báo đến người gửi được 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
.
Trình nhận trên web có thể gửi thông báo đến từng người gửi, để phản hồi thông báo đã nhận hoặc do sự thay đổi trạng thái của ứng dụng. Ngoài việc nhắn tin hai điểm (có giới hạn 64 kb), Bộ thu trên web cũng có thể phát thông báo tới tất cả người gửi được kết nối.
Truyền cho thiết bị âm thanh
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 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 lượt phát và khả năng tương thích với Android TV.
Tích hợp ứng dụng của bạn với điều khiển từ xa
Trình thu nhận web của Google chạy trên thiết bị Android TV sẽ chuyển dữ liệu đầu vào từ đầu vào điều khiển của thiết bị (ví dụ: điều khiển từ xa cầm tay) thành các 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 để điều khiển chế độ phát nội dung nghe nhìn của ứng dụng nhằm cho phép cơ bản điều khiển chế độ phát từ dữ liệu đầ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 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 giả định rằng "Android" trong chuỗi tác nhân người dùng luôn chỉ 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 tệp GZIP rõ ràng để tìm nạp dữ liệu. Hãy đảm bảo dữ liệu nghe nhì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 các 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 kết nối 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. 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 của bạn. - Khi định cấu hình chứng chỉ HTTPS của trang web của người nhận, hãy nhớ thêm các chứng chỉ CA trung gian. Hãy xem trang kiểm thử 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 chứng chỉ CA có nhãn “tải xuống bổ sung”, thì chứng chỉ đó có thể không tải 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 Android TV có thể hiển thị trang ở độ phân giải tối đa 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.