ניפוי באגים באפליקציות מקלט העברה

1. סקירה כללית

ה-codelab הזה ילמד אותך איך להוסיף את מכשיר לניפוי באגים להעברה (cast) לאפליקציה הקיימת של מקלט האינטרנט בהתאמה אישית.

מה זה Google Cast?

ערכת ה-SDK של Google Cast מאפשרת לאפליקציה להפעיל תוכן ולשלוט בהפעלה במכשירים שתומכים ב-Google Cast. הכלי מספק את רכיבי ממשק המשתמש הנדרשים על סמך רשימת המשימות לעיצוב של Google Cast.

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

מה אנחנו הולכים ליצור?

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

פרטים נוספים זמינים במדריך ליומן ניפוי הבאגים של Cast.

מה תלמדו

• איך מגדירים את הסביבה לפיתוח של Web Receiver.
• איך משלבים את Debug Logger במקלט Cast.

מה נדרש

• דפדפן Google Chrome העדכני ביותר.
• שירות אירוח HTTPS, כמו Firebase Hosting או ngrok.
• מכשיר Google Cast, כמו Chromecast או Android TV, עם הגדרת גישה לאינטרנט.
• טלוויזיה או צג עם כניסת HDMI.

ניסיון

• צריך להיות לכם ניסיון קודם ב-Cast ולהבין איך פועל מקלט אינטרנט של Cast.
• נדרש ידע קודם בפיתוח אתרים.
• בנוסף, צריך ניסיון קודם בצפייה בטלוויזיה :)

2. קבלת קוד לדוגמה

אתם יכולים להוריד את כל הקוד לדוגמה למחשב...

file_downloadהורדת המקור

ופותחים את קובץ ה-ZIP שהורדתם.

3. פריסה של המקלט באופן מקומי

כדי להשתמש במקלט האינטרנט עם מכשיר Cast, המכשיר צריך להתארח במקום שבו מכשיר ה-Cast יכול להגיע אליו. אם כבר יש לכם שרת זמין שתומך ב-https, דלגו על ההוראות הבאות ושימו לב לכתובת ה-URL, כי תצטרכו אותה בקטע הבא.

אם אין לכם שרת זמין לשימוש, תוכלו להשתמש ב-אירוח ב-Firebase או ב-ngrok.

הפעלת השרת

אחרי שמגדירים את השירות שבחרתם, עוברים אל app-start ומפעילים את השרת.

כותבים לעצמכם את כתובת ה-URL של המקלט המתארח. תשתמשו בו בקטע הבא.

4. רישום אפליקציה ב-Cast Console

כדי להריץ מקלט אינטרנט מותאם אישית, כפי שנוצר בקודלאב הזה, במכשירי Chromecast, צריך לרשום את האפליקציה. אחרי שתירשמו את האפליקציה, תקבלו מזהה אפליקציה שבו האפליקציה השולחת צריכה להשתמש כדי לבצע קריאות ל-API, למשל כדי להפעיל אפליקציית מקלט.

לוחצים על 'הוספת אפליקציה חדשה'.

בוחרים באפשרות 'Custom Receiver' (מקלט מותאם אישית). זה מה שאנחנו יוצרים.

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

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

לוחצים על 'הוספת מכשיר חדש'.

מזינים את המספר הסידורי שמודפס על גב מכשיר ההעברה (cast) ומעניקים לו שם תיאורי. אפשר למצוא את המספר הסידורי גם על ידי הפעלת Cast של התוכן במסך ב-Chrome כשניגשים אל Google Cast SDK Console.

יחלפו 5 עד 15 דקות עד שהמקלט והמכשיר יהיו מוכנים לבדיקה. לאחר המתנה של 5-15 דקות, עליך להפעיל מחדש את מכשיר ה-Cast.

5. הרצת האפליקציה לדוגמה

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

1. פותחים את הכלי לניהול (CaC) בדפדפן.

2. יש להשתמש במזהה המקבל המוגדר כברירת מחדל ב-CC1AD845 וללחוץ על הלחצן SET APP ID.
3. לוחצים על לחצן ההעברה (Cast) בפינה הימנית העליונה ובוחרים את המכשיר שתומך ב-Google Cast.

4. עוברים לכרטיסייה LOAD MEDIA בחלק העליון.

5. משנים את לחצן הבחירה של סוג הבקשה ל-LOAD.
6. לוחצים על הלחצן SEND REQUEST כדי להפעיל סרטון לדוגמה.
7. הסרטון יתחיל לפעול במכשיר שתומך ב-Google Cast כדי לראות איך נראית פונקציונליות בסיסית של המקלט באמצעות מקלט ברירת המחדל.

6. הכנת פרויקט ההתחלה

אנחנו צריכים להוסיף תמיכה ב-Google Cast לאפליקציה שהורדת. ריכזנו כאן כמה מונחים של Google Cast שבהם נשתמש ב-codelab הזה:

