Analytics for PWAs¶

const DISPLAY_MODES = [
  "picture-in-picture",
  "window-controls-overlay",
  "fullscreen",
  "standalone",
  "minimal-ui",
];

/** @returns {{ displayMode: string, appMode: boolean }} */
export function getDisplayContext() {
  // Safari: iOS/iPadOS Home Screen web apps and macOS Dock web apps set navigator.standalone.
  if (navigator.standalone === true) {
    return { displayMode: "standalone", appMode: true };
  }
  for (const mode of DISPLAY_MODES) {
    if (matchMedia(`(display-mode: ${mode})`).matches) {
      // fullscreen can come from the Fullscreen API in a normal tab.
      const appMode = mode !== "fullscreen" || !document.fullscreenElement;
      return { displayMode: mode, appMode };
    }
  }
  return { displayMode: "browser", appMode: false };
}

/** Calls back when the display mode changes (for example, after an install
 *  opens the app window, or when window controls overlay is toggled). */
export function onDisplayModeChange(callback) {
  const queries = DISPLAY_MODES.map((m) => matchMedia(`(display-mode: ${m})`));
  const handler = () => callback(getDisplayContext());
  for (const q of queries) q.addEventListener("change", handler);
  return () => queries.forEach((q) => q.removeEventListener("change", handler));
}

const PARAM = "source";
const KEY = "analytics.launchSource";

function safeSession(fn, fallback = null) {
  try {
    return fn(sessionStorage);
  } catch {
    return fallback; // storage blocked (private mode, sandboxed iframe, policy)
  }
}

/** Determine how this window's session started. Call once, early. */
export function captureLaunchSource() {
  const url = new URL(location.href);
  let source = url.searchParams.get(PARAM);

  // Trusted Web Activity: the first navigation has an android-app:// referrer.
  if (!source && document.referrer.startsWith("android-app://")) {
    source = `twa:${document.referrer.slice("android-app://".length).split("/")[0]}`;
  }

  if (source) {
    safeSession((s) => s.setItem(KEY, source));
    url.searchParams.delete(PARAM);
    history.replaceState(history.state, "", url); // keep router state intact
  }
  return getLaunchSource();
}

export function getLaunchSource() {
  return safeSession((s) => s.getItem(KEY)) ?? (document.referrer ? "referral" : "direct");
}

export function getServiceWorkerStatus() {
  if (!("serviceWorker" in navigator)) return "unsupported";
  return navigator.serviceWorker.controller ? "controlled" : "supported";
}

/** Ask the controlling worker for its version; resolves null after a timeout
 *  so analytics never waits on a slow or old worker. */
export function getServiceWorkerVersion(timeoutMs = 1000) {
  const controller = navigator.serviceWorker?.controller;
  if (!controller) return Promise.resolve(null);
  return new Promise((resolve) => {
    const { port1, port2 } = new MessageChannel();
    const timer = setTimeout(() => {
      port1.close();
      resolve(null);
    }, timeoutMs);
    port1.onmessage = (event) => {
      clearTimeout(timer);
      port1.close();
      resolve(event.data?.version ?? null);
    };
    controller.postMessage({ type: "GET_VERSION" }, [port2]);
  });
}

const SW_VERSION = "2026.09.20-1";

self.addEventListener("message", (event) => {
  if (event.data?.type === "GET_VERSION" && event.ports[0]) {
    event.ports[0].postMessage({ version: SW_VERSION });
  }
});

import "./queue.js"; // defines globalThis.AnalyticsQueue (shared with the SW)
import { getDisplayContext, onDisplayModeChange } from "./context.js";
import { captureLaunchSource } from "./launch.js";
import { getServiceWorkerStatus, getServiceWorkerVersion } from "./sw-context.js";
import { getSessionId } from "./identity.js";

const ENDPOINT = "/analytics/collect";
const BATCH_SIZE = 20;
const FLUSH_DELAY_MS = 5000;
const MAX_BEACON_BYTES = 60 * 1024; // below the 64 KiB beacon/keepalive limit

const queue = globalThis.AnalyticsQueue;
const replay = () => queue.flush(postBatch).catch(() => {}); // retried on next trigger
let buffer = [];
let flushTimer = 0;
let deferred = null; // { controller, result } for fetchLater
const ctx = {
  ...getDisplayContext(),
  launchSource: captureLaunchSource(),
  swStatus: getServiceWorkerStatus(),
  swVersion: null,
  appVersion: document.documentElement.dataset.appVersion ?? "unknown",
};

