Page Lifecycle tracker documentation

page-lifecycle-tracker follows the state of a web page in the Page Lifecycle API: active, passive, hidden, frozen and terminated. It gets the state from the browser events focus, blur, visibilitychange, freeze, resume, pagehide and pageshow.

The library is for monitoring and telemetry code. A monitor discards the samples of a hidden page. An exporter sends the last data before the page goes away. A Web Vitals library starts a new page view after a restore from the back/forward cache (bfcache).

All libraries of a page share one tracker. In each transition, the subscribers of the observe phase start before the subscribers of the export phase. Thus the monitors record their last values before the exporter sends them, whatever the order of the scripts.

The package has no dependencies. It is an ECMAScript module with TypeScript types, and its license is MIT.

Start here

• Getting started: install the package and subscribe to the transitions.
• API reference: each function, class, method and type of the package.
• Browser support: the events in Chromium, Firefox and Safari, with the sources.

Concepts

• States and transitions: the five states, the events that change them, and a simulator.
• Capture phase and listener order: why the tracker listens in the capture phase, and where that is not sufficient.
• The shared tracker and the phases: one tracker for each page, and monitors before exporters.
• Back/forward cache (bfcache): the transitions into the cache and out of it.
• The freeze event: when Chromium freezes a page, and what resume does.
• Marks: the transitions in a measurement window.

Recipes

• Flush OpenTelemetry at the end of the page: send the last spans and metrics after the monitors.
• Pause timers while the page is hidden: stop a poller in the background.
• Discard the samples of a window: keep only the measurements of a visible page.
• Detect a back/forward cache restore: start a new page view after a restore.