notRestoredReasons API voor Back-Forward Cache

Ontdek welke navigaties zijn geblokkeerd voor het gebruik van de bfcache en waarom.

De property notRestoredReasons, toegevoegd aan de klasse PerformanceNavigationTiming, rapporteert informatie over of frames in het document zijn geblokkeerd voor het gebruik van de bfcache bij navigatie en waarom. Ontwikkelaars kunnen deze informatie gebruiken om pagina's te identificeren die moeten worden geüpdatet om ze compatibel te maken met bfcache, waardoor de siteprestaties worden verbeterd.

Huidige status

De notRestoredReasons API is beschikbaar vanaf Chrome 123 en wordt geleidelijk uitgerold.

Concepten en gebruik

Moderne browsers bieden een optimalisatiefunctie voor geschiedenisnavigatie, de Back-Forward Cache (bfcache). Hierdoor wordt een pagina meteen geladen als gebruikers teruggaan naar een pagina die ze al hebben bezocht. Pagina's kunnen om verschillende redenen worden geblokkeerd voor toegang tot de bfcache of worden verwijderd terwijl ze in de bfcache staan. Sommige redenen zijn vereist door een specificatie en sommige zijn specifiek voor browserimplementaties.

Eerder konden ontwikkelaars niet achterhalen waarom hun pagina's werden geblokkeerd voor het gebruik van de bfcache in het veld, hoewel er een test in de tools voor ontwikkelaars in Chrome was. De klasse PerformanceNavigationTiming is uitgebreid met een property notRestoredReasons om monitoring in het veld mogelijk te maken. Dit retourneert een object met gerelateerde informatie over het bovenste frame en alle iframes die in het document aanwezig zijn:

  • Redenen waarom ze zijn geblokkeerd voor het gebruik van de bfcache.
  • Details zoals frame id en name, om iframes in de HTML te identificeren.

    Zo kunnen ontwikkelaars actie ondernemen om die pagina's compatibel te maken met bfcache en zo de siteprestaties te verbeteren.

Voorbeelden

Een PerformanceNavigationTiming-instantie kan worden verkregen via functies zoals Performance.getEntriesByType() en PerformanceObserver.

Je kunt bijvoorbeeld de volgende functie aanroepen om alle PerformanceNavigationTiming-objecten in de prestatietijdlijn te retourneren en hun notRestoredReasons te registreren:

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);
  }
}

Voor geschiedenisnavigaties retourneert de eigenschap PerformanceNavigationTiming.notRestoredReasons een object met de volgende structuur, die de geblokkeerde status van het frame op het hoogste niveau vertegenwoordigt:

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

De property's zijn:

children
Een matrix van objecten die de geblokkeerde status vertegenwoordigen van frames met dezelfde oorsprong die zijn ingesloten in het frame op het hoogste niveau. Elk object heeft dezelfde structuur als het bovenliggende object. Op deze manier kan een onbeperkt aantal niveaus van ingesloten frames recursief in het object worden weergegeven. Als het frame geen onderliggende elementen heeft, is de matrix leeg.
id
Een tekenreeks die de kenmerkwaarde id van het frame vertegenwoordigt (bijvoorbeeld <iframe id="foo" src="...">). Als het frame geen id heeft, is de waarde null. Voor de pagina op het hoogste niveau is dit null.
name
Een tekenreeks die de kenmerkwaarde name van het frame vertegenwoordigt (bijvoorbeeld <iframe name="bar" src="...">). Als het frame geen name heeft, is de waarde een lege tekenreeks. Voor de pagina op het hoogste niveau is dit null.
reasons
Een matrix van tekenreeksen die elk een reden vertegenwoordigen waarom de genavigeerde pagina is geblokkeerd voor het gebruik van de bfcache. Er zijn veel verschillende redenen waarom blokkering kan plaatsvinden. Ga naar het gedeelte Redenen voor blokkering voor meer informatie.
src
Een tekenreeks die het pad naar de bron van het frame vertegenwoordigt (bijvoorbeeld <iframe src="b.html">). Als het frame geen src heeft, is de waarde een lege tekenreeks. Voor de pagina op het hoogste niveau is dit null.
url
Een tekenreeks die de URL van de genavigeerde pagina/het genavigeerde iframe vertegenwoordigt.