getServiceWorkerVersion().then((v) => (ctx.swVersion = v));
onDisplayModeChange((display) => {
  Object.assign(ctx, display);
  track("display_mode_change", { to: display.displayMode });
});

export function track(name, props = {}) {
  const event = {
    id: crypto.randomUUID(),
    name,
    ts: Date.now(),
    session: getSessionId(),
    props,
    ctx: { ...ctx, online: navigator.onLine },
  };
  buffer.push(event);
  armDeferredSend();
  if (buffer.length >= BATCH_SIZE) flush();
  else if (!flushTimer) flushTimer = setTimeout(flush, FLUSH_DELAY_MS);
  return event.id;
}

/** Normal path while the page is alive: fetch, falling back to IndexedDB. */
async function flush() {
  clearTimeout(flushTimer);
  flushTimer = 0;
  const events = takeBuffer();
  if (!events.length) return;
  if (!navigator.onLine || !(await postBatch(events))) {
    await persist(events);
  }
}

/** Sends a batch; resolves true if the server accepted or permanently
 *  rejected it (so a malformed batch doesn't loop forever). */
export async function postBatch(events) {
  try {
    const res = await fetch(ENDPOINT, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ sentAt: Date.now(), events }),
      credentials: "same-origin",
    });
    if (res.ok) return true;
    // 4xx other than timeout/rate limit: retrying won't help.
    return res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429;
  } catch {
    return false; // network error: offline, captive portal, DNS failure
  }
}

/** End-of-life path: the page is being hidden and may never run again. */
function flushOnHide() {
  clearTimeout(flushTimer);
  flushTimer = 0;
  const events = takeBuffer();
  if (!events.length) return;
  if (!navigator.onLine) {
    persist(events); // best effort: IndexedDB writes usually complete
    return;
  }
  for (const chunk of chunkBySize(events, MAX_BEACON_BYTES)) {
    const body = JSON.stringify({ sentAt: Date.now(), events: chunk });
    const blob = new Blob([body], { type: "application/json" });
    let queued = false;
    try {
      queued = navigator.sendBeacon?.(ENDPOINT, blob) ?? false;
    } catch {
      queued = false;
    }
    if (!queued) {
      try {
        fetch(ENDPOINT, { method: "POST", body: blob, keepalive: true, headers: { "Content-Type": "application/json" } })
          .catch(() => persist(chunk));
      } catch {
        persist(chunk);
      }
    }
  }
}

/** fetchLater keeps an up-to-date copy of the buffer queued in the browser.
 *  If the page is discarded or crashes, the browser still sends it. */
function armDeferredSend() {
  if (typeof globalThis.fetchLater !== "function") return;
  dropDeferredSent();
  cancelDeferredSend();
  if (!buffer.length) return;
  const body = JSON.stringify({ sentAt: Date.now(), deferred: true, events: buffer });
  if (body.length > MAX_BEACON_BYTES) return; // normal flush will handle it
  const controller = new AbortController();
  try {
    const result = fetchLater(ENDPOINT, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body,
      signal: controller.signal,
      activateAfter: 60_000, // send after a minute even if the page lives on
    });
    deferred = { controller, result, ids: new Set(buffer.map((e) => e.id)) };
  } catch {
    deferred = null; // QuotaExceededError or policy: rely on the other paths
  }
}

function cancelDeferredSend() {
  if (deferred && !deferred.result.activated) deferred.controller.abort();
  deferred = null;
}

/** If the pending fetchLater already fired, its events were sent: drop them. */
function dropDeferredSent() {
  if (deferred?.result.activated) {
    const sent = deferred.ids;
    buffer = buffer.filter((e) => !sent.has(e.id));
    deferred = null;
  }
}

function takeBuffer() {
  dropDeferredSent();
  cancelDeferredSend();
  const events = buffer;
  buffer = [];
  return events;
}

async function persist(events) {
  try {
    await queue.enqueue(events);
    // Ask the service worker to replay when connectivity returns (Chromium).
    const reg = await navigator.serviceWorker?.ready;
    await reg?.sync?.register("analytics-replay");
  } catch {
    // Storage unavailable or quota exceeded: the events are lost. Don't throw
    // from analytics code.
  }
}