• אפליקציית שליחת הודעות שפועלת במכשיר נייד או במחשב נייד,
• אפליקציית מקלט שפועלת במכשיר Google Cast או Android TV.

עכשיו אתם מוכנים להמשיך לפתח את הפרויקט באמצעות עורך הטקסט המועדף עליכם:

1. בוחרים את הספרייה app-start מההורדה של קוד לדוגמה.
2. פתיחת js/receiver.js ו-index.html

הערה: במהלך העבודה ב-Codelab הזה, http-server אמור לזהות את השינויים שביצעת. אם לא, נסו להפסיק ולהפעיל מחדש את http-server.

עיצוב אפליקציות

אפליקציית המכשיר המקבל מפעילה את סשן ההעברה (cast) וממתינה לקבלת בקשת LOAD (כמו הפקודה להפעלת קטע מדיה) מהשולח.

האפליקציה מורכבת מתצוגה ראשית אחת, שמוגדרת ב-index.html, וקובץ JavaScript אחד שנקרא js/receiver.js ומכיל את כל הלוגיקה שדרושה כדי שהמקלט יפעל.

index.html

קובץ ה-HTML הזה מכיל את כל ממשק המשתמש של אפליקציית המקבל.

receiver.js

הסקריפט הזה מנהל את כל הלוגיקה של אפליקציית המקבל שלנו.

שאלות נפוצות

• מה זה Google Cast?
• איך הופכים למפתחים של Google Cast?

7. שילוב עם CastDebugLogger API

באמצעות Cast Receiver SDK, מפתחים יכולים להשתמש ב-CastDebugLogger API כדי לנפות באגים באפליקציית המקלט בקלות.

אפשר לקרוא פרטים נוספים במדריך לניפוי באגים בהעברה (cast).

אתחול

מוסיפים את הסקריפט הבא לתג <head> של אפליקציית המקלט, מיד אחרי הסקריפט של ה-SDK של מקלט האינטרנט, ב-index.html:

<head>
  ...
  <script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <!-- Cast Debug Logger -->
  <script src="//www.gstatic.com/cast/sdk/libs/devtools/debug_layer/caf_receiver_logger.js"></script>
</head>

ב-js/receiver.js בחלק העליון של הקובץ, מתחת ל-playerManager, מקבלים את המופע CastDebugLogger ומפעילים את ה-logger ב-event listener של READY:

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

// Debug Logger
const castDebugLogger = cast.debug.CastDebugLogger.getInstance();
const LOG_TAG = 'MyAPP.LOG';

// Enable debug logger and show a 'DEBUG MODE' overlay at top left corner.
context.addEventListener(cast.framework.system.EventType.READY, () => {
  if (!castDebugLogger.debugOverlayElement_) {
      castDebugLogger.setEnabled(true);
  }
});

כשיומן ניפוי הבאגים מופעל, מוצגת שכבת-על של DEBUG MODE במכשיר המקבל.

רישום ביומן של אירועי שחקנים

באמצעות CastDebugLogger אפשר לתעד בקלות אירועי נגן שמופעל על ידי Cast Web Receiver SDK, ולהשתמש ברמות שונות של יומן כדי לתעד את נתוני האירוע. ההגדרה של loggerLevelByEvents מקבלת את הערכים cast.framework.events.EventType ו-cast.framework.events.category כדי לציין את האירועים שרוצים לתעד ביומן.

צריך להוסיף את המקטע הבא מתחת ל-event listener של READY כדי לתעד כאשר אירועי CORE של הנגן מופעלים או כאשר משודר שינוי ב-mediaStatus:

...

// Set verbosity level for Core events.
castDebugLogger.loggerLevelByEvents = {
  'cast.framework.events.category.CORE': cast.framework.LoggerLevel.INFO,
  'cast.framework.events.EventType.MEDIA_STATUS': cast.framework.LoggerLevel.DEBUG
};

רישום הודעות ותגים בהתאמה אישית

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

• castDebugLogger.error(custom_tag, message);
• castDebugLogger.warn(custom_tag, message);
• castDebugLogger.info(custom_tag, message);
• castDebugLogger.debug(custom_tag, message);

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

כדי להציג יומנים בפעולה, מוסיפים יומנים למעכב LOAD.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD,
      loadRequestData => {
    // Listed in order from highest to lowest priority.
    castDebugLogger.error(LOG_TAG, 'Test error log');

    castDebugLogger.warn(LOG_TAG, 'Test warn log');

    castDebugLogger.info(LOG_TAG, 'Intercepting LOAD request', loadRequestData);

    castDebugLogger.debug(LOG_TAG, 'Test debug log');

    return loadRequestData;
  }
);

כדי לקבוע אילו הודעות יופיעו בשכבת-העל של ניפוי הבאגים, מגדירים את רמת היומן ב-loggerLevelByTags לכל תג בהתאמה אישית. לדוגמה, הפעלת תג בהתאמה אישית עם רמת יומן cast.framework.LoggerLevel.DEBUG תציג את כל ההודעות שנוספו עם הודעות יומן של שגיאה, אזהרה, מידע ותוצאות ניפוי באגים. דוגמה נוספת: הפעלת תג מותאם אישית ברמה WARNING תציג רק הודעות שגיאה ואזהרה ביומן.

