API de cache de avanço e retorno notRestoredReasons

Descubra quais navegações foram bloqueadas de usar o bfcache e por quê.

Chris Mills
Barry Pollard

A propriedade notRestoredReasons, adicionada à classe PerformanceNavigationTiming, informa se os frames presentes no documento foram impedidos de usar o bfcache na navegação e por quê. Os desenvolvedores podem usar essas informações para identificar páginas que precisam de atualizações para serem compatíveis com o bfcache, melhorando assim o desempenho do site.

Status atual

A API notRestoredReasons foi lançada no Chrome 123 e está sendo disponibilizada gradualmente.

Conceitos e uso

Os navegadores modernos oferecem um recurso de otimização para a navegação no histórico chamado cache de avanço e retorno (bfcache). Isso permite uma experiência de carregamento instantâneo quando os usuários voltam a uma página que já visitaram. As páginas podem ser bloqueadas de entrar no bfcache ou serem removidas enquanto estão nele por diferentes motivos, alguns exigidos por uma especificação e outros específicos das implementações do navegador.

Antes, não havia como os desenvolvedores descobrirem por que as páginas deles estavam bloqueadas para usar o bfcache no campo, embora houvesse um teste nas ferramentas para desenvolvedores do Chrome. Para ativar o monitoramento no campo, a classe PerformanceNavigationTiming foi estendida para incluir uma propriedade notRestoredReasons. Isso retorna um objeto que contém informações relacionadas no frame principal e em todos os iframes presentes no documento:

  • Motivos pelos quais eles foram impedidos de usar o bfcache.

  • Detalhes como frame id e name para ajudar a identificar iframes no HTML.

    Isso permite que os desenvolvedores tomem medidas para tornar essas páginas compatíveis com o bfcache, melhorando assim o desempenho do site.

Exemplos

Uma instância de PerformanceNavigationTiming pode ser obtida de recursos como Performance.getEntriesByType() e PerformanceObserver.

Por exemplo, você pode invocar a seguinte função para retornar todos os objetos PerformanceNavigationTiming presentes na linha do tempo de performance e registrar os notRestoredReasons deles:

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

Para navegações de histórico, a propriedade PerformanceNavigationTiming.notRestoredReasons retorna um objeto com a seguinte estrutura, que representa o estado bloqueado do frame de nível superior:

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

As propriedades são as seguintes:

children
Uma matriz de objetos que representam o estado bloqueado de frames de mesma origem incorporados no frame de nível superior. Cada objeto tem a mesma estrutura do objeto pai. Assim, qualquer número de níveis de frames incorporados pode ser representado dentro do objeto de forma recursiva. Se o frame não tiver filhos, a matriz vai estar vazia.
id
Uma string que representa o valor do atributo id do frame (por exemplo, <iframe id="foo" src="...">). Se o frame não tiver id, o valor será null. Para a página de nível superior, é null.
name
Uma string que representa o valor do atributo name do frame (por exemplo, <iframe name="bar" src="...">). Se o frame não tiver name, o valor será uma string vazia. Para a página de nível superior, é null.
reasons
Uma matriz de strings, cada uma representando um motivo pelo qual a página navegada foi impedida de usar o bfcache. O bloqueio pode ocorrer por vários motivos. Consulte a seção Motivos de bloqueio para mais detalhes.
src
Uma string que representa o caminho para a origem do frame (por exemplo, <iframe src="b.html">). Se o frame não tiver um src, o valor será uma string vazia. Para a página de nível superior, é null.
url
Uma string que representa o URL da página/iframe navegados.

Para objetos PerformanceNavigationTiming que não representam navegações de histórico, a propriedade notRestoredReasons vai retornar null.

Observe que notRestoredReasons também retorna null quando não há motivos de bloqueio. Portanto, o fato de ser null não indica que o bfcache foi ou não usado. Para isso, use a propriedade event.persisted.

Informar bloqueio do bfcache em frames de mesma origem

Quando uma página tem frames de mesma origem incorporados, o valor notRestoredReasons retornado contém um objeto dentro da propriedade children que representa o estado bloqueado de cada frame incorporado.

Exemplo:

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

Informar sobre bloqueio do bfcache em frames de origem cruzada

Quando uma página tem frames de origem cruzada incorporados, limitamos a quantidade de informações compartilhadas sobre eles para evitar o vazamento de informações de origem cruzada. Incluímos apenas informações que a página externa já conhece e se a subárvore de origem cruzada bloqueou ou não o bfcache. Não incluímos motivos de bloqueio nem informações sobre níveis mais baixos da subárvore, mesmo que alguns subníveis sejam da mesma origem.

Exemplo:

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

Para todos os iframes de origem cruzada, informamos null para o valor reasons do frame, e o frame de nível superior mostra o motivo "masked". "masked" também pode ser usado por motivos específicos do user agent e nem sempre indica um problema em um iframe.

Consulte a seção Segurança e privacidade na explicação para mais detalhes sobre considerações de segurança e privacidade.

Motivos do bloqueio

Como dissemos antes, há muitos motivos diferentes para o bloqueio ocorrer:

Confira alguns exemplos dos motivos mais comuns para o bfcache não poder ser usado:

  • unload-listener: a página registra um manipulador unload, o que impede o uso do bfcache em determinados navegadores. Consulte Descontinuação do evento "unload" para mais informações.
  • response-cache-control-no-store: a página usa no-store como um valor cache-control.
  • related-active-contents: a página foi aberta de outra página (usando "duplicar guia") que ainda tem uma referência a ela.

Feedback

A equipe do Chromium quer saber sobre suas experiências com a API bfcache notRestoredReasons.

Fale sobre o design da API

Há algo na API que não funciona como você esperava? Ou há métodos ou propriedades ausentes que você precisa implementar sua ideia? Tem uma dúvida ou um comentário sobre o modelo de segurança? Registre um problema de especificação no repositório do GitHub correspondente ou adicione suas ideias a um problema já existente.

Informar um problema com a implementação

Você encontrou um bug na implementação do Chromium? Ou a implementação é diferente da especificação? Registre um bug no nosso Issue Tracker. Inclua o máximo de detalhes possível, instruções simples para reprodução e especifique o componente como UI > Browser > Navigation > BFCache.

Mostrar suporte à API

Você planeja usar a API bfcache notRestoredReasons? Seu apoio público ajuda a equipe do Chromium a priorizar recursos e mostra a outros fornecedores de navegadores a importância de oferecer suporte a eles.

Envie um tweet para @ChromiumDev usando a hashtag #NotRestoredReasons e informe onde e como você está usando.

Links úteis