Learning

5.2 The lifecycle flusher: recipe, bfcache, and why unload is out

One flush per hidden transition, bfcache restores identified precisely via persisted pageshow, and the layered case against unload.

Levels: Intermediate ~16 min read

Intermediate

The lifecycle rules from the previous page compile into one small class: flush exactly once per hidden transition, notice back/forward-cache restores without hallucinating them, and never touch unload. This page builds that class, then defends each design decision against the failure modes that real analytics SDKs have shipped with.

The recipe

The flusher wires three listeners around one latch. The visibilitychange handler checks the state and flips the latch before flushing — so a re-entrant event or the pagehide that follows cannot double-send. The pagehide listener is a fallback for the rare ordering where it arrives without a prior visibility change; the latch makes it a no-op in the normal sequence. And pageshow with persisted === true is the only restore signal — for reasons the next section makes precise:

Interactive Runnable example

Edit

// The Lifecycle Flusher recipe: one flush per hidden transition,
// bfcache-aware, never double-flushing.
//
// Design decisions, each tied to a spec fact or an honest browser
// behavior note:
//   - Primary key: the STATE TRANSITION to hidden (the Beacon
//     spec's MUST), observed via visibilitychange.
//   - A LATCH (this.hidden) makes the flush idempotent across the
//     visibilitychange-then-pagehide sequence browsers emit on
//     desktop navigation.
//   - pageshow with persisted=true is the ONLY bfcache-restore
//     signal; visibilitychange->visible alone also fires on plain
//     tab-switch-back, so the restore hook must NOT live there.
//   - No unload/beforeunload listeners: unload is deprecated and
//     bfcache-hostile in modern browsers (a browser-behavior fact,
//     not spec text), and neither event is reliable on mobile.
//   - getVisibility is injectable so tests can drive states; the
//     default reads the real document.

class LifecycleFlusher {
  constructor(opts) {
    this.url = opts.url;
    this.onFlush = opts.onFlush;       // () => BodyInit | null
    this.onRestore = opts.onRestore;   // () => void  (bfcache only)
    this.getVisibility = opts.getVisibility ||
      (() => document.visibilityState);
    this.send = opts.send ||
      ((u, d) => navigator.sendBeacon(u, d));
    this.hidden = false;
    this.flushes = 0;
    this.attach();
  }

attach() {
    document.addEventListener('visibilitychange', () => {
      if (this.getVisibility() === 'hidden' && !this.hidden) {
        this.hidden = true;
        this.flush();                       // the spec's MUST moment
      } else if (this.getVisibility() === 'visible' && this.hidden) {
        this.hidden = false;                // unlatch only: plain
      }                                     // tab-switch-back is NOT
    });                                     // a bfcache restore

// Desktop fallback: pagehide can arrive without a prior
    // visibilitychange in edge cases; the latch prevents a second
    // flush when both fire in order:
    window.addEventListener('pagehide', () => {
      if (!this.hidden) {
        this.hidden = true;
        this.flush();
      }
    });

// bfcache restore: ONLY persisted pageshow counts.
    window.addEventListener('pageshow', (e) => {
      if (e.persisted) {
        this.hidden = false;
        if (this.onRestore) this.onRestore();
      }
    });
  }

flush() {
    const data = this.onFlush();
    if (data === null) return;   // "nothing to send" is a valid answer
    this.flushes++;
    this.send(this.url, data);
  }

flushNow() {   // manual escape hatch (e.g. a guard before sign-out)
    this.flush();
  }
}

// -- Drive the recipe with synthetic state changes ----------------
const sent = [];
const flusher = new LifecycleFlusher({
  url: 'https://collect.example.com/flush',
  onFlush: () => JSON.stringify({ event: 'flush', n: flusher.flushes + 1 }),
  onRestore: () => console.log('bfcache restore detected: re-init state'),
  send: (url, data) => { sent.push(data); return true; },
  getVisibility: () => document.visibilityState,
});

function setVisibility(state) {
  Object.defineProperty(document, 'visibilityState', {
    configurable: true,
    get: () => state,
  });
  document.dispatchEvent(new Event('visibilitychange'));
}

// 1. Tab switch away -> exactly one flush:
setVisibility('hidden');

// 2. Navigation: pagehide ALSO fires -> the latch blocks a second:
window.dispatchEvent(new Event('pagehide'));

// 3. Tab switch back -> no flush, no restore:
setVisibility('visible');

// 4. Hidden again, then bfcache-style restore:
setVisibility('hidden');
const restoreEvent = new Event('pageshow');
Object.defineProperty(restoreEvent, 'persisted', { value: true });
window.dispatchEvent(restoreEvent);

console.log('flushes total =', flusher.flushes, '(expected 2)');
console.log('beacons sent  =', sent.length, '(expected 2)');
console.log('beacon #1     =', sent[0]);

// In production, wire the real transports:
//   send: (u, d) => navigator.sendBeacon(u, d)
//   getVisibility: () => document.visibilityState
// and return null from onFlush when your queue is empty.

Ready to run.

The output is the contract in miniature: one flush for the tab-switch, no second flush when pagehide follows the hidden transition, nothing on plain tab-switch-back, and the restore hook firing exactly once for the persisted pageshow. The injectable getVisibility and send options exist so tests can drive the state machine — in production the defaults read the real document and call the real navigator.sendBeacon.

bfcache: why restores must be identified precisely

A page restored from the back/forward cache resumes mid-execution: timers, listeners, and module state survived the freeze. Two consequences follow. Analytics must count the restore as a new pageview — tagged as a restore, or dashboards double-count nothing but undercount returns — and anything session-scoped may need re-initializing. The trap is that visibilitychange → visible fires on every ordinary tab-switch-back too; only pageshow with persisted distinguishes an actual bfcache restore from a user coming back from lunch. The flusher therefore unlatches its state on the visible transition (so the next hidden can flush) but defers the restore callback to the persisted pageshow — splitting the two concerns that naive SDKs merge into one spurious 'restore' per tab switch.

Why unload and beforeunload are absent

The recipe registers no unload or beforeunload listeners, and the reasoning is layered. Reliability: neither fires in the scenarios where mobile pages actually die — app switches and OS kills — so code keyed on them is silent exactly when it matters most. Compatibility cost: pages that register unload handlers are excluded from bfcache in major engines, trading away the fastest possible back-navigation for a signal that arrives unreliably anyway; browsers have been progressively deprecating the event on those grounds (a browser-policy evolution — not spec text — that current engine documentation tracks). Redundancy: everything unload could still deliver here, the hidden transition already delivers, earlier and with a spec guarantee behind it. When a migration genuinely requires touching the old events, the flusher's flushNow() is the escape hatch — callable from anywhere, including a guard you control, without the lifecycle core ever depending on those events.

Quick check

The page fires visibilitychange → visible after a plain tab switch back. What should the flusher do?

// inside the visibilitychange handler
if (document.visibilityState === 'visible') {
  ?
}

Key takeaways

One flush per hidden transition: a latch set before flush() makes visibilitychange-then-pagehide idempotent.
pagehide stays as a latched fallback; flushNow() is the manual escape hatch.
bfcache restore = pageshow with persisted === true — never the visible transition alone.
No unload/beforeunload: unreliable on mobile, bfcache-hostile, redundant given the hidden-transition guarantee.
Injectable getVisibility/send make the whole state machine testable without a browser's cooperation.

Was this page helpful?

Yes No

Mark this learning resource complete to track your learning progress.

Suggest an edit