ההגדרה loggerLevelByTags היא אופציונלית. אם לא הגדרתם תג מותאם אישית ברמת היומן שלו, כל הודעות היומן יוצגו בשכבת-העל של ניפוי הבאגים.

מוסיפים את הטקסט הבא מתחת לקריאה ל-loggerLevelByEvents:

...

// Set verbosity level for custom tags.
castDebugLogger.loggerLevelByTags = {
    LOG_TAG: cast.framework.LoggerLevel.DEBUG, // display all levels
};

...

8. שימוש בשכבת-העל של ניפוי הבאגים

יומן ניפוי הבאגים של Cast מספק שכבת-על לניפוי באגים בנמען כדי להציג את הודעות היומן בהתאמה אישית. אפשר להשתמש ב-showDebugLogs כדי להחליף את מצב שכבת-העל של ניפוי הבאגים וב-clearDebugLogs כדי למחוק את הודעות היומן בשכבת-העל.

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

// Enable debug logger and show a 'DEBUG MODE' overlay at top left corner.
context.addEventListener(cast.framework.system.EventType.READY, () => {
  if (!castDebugLogger.debugOverlayElement_) {
      castDebugLogger.setEnabled(true);

      // Show debug overlay.
      castDebugLogger.showDebugLogs(true);

      // Clear log messages on debug overlay.
      castDebugLogger.clearDebugLogs();
  }
});

9. שימוש בכלי Command and Control (CaC)

סקירה כללית

הכלי לניהול (CaC) מתעד את היומנים ומנהל את שכבת-העל של ניפוי הבאגים.

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

התחלת חיבור חדש להפעלת Cast:

1. פותחים את כלי ה-CaC, מגדירים את מזהה האפליקציה של המקבל ולוחצים על הלחצן להפעלת Cast כדי להפעיל Cast של התוכן למקלט.
2. מעבירים אפליקציית שליחה נפרדת לאותו מכשיר עם אותו מזהה אפליקציה של מקלט.
3. טוענים מדיה מהאפליקציה של השולח, והודעות מהיומן יופיעו בכלי.

הצטרפות להפעלת Cast קיימת:

1. אחזור של מזהה הסשן של ההעברה (cast) באמצעות SDK של מקלט או SDK של שולח. בצד של המקבל, מזינים את הקוד הבא כדי לקבל את מזהה הסשן במסוף כלי לניפוי באגים מרחוק של Chrome:

cast.framework.CastReceiverContext.getInstance().getApplicationData().sessionId;

לחלופין, אפשר לקבל את מזהה הסשן משולח אינטרנט מחובר, באמצעות השיטה הבאה:

cast.framework.CastContext.getInstance().getCurrentSession().getSessionId();

2. מזינים את מזהה הסשן בכלי CaC ולוחצים על הלחצן RESUME.
3. לחצן ההעברה (cast) אמור להיות מחובר ולהתחיל להציג הודעות ביומן בכלי.

דברים שכדאי לנסות

בשלב הבא נשתמש בכלי CaC כדי לראות יומנים במכשיר המקבל לדוגמה.

1. פותחים את הכלי ל-CaC.

2. מזינים את מזהה האפליקציה של המקבל לדוגמה ולוחצים על הלחצן SET APP ID.
3. לוחצים על לחצן ההעברה (Cast) בפינה הימנית העליונה ובוחרים את המכשיר שתומך ב-Google Cast כדי לפתוח את המקלט.

4. עוברים לכרטיסייה LOAD MEDIA בחלק העליון.

5. משנים את לחצן הבחירה של סוג הבקשה ל-LOAD.
6. לוחצים על הלחצן SEND REQUEST כדי להפעיל סרטון לדוגמה.

7. עכשיו אמור להופיע במכשיר סרטון לדוגמה. היומנים מהשלבים הקודמים יתחילו להופיע בכרטיסייה 'Log Messages' (הודעות ביומן) בתחתית הכלי.

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

• לוחצים על הכרטיסייה MEDIA INFO או MEDIA STATUS כדי לראות את פרטי המדיה וסטטוס המדיה.
• לוחצים על הלחצן SHOW OVERLAY כדי להציג שכבת-על לניפוי באגים במכשיר הקולט.
• לוחצים על הלחצן CLEAR CACHE AND STOP כדי לטעון מחדש את אפליקציית המכשיר המקבל ולהעביר שוב.

10. מזל טוב

עכשיו אתם יודעים איך להוסיף את Cast Debug Logger לאפליקציית Web Receiver עם תמיכה ב-Cast באמצעות ה-SDK העדכני של Cast Receiver.

פרטים נוספים זמינים במדריכים למפתחים של Cast Debug Logger ושל כלי הבקרה והפיקוד (CaC).