הוספת תכונות ליבה למקלט האינטרנט המותאם אישית

בדף הזה יש קטעי קוד ותיאורים של התכונות שזמינות באפליקציית Custom Web Receiver.

1. רכיב cast-media-player שמייצג את ממשק המשתמש המובנה של הנגן שמסופק עם Web Receiver.
2. סגנון מותאם אישית שדומה ל-CSS לרכיב cast-media-player, כדי לסגנן רכיבים שונים בממשק המשתמש, כמו background-image, splash-image ו-font-family.
3. רכיב סקריפט לטעינת מסגרת Web Receiver.
4. קוד JavaScript ליירוט הודעות וטיפול באירועים.
5. הוספה לתור להפעלה אוטומטית.
6. אפשרויות להגדרת ההפעלה.
7. אפשרויות להגדרת ההקשר של Web Receiver.
8. אפשרויות להגדרת פקודות שנתמכות באפליקציית Web Receiver.
9. קריאה ל-JavaScript כדי להפעיל את אפליקציית Web Receiver.

הגדרות ואפשרויות של אפליקציות

הגדרת האפליקציה

‫ CastReceiverContext היא המחלקה החיצונית ביותר שחשופה למפתח, והיא מנהלת את הטעינה של ספריות בסיסיות ומטפלת באתחול של Web Receiver SDK. ערכת ה-SDK מספקת ממשקי API שמאפשרים למפתחי אפליקציות להגדיר את ערכת ה-SDK באמצעות CastReceiverOptions. ההגדרות האלה מוערכות פעם אחת בכל הפעלה של האפליקציה, ומועברות ל-SDK כשמגדירים את הפרמטר האופציונלי בקריאה ל-start.

בדוגמה הבאה אפשר לראות איך משנים את התנהגות ברירת המחדל של זיהוי אם החיבור של השולח עדיין פעיל. אם Web Receiver לא הצליח לתקשר עם השולח במשך maxInactivity שניות, נשלח אירוע SENDER_DISCONNECTED. ההגדרה האישית שלמטה מבטלת את הגדרת הזמן הקצוב לתפוגה. האפשרות הזו יכולה להיות שימושית כשמנפים באגים בבעיות, כי היא מונעת מאפליקציית Web Receiver לסגור את סשן ניפוי הבאגים ב-Chrome Remote Debugger כשאין שולחים מחוברים במצב IDLE.

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);

הגדרת הנגן

כשמטעינים תוכן, Web Receiver SDK מספק דרך להגדיר משתני הפעלה כמו מידע על DRM, הגדרות ניסיון חוזר ומטפלי בקשות באמצעות cast.framework.PlaybackConfig. המידע הזה מטופל על ידי PlayerManager ונבדק בזמן יצירת השחקנים. שחקנים נוצרים בכל פעם שמועברת טעינה חדשה אל Web Receiver SDK. שינויים ב-PlaybackConfig אחרי שהשחקן נוצר מוערכים בטעינת התוכן הבאה. ערכת ה-SDK מספקת את השיטות הבאות לשינוי PlaybackConfig.

• ‫CastReceiverOptions.playbackConfig כדי לשנות את אפשרויות ההגדרה שמוגדרות כברירת מחדל כשמאתחלים את CastReceiverContext.
• ‫PlayerManager.getPlaybackConfig() כדי לקבל את ההגדרה הנוכחית.
• ‫PlayerManager.setPlaybackConfig() כדי לעקוף את ההגדרה הנוכחית. ההגדרה הזו חלה על כל הטעינות הבאות או עד שהיא מוחלפת שוב.
• ‫PlayerManager.setMediaPlaybackInfoHandler() כדי להחיל הגדרות נוספות רק על פריט המדיה שנמצא בטעינה, בנוסף להגדרות הנוכחיות. הפונקציה handler נקראת ממש לפני יצירת השחקן. השינויים שמבצעים כאן לא קבועים ולא נכללים בשאילתות אל getPlaybackConfig(). כשהפריט הבא של המדיה נטען, המערכת קוראת שוב ל-handler הזה.

