mdn · chrisdavidmills · Apr 12, 2024 · Jul 14, 2023 · Jul 17, 2023 · Jul 17, 2023
@@ -0,0 +1,41 @@
+---
+title: NotRestoredReasonDetails
+slug: Web/API/NotRestoredReasonDetails
+page-type: web-api-interface
+status:
+ - experimental
+browser-compat: api.NotRestoredReasonDetails
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`NotRestoredReasonDetails`** interface of the {{domxref("Performance API", "Performance API", "", "nocode")}} represents a single reason why a navigated page was blocked from using the [back/forward cache (bfcache)](https://web.dev/articles/bfcache).
+
+An array of `NotRestoredReasonDetails` objects can be accessed via the {{domxref("NotRestoredReasons.reasons")}} property.
+
+## Instance properties
+
+- {{domxref("NotRestoredReasonDetails.reason", "reason")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+ - : A string describing a reason that the page was blocked from using the back/forward cache.
+
+## Instance methods
+
+- {{domxref("NotRestoredReasonDetails.toJSON", "toJSON()")}} {{Experimental_Inline}}
+ - : A {{Glossary("Serialization","serializer")}}; returns a JSON representation of the `NotRestoredReasonDetails` object.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
@@ -0,0 +1,63 @@
+---
+title: "NotRestoredReasonDetails: reason property"
+short-title: reason
+slug: Web/API/NotRestoredReasonDetails/reason
+page-type: web-api-instance-property
+status:
+ - experimental
+browser-compat: api.NotRestoredReasonDetails.reason
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`reason`** read-only property of the
+{{domxref("NotRestoredReasonDetails")}} interface returns a string describing a reason that the page was blocked from using the [back/forward cache (bfcache)](https://web.dev/articles/bfcache).
+
+## Value
+
+A string.
+
+There are many different reasons why blocking could occur, and browsers can choose to implement their own specific reasons for blocking, based on how they operate. Developers should avoid depending on specific wording for reasons and be prepared to handle new reasons being added and deleted.
+
+The initial values listed in the specification are:
+
+- `"fetch"`
+ - : While unloading, a fetch initiated by the current document (e.g. via {{domxref("fetch()")}}) was canceled while ongoing. As a result, the page was not in a stable state that could be stored in the bfcache.
+- `"lock"`
+ - : While unloading, held locks and lock requests were terminated, so the page was not in a stable state that could be stored in the bfcache.
+- `"masked"`
+ - : The exact reason is hidden for privacy purposes. This value can mean one of the following:
+ - The current document has children contained in a cross-origin {{htmlelement("iframe")}}, and they prevented storage in the bfcache.
+ - The current Document could not be stored in the bfcache for user agent-specific reasons.
+- `"navigation-failure"`
+ - : The original navigation that created the current document errored, and storing the resulting error document in the bfcache was prevented.
+- `"parser-aborted"`
+ - : The current document never finished its initial HTML parsing, and storing the unfinished document in the bfcache was prevented.
+- `"websocket"`
+ - : While unloading, an open [WebSocket](/en-US/docs/Web/API/WebSockets_API) connect was shut down, so the page was not in a stable state that could be stored in the bfcache.
+
+Additional blocking reasons may be used by some browsers, for example:
+
+- `"unload-listener"`
+ - : The page registers an [`unload`](/en-US/docs/Web/API/Window/unload_event) handler, which prevents bfcache usage. This serves as a useful warning, as `unload` is deprecated. See [Deprecating the unload event](https://developer.chrome.com/docs/web-platform/deprecating-unload) for more information.
+- `"response-cache-control-no-store"`
+ - : The page uses `no-store` as a {{httpheader("Cache-Control")}} header value.
+- `"related-active-contents"`
+ - : The page was opened from another page that still has a reference to this page, for example using "duplicate tab" functionality.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
@@ -0,0 +1,54 @@
+---
+title: "NotRestoredReasonDetails: toJSON() method"
+short-title: toJSON()
+slug: Web/API/NotRestoredReasonDetails/toJSON
+page-type: web-api-instance-method
+status:
+ - experimental
+browser-compat: api.NotRestoredReasonDetails.toJSON
+spec-urls: https://html.spec.whatwg.org/multipage/nav-history-apis.html#notrestoredreasondetails
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`toJSON()`** method of the {{domxref("NotRestoredReasonDetails")}} interface is a {{Glossary("Serialization","serializer")}}; it returns a JSON representation of the {{domxref("NotRestoredReasonDetails")}} object.
+
+## Syntax
+
+```js-nolint
+toJSON()
+```
+
+### Parameters
+
+None.
+
+### Return value
+
+A {{jsxref("JSON")}} object that is the serialization of the {{domxref("NotRestoredReasonDetails")}} object.
+
+## Examples
+
+The following function will return a JSON representation of the first `NotRestoredReasonDetails` object of the `NotRestoredReasons` object from the first `PerformanceNavigationTiming` object currently present in the performance timeline:
+
+```js
+function returnNRR() {
+ const navEntries = performance.getEntriesByType("navigation");
+ let navEntry = navEntries[0];
+ return navEntry.notRestoredReasons.reasons[0].toJSON();
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{jsxref("JSON")}}
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
@@ -0,0 +1,39 @@
+---
+title: "NotRestoredReasons: children property"
+short-title: children
+slug: Web/API/NotRestoredReasons/children
+page-type: web-api-instance-property
+status:
+ - experimental
+browser-compat: api.NotRestoredReasons.children
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`children`** read-only property of the
+{{domxref("NotRestoredReasons")}} interface returns an array of {{domxref("NotRestoredReasons")}} objects, one for each child {{htmlelement("iframe")}} embedded in the current document, which may contain reasons why the top-level frame was blocked relating to the child frames.
+
+Each object has the same structure as the parent object — this way, any number of levels of embedded `<iframe>`s can be represented inside the object recursively.
+
+## Value
+
+An array of {{domxref("NotRestoredReasons")}} objects.
+
+If the frame has no children, the array will be empty; if the document is in a cross-origin `<iframe>`, `children` will return `null`.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
@@ -0,0 +1,37 @@
+---
+title: "NotRestoredReasons: id property"
+short-title: id
+slug: Web/API/NotRestoredReasons/id
+page-type: web-api-instance-property
+status:
+ - experimental
+browser-compat: api.NotRestoredReasons.id
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`id`** read-only property of the
+{{domxref("NotRestoredReasons")}} interface returns a string representing the `id` attribute value of the {{htmlelement("iframe")}} the document is contained in (for example `<iframe id="foo" src="...">`).
+
+## Value
+
+A string.
+
+If the document is not in an `<iframe>` or the `<iframe>` has no `id` set, `id` will return `null`.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
@@ -0,0 +1,51 @@
+---
+title: NotRestoredReasons
+slug: Web/API/NotRestoredReasons
+page-type: web-api-interface
+status:
+ - experimental
+browser-compat: api.NotRestoredReasons
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`NotRestoredReasons`** interface of the {{domxref("Performance API", "Performance API", "", "nocode")}} provides report data containing reasons why the current document was blocked from using the [back/forward cache (bfcache)](https://web.dev/articles/bfcache) on navigation.
+
+These objects are accessed via the {{domxref("PerformanceNavigationTiming.notRestoredReasons")}} property.
+
+## Instance properties
+
+- {{domxref("NotRestoredReasons.children", "children")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+ - : An array of `NotRestoredReasons` objects, one for each child {{htmlelement("iframe")}} embedded in the current document, which may contain reasons why the top-level frame was blocked relating to the child frames. Each object has the same structure as the parent object — this way, any number of levels of embedded `<iframe>`s can be represented inside the object recursively. If the frame has no children, the array will be empty; if the document is in a cross-origin `<iframe>`, `children` will return `null`.
+- {{domxref("NotRestoredReasons.id", "id")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+ - : A string representing the `id` attribute value of the `<iframe>` the document is contained in (for example `<iframe id="foo" src="...">`). If the document is not in an `<iframe>` or the `<iframe>` has no `id` set, `id` will return `null`.
+- {{domxref("NotRestoredReasons.name", "name")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+ - : A string representing the `name` attribute value of the `<iframe>` the document is contained in (for example `<iframe name="bar" src="...">`). If the document is not in an `<iframe>` or the `<iframe>` has no `name` set, `name` will return `null`.
+- {{domxref("NotRestoredReasons.reasons", "reasons")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+ - : An array of {{domxref("NotRestoredReasonDetails")}} objects, each representing a reason why the navigated page was blocked from using the bfcache. If the document is in a cross-origin `<iframe>`, `reasons` will return `null`, but the parent document may show a `reason` of `"masked"` if any `<iframe>`s blocked bfcache usage for the top-level frame.
+- {{domxref("NotRestoredReasons.src", "src")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+ - : A string representing the path to the source of the `<iframe>` the document is contained in (for example `<iframe src="exampleframe.html">`). If the document is not in an `<iframe>`, `src` will return `null`.
+- {{domxref("NotRestoredReasons.url", "url")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+ - : A string representing the URL of the navigated page or `<iframe>`. If the document is in a cross-origin `<iframe>`, `url` will return `null`.
+
+## Instance methods
+
+- {{domxref("NotRestoredReasons.toJSON", "toJSON()")}} {{Experimental_Inline}}
+ - : A {{Glossary("Serialization","serializer")}}; returns a JSON representation of the `NotRestoredReasons` object.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
@@ -0,0 +1,37 @@
+---
+title: "NotRestoredReasons: name property"
+short-title: name
+slug: Web/API/NotRestoredReasons/name
+page-type: web-api-instance-property
+status:
+ - experimental
+browser-compat: api.NotRestoredReasons.name
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`name`** read-only property of the
+{{domxref("NotRestoredReasons")}} interface returns a string representing the `name` attribute value of the {{htmlelement("iframe")}} the document is contained in (for example `<iframe name="bar" src="...">`).
+
+## Value
+
+A string.
+
+If the document is not in an `<iframe>` or the `<iframe>` has no `name` set, `name` will return `null`.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}
@@ -0,0 +1,37 @@
+---
+title: "NotRestoredReasons: reasons property"
+short-title: reasons
+slug: Web/API/NotRestoredReasons/reasons
+page-type: web-api-instance-property
+status:
+ - experimental
+browser-compat: api.NotRestoredReasons.reasons
+---
+
+{{APIRef("Performance API")}}{{SeeCompatTable}}
+
+The **`reasons`** read-only property of the
+{{domxref("NotRestoredReasons")}} interface returns an array of {{domxref("NotRestoredReasonDetails")}} objects, each representing a reason why the navigated page was blocked from using the [back/forward cache (bfcache)](https://web.dev/articles/bfcache).
+
+## Value
+
+An array of {{domxref("NotRestoredReasonDetails")}} objects. See [Blocking reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons#blocking_reasons) for a list of the possible blocking reasons.
+
+If the document is in a cross-origin {{htmlelement("iframe")}}, `reasons` will return `null`, but the parent document may show a `reason` of `"masked"` if any `<iframe>`s blocked bfcache usage for the top-level frame.
+
+## Examples
+
+See [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons) for examples.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Reporting back/forward cache not restored reasons](/en-US/docs/Web/API/Performance_API/Reporting_backforward_cache_not_restored_reasons)
+- {{domxref("PerformanceNavigationTiming.notRestoredReasons")}}