API notRestoredReasons pour le cache amélioré

Découvrez quelles navigations ont été bloquées pour l'utilisation du bfcache et pourquoi.

Chris Mills
Barry Pollard

La propriété notRestoredReasons, ajoutée à la classe PerformanceNavigationTiming, indique si les frames 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 afin d'être compatibles avec la bfcache, ce qui améliore les performances du site.

État actuel

L'API notRestoredReasons est disponible depuis 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 un chargement instantané lorsque les utilisateurs reviennent sur une page qu'ils ont déjà visitée. Les pages peuvent être bloquées pour empêcher leur entrée dans le cache bfcache ou en être supprimées 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 et ne pouvaient pas utiliser le cache amélioré sur le terrain, bien qu'il existait 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. Cette méthode renvoie un objet contenant des informations associées sur le frame supérieur et tous les iFrames présents dans le document :

  • Les raisons pour lesquelles ils n'ont pas pu utiliser le cache bfcache.

  • Des détails tels 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 la 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 timeline 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 avec la structure suivante, qui 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/"
}

Voici les propriétés :

children
 : tableau d'objets représentant l'état bloqué de tous les cadres de même origine intégrés dans le cadre de premier niveau. Chaque objet a la même structure que l'objet parent. De cette façon, n'importe quel nombre de niveaux de cadres intégrés peut être représenté de manière récursive à l'intérieur de 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 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 de la trame (par exemple, <iframe name="bar" src="...">). Si la trame 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 une raison pour laquelle la page consultée n'a pas pu utiliser le cache bf. Le blocage peut être dû à de nombreuses raisons. Pour en savoir plus, consultez la section Raisons du blocage.
src
 : chaîne représentant le chemin d'accès à la source du frame (par exemple, <iframe src="b.html">). Si le frame n'a pas de src, la valeur sera 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/de l'iFrame vers laquelle l'utilisateur a été redirigé.

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 raisons de blocage. Par conséquent, le fait que cette valeur soit null n'indique pas si le cache bfcache a été utilisé ou non. Pour cela, vous devez utiliser la propriété event.persisted.

Signaler le blocage du bfcache dans les frames d'origine identique

Lorsqu'une page contient des frames de même origine intégrés, la valeur notRestoredReasons renvoyée contient un objet dans la propriété children qui représente 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 bfcache dans les frames d'origine croisée

Lorsqu'une page comporte des frames d'origine croisée intégrés, nous limitons la quantité d'informations partagées à leur sujet pour éviter toute fuite d'informations d'origine croisée. Nous n'incluons que les informations que la page externe connaît déjà et si le sous-arbre d'origine croisée a bloqué ou non le cache arrière/avant. Nous n'incluons aucune raison 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 tous les iframes d'origine croisée, nous signalons null pour la valeur reasons du frame, et le frame de premier niveau affiche le motif "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 un iFrame.

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

Motifs de blocage

Comme nous l'avons vu précédemment, le blocage peut être dû à de nombreuses raisons :

Voici quelques exemples de raisons les plus courantes pour lesquelles le cache 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 "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 (à l'aide de l'option "Dupliquer l'onglet") qui comporte toujours une référence à cette page.

Commentaires

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

Parlez-nous de la conception de l'API

Y a-t-il quelque chose dans l'API qui ne fonctionne pas comme prévu ? Ou bien 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 lié aux spécifications 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 ? 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 comme UI > Browser > Navigation > BFCache.

Soutenir l'API

Comptez-vous utiliser l'API bfcache notRestoredReasons ? 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 pour nous indiquer où et comment vous l'utilisez.

Liens utiles