בדוגמה הבאה אפשר לראות איך מגדירים את PlaybackConfig כשמפעילים את CastReceiverContext. ההגדרה הזו מבטלת את הבקשות היוצאות לקבלת קובצי מניפסט. ה-handler מציין שצריך לשלוח בקשות Access-Control של CORS באמצעות פרטי כניסה כמו קובצי Cookie או כותרות הרשאות.

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

בדוגמה הבאה מוצג איך לשנות את PlaybackConfig באמצעות getter ו-setter שמופיעים ב-PlayerManager. ההגדרה קובעת שהנגן ימשיך להפעיל את התוכן אחרי שפלחי הקהל נטענו.

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

בדוגמה הבאה מוצג אופן ההגדרה של שינוי ברירת המחדל של PlaybackConfig עבור בקשת טעינה ספציפית באמצעות handler של פרטי הפעלת מדיה. ה-handler מפעיל את השיטה getLicenseUrlForMedia שהוטמעה באפליקציה כדי לקבל את licenseUrl מתוך contentId של הפריט הנוכחי.

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

פונקציית event listener

‫Web Receiver SDK מאפשר לאפליקציית Web Receiver לטפל באירועים של נגן. הפונקציה event listener מקבלת פרמטר cast.framework.events.EventType (או מערך של פרמטרים כאלה) שמציין את האירועים שאמורים להפעיל את הפונקציה. מערכים שהוגדרו מראש של cast.framework.events.EventType שיכולים לעזור בניפוי באגים נמצאים ב-cast.framework.events.category. פרמטר האירוע מספק מידע נוסף על האירוע.

לדוגמה, אם רוצים לדעת מתי מתבצע שידור של שינוי ב-mediaStatus, אפשר להשתמש בלוגיקה הבאה כדי לטפל באירוע:

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
});

יירוט הודעות

ערכת Web Receiver SDK מאפשרת לאפליקציית Web Receiver ליירט הודעות ולהריץ קוד מותאם אישית על ההודעות האלה. הפרמטר של הכלי ליירוט הודעות cast.framework.messages.MessageType מציין איזה סוג הודעה צריך ליירט.

ה-interceptor צריך להחזיר את הבקשה ששונתה או Promise שמסתיימת עם ערך הבקשה ששונה. החזרת null תמנע את הקריאה ל-handler של הודעת ברירת המחדל. פרטים נוספים מופיעים במאמר בנושא טעינת מדיה.

לדוגמה, אם רוצים לשנות את נתוני בקשת הטעינה, אפשר להשתמש בלוגיקה הבאה כדי ליירט ולשנות אותם:

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();

טיפול בשגיאות

כשמתרחשות שגיאות ב-message interceptor, אפליקציית Web Receiver צריכה להחזיר cast.framework.messages.ErrorType ו-cast.framework.messages.ErrorReason מתאימים.

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;
        });
    });

יירוט הודעות לעומת event listener

אלה כמה מההבדלים העיקריים בין חסימת הודעות לבין מאזין אירועים:

• מאזין אירועים לא מאפשר לכם לשנות את נתוני הבקשה.
• השימוש הכי טוב בפונקציה event listener הוא להפעלת ניתוח או פונקציה בהתאמה אישית.

playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });

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

המדיה בטעינה

‫MediaInformation מספק מאפיינים רבים לטעינת מדיה בהודעה cast.framework.messages.MessageType.LOAD, כולל entity, ‏ contentUrl ו-contentId.

