API notRestoredReasons pour le cache amélioré

Découvrez quelles navigations ont été bloquées et pourquoi l'utilisation du cache amélioré a été bloquée.

Chris Mills
Barry Pollard

La propriété notRestoredReasons, ajoutée à la classe PerformanceNavigationTiming, indique si les frames présents dans le document ont été bloqués ou non à utiliser le bfcache lors de la navigation, et pourquoi. Les développeurs peuvent utiliser ces informations pour identifier les pages qui doivent être mises à jour afin de les rendre compatibles avec le cache amélioré, et ainsi améliorer les performances du site.

État actuel

L'API notRestoredReasons a été expédiée depuis Chrome 123 et est déployée progressivement.

Concepts et utilisation

Les navigateurs récents offrent une fonctionnalité d'optimisation de la navigation dans l'historique appelée cache amélioré (bfcache). Cela permet un chargement instantané lorsque les utilisateurs reviennent sur une page qu'ils ont déjà visitée. Certaines pages peuvent être bloquées dans le cache amélioré ou être évincées lorsqu'elles sont en cache pour différentes raisons. Certaines sont requises par une spécification ou sont spécifiques aux implémentations des navigateurs.

Auparavant, les développeurs n'avaient aucun moyen de savoir pourquoi leurs pages n'étaient pas autorisées à utiliser le cache amélioré sur le terrain, même s'il existait un test dans les outils de développement Chrome. Pour activer la surveillance dans le champ, la classe PerformanceNavigationTiming a été étendue pour inclure une propriété notRestoredReasons. Cette opération renvoie un objet contenant des informations associées sur le cadre supérieur et tous les iFrames présents dans le document:

  • Raisons pour lesquelles l'utilisation du cache amélioré a été bloquée.

  • Des détails tels que les cadres id et name, pour faciliter l'identification des cadres iFrame dans le code HTML

    Les développeurs peuvent ainsi prendre des mesures pour rendre ces pages compatibles avec le cache amélioré, et ainsi améliorer les performances du site.

Exemples

Une instance PerformanceNavigationTiming peut être obtenue à partir de fonctionnalités telles que Performance.getEntriesByType() et PerformanceObserver.

Par exemple, vous pouvez appeler la fonction suivante pour renvoyer tous les objets PerformanceNavigationTiming présents dans la chronologie des performances et enregistrer leur 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);
  }
}

Pour les navigations dans l'historique, la propriété PerformanceNavigationTiming.notRestoredReasons renvoie un objet avec la structure suivante, qui représente l'état bloqué du frame de premier niveau:

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

Les propriétés sont les suivantes:

children
Tableau d'objets représentant l'état bloqué de tous les frames de même origine intégrés au frame de niveau supérieur. Chaque objet possède la même structure que l'objet parent. Ainsi, n'importe quel nombre de niveaux de frames intégrés peut être représenté à l'intérieur de l'objet de manière récursive. Si le frame n'a pas d'enfants, le tableau sera vide.
id
Chaîne représentant la valeur de l'attribut id du frame (par exemple, <iframe id="foo" src="...">). Si le frame n'a pas de id, la valeur sera null. Pour la page de premier niveau, il s'agit de null.
name
Chaîne représentant la valeur de l'attribut name du frame (par exemple, <iframe name="bar" src="...">). Si le frame n'a pas de name, la valeur sera une chaîne vide. Pour la page de premier niveau, il s'agit de null.
reasons
Tableau de chaînes représentant chacune la raison pour laquelle la page consultée a été bloquée pour utiliser le cache amélioré. Le blocage peut s'effectuer pour de nombreuses raisons. Pour en savoir plus, consultez la section Motifs de blocage.
src
Chaîne représentant le chemin d'accès à la source de la trame (par exemple, <iframe src="b.html">). Si la trame n'a pas de src, la valeur est une chaîne vide. Pour la page de premier niveau, il s'agit de null.
url
Chaîne représentant l'URL de la page consultée ou de l'iFrame.

