ReportingObserver: חשוב לדעת את תקינות הקוד

פיליפ וולטון
פיליפ וולטון
Twitter GitHub דף הבית

אמ;לק

יש צופה חדש בעיר! ReportingObserver הוא API חדש שמאפשר לדעת מתי באתר שלכם נעשה שימוש ב-API שהוצא משימוש או כשהוא נתקל בהתערבות בדפדפן:

const observer = new ReportingObserver(
  (reports, observer) => {
    for (const report of reports) {
      console.log(report.type, report.url, report.body);
    }
  },
  {buffered: true}
);

observer.observe();

אפשר להשתמש בקריאה החוזרת (callback) כדי לשלוח דוחות לספק קצה עורפי או לספק ניתוח נתונים לניתוח נוסף.

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

מבוא

לפני זמן מה, כתבתי פוסט בבלוג ("Obating your web app") כי מעניין אותי לדעת כמה ממשקי API יש לצורך מעקב אחרי ה"דברים" שמתרחשים באפליקציית אינטרנט. לדוגמה, יש ממשקי API שיכולים לקלוט מידע על ה-DOM: ResizeObserver, IntersectionObserver, MutationObserver. קיימים ממשקי API לתיעוד מדידות של ביצועים: PerformanceObserver. אפילו ממשקי API אחרים כמו window.onerror ו-window.onunhandledrejection מודיעים לנו כשמשהו משתבש.

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

אזהרות במסוף כלי הפיתוח לגבי הוצאה משימוש והתערבויות.
אזהרות ביוזמת הדפדפן במסוף כלי הפיתוח.

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

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

ממשק ה-API

ה-API שונה מממשקי ה-API האחרים מסוג "observer", כמו IntersectionObserver ו-ResizeObserver. אתם מתקשרים למספר הזה, והוא מוסר לכם מידע. המידע שמתקבל בקריאה החוזרת הוא רשימה של בעיות שהדף גרם:

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    // → report.type === 'deprecation'
    // → report.url === 'https://reporting-observer-api-demo.glitch.me'
    // → report.body.id === 'XMLHttpRequestSynchronousInNonWorkerOutsideBeforeUnload'
    // → report.body.message === 'Synchronous XMLHttpRequest is deprecated...'
    // → report.body.lineNumber === 11
    // → report.body.columnNumber === 22
    // → report.body.sourceFile === 'https://reporting-observer-api-demo.glitch.me'
    // → report.body.anticipatedRemoval === <JS_DATE_STR> or null
  }
});

observer.observe();

דוחות מסוננים

אפשר לסנן מראש דוחות כדי לצפות בסוגים מסוימים של דוחות בלבד:

const observer = new ReportingObserver((reports, observer) => {
  ...
}, {types: ['deprecation']});

דוחות במאגר

האפשרות buffered: true מועילה במיוחד כשרוצים לראות את הדוחות שנוצרו לפני שהצופה נוצר:

const observer = new ReportingObserver((reports, observer) => {
  ...
}, {types: ['intervention'], buffered: true});

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

הפסקת הצפייה

כן. יש לו שיטה disconnect:

observer.disconnect(); // Stop the observer from collecting reports.

דוגמאות

דוגמה – דיווח על התערבות בדפדפן לספק ניתוח נתונים:

const observer = new ReportingObserver(
  (reports, observer) => {
    for (const report of reports) {
      sendReportToAnalytics(JSON.stringify(report.body));
    }
  },
  {types: ['intervention'], buffered: true}
);

observer.observe();

דוגמה - קבלת הודעה כאשר ממשקי API יוסרו:

const observer = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    if (report.type === 'deprecation') {
      sendToBackend(`Using a deprecated API in ${report.body.sourceFile} which will be
                     removed on ${report.body.anticipatedRemoval}. Info: ${report.body.message}`);
    }
  }
});

observer.observe();

סיכום

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

עבודה עתידית

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

אני גם נלהב מהכלים שמשלבים את ReportingObserver בתהליכי העבודה שלהם. הכלי Lighthouse הוא דוגמה לכלי שכבר מסמן את ההוצאה משימוש של הדפדפנים כשמריצים את הביקורת 'הימנעות מממשקי API שהוצאו משימוש':

הביקורת של Lighthouse לשימוש בממשקי API שהוצאו משימוש יכולה להשתמש ב-ReportingObserver.
בדיקת Lighthouse לשימוש בממשקי API שהוצאו משימוש יכולה להשתמש ב-ReportingObserver.

ב-Lighthouse משתמשים כרגע בפרוטוקול DevTools כדי להעתיק הודעות במסוף ולדווח על הבעיות האלה למפתחים. במקום זאת, ייתכן שתרצו לעבור אל ReportingObserver כדי לראות את דוחות ההוצאה משימוש המובנים היטב ואת המטא-נתונים הנוספים, כמו תאריך anticipatedRemoval.

מקורות מידע נוספים: