API de notRestoredReasons de la memoria caché atrás/adelante

Descubre qué navegaciones se bloquearon para usar la bfcache y por qué.

Chris Mills
Barry Pollard

La propiedad notRestoredReasons, que se agregó a la clase PerformanceNavigationTiming, informa si se bloqueó el uso de bfcache en la navegación de los marcos presentes en el documento y por qué. Los desarrolladores pueden usar esta información para identificar páginas que necesitan actualizaciones para que sean compatibles con la bfcache, lo que mejora el rendimiento del sitio.

Estado actual

La API de notRestoredReasons se envió desde Chrome 123 y se está implementando de forma gradual.

Conceptos y uso

Los navegadores modernos proporcionan una función de optimización para la navegación por el historial llamada memoria caché atrás/adelante (bfcache). Esto permite una experiencia de carga instantánea cuando los usuarios regresan a una página que ya visitaron. Es posible que se bloquee el ingreso de las páginas a la bfcache o que se expulsan mientras están en la bfcache por diferentes motivos, algunos son obligatorios de una especificación y otros específicos para las implementaciones del navegador.

Antes, no había forma de que los desarrolladores supieran por qué se impedía que sus páginas usaran la bfcache en campo, aunque había una prueba en las herramientas para desarrolladores de Chrome. Para habilitar la supervisión en el campo, se extendió la clase PerformanceNavigationTiming para incluir una propiedad notRestoredReasons. Se mostrará un objeto que contiene información relacionada en el marco superior y todos los iframes presentes en el documento:

  • Razones por las que se bloqueó el uso de bfcache.

  • Detalles como los marcos id y name, para ayudar a identificar iframes en el HTML

    Esto permite que los desarrolladores tomen medidas para que esas páginas sean compatibles con la bfcache, lo que mejora el rendimiento del sitio.

Ejemplos

Se puede obtener una instancia de PerformanceNavigationTiming de funciones como Performance.getEntriesByType() y PerformanceObserver.

Por ejemplo, puedes invocar la siguiente función para mostrar todos los objetos PerformanceNavigationTiming presentes en el cronograma de rendimiento y registrar su 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 las navegaciones del historial, la propiedad PerformanceNavigationTiming.notRestoredReasons muestra un objeto con la siguiente estructura, que representa el estado bloqueado del marco de nivel superior:

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

Las propiedades son las siguientes:

children
Es un array de objetos que representa el estado bloqueado de cualquier fotograma del mismo origen incorporado en el fotograma de nivel superior. Cada objeto tiene la misma estructura que el objeto superior; de esta manera, se puede representar cualquier cantidad de niveles de marcos incorporados dentro del objeto de manera recurrente. Si el marco no tiene elementos secundarios, el array estará vacío.
id
Es una cadena que representa el valor del atributo id del marco (por ejemplo, <iframe id="foo" src="...">). Si el marco no tiene id, el valor será null. Para la página de nivel superior, es null.
name
Es una cadena que representa el valor del atributo name del marco (por ejemplo, <iframe name="bar" src="...">). Si el marco no tiene name, el valor será una cadena vacía. Para la página de nivel superior, es null.
reasons
Es un array de cadenas que representan un motivo por el que la página navegada no puede usar la bfcache. Existen muchos motivos diferentes por los que se puede producir el bloqueo. Consulta la sección Motivos de bloqueo para obtener más información.
src
Es una cadena que representa la ruta de acceso al origen del marco (por ejemplo, <iframe src="b.html">). Si el marco no tiene src, el valor será una cadena vacía. Para la página de nivel superior, es null.
url
Es una cadena que representa la URL de la página o del iframe por el que se navega.

Para los objetos PerformanceNavigationTiming que no representan navegaciones del historial, la propiedad notRestoredReasons mostrará null.

Ten en cuenta que notRestoredReasons también muestra null cuando no hay motivos de bloqueo, por lo que ser null no es un indicador de que se usó o no se usó la bfcache. Para eso, debes usar la propiedad event.persisted.

Informa el bloqueo de bfcache en fotogramas del mismo origen

Cuando una página tiene marcos del mismo origen incorporados, el valor notRestoredReasons que se muestra contendrá un objeto dentro de la propiedad children que representa el estado bloqueado de cada marco incorporado.

Por ejemplo:

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

Informa el bloqueo de bfcache en fotogramas de origen cruzado

Cuando una página tiene marcos de origen cruzado incorporados, limitamos la cantidad de información que se comparte sobre ellas para evitar que se filtre esa información. Solo incluimos información que la página externa ya conoce y si el subárbol de origen cruzado bloqueó la bfcache. No incluimos ningún motivo de bloqueo ni información sobre los niveles inferiores del subárbol (incluso si algunos subniveles tienen el mismo origen).

Por ejemplo:

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

En el caso de todos los iframes de origen cruzado, informamos null para el valor reasons del fotograma, y el marco de nivel superior mostrará un motivo de "masked". Ten en cuenta que "masked" también se puede usar por motivos específicos de usuarios-agentes, por lo que es posible que no siempre indique un problema en un iframe.

Consulta la sección Seguridad y privacidad en la explicación para obtener más detalles sobre las consideraciones de seguridad y privacidad.

Motivos del bloqueo

Como se mencionó anteriormente, existen muchos motivos diferentes por los que se puede producir el bloqueo:

Los siguientes son ejemplos de algunas de las razones más comunes por las que no se puede usar la bfcache:

  • unload-listener: La página registra un controlador unload, que evita el uso de bfcache en ciertos navegadores. Consulta Da de baja el evento de descarga para obtener más información.
  • response-cache-control-no-store: La página usa no-store como un valor cache-control.
  • related-active-contents: La página se abrió desde otra página (ya sea mediante una "pestaña duplicada") que aún tiene una referencia a esta página.

Comentarios

El equipo de Chromium quiere conocer tu experiencia con la API de notRestoredReasons de bfcache.

Cuéntanos sobre el diseño de la API

¿Algo en la API no funciona como esperabas? ¿O faltan métodos o propiedades que necesitas para implementar tu idea? ¿Tienes alguna pregunta o comentario sobre el modelo de seguridad? Informa un problema de especificaciones en el repositorio de GitHub correspondiente o agrega tus ideas sobre un problema existente.

Informar un problema con la implementación

¿Encontraste un error en la implementación de Chromium? ¿O la implementación es diferente de la especificación? Informa un error en nuestra herramienta de seguimiento de errores. Asegúrate de incluir la mayor cantidad de detalles posible, instrucciones simples para la reproducción y especificar el componente como UI > Browser > Navigation > BFCache. Glitch funciona muy bien para compartir repros rápidos y fáciles.

Demuestra compatibilidad con la API

¿Planeas usar la API de notRestoredReasons de bfcache? Tu asistencia pública ayuda al equipo de Chromium a priorizar funciones y les muestra a otros proveedores de navegadores la importancia de admitirlas.

Envía un tweet a @ChromiumDev con el hashtag #NotRestoredReasons y cuéntanos dónde y cómo lo usas.

Vínculos útiles