Pour les objets PerformanceNavigationTiming qui ne représentent pas les navigations dans l'historique, la propriété notRestoredReasons renvoie null.

Notez que notRestoredReasons renvoie également null en l'absence de motifs bloquants. La valeur null ne signifie donc pas que le cache amélioré a été utilisé ou non. Pour ce faire, vous devez utiliser la propriété event.persisted.

Signaler le blocage du cache amélioré dans les frames de même origine

Lorsqu'une page intègre des frames de même origine, la valeur notRestoredReasons renvoyée contient un objet dans la propriété children représentant l'état bloqué de chaque frame intégré.

Exemple :

{
  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"
}

Signaler le blocage du cache amélioré dans les frames multi-origines

Lorsqu'une page contient des frames multi-origines intégrés, nous limitons la quantité d'informations partagées les concernant afin d'éviter la fuite d'informations multi-origines. Nous n'incluons que les informations que la page externe connaît déjà, et nous tenons compte du fait que la sous-arborescence multi-origine a bloqué ou non le cache amélioré. Nous n'incluons pas de motif bloquant ni d'informations sur les niveaux inférieurs de la sous-arborescence (même si certains sous-niveaux ont la même origine).

Exemple :

{
  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"
}

Pour tous les iFrames multi-origines, nous indiquons null pour la valeur reasons du frame, et le frame de premier niveau affiche la raison "masked". Notez que "masked" peut également être utilisé pour des raisons spécifiques aux user-agents. Il n'est donc pas toujours possible d'indiquer un problème dans un iFrame.

Pour en savoir plus sur les considérations relatives à la sécurité et à la confidentialité, consultez la section Sécurité et confidentialité dans l'explication.

Motifs de blocage

Comme nous l'avons dit plus tôt, le blocage peut avoir plusieurs causes:

Voici quelques-unes des raisons les plus courantes pour lesquelles le cache amélioré ne peut pas être utilisé:

  • unload-listener: la page enregistre un gestionnaire unload, qui empêche l'utilisation du cache amélioré dans certains navigateurs. Pour en savoir plus, consultez la section Abandon de l'événement "unload".
  • response-cache-control-no-store: la page utilise no-store comme valeur cache-control.
  • related-active-contents: la page a été ouverte à partir d'une autre page (soit à l'aide d'un onglet en double), qui contient toujours une référence à cette page.

Commentaires

L'équipe Chromium souhaite connaître votre avis sur votre expérience avec l'API bfcache notRestoredReasons.

Présentez-nous la conception de l'API

Y a-t-il un aspect de l'API qui ne fonctionne pas comme prévu ? Ou s'il manque des méthodes ou des propriétés dont vous avez besoin pour mettre en œuvre votre idée ? Vous avez une question ou un commentaire sur le modèle de sécurité ? Signalez un problème de spécification dans le dépôt GitHub correspondant ou ajoutez vos commentaires à un problème existant.

Signaler un problème d'implémentation

Avez-vous détecté un bug dans l'implémentation de Chromium ? Ou l'implémentation est-elle différente des spécifications ? Signalez un bug dans Issue Tracker. Veillez à inclure autant de détails que possible, des instructions simples pour reproduire le composant et à spécifier le composant en tant que UI > Browser > Navigation > BFCache. Glitch est idéal pour partager des répétitions rapidement et facilement.

Apportez votre soutien à l'API

Prévoyez-vous d'utiliser l'API bfcache notRestoredReasons ? Votre assistance publique aide l'équipe Chromium à hiérarchiser les fonctionnalités et montre aux autres fournisseurs de navigateurs à quel point il est essentiel de les prendre en charge.

Envoyez un tweet à @ChromiumDev avec le hashtag #NotRestoredReasons, et indiquez-nous où et comment vous l'utilisez.

Liens utiles