概要
Web Receiver SDK は、QueueData
と QueueManager
を使用して SDK が提供するデフォルト キューによるキューをサポートするか、cast.framework.QueueBase
を実装して更新に QueueManager
を使用することでカスタムキューを使用できます。
Queueing API を使用すると、次の機能によって Cast とアプリの統合を強化できます。
- Google とパートナーのクラウドキュー実装のサポート。これにより、外部で保存および作成されたキューをキャスト デバイスに直接読み込むことができます。
- すべてを一度に読み込むのではなく、キュー内のアイテムをページ分けするメカニズム。
- 新しいアイテム、前のアイテムに移動、アイテム ウィンドウの取得、キューアイテムのセットに関連するメディア情報の取得など、新しいメッセージのサポート。
- キューアイテムの挿入、削除、更新を管理する
QueueManager
。
デフォルトのキュー
Web Receiver SDK では、デフォルトのキューの形式で、特別なサポートがキューですぐに提供されます。
デフォルトのキューを使用するには、送信者側の読み込みの LoadRequestData
に queueData
を指定するか、PlayerManager#load
を使用してローカル読み込みリクエストを送信します。メディアの読み込みもご覧ください。
レシーバー側では、最初のメディアが読み込まれた後、QueueManager
を使用してキューを変更できます。
カスタムキュー
デフォルト キューにアプリに必要なキューイング機能がない場合は、カスタムキューを作成できるため、機能と柔軟性が向上します。
アプリケーション デベロッパーは、cast.framework.QueueBase
を実装してウェブレシーバ サイドキューを作成できます。
以下は、initialize
呼び出しがオーバーライドされ、キュー項目のリストとキューの説明がキャスト デバイスに提供される単純なキューの基本的な例です。
メディアの読み込みもご覧ください。
// 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
コンストラクタの呼び出しで提供されます。ただし、クラウドキューの実装では、カスタムの Web Receiver ロジックがアイテムを外部で取得し、初期化呼び出しの一部として返すことができます。
キューイング 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 Receiver SDK によって処理されます。
受信メール | パラメータ | 送信レスポンス メッセージ | 戻り値 |
次へ | パラメータは必要ありません。 | MEDIA_STATUS | レシーバーは(必要に応じて nextItems() を介して)フェッチし、次のアイテムの再生を開始します。 |
前へ | パラメータは必要ありません。 | MEDIA_STATUS | ウェブ レシーバーは(必要に応じて prevItems() を使用して)フェッチし、前のアイテムの再生を開始します。 |
FETCH_ITEMS | FetchItemsRequestData | QUEUE_CHANGE | cast.framework.messages.QueueChange。たとえば、挿入のケースでは、JSON 内の items フィールドに、取得された新しいアイテムのリストが含まれます。 |
GET_ITEMS_INFO | itemIds を含む GetItemsInfoRequestData: Array<number> | ITEMS_INFO | キューアイテム情報を含む cast.framework.messages.ItemsInfo。 |
GET_QUEUE_IDS | パラメータは必要ありません。 | QUEUE_IDS | cast.framework.messages.QueueIds。 |
NEXT
/ PREVIOUS
の場合、Web レシーバーの既存のキュー表現にアイテムがない場合、QueueBase.nextItems()
または QueueBase.prevItems()
が自動的に呼び出されて、追加のアイテムを受け取ります。
FETCH_ITEM
の場合、QueueBase
実装の対応する関数 fetchItems
が Cloud Queue に対して呼び出されます。これにより、関連するデータがウェブ レシーバに保存され、保存されます。
さらにアイテムが取得されると、新しいメッセージ タイプ QUEUE_CHANGE
がトリガーされ、送信者に返されます。さまざまなタイプのキューの変更をご覧ください。
GET_ITEMS_INFO
の場合、QueueBase
の実装はトリガーされず、ウェブレシーバーは ID のリストで既知のメディア情報を返します。
キューをシャッフルする
キュー内のアイテムをシャッフルするように設定するには、アイテムをキューに読み込むときに、QueueData
の shuffle
フラグを true
に設定します。
QueueBase
の実装を使用している場合は、shuffle
メソッドを使用して、アイテムのシャッフル リストを返します。
既存のキューをシャッフルするには、QUEUE_SHUFFLE
コマンドではなく、QUEUE_UPDATE
MessageType
の shuffle
フラグを使用します。詳しくは、QueueUpdateRequestData
をご覧ください。
リピートモード
キュー内のアイテムを繰り返すように設定するには、アイテムをキューに読み込むときに、QueueData
の repeatMode
プロパティを目的の RepeatMode
に設定します。
既存のキューの RepeatMode
を変更するには、QueueUpdateRequestData
の repeatMode
プロパティを使用します。このプロパティでは、QUEUE_UPDATE
MessageType
を使用しています。