API de cache de avanço e retorno notRestoredReasons

Encontre 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 bloqueados de usar o bfcache na navegação e por que. Os desenvolvedores podem usar essas informações para identificar páginas que precisam de atualizações para serem compatíveis com o bfcache, melhorando a performance do site.

Status atual

A API notRestoredReasons foi lançada no Chrome 123 e está sendo lançada 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 para uma página que já visitaram. As páginas podem ser bloqueadas para entrar no bfcache ou ser removidas enquanto estão no bfcache por diferentes motivos, alguns exigidos por uma especificação e outros específicos para implementações de navegador.

Antes, os desenvolvedores não tinham como descobrir 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 ampliada para incluir uma propriedade notRestoredReasons. Isso retorna um objeto com informações relacionadas ao frame superior e a todos os iframes presentes no documento:

  • Motivos pelos quais o uso do bfcache foi bloqueado.

  • 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 a performance do site.

Exemplos

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

Por exemplo, é possível invocar a função a seguir para retornar todos os objetos PerformanceNavigationTiming presentes na linha do tempo de performance e registrar o 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 no histórico, a propriedade PerformanceNavigationTiming.notRestoredReasons retorna um objeto com a estrutura a seguir, 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 representa o estado bloqueado de todos os frames de mesma origem incorporados no frame de nível superior. Cada objeto tem a mesma estrutura que o objeto pai. Dessa forma, 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 bloqueada para usar o bfcache. Há muitos motivos diferentes para o bloqueio. 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 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 navegada.

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

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

Relatar o 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 o bloqueio do bfcache em frames de várias origens

Quando uma página tem frames entre origens incorporados, limitamos a quantidade de informações compartilhadas sobre eles para evitar vazamentos de informações entre origens. Só incluímos informações que a página externa já conhece e se o subárvore de origem cruzada bloqueou o bfcache ou não. Não incluímos motivos de bloqueio nem informações sobre níveis mais baixos do subárvore, mesmo que alguns subníveis tenham a 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 um motivo de "masked". O "masked" também pode ser usado por motivos específicos do agente do usuário, portanto, nem sempre indica um problema em um iframe.

Consulte a seção Segurança e privacidade no texto explicativo para mais detalhes sobre as considerações de segurança e privacidade.

Motivos do bloqueio

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

Confira a seguir alguns dos motivos mais comuns para não usar o bfcache:

  • unload-listener: a página registra um gerenciador unload, o que impede o uso do bfcache em determinados navegadores. Consulte Descontinuação do evento de remoção de carga 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 a opção "guia duplicada"), que ainda tem uma referência a essa página.

Feedback

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

Conte sobre o design da API

Há algo na API que não funciona como esperado? Ou há métodos ou propriedades ausentes que você precisa para implementar sua ideia? Tem dúvidas ou comentários sobre o modelo de segurança? Envie um problema de especificação no repositório do GitHub correspondente ou adicione sua opinião a um problema 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? Informe 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. O Glitch é ótimo para compartilhar reprosagens rápidas e fáceis.

Mostrar suporte para a API

Você planeja usar a API notRestoredReasons do bfcache? 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 diga onde e como você está usando.

Links úteis