API notRestoredReasons pour le cache amélioré

Identifiez les navigations qui ont été bloquées à l'aide du bfcache et pourquoi.

Chris Mills
Barry Pollard

La propriété notRestoredReasons, ajoutée à la classe PerformanceNavigationTiming, indique si les cadres présents dans le document ont été empêchés d'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 pour être compatibles avec bfcache, et ainsi améliorer les performances du site.

État actuel

L'API notRestoredReasons est disponible à partir de Chrome 123 et est déployée progressivement.

Concepts et utilisation

Les navigateurs modernes proposent une fonctionnalité d'optimisation de la navigation dans l'historique appelée cache amélioré (bfcache). Cela permet une expérience de chargement instantanée lorsque les utilisateurs reviennent sur une page qu'ils ont déjà consulté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 ne pouvaient pas savoir pourquoi leurs pages étaient bloquées pour utiliser le bfcache sur le terrain, même s'il y avait un test dans les outils pour les développeurs Chrome. Pour permettre la surveillance dans le champ, la classe PerformanceNavigationTiming a été étendue pour inclure une propriété notRestoredReasons. Cela renvoie un objet contenant des informations associées au frame supérieur et à toutes les iFrames présentes 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 bfcache, ce qui améliore 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 dont la structure représente l'état bloqué du frame de niveau supérieur:

{
  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 cadres de même origine intégrés au frame de niveau supérieur. Chaque objet a la même structure que l'objet parent. De cette manière, un nombre illimité de niveaux de cadres intégrés peut être représenté de manière récursive dans l'objet. Si le frame n'a pas d'enfants, le tableau sera vide.
id
Chaîne représentant la valeur de l'attribut id de la trame (par exemple, <iframe id="foo" src="...">). Si la trame ne comporte pas de id, la valeur est 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 est une chaîne vide. Pour la page de premier niveau, il s'agit de null.
reasons
Un tableau de chaînes, chacune représentant un motif pour lequel l'utilisation du bfcache a été bloquée pour la page consultée. Plusieurs raisons peuvent expliquer un blocage. Pour en savoir plus, consultez la section Motifs de blocage.
src
Chaîne représentant le chemin d'accès à la source du frame (par exemple, <iframe src="b.html">). Si le frame ne comporte 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/IFrame consultée.

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 lorsqu'il n'y a pas de motif de blocage. Par conséquent, la valeur null n'indique pas si le bfcache a été utilisé ou non. Pour ce faire, vous devez utiliser la propriété event.persisted.

Signaler le blocage de bfcache 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 de bfcache dans les cadres d'origine croisée

Lorsqu'une page comporte des cadres inter-origines intégrés, nous limitons la quantité d'informations partagées à leur sujet pour éviter toute fuite d'informations inter-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 aucun motif de blocage ni aucune information sur les niveaux inférieurs du sous-arbre (même si certains sous-niveaux sont de 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 toutes les iFrames inter-origines, nous signalons null pour la valeur reasons de la frame, et la frame de premier niveau affiche une raison de "masked". Notez que "masked" peut également être utilisé pour des raisons spécifiques à l'agent utilisateur. Il n'indique donc pas toujours un problème dans une iframe.

Pour en savoir plus sur les considérations liées à la sécurité et à la confidentialité, consultez la section Sécurité et confidentialité de la vidéo explicative.

Motifs de blocage

Comme nous l'avons indiqué précédemment, de nombreuses raisons peuvent expliquer un blocage:

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

  • unload-listener: la page enregistre un gestionnaire unload, ce qui empêche l'utilisation de bfcache dans certains navigateurs. Pour en savoir plus, consultez Abandon de l'événement de déchargement.
  • 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 (à l'aide de l'option "Onglet en double") qui contient toujours une référence à cette page.

Commentaires

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

Parlez-nous de la conception de l'API

L'API ne fonctionne-t-elle pas comme prévu ? Ou manque-t-il des méthodes ou des propriétés dont vous avez besoin pour implémenter 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 trouvé un bug dans l'implémentation de Chromium ? Ou l'implémentation est-elle différente de la spécification ? Signalez un bug dans notre outil de suivi des problèmes. Veillez à inclure autant de détails que possible, des instructions simples pour reproduire le problème et à spécifier le composant en tant que UI > Browser > Navigation > BFCache. Glitch est idéal pour partager des reproductions rapidement et facilement.

Apportez votre soutien à l'API

Comptez-vous utiliser l'API notRestoredReasons bfcache ? Votre soutien public 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