• המאפיין המומלץ לשימוש בהטמעה שלכם הן באפליקציות השולח והן באפליקציות המקבל הוא entity הנכס הוא כתובת URL של קישור עמוק שיכולה להיות רשימת השמעה או תוכן מדיה. האפליקציה צריכה לנתח את כתובת ה-URL הזו ולאכלס לפחות אחד משני השדות האחרים.
• הערך contentUrl תואם לכתובת ה-URL שניתן להפעלה, שבה הנגן ישתמש כדי לטעון את התוכן. לדוגמה, כתובת ה-URL הזו יכולה להפנות למניפסט של DASH.
• הערך של contentId יכול להיות כתובת URL של תוכן שאפשר להפעיל (בדומה לערך של מאפיין contentUrl ) או מזהה ייחודי של התוכן או הפלייליסט שנמצאים בטעינה. אם משתמשים במאפיין הזה כמזהה, האפליקציה צריכה לאכלס כתובת URL שאפשר להפעיל במשחק במאפיין contentUrl.

מומלץ להשתמש ב-entity כדי לאחסן את המזהה האמיתי או פרמטרים של מפתח, ולהשתמש ב-contentUrl לכתובת ה-URL של המדיה. בדוגמה הבאה מוצג קטע קוד שבו הערך entity מופיע בבקשה LOAD והערך contentUrl שניתן להפעלה מאוחזר:

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;
        });
    });

יכולות המכשיר

השיטה getDeviceCapabilities מספקת מידע על מכשיר Cast המחובר ועל מכשיר הווידאו או האודיו שמחובר אליו. בשיטה getDeviceCapabilities מופיע מידע על התמיכה ב-Google Assistant, ב-Bluetooth ובמסך ובמכשירי האודיו המחוברים.

השיטה הזו מחזירה אובייקט שאפשר להריץ עליו שאילתה על ידי העברת אחד מהערכים המפורטים של enum כדי לקבל את יכולת המכשיר עבור ה-enum הזה. ה-enums מוגדרים ב-cast.framework.system.DeviceCapabilities.

בדוגמה הזו נבדק אם מכשיר Web Receiver יכול להפעיל HDR ו-DolbyVision ‏ (DV) באמצעות המקשים IS_HDR_SUPPORTED ו-IS_DV_SUPPORTED, בהתאמה.

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();

טיפול באינטראקציות של משתמשים

משתמש יכול ליצור אינטראקציה עם אפליקציית Web Receiver באמצעות אפליקציות שולחות (אינטרנט, Android ו-iOS), פקודות קוליות במכשירים עם Assistant, פקדי מגע במסכים חכמים ושלטים במכשירי Android TV. ‫Cast SDK מספק ממשקי API שונים כדי לאפשר לאפליקציית Web Receiver לטפל באינטראקציות האלה, לעדכן את ממשק המשתמש של האפליקציה באמצעות user action states, ובאופן אופציונלי לשלוח את השינויים כדי לעדכן שירותי קצה עורפיים.

פקודות מדיה נתמכות

מצבי אמצעי הבקרה בממשק המשתמש מונעים על ידי MediaStatus.supportedMediaCommands באפליקציות השולט ל-iOS ול-Android, באפליקציות של המקלט ובאפליקציות של השלט הרחוק שפועלות במכשירי מגע, ובאפליקציות של המקלט במכשירי Android TV. כשמפעילים ביט מסוים Command בנכס, הכפתורים שקשורים לפעולה הזו מופעלים. אם לא מגדירים את הערך, הלחצן מושבת. אפשר לשנות את הערכים האלה ב-Web Receiver באמצעות:

1. שימוש ב-PlayerManager.setSupportedMediaCommands כדי להגדיר את Commands הספציפי
2. הוספת פקודה חדשה באמצעות addSupportedMediaCommands
3. הסרה של פקודה קיימת באמצעות removeSupportedMediaCommands.

playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

כשהמקבל יכין את MediaStatus המעודכן, הוא יכלול את השינויים בנכס supportedMediaCommands. כשהסטטוס משודר, אפליקציות השולח המחוברות מעדכנות את הלחצנים בממשק המשתמש שלהן בהתאם.

מידע נוסף על פקודות מדיה נתמכות ומכשירי מגע זמין במדריך Accessing UI controls.

ניהול מצבי פעולות משתמש

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