function* chunkBySize(events, maxBytes) {
  let chunk = [];
  let size = 64; // envelope overhead
  for (const e of events) {
    const bytes = JSON.stringify(e).length + 1;
    if (chunk.length && size + bytes > maxBytes) {
      yield chunk;
      chunk = [];
      size = 64;
    }
    chunk.push(e);
    size += bytes;
  }
  if (chunk.length) yield chunk;
}

// Lifecycle wiring.
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "hidden") flushOnHide();
  else replay(); // back in the foreground: replay stored events
});
addEventListener("pagehide", flushOnHide);
addEventListener("pageshow", (event) => {
  if (event.persisted) track("page_view", { path: location.pathname, bfcache: true });
});
addEventListener("online", replay);

// Replay anything left from earlier offline sessions.
replay();

import { track } from "./index.js";

function sendPageView() {
  track("page_view", { path: location.pathname, title: document.title });
}

if (document.prerendering) {
  document.addEventListener("prerenderingchange", sendPageView, { once: true });
} else {
  sendPageView();
}

/* Shared by pages (import "./queue.js") and the service worker
   (importScripts("/analytics/queue.js")). Defines globalThis.AnalyticsQueue. */
(() => {
  const DB_NAME = "analytics";
  const DB_VERSION = 1;
  const STORE = "events";
  const MAX_EVENTS = 5000; // an offline device must not fill the origin's quota
  const MAX_AGE_MS = 72 * 60 * 60 * 1000; // match what your backend accepts

  let dbPromise = null;

  function openDB() {
    if (dbPromise) return dbPromise;
    dbPromise = new Promise((resolve, reject) => {
      const req = indexedDB.open(DB_NAME, DB_VERSION);
      req.onupgradeneeded = () => {
        const db = req.result;
        if (!db.objectStoreNames.contains(STORE)) {
          const store = db.createObjectStore(STORE, { keyPath: "id" });
          store.createIndex("ts", "ts");
        }
      };
      req.onsuccess = () => {
        const db = req.result;
        // A newer version was opened elsewhere: close so its upgrade can run.
        db.onversionchange = () => {
          db.close();
          dbPromise = null;
        };
        resolve(db);
      };
      req.onerror = () => {
        dbPromise = null;
        reject(req.error);
      };
    });
    return dbPromise;
  }

  function done(tx) {
    return new Promise((resolve, reject) => {
      tx.oncomplete = () => resolve();
      tx.onerror = () => reject(tx.error);
      tx.onabort = () => reject(tx.error ?? new DOMException("Aborted", "AbortError"));
    });
  }

  async function enqueue(events) {
    const db = await openDB();
    const tx = db.transaction(STORE, "readwrite");
    const store = tx.objectStore(STORE);
    for (const event of events) store.put(event); // put: idempotent by id
    await done(tx);
    await trim();
  }

  /** Oldest events first; drops expired events while scanning. */
  async function peek(limit) {
    const db = await openDB();
    const cutoff = Date.now() - MAX_AGE_MS;
    const tx = db.transaction(STORE, "readwrite");
    const out = [];
    const req = tx.objectStore(STORE).index("ts").openCursor();
    req.onsuccess = () => {
      const cursor = req.result;
      if (!cursor || out.length >= limit) return;
      if (cursor.value.ts < cutoff) cursor.delete();
      else out.push(cursor.value);
      cursor.continue();
    };
    await done(tx);
    return out;
  }

  async function remove(ids) {
    const db = await openDB();
    const tx = db.transaction(STORE, "readwrite");
    const store = tx.objectStore(STORE);
    for (const id of ids) store.delete(id);
    await done(tx);
  }

  async function count() {
    const db = await openDB();
    const tx = db.transaction(STORE, "readonly");
    const req = tx.objectStore(STORE).count();
    await done(tx);
    return req.result;
  }

  /** Keep at most MAX_EVENTS, deleting the oldest. */
  async function trim() {
    const excess = (await count()) - MAX_EVENTS;
    if (excess <= 0) return;
    const db = await openDB();
    const tx = db.transaction(STORE, "readwrite");
    let deleted = 0;
    const req = tx.objectStore(STORE).index("ts").openCursor();
    req.onsuccess = () => {
      const cursor = req.result;
      if (!cursor || deleted >= excess) return;
      cursor.delete();
      deleted++;
      cursor.continue();
    };
    await done(tx);
  }

  /**
   * Replay stored events. `send(batch)` resolves true when the batch was
   * accepted. Stops at the first failure so order is preserved.
   * A Web Lock stops tabs and the service worker from replaying concurrently.
   */
  async function flush(send, batchSize = 100) {
    const run = async () => {
      let sent = 0;
      for (;;) {
        const batch = await peek(batchSize);
        if (!batch.length) return sent;
        if (!(await send(batch))) {
          throw new Error(`Replay stopped after ${sent} events`);
        }
        await remove(batch.map((e) => e.id));
        sent += batch.length;
      }
    };
    const locks = globalThis.navigator?.locks;
    if (!locks) return run();
    return locks.request("analytics-replay", { ifAvailable: true }, (lock) =>
      lock ? run() : 0 // someone else is replaying
    );
  }

  globalThis.AnalyticsQueue = { enqueue, peek, remove, count, flush, MAX_AGE_MS };
})();

