개요
웹 수신기 SDK는 QueueData
및 QueueManager
를 사용하여 SDK에서 제공하는 기본 큐를 대기열에 추가하거나 업데이트를 위해 cast.framework.QueueBase
를 구현하고 QueueManager
를 사용하여 커스텀 큐를 사용합니다.
Queueing API를 사용하면 애플리케이션에서 다음 기능을 제공하여 Cast와 더 잘 통합할 수 있습니다.
- 외부에서 저장되고 생성된 큐를 Cast 기기에 직접 로드할 수 있도록 Google 및 파트너의 클라우드 큐 구현을 지원합니다.
- 모든 것을 한 번에 로드하는 대신 큐에 항목을 페이지로 나누는 메커니즘
- 다음 항목, 이전 항목으로 이동, 항목 창 가져오기, 일련의 큐 항목과 관련된 미디어 정보 가져오기와 같은 새 메시지를 지원합니다.
- 큐 항목의 삽입, 삭제, 업데이트를 관리하는
QueueManager
기본 대기열
웹 수신기 SDK는 기본 큐 형식의 즉시 큐 지원을 제공합니다.
기본 대기열을 사용하려면 발신자 측 로드의 LoadRequestData
에 queueData
를 제공하거나 PlayerManager#load
를 사용하여 로컬 로드 요청을 보냅니다.
미디어 로드도 참고하세요.
수신자 측에서 초기 미디어가 로드된 후 QueueManager
를 사용하여 큐를 수정할 수 있습니다.
맞춤 대기열
기본 큐가 앱에 필요한 큐 기능을 제공하지 않는 경우, 커스텀 큐를 만드는 기능을 사용하여 더 많은 기능과 유연성을 확보할 수 있습니다.
애플리케이션 개발자는 cast.framework.QueueBase
를 구현하여 웹 수신기를 추가합니다.
다음은 initialize
호출이 재정의되고 큐 설명과 함께 큐 항목 목록이 Cast 기기에 제공되는 간단한 큐의 기본적인 예입니다.
미디어 로드도 참고하세요.
// 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;
}
};
이 예에서는 initialize
호출의 항목 목록이 제공자의 QueueBase
생성자 호출에 제공됩니다. 하지만 클라우드 큐 구현의 경우 맞춤 웹 수신자 로직은 항목을 외부에서 가져온 다음 초기화 호출의 일부로 반환할 수 있습니다.
다음은 대기열 API를 더 포괄적으로 사용하는 방법을 보여주기 위해 대부분의 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);
}
};
위의 예시에서 YourServer
는 클라우드 큐 서버이며 특정 미디어 항목을 가져오는 방법에 관한 로직이 있습니다.
QueueBase
구현 큐를 사용하려면 CastReceiverContext
에서 큐 옵션을 설정합니다.
const context = cast.framework.CastReceiverContext.getInstance();
context.start({queue: new DemoQueue()});
큐 관리
QueueManager
는 현재 저장된 대기열 항목과 현재 재생 항목에 액세스하는 메서드를 제공하여 개발자가 대기열 솔루션을 개발할 수 있는 유연성을 제공합니다. 큐 항목의 삽입, 삭제, 업데이트와 같은 작업도 제공합니다. 다음 스니펫은 QueueManager
의 인스턴스에 액세스하는 방법을 보여줍니다.
const context = cast.framework.CastReceiverContext.getInstance();
const queueManager = context.getPlayerManager().getQueueManager();
기본 큐 관리
초기 큐가 로드되면 QueueManager
를 사용하여 현재 항목 검색, 큐의 모든 항목 검색, 큐의 항목 업데이트와 같은 작업을 insertItems
, removeItems
, updateItems
와 같은 작업에 사용할 수 있습니다.
커스텀 큐 관리
다음은 일부 이벤트를 기반으로 삽입 및 삭제 메서드를 사용하는 맞춤 큐 구현의 예입니다. 또한 이 예에서는 개발자가 광고 시간 삭제와 같이 기존 큐에서 큐 항목을 수정할 수 있는 updateItems
의 사용도 보여줍니다.
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;
}));
}
};
수신 및 발신 메일
수신자 측 대기열 가져오기를 정보 소스로 완전히 지원하기 위해 CAF 수신기 SDK에서 다음과 같은 추가 대기열 메시지를 도입하고 처리합니다.
수신 메시지 | 매개변수 | 발신 응답 메시지 | Return 키 |
다음 | 매개변수가 필요하지 않습니다. | MEDIA_STATUS | 수신기는 (필요한 경우 nextItems()를 통해 가져온) 다음 항목 재생을 시작합니다. |
이전 | 매개변수가 필요하지 않습니다. | MEDIA_STATUS | 웹 수신기가 (필요한 경우 prevItems()를 통해 가져오기) 이전 항목 재생을 시작합니다. |
FETCH_ITEMS | FetchItemsRequestData | QUEUE_CHANGE | Cast.framework.messages.QueueChange. 예를 들어, 삽입 사례의 경우 JSON의 항목 필드에 가져온 새 항목 목록이 포함됩니다. |
GET_ITEMS_INFO | itemIds가 포함된 GetItemsInfoRequestData: 배열<number> | 상품 정보 | cast.framework.messages.ItemsInfo와 함께 큐 항목 정보를 제공합니다. |
GET_QUEUE_IDS | 매개변수가 필요하지 않습니다. | QUEUE_IDS | cast.framework.messages.QueueIds |
NEXT
/PREVIOUS
의 경우 웹 수신기의 기존 큐 표현에 더 많은 항목이 없으면 QueueBase.nextItems()
또는 QueueBase.prevItems()
가 자동으로 호출되어 더 많은 항목을 수신합니다.
FETCH_ITEM
의 경우 QueueBase
구현에서 상응하는 함수 fetchItems
가 클라우드 큐에 호출되고, 이는 저장된 데이터를 저장하기 위해 웹 수신기에 반환될 관련 데이터를 검색합니다.
더 많은 항목을 가져올 때마다 새 메시지 유형 QUEUE_CHANGE
가 트리거되어 발신자에게 다시 전송됩니다. 다양한 유형의 큐 변경사항을 참고하세요.
GET_ITEMS_INFO
의 경우 QueueBase
구현이 트리거되지 않으며 웹 수신기는 이미 ID 목록에 알려진 미디어 정보를 반환합니다.
큐 셔플
큐의 항목을 셔플하도록 설정하려면 큐로 항목을 로드할 때 QueueData
의 shuffle
플래그를 true
로 설정합니다.
QueueBase
구현을 사용하고 있다면 shuffle
메서드를 사용하여 셔플된 항목 목록을 반환합니다.
기존 큐를 셔플하려면 QUEUE_SHUFFLE
명령어 대신 QUEUE_UPDATE
MessageType
의 shuffle
플래그를 사용합니다. 자세한 내용은 QueueUpdateRequestData
를 참고하세요.
반복 모드
큐의 항목을 반복하도록 설정하려면 큐로 항목을 로드할 때 QueueData
의 repeatMode
속성을 원하는 RepeatMode
로 설정합니다.
기존 큐의 RepeatMode
를 변경하려면 QUEUE_UPDATE
MessageType
를 사용하는 QueueUpdateRequestData
의 repeatMode
속성을 사용합니다.