• מגדירים את MediaInformation userActionStates עם העדפות המשתמש כשמטעינים פריט מדיה.
• ליירט הודעות USER_ACTION ולקבוע את הפעולה הנדרשת.
• כדי לעדכן את ממשק המשתמש, צריך לעדכן את MediaInformation UserActionState.

קטע הקוד הבא מיירט את הבקשה LOAD ומאכלס את MediaInformation של LoadRequestData. במקרה הזה, המשתמש אוהב את התוכן שנטען.

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;
    });

קטע הקוד הבא מיירט את ההודעה USER_ACTION ומטפל בקריאה לשרת העורפי עם השינוי המבוקש. לאחר מכן מתבצעת קריאה לעדכון UserActionState בשרת המקבל.

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;
    });
});

בקטע הקוד הבא מבוצעת סימולציה של קריאה לשירות backend. הפונקציה בודקת את UserActionRequestData כדי לראות את סוג השינוי שהמשתמש ביקש, ומבצעת קריאה לרשת רק אם הפעולה נתמכת על ידי ה-Backend.

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));
    }
  });
}

בקטע הקוד הבא, המשתנה UserActionRequestData מתווסף ל-MediaInformation או מוסר ממנו, בהתאם לערך של UserActionState. עדכון הסטטוס של UserActionState של MediaInformation משנה את המצב של הכפתור שמשויך לפעולה המבוקשת. השינוי הזה בא לידי ביטוי בממשק המשתמש של אמצעי הבקרה של התצוגה החכמה, באפליקציה לשלט רחוק ובממשק המשתמש של Android TV. הוא גם מועבר בשידור דרך MediaStatus הודעות יוצאות כדי לעדכן את ממשק המשתמש של אמצעי הבקרה המורחב עבור שולחים ב-iOS וב-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;
}

פקודות קוליות

בשלב הזה, פקודות המדיה הבאות נתמכות ב-Web Receiver SDK במכשירים עם Assistant. היישומים שמוגדרים כברירת מחדל של הפקודות האלה נמצאים ב-cast.framework.PlayerManager.

פקודות מדיה נתמכות באמצעות קול

כדי למנוע הפעלה של פקודת מדיה במכשיר עם Assistant באמצעות פקודה קולית, צריך קודם להגדיר את פקודות המדיה הנתמכות שרוצים לתמוך בהן. לאחר מכן, צריך לאכוף את הפקודות האלה על ידי הפעלת המאפיין CastReceiverOptions.enforceSupportedCommands. ממשק המשתמש במכשירים ששולחים תוכן באמצעות Cast SDK ובמכשירים עם מסך מגע ישתנה בהתאם להגדרות האלה. אם הדגל לא מופעל, הפקודות הקוליות הנכנסות יבוצעו.

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

בדוגמה שלמטה אנחנו מספקים את CastReceiverOptions כשמפעילים את CastReceiverContext. הוספנו תמיכה בפקודה PAUSE ואילצנו את הנגן לתמוך רק בפקודה הזו. עכשיו, אם פקודה קולית תבקש פעולה אחרת, כמו SEEK, היא תידחה. המשתמש יקבל הודעה שהפקודה עדיין לא נתמכת.

const context = cast.framework.CastReceiverContext.getInstance();

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

אפשר להחיל לוגיקה נפרדת על כל פקודה שרוצים להגביל. מסירים את הדגל enforceSupportedCommands. כדי להגביל כל פקודה, אפשר ליירט את ההודעה הנכנסת. כאן אנחנו מיירטים את הבקשה שמסופקת על ידי ה-SDK, כך שפקודות SEEK שמונפקות למכשירים עם Assistant לא מפעילות חיפוש באפליקציית Web Receiver.

עבור פקודות מדיה שהאפליקציה לא תומכת בהן, צריך להחזיר סיבת שגיאה מתאימה, כמו 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;
  });

העברה לרקע מפעילות קולית

