[MVP] Windows installer funnel telemetry (off by default)
MVP for Ilia's review. Do not merge. It needs a GDPR/compliance review before any release build turns it on.
Summary
Users log in on the dashboard but drop off before the desktop app is installed and running. This PR adds anonymous funnel events so that we can see where a Windows install stops.
| Event | Sent by | When |
|---|---|---|
desktop_installer_download_clicked | dashboard, Edison-Watch/edison-watch#1846 | A desktop app download button is clicked |
installer_started | NSIS installer | End of .onInit |
installer_step install_clicked | NSIS installer | The user leaves the folder page |
installer_step old_version_handled + exit_code | NSIS installer | The previous version's uninstaller finished (also fires on a fresh install) |
installer_step files_installed | NSIS installer | End of the install section |
installer_finished success / failed / cancelled (+ exit_code / error_level / blocking_dialog) | NSIS installer | The wizard closes or the install fails |
installer_previous_run_incomplete | NSIS installer | The next run finds an earlier run that never finished (hard Quit paths, killed process) |
app_first_launch | app main process | First start after install, with the same install_id |
- Off by default. It is compiled in only when
SG_INSTALL_TELEMETRY_URLandSG_INSTALL_TELEMETRY_KEYare set at build time (scripts/installer-telemetry-config.mjswrites a git-ignored include; thebuild:win*scripts run it first). Without them, the installer logic is unchanged. No CI workflow sets them, so dev, demo and release all stay off until the review. - Own PostHog project. The events go to a separate installer funnel project with "Discard client IP data" on, never to the dashboard project. The docs list the settings to create ("Setting up the PostHog project").
- Anonymous.
install_idis a random GUID for each installer run. Events set$process_person_profile: falseand$geoip_disable: true. No user, machine, path or account data is sent. - Cannot hang the install. The installer sends with WinHTTP in-process and uses the user's proxy settings. Timeouts are 1 to 1.5 s, including the separate response-header timeout, which defaults to 90 s. After one failed send, or one that takes over 1 s, the run sends nothing more. The app uses
net.fetchwith a 3 s timeout and does not block startup. - Opt-out:
/NOTELEMETRY,DO_NOT_TRACK=1orSEALGATE_NO_TELEMETRY=1. The app also sends nothing forcustom,localanddevbackends.
The full design, privacy notes, known gaps and a manual Windows VM test plan (cases A to N) are in packages/desktop/docs/installer-telemetry.md.
Per-download id
The edison-watch side (being built on #1846) serves the installer as SealGate-<ver>-<arch>-setup_dl-<16 hex>.exe, with a random id per download. The id is not stored and not linked to the user.
- The installer reads the id from its own file name. A browser
(1)suffix does not matter. - Fallback: the same
_dl-<id>token in theHostUrlorReferrerUrlline of its Zone.Identifier stream. - With an id, every installer event carries
download_idanddownload_id_source, and the marker passes both toapp_first_launch. - No id, or a malformed one, sends no field and changes nothing else.
Dashboard side
This is Edison-Watch/edison-watch#1846. It instruments the shared downloadClient helper, with the properties platform, found, app_version and asset. The per-download id joins the download to the install for each download. The dashboard event that is linked to the logged-in user does not carry the id.
Findings
- electron-builder's hard
Quitpaths ("SealGate cannot be closed", locked files, decompression failed) skip all NSIS callbacks. They are now reported on the next attempt asinstaller_previous_run_incomplete. - If the old uninstaller fails, electron-builder shows a
MessageBoxwith no/SDdefault, so a silent auto-update can wait on a dialog. The event carriesblocking_dialog=true. The fix is the separate PR #142. Both PRs definecustomUnInstallCheck, so the second to merge gets a small conflict, which I will resolve. customUnInstallCheckreplaces electron-builder's default handling of the uninstaller result. The macro reproduces the app-builder-lib 26.x default, andnsisUninstallCheck.test.tspins the upstream function.
Code review
A strict maintainability review ran on the diff. Fixed in f76282d:
- The
build:win*scripts now regenerate the config, so a stale test endpoint cannot ship. seconds_since_installis now correct on retries.installer.nshis now the one owner of the electron-builder hooks.- The upstream-copy pin test.
- The slow-send breaker.
upgradeno longer depends on the/currentuserflag.- No run record in the UAC inner instance.
- The step is renamed to
old_version_handled. - The app send is simpler.
Not taken: the app does not move to the env-config PostHog key. The marker keeps the installer's endpoint, so that the installer and the app always report to the same project.
Test plan
-
npm run typecheck,npx vitest run: 230 tests pass, 20 of them new. - Cross-built the NSIS installer on Linux (electron-builder + wine,
-WX), with telemetry on and off. - Under wine, against a local mock endpoint (
scripts/mock-capture-server.mjs), never the production PostHog or Sentry:- The clean install sends all steps and
success. The upgrade sendsupgrade=true. The cancel sendscancelled. - The forced old-uninstaller failure sends
failedwithexit_code=1. - A killed run is reported by the next run.
- The telemetry-off build,
/NOTELEMETRYandDO_NOT_TRACKall send 0 events. - A refused connection adds no time. An endpoint that never answers adds about 2 s and gets one request only.
- Download id from the file name:
_dl-<16 hex>: found.- With a
(1)suffix: found. - Plain name, a non-hex character, 17 digits: no field.
- The full flow from download to first launch carries one id.
- The clean install sends all steps and
-
app_first_launch: Electron's main loop hangs under wine, so this step ran on the Linux build of the same app, reading the marker that the wine install wrote. - Manual run on a real Windows VM (docs, cases A to N). Case N, the Zone.Identifier fallback, cannot run under wine.
š¤ Generated with Claude Code