From 0528823eb86d22f82f2073bcc14ed178a3bee8d5 Mon Sep 17 00:00:00 2001 From: Ryan Parry Date: Thu, 19 Nov 2026 17:00:48 +0000 Subject: [PATCH] Keep each install in one Unleash experiment cohort across launches (STA-574) Unleash keeps a user in a percentage-rollout group by `userId`, falling back to a `sessionId` that changes every launch, so a logged-out install would get a new cohort each time it opened. The main process now sends `properties[experimentCohortHash]` on every flag fetch: a salted SHA-256 of the install's instance ID, which can't be matched to the raw ID. A rollout can then use it for stickiness. Needs Trust & Safety sign-off before release: it's a stable per-install ID, sent regardless of analytics consent. Co-Authored-By: Claude Opus 5.5 --- src/main/src/Application.ts | 6 +++++ src/main/src/unleash/client.test.ts | 27 +++++++++++++++++++ src/main/src/unleash/client.ts | 12 ++++++++- src/main/src/unleash/experimentCohort.test.ts | 23 ++++++++++++++++ src/main/src/unleash/experimentCohort.ts | 14 ++++++++++ 5 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 src/main/src/unleash/experimentCohort.test.ts create mode 100644 src/main/src/unleash/experimentCohort.ts diff --git a/src/main/src/Application.ts b/src/main/src/Application.ts index 64ca539083..4019a3a194 100644 --- a/src/main/src/Application.ts +++ b/src/main/src/Application.ts @@ -53,6 +53,7 @@ import SubPersistor from "./store/SubPersistor"; import { isTelemetryEnabled, setTelemetryEnabled, setTelemetryInstanceId } from "./telemetry/state"; import TrayIcon from "./TrayIcon"; import { UnleashClient } from "./unleash/client"; +import { experimentCohortHash } from "./unleash/experimentCohort"; import { synchronizeFeatureFlags } from "./unleash/ipc"; /** test if the running version is a major downgrade (downgrading by a major or minor version, @@ -522,6 +523,11 @@ class Application { unleashClient.setContext({ userId: String(storedUserId) }); } + // Experiment cohorts. Needs Trust & Safety sign-off before release: see unleash/experimentCohort.ts. + if (this.mAppMetadata?.instanceId !== undefined) { + unleashClient.setExperimentCohortHash(experimentCohortHash(this.mAppMetadata.instanceId)); + } + synchronizeFeatureFlags(unleashClient); // Collect metadata before creating the main window — the renderer diff --git a/src/main/src/unleash/client.test.ts b/src/main/src/unleash/client.test.ts index 47f11e152b..09765d1056 100644 --- a/src/main/src/unleash/client.test.ts +++ b/src/main/src/unleash/client.test.ts @@ -187,6 +187,33 @@ describe("UnleashClient", () => { const params = await fetchedParams("1.0.0"); expect(params.has("userId")).toBe(false); }); + + it("omits the experiment-cohort hash when not set", async () => { + const params = await fetchedParams("1.0.0"); + expect(params.has("properties[experimentCohortHash]")).toBe(false); + }); + + it("sends the experiment-cohort hash under properties once set", async () => { + fetchMocker.mockResponseOnce(toggleBody([])); + const client = new UnleashClient("1.0.0"); + client.setExperimentCohortHash("abc123"); + await client.fetchFeatureFlags(); + + const params = new URLSearchParams(new URL(fetchMocker.requests()[0]!.url).search); + expect(params.get("properties[experimentCohortHash]")).toBe("abc123"); + }); + + it("keeps the experiment-cohort hash when the renderer sets the context", async () => { + fetchMocker.mockResponseOnce(toggleBody([])); + const client = new UnleashClient("1.0.0"); + client.setExperimentCohortHash("abc123"); + client.setContext({ userId: "42" }); + await client.fetchFeatureFlags(); + + const params = new URLSearchParams(new URL(fetchMocker.requests()[0]!.url).search); + expect(params.get("userId")).toBe("42"); + expect(params.get("properties[experimentCohortHash]")).toBe("abc123"); + }); }); // ============================================================ diff --git a/src/main/src/unleash/client.ts b/src/main/src/unleash/client.ts index a56a2f5466..568f19b72e 100644 --- a/src/main/src/unleash/client.ts +++ b/src/main/src/unleash/client.ts @@ -23,6 +23,7 @@ type UnleashContext = { appVersion: string; os: ReturnType; channel: "beta" | "stable"; + experimentCohortHash?: string; }; }; @@ -61,6 +62,7 @@ export class UnleashClient { #flags: FeatureFlag[] = []; #context: FlagContext = {}; + #experimentCohortHash: string | undefined; constructor(appVersion: string, options?: UnleashClientOptions) { this.#sessionId = randomUUID(); @@ -148,6 +150,11 @@ export class UnleashClient { this.#context = context; } + /** See experimentCohort.ts. */ + setExperimentCohortHash(hash: string): void { + this.#experimentCohortHash = hash; + } + async postMetrics(bucket: FlagMetricsBucket): Promise { const result = await this.#apiClient.POST("/api/frontend/client/metrics", { body: { @@ -256,6 +263,9 @@ export class UnleashClient { appVersion: this.#appVersion, os: platform(), channel: this.#channel, + ...(this.#experimentCohortHash !== undefined && { + experimentCohortHash: this.#experimentCohortHash, + }), }, }; } @@ -279,7 +289,7 @@ function serializeContext(context: UnleashContext): string { if (context.userId) params.set("userId", context.userId); for (const [key, value] of Object.entries(context.properties)) { - params.set(`properties[${key}]`, value); + if (value !== undefined) params.set(`properties[${key}]`, value); } return params.toString(); diff --git a/src/main/src/unleash/experimentCohort.test.ts b/src/main/src/unleash/experimentCohort.test.ts new file mode 100644 index 0000000000..0db171a286 --- /dev/null +++ b/src/main/src/unleash/experimentCohort.test.ts @@ -0,0 +1,23 @@ +import { describe, expect, it } from "vitest"; + +import { experimentCohortHash } from "./experimentCohort"; + +const INSTANCE_ID = "3f2b8c1e-4d5a-4f6b-9c7d-8e9f0a1b2c3d"; + +describe("experimentCohortHash", () => { + it("gives the same install the same hash every time", () => { + expect(experimentCohortHash(INSTANCE_ID)).toBe(experimentCohortHash(INSTANCE_ID)); + }); + + it("gives different installs different hashes", () => { + expect(experimentCohortHash(INSTANCE_ID)).not.toBe( + experimentCohortHash("00000000-0000-4000-8000-000000000000"), + ); + }); + + it("never contains the instance ID itself", () => { + const hash = experimentCohortHash(INSTANCE_ID); + expect(hash).toMatch(/^[0-9a-f]{64}$/); + expect(hash).not.toContain(INSTANCE_ID); + }); +}); diff --git a/src/main/src/unleash/experimentCohort.ts b/src/main/src/unleash/experimentCohort.ts new file mode 100644 index 0000000000..60cfbc8e37 --- /dev/null +++ b/src/main/src/unleash/experimentCohort.ts @@ -0,0 +1,14 @@ +import { createHash } from "node:crypto"; + +// TRUST & SAFETY SIGN-OFF REQUIRED before release: a stable per-install ID sent to Unleash on every +// flag fetch, regardless of analytics consent. It keeps an install in one experiment cohort across +// launches; without it, logged-out installs fall back to a per-launch sessionId. Salted, so it +// can't be matched to the raw instance ID. + +const SALT = "vortex-experiment-cohort:"; + +/** The install's experiment-cohort hash: hex SHA-256 of the salted instance ID. */ +export const experimentCohortHash = (instanceId: string): string => + createHash("sha256") + .update(SALT + instanceId) + .digest("hex");