From ea082d549d8b30b9d815bf40bc2617f311edf204 Mon Sep 17 00:00:00 2001 From: Matt Hillsdon Date: Fri, 20 Nov 2026 18:40:40 +0000 Subject: [PATCH] Report where each tab keeps its project as a user property The session-storage fallback costs code and test surface, and we do not know how many sessions use it. project_storage says whether a tab is on the projects database, on the fallback because the browser has no IndexedDB, on the fallback because the database would not open, or in iframe controller mode where the embedding page keeps the project. --- docs/analytics-events.md | 11 ++++++++--- src/App.tsx | 9 ++++++++- src/fs/current-project.test.ts | 10 ++++++++++ src/fs/current-project.ts | 22 ++++++++++++++++++++++ 4 files changed, 48 insertions(+), 4 deletions(-) diff --git a/docs/analytics-events.md b/docs/analytics-events.md index f1a5b47cf..ebf8f2f96 100644 --- a/docs/analytics-events.md +++ b/docs/analytics-events.md @@ -10,13 +10,18 @@ at the end maps the previous UA-shaped events to their replacements. Set once on app boot. Auto-attach to every subsequent event for the same user, available as user-scoped breakdowns in GA4. -| Name | Values | Set when | Notes | -| ------------------ | ------------ | -------- | -------------------------------------------------------------- | -| `webusb_available` | `yes` / `no` | App boot | From `"usb" in navigator`. Same name and values as ml-trainer. | +| Name | Values | Set when | Notes | +| ------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `webusb_available` | `yes` / `no` | App boot | From `"usb" in navigator`. Same name and values as ml-trainer. | +| `project_storage` | `database` / `session_no_indexeddb` / `session_open_failed` / `host` | App boot, once the projects database has opened or failed to | Where the tab keeps its project. `database` is IndexedDB. The two `session_` values are the session-storage fallback: the browser has no IndexedDB, or it has but the database would not open. `host` is iframe controller mode, where the embedding page keeps the project. | Unlike ml-trainer there is no `webbluetooth_available`: the editor doesn't use Bluetooth. +`project_storage` is there to show how many sessions really run without the +projects database, and why, which decides whether the session-storage fallback +is worth keeping. + ## Device events Same event family and params as ml-trainer so a cross-product device dashboard diff --git a/src/App.tsx b/src/App.tsx index 9b5bb0b8e..e9baa5d36 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -23,7 +23,10 @@ import SearchProvider from "./documentation/search/search-hooks"; import { ActiveEditorProvider } from "./editor/active-editor-hooks"; import { FileSystem } from "./fs/fs"; import { FileSystemProvider } from "./fs/fs-hooks"; -import { openProjectsDatabase } from "./fs/current-project"; +import { + openProjectsDatabase, + reportProjectStorageMode, +} from "./fs/current-project"; import { createHost, IframeHost } from "./fs/host"; import { parseProjectLink, PendingProjectLink } from "./fs/project-link"; import { FSStorage } from "./fs/storage"; @@ -93,6 +96,10 @@ const App = () => { "webusb_available", "usb" in navigator ? "yes" : "no" ); + if (iframeMode) { + // Otherwise reported when the projects database opens, or fails to. + reportProjectStorageMode(logging, "host"); + } const statusListener = (event: ConnectionStatusChange) => logDeviceStatusChange(logging, event); device.addEventListener("status", statusListener); diff --git a/src/fs/current-project.test.ts b/src/fs/current-project.test.ts index f3b557a40..72d07e89b 100644 --- a/src/fs/current-project.test.ts +++ b/src/fs/current-project.test.ts @@ -48,6 +48,7 @@ describe("openProjectsDatabase", () => { const db = await openProjectsDatabase(logging); expect(db).toBeInstanceOf(ProjectsDatabase); expect(isActive()).toEqual(true); + expect(logging.userProperties.project_storage).toEqual("database"); db!.close(); }); @@ -58,6 +59,9 @@ describe("openProjectsDatabase", () => { expect(await openProjectsDatabase(logging)).toBeUndefined(); expect(logging.errors[0].message).toMatch(/using session storage/); expect(isActive()).toEqual(false); + expect(logging.userProperties.project_storage).toEqual( + "session_open_failed" + ); }); it("gives up quietly on an incompatible database on public stages", async () => { @@ -76,6 +80,9 @@ describe("openProjectsDatabase", () => { expect(await openProjectsDatabase(logging, false)).toBeUndefined(); expect(logging.errors).toEqual([]); expect(hasStorageVersionError()).toEqual(true); + expect(logging.userProperties.project_storage).toEqual( + "session_open_failed" + ); }); it("gives up without IndexedDB", async () => { @@ -86,6 +93,9 @@ describe("openProjectsDatabase", () => { }); try { expect(await openProjectsDatabase(logging)).toBeUndefined(); + expect(logging.userProperties.project_storage).toEqual( + "session_no_indexeddb" + ); } finally { Object.defineProperty(globalThis, "indexedDB", { value: original, diff --git a/src/fs/current-project.ts b/src/fs/current-project.ts index 1bf807c57..571e2dca0 100644 --- a/src/fs/current-project.ts +++ b/src/fs/current-project.ts @@ -49,6 +49,25 @@ export const sessionStorageIfPossible = (): Storage | undefined => { } }; +/** + * Where a tab keeps its project, as the project_storage user property. + * + * It is there to answer one question: how many sessions really run without + * the projects database, and why. That decides whether the session-storage + * fallback earns its keep. + */ +export type ProjectStorageMode = + | "database" + | "session_no_indexeddb" + | "session_open_failed" + // Iframe controller mode: the embedding page keeps the project. + | "host"; + +export const reportProjectStorageMode = ( + logging: Logging, + mode: ProjectStorageMode +): void => logging.setUserProperty("project_storage", mode); + /** * Opens the projects database, or explains why not. * @@ -63,13 +82,16 @@ export const openProjectsDatabase = async ( publicFacing: boolean = isPublicFacingStage() ): Promise => { if (typeof indexedDB === "undefined") { + reportProjectStorageMode(logging, "session_no_indexeddb"); return undefined; } try { const db = await ProjectsDatabase.open(); reportProjectsDatabaseActive(); + reportProjectStorageMode(logging, "database"); return db; } catch (e) { + reportProjectStorageMode(logging, "session_open_failed"); if (isVersionError(e) && !publicFacing) { reportStorageVersionError(e); } else {