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

Encuentra 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 la bfcache en la navegación para los marcos presentes en el documento y por qué. Los desarrolladores pueden usar esta información para identificar las páginas que necesitan actualizaciones para que sean compatibles con la bfcache y, de esta manera, mejorar el rendimiento del sitio.

Estado actual

La API de notRestoredReasons se envió desde Chrome 123 y se está lanzando 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. Se puede bloquear el ingreso de las páginas a la bfcache o expulsarlas mientras están en ella por diferentes motivos, algunos de los cuales se exigen en una especificación y otros son específicos de las implementaciones del navegador.

Anteriormente, los desarrolladores no tenían forma de averiguar por qué se bloqueaba el uso de la bfcache en sus páginas en el 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. Esto devuelve un objeto que contiene información relacionada con el marco superior y todos los iframes presentes en el documento:

  • Motivos por los que se bloqueó el uso de la bfcache.

  • Detalles como id y name de marcos 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 a partir de funciones como Performance.getEntriesByType() y PerformanceObserver.

Por ejemplo, puedes invocar la siguiente función para que devuelva todos los objetos PerformanceNavigationTiming presentes en la línea de tiempo de rendimiento y registre 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);
  }
}

En el caso de las navegaciones del historial, la propiedad PerformanceNavigationTiming.notRestoredReasons devuelve 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 representan el estado bloqueado de cualquier marco del mismo origen incorporado en el marco 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 forma 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
Un array de cadenas que representan un motivo por el que se bloqueó la página navegada para que no use la bfcache. Existen muchos motivos por los que se puede producir un bloqueo. Consulta la sección Motivos del bloqueo para obtener más detalles.
src
Es una cadena que representa la ruta de acceso a la fuente 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 el iframe por el que se navegó.

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

Ten en cuenta que notRestoredReasons también devuelve null cuando no hay motivos de bloqueo, por lo que este valor null no es un indicador de que se haya usado o no la bfcache. Para ello, debes usar la propiedad event.persisted.

Informa el bloqueo de bfcache en marcos del mismo origen

Cuando una página tiene marcos de origen idéntico 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 marcos de origen cruzado

Cuando una página tiene marcos de origen cruzado incorporados, limitamos la cantidad de información que se comparte sobre ellos para evitar que se filtre información de origen cruzado. Solo incluimos información que la página externa ya conoce y si el subárbol de origen cruzado bloqueó la bfcache o no. No incluimos ningún motivo de bloqueo ni información sobre los niveles inferiores del subárbol (incluso si algunos subniveles son del 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 todos los iframes de origen cruzado, informamos null para el valor reasons del marco, 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 del usuario-agente, por lo que es posible que no siempre indique un problema en un iframe.

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

Motivos del bloqueo

Como dijimos antes, existen muchos motivos diferentes por los que se puede producir un bloqueo:

A continuación, se incluyen ejemplos de algunos de los motivos más comunes por los que no se puede usar la bfcache:

  • unload-listener: La página registra un controlador unload, lo que impide el uso de la bfcache en ciertos navegadores. Ten en cuenta que Chrome ya no emite este motivo a partir de Chrome 155, excepto cuando los sitios volvieron a habilitar los eventos unload. Consulta Baja del evento unload para obtener más información.
  • response-cache-control-no-store: La página usa no-store como un valor de cache-control.
  • related-active-contents: La página se abrió desde otra página (con la opción "Duplicar pestaña") que aún tiene una referencia a esta página.

Comentarios

El equipo de Chromium quiere conocer tus experiencias con la API de bfcache notRestoredReasons.

Cuéntanos sobre el diseño de la API

¿Hay algo en la API que 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 especificación en el repositorio de GitHub correspondiente o agrega tus comentarios a un problema existente.

Informa 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 tantos detalles como sea posible, instrucciones para reproducir el problema y especificar el componente como UI > Browser > Navigation > BFCache.

Muestra compatibilidad con la API

¿Planeas usar la API de notRestoredReasons de bfcache? Tu apoyo público ayuda al equipo de Chromium a priorizar las funciones y les muestra a otros proveedores de navegadores lo importante que es admitirlas.

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

Vínculos útiles