הבאים בתור

סקירה כללית

ה-SDK של מקלט האינטרנט תומך ב'הבאים בתור' עם תור ברירת המחדל שסופק על ידי ה-SDK באמצעות QueueData וב-QueueManager, או באמצעות תור מותאם אישית על ידי הטמעת cast.framework.QueueBase ו-QueueManager לעדכונים.

ה-Quueing API מאפשר לאפליקציות להשתלב טוב יותר ב-Cast על ידי שימוש בתכונות הבאות:

• תמיכה בהטמעה של 'הבאים בתור' בענן של Google ושל שותפים, כדי שאפשר יהיה לטעון באופן ישיר אל מכשירי Cast את התור שנשמר באופן חיצוני.
• מנגנונים שמאפשרים עימוד של פריטים בתור במקום לטעון הכול בבת אחת.
• תמיכה בהודעות חדשות, כמו מעבר לפריט הבא, הפריט הקודם, אחזור חלון של פריטים, כמו גם קבלת מידע על מדיה שקשור לקבוצה של פריטים בתור.
• ה-QueueManager כדי לנהל הוספה, הסרה ועדכון של פריטים ב'הבאים בתור'.

תור ברירת המחדל

ה-SDK של מקלט האינטרנט מספק תמיכה מוגבלת בתור מחוץ לחבילות בתור תור ברירת מחדל.

כדי להשתמש בתור ברירת המחדל, צריך לספק את המספר queueData בLoadRequestData של הטעינות בצד השולח או לשלוח בקשת טעינה מקומית באמצעות PlayerManager#load. יש לעיין גם בטעינת מדיה.

אזהרה: אין להוסיף או לשנות את הנכס של queueData של יירוט LOAD. לא תהיה לכך השפעה על ההפעלה, כי queueData כבר נקרא והוחלה על 'הבאים בתור'.

בצד של המקבל, אפשר לשנות את התור באמצעות 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;
    }));
  }
};

הודעות נכנסות ויוצאות

כדי לתמוך באופן מלא באחזור בתור הצד של המקלט כמקור האמת, ההודעות הנוספות הבאות בתור מטופלות מוצגות ומטופלות על ידי ה-SDK של המקלט:

הודעה נכנסת	פרמטרים	הודעת תגובה יוצאת	חזרה
הבא	לא נדרש פרמטר.	MEDIA_STATUS	המקבל יאחזר (באמצעות אחזור את הפריט הבא) (במידת הצורך), ויתחיל להשמיע את הפריט הבא.
הקודם	לא נדרש פרמטר.	MEDIA_STATUS	מקלט האינטרנט יבצע שליפה (באמצעות שליפה קודמת (prevItems) במידת הצורך ויתחיל להפעיל את הפריט הקודם.
FETCH_ITEMS	FetchItemsRequestData	QUEUE_CHANGE	cast.framework.messages.QueueChange. לדוגמה, במקרה של הוספה, שדה הפריטים ב-JSON יכיל את רשימת הפריטים החדשים שאוחזרו.
GET_ITEMS_INFO	GetItemsInfoRequestData שמכיל itemIds: Array<number>	ITEMS_INFO	cast.framework.messages.ItemsInfo עם מידע על הפריט בתור.
GET_QUEUE_IDS	לא נדרש פרמטר.	QUEUE_IDS	cast.framework.messages.QueueIds.

עבור NEXT/PREVIOUS, אם בייצוג הקיים בתור בתור מקלט אינטרנט אין פריטים, QueueBase.nextItems() או QueueBase.prevItems() מופעל אוטומטית לקבלת פריטים נוספים.

עבור הפונקציה FETCH_ITEM, הפונקציה המתאימה fetchItems בהטמעה של QueueBase נקראת לתורים בענן, שמאחזרת את הנתונים הרלוונטיים שיוחזרו למקלט האינטרנט לאחסון.

בכל פעם שפריטים נוספים מאוחזרים, סוג הודעה חדש מופעל, QUEUE_CHANGE, ונשלח בחזרה לשולח. הצגת הסוגים השונים של שינויים בתור.

לגבי GET_ITEMS_INFO, ההטמעה של QueueBase לא מופעלת, והמקלט באינטרנט מחזיר מידע מדיה שכבר ידוע ברשימת המזהים.

הערה: באופן כללי, הודעות התור בתור נכנס ויוצא מטופלות על ידי ה-SDK של השולח (אינטרנט, iOS ו-Android) כדי לוודא שממשק המשתמש המתאים יוצג בצד השולח. מפתחי אפליקציות יכולים ליירט הודעות כאלה או להאזין להן לפי הצורך.

הפעלה אקראית של 'הבאים בתור'

כדי להגדיר השמעה אקראית של הפריטים ב'הבאים בתור', הגדירו את הדגל shuffle של QueueData כ-true בזמן טעינת הפריטים בתור.

אם משתמשים בהטמעה של QueueBase, אפשר להשתמש בשיטה shuffle כדי להחזיר רשימה אקראית של פריטים.

להפעלה אקראית של התור הקיים, משתמשים בסימון shuffle של QUEUE_UPDATE MessageType, במקום בפקודה QUEUE_SHUFFLE. מידע נוסף זמין כאן: QueueUpdateRequestData.

מצב חזרה

כדי להגדיר אילו פריטים יחזרו על עצמם, מגדירים את המאפיין repeatMode של QueueData לערך הרצוי RepeatMode כשטוענים את הפריטים ל'הבאים בתור'.

כדי לשנות את RepeatMode בתור קיים, השתמשו בנכס repeatMode של QueueUpdateRequestData, שמשתמש ב-QUEUE_UPDATE MessageType.