אם פלטפורמת Cast מפעילה את הצליל של האפליקציה ברקע בגלל פעילות של Assistant, כמו האזנה לדיבור של המשתמש או מענה לו, הודעה של NOT_IN_FOCUS עם הסמל FocusState נשלחת לאפליקציית Web Receiver כשהפעילות מתחילה. כשמסיימים את הפעילות, נשלחת הודעה נוספת עם IN_FOCUS. בהתאם לאפליקציה ולמדיה שמופעלת, יכול להיות שתרצו להשהות את המדיה כשהמצב של FocusState הוא NOT_IN_FOCUS. כדי לעשות זאת, צריך ליירט את סוג ההודעה FOCUS_STATE.

לדוגמה, חוויית משתמש טובה היא להשהות את ההפעלה של ספר אודיו אם Assistant מגיבה לשאלה של משתמש.

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;
  });

שפת הכתוביות שנקבעה באמצעות קול

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

לדוגמה, הערך של isSuggestedLanguage מוגדר כ-true עבור הפקודה 'Ok Google, turn captions on', כי השפה נקבעה לפי השפה שבה נאמרה הפקודה. אם השפה מצוינת באופן מפורש, כמו בבקשה "OK Google, turn on English captions", הערך של isSuggestedLanguage מוגדר כ-false.

מטא-נתונים ושימוש בהעברת תוכן קולי

כברירת מחדל, פקודות קוליות מטופלות על ידי Web Receiver, אבל חשוב לוודא שהמטא-נתונים של התוכן מלאים ומדויקים. כך אפשר לוודא שהפקודות הקוליות מטופלות בצורה נכונה על ידי Assistant, ושהמטא-נתונים מוצגים בצורה נכונה בסוגים חדשים של ממשקי משתמש, כמו אפליקציית Google Home ומסכים חכמים כמו Google Home Hub.

החלפת רמקול

שמירת מצב הסשן היא הבסיס להעברת סטרימינג, שבה משתמשים יכולים להעביר סטרימינג קיים של אודיו ווידאו בין מכשירים באמצעות פקודות קוליות, אפליקציית Google Home או מסכים חכמים. הפעלת המדיה נפסקת במכשיר אחד (המקור) וממשיכה במכשיר אחר (היעד). כל מכשיר Cast עם הקושחה העדכנית יכול לשמש כמקור או כיעד בהעברת סטרימינג.

זרימת האירועים בהעברת נתונים לשידור היא:

1. במכשיר המקור:
   1. הפעלת המדיה נפסקת.
   2. אפליקציית Web Receiver מקבלת פקודה לשמירת מצב המדיה הנוכחי.
   3. אפליקציית Web Receiver מושבתת.
2. במכשיר היעד:
   1. אפליקציית Web Receiver נטענת.
   2. אפליקציית Web Receiver מקבלת פקודה לשחזור מצב המדיה שנשמר.
   3. הפעלת המדיה תמשיך.

אלמנטים של מצב המדיה:

• מיקום ספציפי או חותמת זמן של השיר, הסרטון או פריט המדיה.
• המיקום שלו בתור רחב יותר (כמו פלייליסט או רדיו של אומן).
• המשתמש המאומת.
• מצב ההפעלה (לדוגמה, מופעלת או מושהית).

הפעלת החלפת רמקול

כדי להטמיע העברת סטרימינג ב-Web Receiver:

1. מעדכנים את supportedMediaCommands באמצעות הפקודה STREAM_TRANSFER:

   playerManager.addSupportedMediaCommands(
   cast.framework.messages.Command.STREAM_TRANSFER, true);

2. אפשר גם לבטל את ההגדרה של מיירטי ההודעות SESSION_STATE ו-RESUME_SESSION כמו שמתואר במאמר שמירה של מצב הסשן. כדאי לשנות את ההגדרות האלה רק אם צריך לאחסן נתונים מותאמים אישית כחלק מתמונת המצב של הסשן. אחרת, הטמעת ברירת המחדל לשמירת מצבי סשן תתמוך בהעברת סטרימינג.

