API de cache de avanço e retorno notRestoredReasons

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

Chris Mills

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 e torná-las compatíveis com o bfcache, melhorando o desempenho do site.

Status atual

Testar a API bfcache notRestoredReasons

A partir da versão 109, a API bfcache notRestoredReasons está disponível como um teste de origem no Chromium. Encontre informações atualizadas sobre a programação de lançamentos deste recurso na página de recursos ChromeStatus.com. Consulte o roteiro do Chrome para ver as datas de lançamento das versões.

Para testar a API bfcache notRestoredReasons, inscreva-se no teste de origem e use essa API nos seus experimentos. Consulte Participar de um teste de origem para ver instruções sobre como usar o token após o registro.

Conceitos e uso

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

Antes, os desenvolvedores não tinham como descobrir por que as páginas não usavam o bfcache em 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 sobre todos os frames presentes no documento:

• Detalhes como os frames id e name, para ajudar a identificá-los no HTML.
• Se o uso do bfcache foi bloqueado.

• Motivos pelo qual foram impedidos de usar o bfcache.

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

Exemplos

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

Por exemplo, é possível invocar a seguinte função para retornar todos os objetos PerformanceNavigationTiming presentes na linha do tempo de desempenho e registrar o 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);
  }
}

Para navegações do 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:

{
  blocked: true,
  children: [],
  id: "",
  name: "",
  reasons: [ "Internal Error", "Unload handler" ],
  src: "",
  url: "a.com"
}

As propriedades são as seguintes:

blocked

Um valor booleano que especifica se a página navegada está bloqueada para usar o bfcache (true) ou não (false).

children

É uma matriz de objetos que representam o estado bloqueado de todos os frames incorporados ao frame de nível superior. Cada objeto tem a mesma estrutura do objeto pai. Dessa forma, qualquer número de níveis de frames incorporados pode ser representado dentro do objeto de maneira 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 uma id, o valor será uma string vazia.

name

É uma string que representa o valor do atributo name do frame (por exemplo, <iframe name="bar" src="...">). Se o frame não tiver uma name, o valor será uma string vazia.

reasons

Uma matriz de strings, cada uma representando um motivo pelo qual a página acessada foi bloqueada de usar o bfcache. O bloqueio pode ocorrer por diversos motivos. Consulte a seção Motivos de bloqueio abaixo 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.

url

É uma string que representa o URL da página navegada.

Para objetos PerformanceNavigationTiming que não representam navegações do histórico, a propriedade notRestoredReasons retornará null. Isso é útil para determinar se o bfcache não é relevante para uma navegação específica, em vez de notRestoredReasons não ter suporte, nesse caso, ele retornaria undefined.

Como informar o bloqueio de bfcache em frames de mesma origem

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

Exemplo:

{
  blocked: false,
  children: [
    { url: "a.com", src: "b.a.com", id: "b", name: "b", blocked: false, reasons: [], children: [] },
    { url: "a.com", src: "c.a.com", id: "c", name: "c", blocked: true, reasons: [ "BroadcastChannel" ], children: [] },
    { url: "a.com", src: "d.a.com", id: "d", name: "d", blocked: false, reasons: [], children: [] }
  ],
  id: "",
  name: "",
  reasons: [],
  src: "",
  url:"a.com"
}

Como informar o bloqueio de 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 dados de origem cruzada. Incluímos apenas informações que a página externa já conhece e se a subárvore de origem cruzada bloqueou o bfcache ou não. Não incluímos motivos de bloqueio nem informações sobre os níveis mais baixos da subárvore, mesmo que alguns subníveis sejam da mesma origem.

Exemplo:

{
  blocked: false,
  children: [
    { url: "a.com", src: "c.a.com", id: "c", name: "c", blocked: true, reasons: [ "ScreenReader" ], children: [] },
    /* cross-origin frame */
    { url: "", src: "b.com", id: "d", name: "d", blocked: true, reasons: [], children: [] }
  ],
  id: "",
  name: "",
  reasons: [],
  src: "",
  url:"a.com"
}

Se vários frames de origem cruzada tiverem motivos de bloqueio, selecionaremos aleatoriamente um iframe de origem cruzada e informaremos se ele bloqueou o bfcache ou não. Para o restante dos frames, informamos null para o valor blocked. O objetivo é impedir que pessoas mal-intencionadas deduzam informações sobre o estado do usuário em sites que não controlam, incorporando vários frames de terceiros em uma página e comparando as informações de bloqueio de cada um.

{
  blocked: false,
  children: [
    /* cross-origin frames */
    {url: "", src: "b.com", id: "b", name: "b", blocked: null, reasons: [], children: []},
    {url: "", src: "c.com", id: "c", name: "c", blocked: true, reasons: [], children: []},
    {url: "", src: "d.com", id: "d", name: "d", blocked: null, reasons: [], children: []}
  ]
  id: "",
  name: "",
  reasons: [],
  src: "",
  url:"a.com"
}

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

Motivos de bloqueio

Como dissemos anteriormente, o bloqueio pode ocorrer por diversos motivos. Compilamos uma planilha prática mostrando todas as strings de motivo e explicando o que elas significam.

Vale a pena destacar algumas categorias principais de motivos:

• Circumstantial: refere-se a motivos de bloqueio não diretamente relacionados ao código da página do desenvolvedor. Por exemplo, um componente relacionado falhou, algo deu errado com o processo de carregamento, a página está em um estado temporário que não pode ser armazenado em cache, o bfcache foi desativado devido à memória insuficiente ou um service worker fez algo na página que a desqualifica do armazenamento em cache.
• Extensions: há alguns motivos diferentes para as mensagens relacionadas às extensões. Geralmente, combinamos alguns motivos diferentes no motivo "Extensões". Somos intencionalmente vagos sobre os motivos de bloqueio relacionados a extensões, porque não queremos fornecer muitas informações sobre quais extensões o usuário instalou, quais estão ativas na página, o que está fazendo etc.
• PageSupportNeeded: o código do desenvolvedor está usando um recurso de plataforma da Web que não bloqueia bfcache, mas está em um estado que bloqueia bfcache. Por exemplo, a página atualmente tem um BroadcastChannel com listeners registrados ou uma conexão IndexedDB aberta. Ou a página registrou um gerenciador unload, que atualmente impede que o bfcache seja usado em alguns navegadores.
• SupportPending: o código do desenvolvedor usa um recurso de plataforma da Web que desqualifica a página do bfcache, por exemplo, a API Web Serial, a API Web Authentication, a API File System Access ou a API Media Session. Ou a página está usando Cache-Control: no-store, que, no momento, impede que o bfcache seja usado em alguns navegadores. Essa categoria também é usada para informar a presença de uma ferramenta fora da página que está bloqueando o bfcache, como um leitor de tela ou o gerenciador de senhas do Chrome.

Feedback

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

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 para implementar sua ideia? Tem alguma dúvida ou comentário sobre o modelo de segurança? Registre um problema de especificação no [repositório do GitHub][feedback] correspondente ou adicione suas ideias 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? Registre um bug em new.crbug.com. 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 funciona muito bem para compartilhar repetições rápidas e fáceis.

Mostrar suporte à API

Você planeja usar a API bfcache notRestoredReasons? Seu suporte público ajuda a equipe do Chromium a priorizar recursos e mostra a outros fornecedores de navegador como é fundamental oferecer suporte a eles.

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

Links úteis

• Cache de avanço e retorno
• Explicações públicas
• Bug de rastreamento do Chromium
• Teste de origem da API NotRestoredReason para o cache de avanço e retorno
• Página de recursos do ChromeStatus.com
• Intenção de fazer experimentos