Voor PerformanceNavigationTiming-objecten die geen geschiedenisnavigaties vertegenwoordigen, retourneert de property notRestoredReasons de waarde null.

notRestoredReasons retourneert ook null als er geen blokkeringsredenen zijn. Als dit null is, is dit dus geen indicator dat de bfcache wel of niet is gebruikt. Hiervoor moet je de property event.persisted gebruiken.

Bfcache-blokkering melden in frames met dezelfde oorsprong

Als een pagina frames van dezelfde oorsprong bevat, bevat de geretourneerde notRestoredReasons-waarde een object in de property children die de geblokkeerde status van elk ingesloten frame vertegenwoordigt.

Voorbeeld:

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

Blokkering van Back-Forward Cache in cross-origin frames melden

Als een pagina cross-origin frames bevat, beperken we de hoeveelheid informatie die erover wordt gedeeld om te voorkomen dat cross-origin informatie wordt gelekt. We nemen alleen informatie op die de buitenste pagina al weet en of de cross-origin-substructuur bfcache heeft geblokkeerd of niet. We nemen geen blokkeringsredenen of informatie over lagere niveaus van de substructuur op (zelfs als sommige subniveaus dezelfde oorsprong hebben).

Voorbeeld:

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

Voor alle cross-origin iframes rapporteren we null voor de waarde reasons voor het frame. Het frame op het hoogste niveau toont de reden "masked". "masked" kan ook worden gebruikt voor redenen die specifiek zijn voor de user-agent. Dit geeft dus niet altijd een probleem in een iframe aan.

Ga naar het gedeelte Beveiliging en privacy in de uitleg voor meer informatie over beveiligings- en privacyoverwegingen.

Redenen voor blokkering

Zoals we eerder hebben gezegd, zijn er veel verschillende redenen waarom blokkering kan plaatsvinden:

Hieronder volgen voorbeelden van enkele van de meest voorkomende redenen waarom de bfcache niet kan worden gebruikt:

  • unload-listener: De pagina registreert een unload-handler, waardoor het gebruik van bfcache in bepaalde browsers wordt voorkomen. Chrome geeft deze reden niet meer door vanaf Chrome 155, behalve als sites zich opnieuw hebben aangemeld voor unload-gebeurtenissen. Ga naar Beëindiging van de gebeurtenis unload voor meer informatie.
  • response-cache-control-no-store: De pagina gebruikt no-store als cache-control-waarde.
  • related-active-contents: De pagina is geopend vanaf een andere pagina (met Tabblad dupliceren) die nog steeds een verwijzing naar deze pagina bevat.

Feedback

Het Chromium-team wil graag weten wat je ervaringen zijn met de bfcache notRestoredReasons API.

Vertel ons over het API-ontwerp

Werkt de API niet zoals je verwacht? Of ontbreken er methoden of eigenschappen die je nodig hebt om je idee te implementeren? Heeft u een vraag of opmerking over het beveiligingsmodel? Dien een specificatieprobleem in bij de bijbehorende GitHub-repo of voeg je gedachten toe aan een bestaand probleem.

Een probleem met de implementatie melden

Heb je een bug gevonden in de implementatie van Chromium? Of is de implementatie anders dan de specificatie? Meld een bug in onze Issue Tracker. Zorg dat je zo veel mogelijk details en instructies voor reproductie opneemt en de component specificeert als UI > Browser > Navigation > BFCache.

Ondersteuning voor de API tonen

Bent u van plan de bfcache notRestoredReasons API te gebruiken? Met je openbare steun help je het Chromium-team om prioriteit te geven aan functies en laat je andere browserleveranciers zien hoe belangrijk het is om deze te ondersteunen.

Stuur een tweet naar @ChromiumDev met de hashtag #NotRestoredReasons en laat ons weten waar en hoe je de API gebruikt.

Nuttige links