שמירה של מצב הסשן

‫Web Receiver SDK מספק הטמעה שמוגדרת כברירת מחדל לאפליקציות Web Receiver כדי לשמור את מצבי הסשן. לשם כך, הוא מצלם תמונה של סטטוס המדיה הנוכחי, ממיר את הסטטוס לבקשת טעינה וממשיך את הסשן עם בקשת הטעינה.

אפשר לבטל את בקשת הטעינה שנוצרה על ידי Web Receiver ב-SESSION_STATE message interceptor, אם צריך. אם רוצים להוסיף נתונים מותאמים אישית לבקשת הטעינה, מומלץ להוסיף אותם ל-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;
    });

אפשר לאחזר את הנתונים המותאמים אישית מ-loadRequestData.customData ב-RESUME_SESSION interceptor של ההודעה.

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;
    });

טעינה מראש של תוכן

ה-Web Receiver תומך בטעינה מראש של פריטי מדיה אחרי הפריט הנוכחי שמופעל בתור.

פעולת הטעינה מראש מורידה מראש כמה קטעים של הפריטים הבאים. ההגדרה מתבצעת בערך preloadTime באובייקט QueueItem (ברירת המחדל היא 20 שניות אם לא צוין ערך). הזמן מוצג בשניות, ביחס לסוף הפריט שמופעל כרגע . אפשר להזין רק ערכים חיוביים. לדוגמה, אם הערך הוא 10 שניות, הפריט הזה ייטען מראש 10 שניות לפני שהפריט הקודם יסיים את ההפעלה. אם הזמן שנדרש לטעינה מראש גבוה מהזמן שנותר בפריט הנוכחי, הטעינה מראש תתבצע בהקדם האפשרי. לכן, אם מציינים ערך גדול מאוד של טעינה מראש ב-queueItem, אפשר להשיג את האפקט של טעינה מראש של הפריט הבא בכל פעם שמפעילים את הפריט הנוכחי. עם זאת, אנחנו משאירים את ההגדרה והבחירה של הערך הזה למפתח, כי הוא יכול להשפיע על רוחב הפס ועל ביצועי הסטרימינג של הפריט שמופעל כרגע.

כברירת מחדל, טעינה מראש תפעל עבור תוכן בפורמטים HLS, ‏ DASH ו-Smooth streaming.

קובצי אודיו ווידאו רגילים בפורמט MP4, כמו MP3, לא ייטענו מראש כי מכשירי Cast תומכים רק ברכיב מדיה אחד, ואי אפשר להשתמש בהם לטעינה מראש בזמן שפריט תוכן קיים עדיין מוצג.

הודעות מותאמות אישית

החלפת הודעות היא שיטת האינטראקציה העיקרית באפליקציות של Web Receiver.

השולח מנפיק הודעות ל-Web Receiver באמצעות ממשקי ה-API של השולח עבור הפלטפורמה שבה השולח פועל (Android, ‏ iOS, אינטרנט). לאובייקט האירוע (שהוא המופע של הודעה) שמועבר למאזיני האירועים יש רכיב נתונים (event.data) שבו הנתונים מקבלים את המאפיינים של סוג האירוע הספציפי.

אפליקציית Web Receiver יכולה להאזין להודעות במרחב שמות ספציפי. כתוצאה מכך, אפליקציית Web Receiver תומכת בפרוטוקול של מרחב השמות הזה. לאחר מכן, כל שולח שמחובר למרחב השמות הזה ורוצה לתקשר בו צריך להשתמש בפרוטוקול המתאים.

כל מרחבי השמות מוגדרים על ידי מחרוזת וחייבים להתחיל ב-'urn:x-cast:' ואחריהם כל מחרוזת. לדוגמה, ‫"urn:x-cast:com.example.cast.mynamespace".

הנה קטע קוד של Web Receiver להאזנה להודעות מותאמות אישית משולחים מחוברים:

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();

