Tổng quan
SDK của Bộ thu web hỗ trợ việc xếp hàng đợi bằng
hàng đợi mặc định do
SDK cung cấp bằng cách sử dụng
QueueData
và
QueueManager
hoặc sử dụng hàng đợi tuỳ chỉnh bằng cách
triển khai
cast.framework.QueueBase
và sử dụng
QueueManager
để cập nhật.
API xếp hàng cho phép các ứng dụng tích hợp tốt hơn với Cast bằng cách cung cấp các tính năng sau:
- Hỗ trợ việc triển khai hàng đợi đám mây của Google và đối tác để hàng đợi được lưu trữ và tạo bên ngoài có thể được tải trực tiếp vào thiết bị Truyền.
- Cơ chế cho phép phân trang các mục trong hàng đợi thay vì tải mọi nội dung cùng một lúc.
- Hỗ trợ cho việc nhắn tin mới, chẳng hạn như chuyển đến mục tiếp theo, mục trước đó, tìm nạp cửa sổ các mục, cũng như nhận thông tin phương tiện liên quan đến một tập hợp các mục trong hàng đợi.
QueueManager
để quản lý việc chèn, xoá và cập nhật các mục trong hàng đợi.
Hàng đợi mặc định
SDK Bộ thu web cung cấp dịch vụ hỗ trợ hàng đợi có giới hạn, ngay ở hàng đợi mặc định.
Để sử dụng hàng đợi mặc định, hãy cung cấp queueData
trong LoadRequestData
tải phía người gửi của bạn hoặc gửi yêu cầu tải cục bộ bằng PlayerManager#load
.
Ngoài ra, hãy xem phần Đang tải nội dung nghe nhìn.
Ở phía bộ thu, bạn có thể sửa đổi hàng đợi này bằng cách sử dụng
QueueManager
sau khi nội dung nghe nhìn ban đầu được tải.
Hàng đợi tùy chỉnh
Nếu hàng đợi mặc định không cung cấp chức năng xếp hàng đợi cần thiết cho ứng dụng, bạn có thể tạo hàng đợi tuỳ chỉnh, cho phép nhiều khả năng và tính linh hoạt hơn.
Các nhà phát triển ứng dụng có thể tạo hàng đợi bên của Bộ thu dữ liệu web bằng cách triển khai
cast.framework.QueueBase
.
Dưới đây là ví dụ cơ bản về hàng đợi đơn giản, trong đó lệnh gọi initialize
sẽ bị ghi đè, sau đó cung cấp danh sách các mục trong hàng đợi cùng với nội dung mô tả trong hàng đợi cho Thiết bị truyền.
Ngoài ra, hãy xem phần Đang tải nội dung nghe nhìn.
// Creates a simple queue with a combination of contents.
const DemoQueue = class extends cast.framework.QueueBase {
constructor() {
super();
/**
* List of media urls.
* @private @const {!Array<string>}
*/
this.myMediaUrls_ = [...];
}
/**
* Provide a list of items.
* @param {!cast.framework.messages.LoadRequestData} loadRequestData
* @return {!cast.framework.messages.QueueData}
*/
initialize(loadRequestData) {
const items = [];
for (const mediaUrl of this.myMediaUrls_) {
const item = new cast.framework.messages.QueueItem();
item.media = new cast.framework.messages.MediaInformation();
item.media.contentId = mediaUrl;
items.push(item);
}
let queueData = loadRequestData.queueData;
// Create a new queue with media from the load request if one doesn't exist.
if (!queueData) {
queueData = new cast.framework.messages.QueueData();
queueData.name = 'Your Queue Name';
queueData.description = 'Your Queue Description';
queueData.items = items;
// Start with the first item in the playlist.
queueData.startIndex = 0;
// Start from 10 seconds into the first item.
queueData.currentTime = 10;
}
return queueData;
}
};
Trong ví dụ này, danh sách các mục trong lệnh gọi initialize
được cung cấp trong lệnh gọi hàm tạo QueueBase
của nhà cung cấp. Tuy nhiên, để triển khai hàng đợi trên đám mây, logic Trình nhận web tuỳ chỉnh có thể tìm nạp các mục bên ngoài rồi trả về các phần đó trong lệnh gọi khởi chạy.
Để minh hoạ cách sử dụng API hàng đợi đầy đủ hơn, sau đây là một hàng đợi minh hoạ triển khai hầu hết lớp QueueBase
.
const DemoQueue = class extends cast.framework.QueueBase {
constructor() {
/** @private {} */
super();
YourServer.onSomeEvent = this.updateEntireQueue_;
}
/**
* Initializes the queue.
* @param {!cast.framework.messages.LoadRequestData} loadRequestData
* @return {!cast.framework.messages.QueueData}
*/
initialize(loadRequestData) {
let queueData = loadRequestData.queueData;
// Create a new queue with media from the load request if one doesn't exist.
if (!queueData) {
queueData = new cast.framework.messages.QueueData();
queueData.name = 'Your Queue Name';
queueData.description = 'Your Queue Description';
// Put the first set of items into the queue
const items = this.nextItems();
queueData.items = items;
// Start with the first item in the playlist.
queueData.startIndex = 0;
// Start from 10 seconds into the first item.
queueData.currentTime = 10;
}
return queueData;
}
/**
* Picks a set of items from remote server after the reference item id and
* return as the next items to be inserted into the queue. When
* referenceItemId is omitted, items are simply appended to the end of the
* queue.
* @param {number} referenceItemId
* @return {!Array<cast.framework.QueueItem>}
*/
nextItems(referenceItemId) {
// Assume your media has a itemId and the media url
return this.constructQueueList_(YourServer.getNextMedias(referenceItemId));
}
/**
* Picks a set of items from remote server before the reference item id and
* return as the items to be inserted into the queue. When
* referenceItemId is omitted, items are simply appended to beginning of the
* queue.
* @param {number} referenceItemId
* @return {!Array<cast.framework.QueueItem>}
*/
prevItems(referenceItemId) {
return this.constructQueueList_(YourServer.getPrevMedias(referenceItemId));
}
/**
* Constructs a list of QueueItems based on the media information containing
* the item id and the media url.
* @param {number} referenceItemId
* @return {!Array<cast.framework.QueueItem>}
*/
constructQueueList_(medias) {
const items = [];
for (media of medias) {
const item = new cast.framework.messages.QueueItem(media.itemId);
item.media = new cast.framework.messages.MediaInformation();
item.media.contentId = media.url;
items.push(item);
}
return items;
}
/**
* Logs the currently playing item.
* @param {number} itemId The unique id for the item.
* @export
*/
onCurrentItemIdChanged(itemId) {
console.log('We are now playing video ' + itemId);
YourServer.trackUsage(itemId);
}
};
Trong ví dụ trên, YourServer
là máy chủ hàng đợi trên đám mây của bạn và có logic về cách tìm nạp một số mục nội dung đa phương tiện.
Để sử dụng hàng đợi được triển khai QueueBase
, người dùng sẽ đặt tuỳ chọn hàng đợi trong CastReceiverContext
:
const context = cast.framework.CastReceiverContext.getInstance();
context.start({queue: new DemoQueue()});
Quản lý danh sách chờ
QueueManager
cho phép nhà phát triển linh hoạt trong việc phát triển các giải pháp xếp hàng đợi bằng cách cung cấp phương thức để truy cập vào danh sách các mục trong hàng đợi hiện được lưu trữ cũng như mục phát hiện tại. Tính năng này cũng cung cấp các thao tác như chèn, xoá và cập nhật các mục trong hàng đợi. Đoạn mã sau đây cho biết cách truy cập vào một
bản sao của
QueueManager
:
const context = cast.framework.CastReceiverContext.getInstance();
const queueManager = context.getPlayerManager().getQueueManager();
Quản lý hàng đợi mặc định
Sau khi hàng đợi ban đầu được tải, bạn có thể dùng QueueManager
để thực hiện các thao tác như truy xuất mục hiện tại, truy xuất tất cả mục trong hàng đợi và cập nhật các mục trong hàng đợi bằng insertItems
, removeItems
và updateItems
.
Quản lý hàng đợi tùy chỉnh
Dưới đây là ví dụ về cách triển khai hàng đợi tuỳ chỉnh sử dụng các phương thức chèn và xoá dựa trên một số sự kiện. Ví dụ này cũng minh họa cách sử dụng
updateItems
trong đó nhà phát triển có thể sửa đổi các mục trong hàng đợi trong hàng đợi hiện tại, chẳng hạn như
xóa điểm chèn quảng cáo.
const DemoQueue = class extends cast.framework.QueueBase {
constructor() {
super();
/** @private @const {!cast.framework.QueueManager} */
this.queueManager_ = context.getPlayerManager().getQueueManager();
}
/**
* Provide a list of items.
* @param {!cast.framework.messages.LoadRequestData} loadRequestData
* @return {!cast.framework.messages.QueueData}
*/
initialize(loadRequestData) {
// Your normal initialization; see examples above.
return queueData;
}
/** Inserts items to the queue. */
onSomeEventTriggeringInsertionToQueue() {
const twoMoreUrls = ['http://url1', 'http://url2'];
const items = [];
for (const mediaUrl of twoMoreUrls) {
const item = new cast.framework.QueueItem();
item.media = new cast.framework.messages.MediaInformation();
item.media.contentId = mediaUrl;
items.push(item);
}
// Insert two more items after the current playing item.
const allItems = this.queueManager_.getItems();
const currentItemIndex = this.queueManager_.getCurrentItemIndex();
const nextItemIndex = currentItemIndex + 1;
let insertBefore = undefined;
if (currentItemIndex >= 0 &&
currentItemIndex < allItems.length - 1) {
insertBefore = allItems[nextItemIndex].itemId;
}
this.queueManager_.insertItems(items, insertBefore);
}
/** Removes a particular item from the queue. */
onSomeEventTriggeringRemovalFromQueue() {
this.queueManager_.removeItems([2]);
}
/** Removes all the ads from all the items across the entire queue. */
onUserBoughtAdFreeVersion() {
const items = this.queueManager_.getItems();
this.queueManager_.updateItems(items.map(item => {
item.media.breaks = undefined;
return item;
}));
}
};
Tin nhắn đến và đi
Để hỗ trợ đầy đủ tính năng tìm nạp hàng đợi phía người nhận dưới dạng nguồn đáng tin cậy, các thông báo xếp hàng bổ sung sau đây sẽ được SDK trình nhận CAF giới thiệu và xử lý:
Tin nhắn đến | Thông số | Thông báo phản hồi về cuộc gọi đi | Quay lại |
TIẾP THEO | Không cần tham số. | MEDIA_STATUS | Trình nhận sẽ (tìm nạp thông qua nextItems() nếu cần) và bắt đầu phát mục tiếp theo. |
TRƯỚC TRƯỚC | Không cần tham số. | MEDIA_STATUS | Web receiver sẽ (tìm nạp thông qua prevItems() nếu cần) và bắt đầu phát mục trước đó. |
bashi_ITEMS | FetchItemsRequestData | QUEUE_CHANGE | Một Cast.framework.notifications.QueueChange. Ví dụ: đối với trường hợp chèn, trường mục trong JSON sẽ chứa danh sách các mục mới được tìm nạp. |
GET_ITEMS_INFO | GetItemsInfoRequestData chứa itemIds: Array<number> | ITEMS_INFO (Mục) | Cast.framework.notifications.ItemsInfo với thông tin mục trong hàng đợi. |
GET_QUEUE_IDS | Không cần tham số. | displayName_IDS | Cast.framework.notifications.QueueIds. |
Đối với NEXT
/PREVIOUS
, nếu giá trị biểu thị trong hàng đợi hiện có trên Web receiver
không có thêm mục nào, QueueBase.nextItems()
hoặc
QueueBase.prevItems()
sẽ tự động được gọi để nhận thêm các mục.
Đối với FETCH_ITEM
, hàm tương ứng
fetchItems
trong quá trình triển khai QueueBase
được gọi cho hàng đợi đám mây. Hàm này sẽ truy xuất dữ liệu
có liên quan cần trả về cho Bộ thu web để lưu trữ.
Bất cứ khi nào có nhiều mục hơn được tìm nạp, loại thông báo mới QUEUE_CHANGE
sẽ được kích hoạt và gửi lại cho người gửi. Xem các loại thay đổi hàng đợi khác nhau.
Đối với GET_ITEMS_INFO
,
cách triển khai của QueueBase
không được kích hoạt và Bộ thu web trả về thông tin nội dung phương tiện
đã biết cho danh sách mã nhận dạng.
Đang sắp xếp hàng đợi
Để sắp xếp các mục trong hàng đợi của bạn, hãy đặt cờ shuffle
của QueueData
thành true
khi tải các mục của bạn vào hàng đợi.
Nếu bạn đang sử dụng phương thức triển khai QueueBase
, hãy sử dụng phương thức shuffle
để trả về danh sách các mục đã xáo trộn.
Để xáo trộn một hàng đợi hiện có, hãy sử dụng cờ
shuffle
của QUEUE_UPDATE
MessageType
,
thay vì lệnh QUEUE_SHUFFLE
. Vui lòng xem
QueueUpdateRequestData
để biết thêm thông tin.
Chế độ lặp lại
Để lặp lại các mục trong hàng đợi, hãy đặt thuộc tính repeatMode
của QueueData
thành RepeatMode
mong muốn khi tải các mục của bạn vào hàng đợi.
Để thay đổi RepeatMode
của hàng đợi hiện có, hãy sử dụng thuộc tính
repeatMode
của
QueueUpdateRequestData
,
sử dụng QUEUE_UPDATE
MessageType
.