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. Les pages peuvent être bloquées pour accéder au bfcache ou être supprimées du bfcache pour différentes raisons, certaines requises par une spécification et d'autres spécifiques aux implémentations de navigateur.

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 activer la surveillance sur le terrain, 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:

  • Motifs pour lesquels l'utilisation du bfcache a été bloquée.

  • Informations telles que les cadres id et name, pour identifier les iFrames 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 consigner 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 cadre de premier niveau. 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 de la trame (par exemple, <iframe name="bar" src="...">). Si la trame ne comporte 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 de 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 contient des cadres de même origine intégrés, la valeur notRestoredReasons renvoyée contient un objet dans la propriété children représentant l'état bloqué de chaque cadre 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 si le sous-arbre inter-origine a bloqué bfcache ou non. 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 en matière de sécurité et de 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.

Afficher la compatibilité avec 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 en utilisant le hashtag #NotRestoredReasons et indiquez-nous où et comment vous l'utilisez.

Liens utiles