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

Descubre qué navegaciones se bloquearon para que no se usara la bfcache y por qué.

Chris Mills

Barry Pollard

La propiedad notRestoredReasons, agregada a la clase PerformanceNavigationTiming, informa si se impidió que los marcos presentes en el documento usaran la bfcache en la navegación 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 este modo, mejorar el rendimiento del sitio.

Estado actual

La API de notRestoredReasons se lanzó en 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 vuelven a una página que ya visitaron. Las páginas pueden bloquearse para que no ingresen a la bfcache o pueden desalojarse mientras están en la bfcache por diferentes motivos, algunos requeridos por una especificación y otros específicos de las implementaciones del navegador.

Anteriormente, los desarrolladores no podían saber 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 sobre el marco superior y todos los elementos iframe presentes en el documento:

Son los motivos por los que se bloqueó el uso de la bfcache.
Detalles como los marcos id y name, para ayudar a identificar los iframes en el código HTML

Esto permite que los desarrolladores tomen medidas para que esas páginas sean compatibles con la bfcache y, de este modo, mejoren el rendimiento del sitio.

Ejemplos

Se puede obtener una instancia de PerformanceNavigationTiming a partir de atributos como Performance.getEntriesByType() y PerformanceObserver.

Por ejemplo, podrías invocar la siguiente función para devolver todos los objetos PerformanceNavigationTiming presentes en la línea de tiempo 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 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 representa el estado de bloqueo de los marcos del mismo origen incorporados en el marco de nivel superior. Cada objeto tiene la misma estructura que el objeto principal. De esta manera, se puede representar cualquier cantidad de niveles de marcos incorporados dentro del objeto de forma recursiva. Si el frame no tiene elementos secundarios, el array estará vacío.
id: Es una cadena que representa el valor del atributo id del fotograma (por ejemplo, <iframe id="foo" src="...">). Si el fotograma 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 fotograma (por ejemplo, <iframe name="bar" src="...">). Si el fotograma 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 se bloqueó el uso de la bfcache en la página a la que se navegó. El bloqueo puede ocurrir por muchos motivos diferentes. Consulta la sección Motivos de bloqueo para obtener más detalles.
src: Es una cadena que representa la ruta de acceso a la fuente del fotograma (por ejemplo, <iframe src="b.html">). Si el fotograma 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 al que se navegó.

En el caso de los objetos PerformanceNavigationTiming que no representan navegaciones por el historial, la propiedad notRestoredReasons devolverá null.

Ten en cuenta que notRestoredReasons también devuelve null cuando no hay motivos de bloqueo, por lo que el hecho de que sea null no indica que se haya usado o no la bfcache. Para ello, debes usar la propiedad event.persisted.

Informa el bloqueo de bfcache en los marcos del mismo origen

Cuando una página tiene marcos del mismo origen incorporados, el valor de notRestoredReasons devuelto 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 sobre el bloqueo de bfcache en los marcos de origen cruzado

Cuando una página tiene marcos incorporados de origen cruzado, limitamos la cantidad de información que se comparte sobre ellos para evitar la filtración de información de origen cruzado. Solo incluimos la información que ya conoce la página externa 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"
}

Para todos los iframe de origen cruzado, informamos null para el valor de reasons del iframe, y el iframe de nivel superior mostrará un motivo de "masked". Ten en cuenta que "masked" también se puede usar por motivos específicos del agente de usuario, por lo que no siempre indica 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 de bloqueo

Como mencionamos anteriormente, existen muchos motivos diferentes por los que se puede producir el 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 bfcache en ciertos navegadores. 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 (ya sea con la opción "Duplicar pestaña") que aún tiene una referencia a esta página.

Comentarios

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

Cuéntanos sobre el diseño de la API

¿Hay algo sobre 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 tu opinión 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 nuestro sistema de seguimiento de problemas. Asegúrate de incluir tantos detalles como puedas, instrucciones simples para reproducir el problema y especificar el componente como UI > Browser > Navigation > BFCache.

Cómo mostrar compatibilidad con la API

¿Piensas usar la API de bfcache notRestoredReasons? Tu apoyo público ayuda al equipo de Chromium a priorizar funciones y 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.