import { track } from "./index.js";

let deferredPrompt = null;
let lastPromptSource = null;
const PROMOTABLE_KEY = "analytics.installPromotable";

addEventListener("beforeinstallprompt", (event) => {
  event.preventDefault(); // suppress the mini-infobar; show your own UI
  deferredPrompt = event;
  // Fires on every eligible page load: report once per session.
  try {
    if (!sessionStorage.getItem(PROMOTABLE_KEY)) {
      sessionStorage.setItem(PROMOTABLE_KEY, "1");
      track("install_promotable", { platforms: event.platforms ?? [] });
    }
  } catch {
    track("install_promotable", {});
  }
  document.dispatchEvent(new CustomEvent("installavailable"));
});

/** Call from a click handler (user activation is required). */
export async function promptInstall(source) {
  if (!deferredPrompt) return "unavailable";
  const promptEvent = deferredPrompt;
  deferredPrompt = null; // an event can be prompted only once
  lastPromptSource = source;
  track("install_prompt_shown", { source });
  try {
    const { outcome, platform } = await promptEvent.prompt();
    track("install_prompt_result", { source, outcome, platform });
    return outcome; // "accepted" | "dismissed"
  } catch (error) {
    track("install_prompt_error", { source, error: error.name });
    return "error";
  }
}

addEventListener("appinstalled", () => {
  // Also fires for installs from the browser's own UI (address bar, menu).
  track("app_installed", { via: lastPromptSource ?? "browser_ui" });
  lastPromptSource = null;
});

// Loaded with importScripts() after sw.js defines SW_VERSION.
importScripts("/analytics/queue.js");

const COLLECT = "/analytics/collect";

async function recordSW(name, props) {
  const event = {
    id: crypto.randomUUID(),
    name,
    ts: Date.now(),
    session: null, // no page session in the worker
    props,
    ctx: { source: "service-worker", swVersion: SW_VERSION, online: navigator.onLine },
  };
  await self.AnalyticsQueue.enqueue([event]);
  // Try to send right away; if it fails, a later flush or sync replays it.
  try {
    await self.AnalyticsQueue.flush(async (batch) => {
      const res = await fetch(COLLECT, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ sentAt: Date.now(), events: batch }),
      });
      return res.ok;
    });
  } catch {
    if (self.registration.sync) {
      await self.registration.sync.register("analytics-replay").catch(() => {});
    }
  }
}

self.addEventListener("push", (event) => {
  // Payload format is yours: { id, title, body, url, campaign }.
  let data = {};
  try {
    data = event.data?.json() ?? {};
  } catch {
    data = { title: event.data?.text() ?? "Update" };
  }
  const nid = data.id ?? "unknown";

  event.waitUntil(
    (async () => {
      // Don't make the user wait for an analytics round trip: start recording,
      // show the notification, then wait for both inside waitUntil().
      const received = recordSW("push_received", { nid, campaign: data.campaign }).catch(() => {});
      try {
        await self.registration.showNotification(data.title ?? "Update", {
          body: data.body,
          tag: data.tag,
          icon: "/icons/icon-192.png",
          badge: "/icons/badge-72.png",
          data: { nid, url: data.url ?? "/", campaign: data.campaign },
          actions: data.actions ?? [],
        });
      } catch (error) {
        // Permission revoked between send and receipt, invalid options, etc.
        await recordSW("notification_error", { nid, error: error.name }).catch(() => {});
        await received;
        return;
      }
      await Promise.all([
        received,
        recordSW("notification_shown", { nid, campaign: data.campaign }).catch(() => {}),
      ]);
    })()
  );
});