באופן דומה, אפליקציות Web Receiver יכולות לשלוח הודעות לשולחים מחוברים כדי לעדכן אותם לגבי המצב של Web Receiver. אפליקציית Web Receiver יכולה לשלוח הודעות באמצעות sendCustomMessage(namespace, senderId, message) ב-CastReceiverContext. מקלט אינטרנט יכול לשלוח הודעות לשולח מסוים, בתגובה להודעה שהתקבלה או בגלל שינוי במצב האפליקציה. בנוסף להודעות ישירות (עם מגבלה של 64kb), מקלט אינטרנט יכול גם לשדר הודעות לכל השולחים המחוברים.

הפעלת Cast למכשירי אודיו

לקבלת תמיכה בהפעלה של אודיו בלבד, אפשר לעיין במדריך של Google Cast למכשירי אודיו.

Android TV

בקטע הזה מוסבר איך Google Web Receiver משתמש בקלט שלכם להפעלה, ואיך הוא תואם ל-Android TV.

שילוב האפליקציה עם השלט הרחוק

ה-Web Receiver של Google שפועל במכשיר Android TV מתרגם קלט מהקלט של אמצעי הבקרה של המכשיר (כלומר, שלט רחוק) כהודעות הפעלת מדיה שמוגדרות במרחב השמות urn:x-cast:com.google.cast.media, כפי שמתואר במאמר הודעות הפעלת מדיה. האפליקציה שלכם צריכה לתמוך בהודעות האלה כדי לשלוט בהפעלת המדיה באפליקציה, וכך לאפשר שליטה בסיסית בהפעלה באמצעות אמצעי הקלט של Android TV.

הנחיות לתאימות ל-Android TV

ריכזנו כאן כמה המלצות וטעויות נפוצות שכדאי להימנע מהן כדי לוודא שהאפליקציה שלכם תהיה תואמת ל-Android TV:

• שימו לב שמחרוזת user-agent מכילה גם Android וגם CrKey. יכול להיות שאתרים מסוימים יפנו אתכם לאתר לנייד בלבד כי הם מזהים את התווית Android. אל תניחו שהמחרוזת 'Android' בסוכן המשתמש תמיד מציינת משתמש בנייד.
• יכול להיות שחבילת המדיה של Android תשתמש ב-GZIP שקוף כדי לאחזר נתונים. חשוב לוודא שנתוני המדיה יכולים להגיב ל-Accept-Encoding: gzip.
• יכול להיות שאירועי מדיה ב-HTML5 ב-Android TV יופעלו בתזמון שונה מזה של Chromecast, ולכן יכול להיות שיוצגו בעיות שהיו מוסתרות ב-Chromecast.
• כשמעדכנים את המדיה, משתמשים באירועים שקשורים למדיה ומופעלים על ידי רכיבי <audio>/<video>, כמו timeupdate, pause ו-waiting. מומלץ להימנע משימוש באירועים שקשורים לרשת, כמו progress,‏ suspend ו-stalled, כי הם בדרך כלל תלויים בפלטפורמה. מידע נוסף על טיפול באירועי מדיה במקלט זמין במאמר בנושא אירועי מדיה.
• כשמגדירים את אישורי ה-HTTPS של אתר הנמען, חשוב לכלול אישורי CA ביניים. כדי לבדוק אם נתיב האישורים המהימן של האתר כולל אישור CA עם התווית extra download, כדאי לעיין בדף הבדיקה של Qualsys SSL. אם הוא כולל אישור כזה, יכול להיות שהאתר לא ייטען בפלטפורמות מבוססות-Android.
• כשמשתמשים ב-Chromecast, דף המקלט מוצג במישור גרפיקה של 720p, אבל בפלטפורמות אחרות של Cast, כולל Android TV, יכול להיות שהדף יוצג עד 1080p. חשוב לוודא שדף המקלט שלכם משתנה בצורה חלקה ברזולוציות שונות.