ה-API של 'מטמון לדף הקודם/הבא' notRestoredReasons ב-API

לבדוק אילו ניווטים נחסמו משימוש ב-bfcache ומהן הסיבות לכך.

Chris Mills
Barry Pollard

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

הסטטוס הנוכחי

ממשק ה-API של notRestoredReasons הושק ב-Chrome 123 והוא יפורסם בהדרגה.

מושגים ושימוש

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

בעבר, למפתחים לא הייתה אפשרות לברר למה הדפים שלהם נחסמו משימוש ב-bfcache בשטח, אבל היה בדיקה בכלים למפתחים של Chrome. כדי לאפשר מעקב בשטח, הכיתה PerformanceNavigationTiming הורחבה כך שתכלול את הנכס notRestoredReasons. הפונקציה מחזירה אובייקט שמכיל מידע קשור לגבי המסגרת העליונה וכל תגי ה-iframe שקיימים במסמך:

  • הסיבות לכך שהם נחסמו משימוש ב-bfcache.

  • פרטים כמו המסגרת id ו-name, כדי לזהות iframes ב-HTML.

    כך המפתחים יכולים לבצע פעולות כדי שהדפים האלה יהיו תואמים ל-bfcache, וכך לשפר את ביצועי האתר.

דוגמאות

אפשר לקבל מופע של PerformanceNavigationTiming מתכונות כמו Performance.getEntriesByType() ו-PerformanceObserver.

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

function returnNRR() {
  const navEntries = performance.getEntriesByType("navigation");
  for (let i = 0; i < navEntries.length; i++) {
    console.log(`Navigation entry ${i}`);
    let navEntry = navEntries[i];
    console.log(navEntry.notRestoredReasons);
  }
}

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

{
  children: [],
  id: null,
  name: null,
  reasons: [
    {"reason", "unload-listener"}
  ],
  src: null,
  url: "https://www.example.com/page/"
}

המאפיינים הם:

children
מערך של אובייקטים שמייצגים את הסטטוס 'חסום' של כל התמונות הסטטיות מאותו מקור שמוטמעות בתמונה ברמה העליונה. לכל אובייקט יש את אותו מבנה כמו של אובייקט ההורה – כך אפשר לייצג בתוך האובייקט כל מספר של רמות של פריימים מוטמעים באופן רספונסיבי. אם למסגרת אין צאצאים, המערך יהיה ריק.
id
מחרוזת שמייצגת את ערך המאפיין id של המסגרת (לדוגמה, <iframe id="foo" src="...">). אם למסגרת אין id, הערך יהיה null. בדף ברמה העליונה, הערך הוא null.
name
מחרוזת שמייצגת את ערך המאפיין name של הפריים (לדוגמה <iframe name="bar" src="...">). אם אין לפריים name, הערך יהיה מחרוזת ריקה. בדף ברמה העליונה, הערך הוא null.
reasons
מערך של מחרוזות, שכל אחת מהן מייצגת סיבה לכך שהדף שאליו מנווטים נחסם משימוש ב-bfcache. יש הרבה סיבות אפשריות לחסימה. פרטים נוספים זמינים בקטע סיבות לחסימה.
src
מחרוזת שמייצגת את הנתיב למקור של המסגרת (לדוגמה <iframe src="b.html">). אם אין למסגרת src, הערך יהיה מחרוזת ריקה. בדף ברמה העליונה, הערך הוא null.
url
מחרוזת שמייצגת את כתובת ה-URL של הדף או ה-iframe שאליו בוצעה הניווט.

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

הערה: הפונקציה notRestoredReasons מחזירה את הערך null גם אם אין סיבות לחסימה, כך שהערך null לא מציין אם נעשה שימוש ב-bfcache או לא. לשם כך, צריך להשתמש במאפיין event.persisted.

דיווח על חסימה של bfcache בפריימים מאותו מקור

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

לדוגמה:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example.com/"
    },
    {
      children: [],
      id: "iframe-id2",
      name: "iframe-name2",
      reasons: [
        {"reason": "unload-listener"}
      ],
      src: "./unload-examples.html",
      url: "https://www.example.com/unload-examples.html"
    },
  ],
  id: null,
  name: null,
  reasons: [],
  src: null,
  url:"https://www.example.com"
}

דיווח על חסימה של bfcache במסגרות חוצות-דומיינים

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

לדוגמה:

{
  children: [
    {
      children: [],
      id: "iframe-id",
      name: "iframe-name",
      reasons: [],
      src: "./index.html",
      url: "https://www.example2.com/"
    }
  ],
  id: null,
  name: null,
  reasons: [
        {"reason": "masked"}
  ],
  src: null,
  url:"https://www.example.com"
}

לכל iframes שמקורם במקור אחר, אנחנו מדווחים על הערך null עבור הערך reasons של הפריים, והפריים ברמה העליונה יציג את הסיבה "masked". הערה: יכול להיות ש-"masked" ישמש גם מסיבות ספציפיות לסוכנות משתמשים, ולכן לא תמיד הוא מציין בעיה ב-iframe.

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

סיבות לחסימה

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

ריכזנו כאן דוגמאות לכמה מהסיבות הנפוצות ביותר לכך שאי אפשר להשתמש במטמון לדף הקודם/הבא:

  • unload-listener: הדף רושם handler של unload, שמונע שימוש במטמון לדף הקודם/הבא בדפדפנים מסוימים. מידע נוסף זמין במאמר הוצאה משימוש של אירוע הסרת הנתונים שנטענו.
  • response-cache-control-no-store: הדף משתמש ב-no-store כערך cache-control.
  • related-active-contents: הדף נפתח מדף אחר (באמצעות 'כרטיסייה כפולה') שעדיין יש בו הפניה לדף הזה.

משוב

צוות Chromium רוצה לשמוע על חוויית השימוש שלך ב-API notRestoredReasons של המטמון לדף הקודם/הבא.

תיאור של עיצוב ה-API

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

דיווח על בעיה בהטמעה

מצאתם באג בהטמעה של Chromium? או שההטמעה שונה מהמפרט? דווחו על באג בכלי למעקב אחר בעיות. חשוב לכלול כמה שיותר פרטים, הוראות פשוטות לשחזור הבעיה וגם לציין את הרכיב כ-UI > Browser > Navigation > BFCache. Glitch הוא כלי מצוין לשיתוף שחזור מהיר וקל של באגים.

תמיכה ב-API

אתם מתכננים להשתמש ב-API notRestoredReasons של bfcache? התמיכה הציבורית שלכם עוזרת לצוות Chromium לתעדף תכונות, ומראה לספקי דפדפנים אחרים כמה חשובה התמיכה בהן.

אפשר לשלוח ציוץ אל @ChromiumDev באמצעות ההאשטאג #NotRestoredReasons ולספר לנו איפה ואיך אתם משתמשים בו.

קישורים שימושיים