self.addEventListener("notificationclick", (event) => {
  const { nid, url, campaign } = event.notification.data ?? {};
  event.notification.close();

  // Carry the notification id into the page so the session can be attributed.
  const target = new URL(url ?? "/", self.location.origin);
  target.searchParams.set("source", "notification");
  target.searchParams.set("nid", nid ?? "unknown");

  event.waitUntil(
    Promise.all([
      recordSW("notification_click", { nid, campaign, action: event.action || "default" }),
      openOrFocus(target.href),
    ])
  );
});

self.addEventListener("notificationclose", (event) => {
  const { nid, campaign } = event.notification.data ?? {};
  event.waitUntil(recordSW("notification_dismissed", { nid, campaign }));
});

async function openOrFocus(href) {
  const windows = await self.clients.matchAll({ type: "window", includeUncontrolled: true });
  for (const client of windows) {
    if (client.url === href && "focus" in client) return client.focus();
  }
  return self.clients.openWindow(href);
}

import { track } from "./index.js";

export async function watchNotificationPermission() {
  if (!("Notification" in globalThis)) return;
  const KEY = "analytics.lastNotificationPermission";
  const report = (state) => {
    let last = null;
    try {
      last = localStorage.getItem(KEY);
      localStorage.setItem(KEY, state);
    } catch {}
    if (last !== state) track("notification_permission", { state, previous: last });
  };

  report(Notification.permission); // "default" | "granted" | "denied"
  try {
    const status = await navigator.permissions.query({ name: "notifications" });
    status.addEventListener("change", () => report(Notification.permission));
  } catch {
    // Permissions API doesn't know "notifications" in this engine.
  }
}

import { track } from "./index.js";

export function reportNavigationTiming() {
  const [nav] = performance.getEntriesByType("navigation");
  if (!nav) return;

  const activation = nav.activationStart ?? 0; // prerendered pages
  const handledBySW = nav.workerStart > 0;

  track("navigation_timing", {
    type: nav.type, // navigate | reload | back_forward | prerender
    handledBySW,
    ttfb: Math.round(Math.max(0, nav.responseStart - activation)),
    swAndResponse: handledBySW ? Math.round(nav.responseEnd - nav.workerStart) : null,
    deliveryType: nav.deliveryType ?? null,
    // Static Routing API: engines expose different subsets of these fields.
    // Spec names (Safari 27) first, then Chromium's non-standard names.
    routerMatched: nav.workerMatchedRouterSource ?? nav.workerMatchedSourceType ?? null,
    routerFinal: nav.workerFinalRouterSource ?? nav.workerFinalSourceType ?? null,
    routerEvalMs: nav.workerRouterEvaluationStart > 0
      ? Math.round(nav.workerRouterEvaluationStart - activation)
      : null,
    cacheLookupMs: nav.workerCacheLookupStart > 0
      ? Math.round(nav.workerCacheLookupStart - activation)
      : null,
    transferSize: nav.transferSize, // 0 often means cache (HTTP or worker)
  });
}

// Run after load so the entry is complete.
if (document.readyState === "complete") reportNavigationTiming();
else addEventListener("load", reportNavigationTiming, { once: true });

self.addEventListener("fetch", (event) => {
  if (event.request.mode !== "navigate") return;
  event.respondWith(
    (async () => {
      const started = Date.now();
      let source = "network";
      let response;
      try {
        response = await event.preloadResponse;
        if (response) source = "preload";
        else response = await fetch(event.request);
      } catch {
        response = await caches.match(event.request);
        source = response ? "cache" : "offline-fallback";
        response ??= await caches.match("/offline.html");
      }
      // Record after responding (recordSW comes from sw-push-analytics.js).
      event.waitUntil(
        recordSW("sw_navigation", {
          path: new URL(event.request.url).pathname,
          source,
          ms: Date.now() - started,
        })
      );
      return response ?? Response.error();
    })()
  );
});