Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

test(userIdService): add tests for user ID generation consistency across browser updates and different browsers

Bill Yangb9dc8143ebb1
diff --git a/server/src/services/userId/normalizeUserAgent.test.ts b/server/src/services/userId/normalizeUserAgent.test.ts
new file mode 100644
index 000000000..3ca60a223
--- /dev/null
+++ b/server/src/services/userId/normalizeUserAgent.test.ts
@@ -0,0 +1,171 @@
+import { describe, expect, it } from "vitest";
+import { normalizeUserAgentForIdentity } from "./normalizeUserAgent.js";
+
+/**
+ * Every fixture below is a real user agent captured off production ingestion
+ * (op.gg's Rybbit instance, 2026-08-18), so the pairs that must collapse are
+ * pairs that actually did split a visitor in two.
+ */
+const UA = {
+ opggElectron251:
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) opgg-electron-app/2.5.1 Chrome/132.0.6834.210 Electron/34.5.7 Safari/537.36",
+ opggElectron253:
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) opgg-electron-app/2.5.3 Chrome/142.0.7444.265 Electron/39.8.13 Safari/537.36",
+ chromeWin150:
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",
+ chromeWin151:
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36",
+ edgeWin151:
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36 Edg/151.0.0.0",
+ safariIos1857:
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.7 Mobile/15E148 Safari/604.1",
+ safariIos266:
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1",
+ safariIpad266:
+ "Mozilla/5.0 (iPad; CPU OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6 Mobile/15E148 Safari/604.1",
+ chromeIos:
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 26_0_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/151.0.7922.112 Mobile/15E148 Safari/604.1",
+ chromeIosPatched:
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 26_0_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/151.0.7922.140 Mobile/15E148 Safari/604.1",
+ macSafari:
+ "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15",
+ androidS928N:
+ "Mozilla/5.0 (Linux; Android 15; SM-S928N Build/AP3A.240905.015) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Mobile Safari/537.36",
+ androidA536N:
+ "Mozilla/5.0 (Linux; Android 15; SM-A536N Build/AP3A.240905.015) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Mobile Safari/537.36",
+ reactNative:
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) RybbitReactNative/0.1.1 8.0.14",
+ reactNativeBumped:
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 26_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) RybbitReactNative/0.2.0 8.1.0",
+ firefox: "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:153.0) Gecko/20100101 Firefox/153.0",
+ firefoxNext: "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:154.0) Gecko/20100101 Firefox/154.0",
+ // In-app browsers put hardware identifiers in the same slash-delimited slot a
+ // version normally occupies, which an over-eager rule will happily destroy.
+ fbIosPhone12:
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 [FBAN/FBIOS;FBDV/iPhone12,8;FBAV/440.0.0.32.108]",
+ fbIosPhone14:
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 [FBAN/FBIOS;FBDV/iPhone14,8;FBAV/440.0.0.32.108]",
+ fbIosPhone12Updated:
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 [FBAN/FBIOS;FBDV/iPhone12,8;FBAV/441.0.0.28.90]",
+ fbAndroidJ320F:
+ "Mozilla/5.0 (Linux; Android 9; SM-J320F) AppleWebKit/537.36 [FBAN/EMA;FBDV/SM-J320F;FBCA/armeabi-v7a:armeabi;FBAV/239.0.0.10.109]",
+ fbAndroidG930F:
+ "Mozilla/5.0 (Linux; Android 9; SM-G930F) AppleWebKit/537.36 [FBAN/EMA;FBDV/SM-G930F;FBCA/armeabi-v7a:armeabi;FBAV/239.0.0.10.109]",
+ // Two different handsets whose *model names* contain a dotted number.
+ nokia61Plus:
+ "Mozilla/5.0 (Linux; Android 10; Nokia 6.1 Plus Build/QKQ1.190828.002; wv) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.7778.178 Mobile Safari/537.36",
+ nokia83Plus:
+ "Mozilla/5.0 (Linux; Android 10; Nokia 8.3 Plus Build/QKQ1.190828.002; wv) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.7778.178 Mobile Safari/537.36",
+};
+
+const same = (a: string, b: string) => expect(normalizeUserAgentForIdentity(a)).toBe(normalizeUserAgentForIdentity(b));
+const differs = (a: string, b: string) =>
+ expect(normalizeUserAgentForIdentity(a)).not.toBe(normalizeUserAgentForIdentity(b));
+
+describe("normalizeUserAgentForIdentity", () => {
+ describe("survives updates", () => {
+ // The regression this exists for: op.gg's auto-updater flipped the whole
+ // install base to 2.5.3 inside a day (the diagnosed boundary was 2.5.2 β†’
+ // 2.5.3), re-minting every id. The captured pair below spans the same
+ // three-token move β€” app, Chromium and Electron versions all at once.
+ it("collapses an Electron app update (app, Chromium and Electron all bumped)", () => {
+ same(UA.opggElectron251, UA.opggElectron253);
+ });
+
+ it("collapses a Chrome major bump", () => same(UA.chromeWin150, UA.chromeWin151));
+
+ it("collapses an iOS point release, which moves both the OS and Safari tokens", () => {
+ same(UA.safariIos1857, UA.safariIos266);
+ });
+
+ // Chrome on iOS does not do UA reduction, so every patch used to reset it.
+ it("collapses a Chrome-on-iOS patch", () => same(UA.chromeIos, UA.chromeIosPatched));
+
+ it("collapses a Firefox bump, including the rv: revision", () => same(UA.firefox, UA.firefoxNext));
+
+ it("collapses a React Native app bump, including the bare trailing version", () => {
+ same(UA.reactNative, UA.reactNativeBumped);
+ });
+ });
+
+ describe("keeps distinct devices distinct", () => {
+ it("separates browser families on the same OS", () => differs(UA.chromeWin151, UA.edgeWin151));
+ it("separates Firefox from Chrome", () => differs(UA.chromeWin151, UA.firefox));
+ it("separates operating systems", () => differs(UA.chromeWin151, UA.macSafari));
+ it("separates iPhone from iPad", () => differs(UA.safariIos266, UA.safariIpad266));
+ it("separates Safari from Chrome on the same iPhone", () => differs(UA.safariIos266, UA.chromeIos));
+ it("separates a native app from the browser on the same OS", () => {
+ differs(UA.reactNative, UA.safariIos266);
+ });
+
+ // Android model strings carry digits but never change under the user, so
+ // they are entropy worth keeping.
+ it("keeps Android device models apart", () => differs(UA.androidS928N, UA.androidA536N));
+ });
+
+ describe("keeps hardware identifiers, which never change under the user", () => {
+ // Regression: an earlier rule elided any slash value containing a digit,
+ // turning `FBDV/iPhone12,8` into `FBDV/#,8` and fusing every iPhone model
+ // that shared a point release.
+ it("keeps the iOS device model in a Facebook in-app user agent", () => {
+ expect(normalizeUserAgentForIdentity(UA.fbIosPhone12)).toContain("FBDV/iPhone12,8");
+ });
+
+ it("separates two iPhone models behind the same in-app browser", () => {
+ differs(UA.fbIosPhone12, UA.fbIosPhone14);
+ });
+
+ it("still collapses the in-app browser's own version bump", () => {
+ same(UA.fbIosPhone12, UA.fbIosPhone12Updated);
+ });
+
+ it("keeps the Android model and CPU ABI in a Facebook in-app user agent", () => {
+ const normalized = normalizeUserAgentForIdentity(UA.fbAndroidJ320F);
+ expect(normalized).toContain("FBDV/SM-J320F");
+ expect(normalized).toContain("FBCA/armeabi-v7a:armeabi");
+ });
+
+ it("separates two Android models behind the same in-app browser", () => {
+ differs(UA.fbAndroidJ320F, UA.fbAndroidG930F);
+ });
+
+ // Regression: a two-group bare-version rule read the `6.1` in `Nokia 6.1
+ // Plus` as a version and merged it with every other dotted Nokia.
+ it("keeps a dotted marketing model name", () => {
+ expect(normalizeUserAgentForIdentity(UA.nokia61Plus)).toContain("Nokia 6.1 Plus");
+ });
+
+ it("separates two handsets whose model names differ only in their digits", () => {
+ differs(UA.nokia61Plus, UA.nokia83Plus);
+ });
+ });
+
+ describe("mechanics", () => {
+ it("elides every version token in a representative desktop UA", () => {
+ expect(normalizeUserAgentForIdentity(UA.chromeWin151)).toBe(
+ "Mozilla/# (Windows NT #; Win64; x64) AppleWebKit/# (KHTML, like Gecko) Chrome/# Safari/#"
+ );
+ });
+
+ it("keeps the Android model while eliding the OS and build", () => {
+ expect(normalizeUserAgentForIdentity(UA.androidS928N)).toBe(
+ "Mozilla/# (Linux; Android #; SM-S928N Build/#) AppleWebKit/# (KHTML, like Gecko) Chrome/# Mobile Safari/#"
+ );
+ });
+
+ it("is idempotent, so a normalized value re-normalizes to itself", () => {
+ for (const ua of Object.values(UA)) {
+ const once = normalizeUserAgentForIdentity(ua);
+ expect(normalizeUserAgentForIdentity(once)).toBe(once);
+ }
+ });
+
+ it("passes an empty user agent through untouched", () => {
+ expect(normalizeUserAgentForIdentity("")).toBe("");
+ });
+
+ it("leaves a version-free user agent alone", () => {
+ expect(normalizeUserAgentForIdentity("Mediapartners-Google")).toBe("Mediapartners-Google");
+ });
+ });
+});
diff --git a/server/src/services/userId/normalizeUserAgent.ts b/server/src/services/userId/normalizeUserAgent.ts
new file mode 100644
index 000000000..4fe6c8829
--- /dev/null
+++ b/server/src/services/userId/normalizeUserAgent.ts
@@ -0,0 +1,133 @@
+/**
+ * Strip version numbers out of a user agent so the anonymous fingerprint
+ * survives a browser or app update.
+ *
+ * `generateUserId` hashes the raw user agent, so every byte of it is part of a
+ * visitor's identity β€” including the version tokens that change every time
+ * their browser or app updates. An update therefore mints a brand-new "user"
+ * for the same person on the same machine.
+ *
+ * On the web that damage is invisible because vendors stagger rollouts: the
+ * resets dribble in over weeks and read as ordinary new-visitor acquisition.
+ * It becomes obvious when an update is *synchronised* β€” an Electron app whose
+ * auto-updater flips the whole install base inside a day re-mints every
+ * identity at once, so any reporting window spanning the release counts each
+ * machine twice (measured on op.gg's desktop app, 2026-08-14: `user_id`
+ * overlap across the release boundary fell to 1.6%, and identity survived only
+ * for the machines that had *not* updated).
+ *
+ * The fix is to hash a version-free view of the user agent. What we remove is
+ * exactly what an update changes:
+ *
+ * - numeric version tokens after a slash β€” `Chrome/151.0.0.0`,
+ * `Firefox/153.0`, `Edg/143.0.0.0`, `CriOS/151.0.7922.112`,
+ * `Electron/39.8.13`, `Version/26.6`
+ * - alphanumeric build ids under a known key β€” `Mobile/15E148`,
+ * `Build/UP1A.231005.007`
+ * - Gecko's `rv:153.0`
+ * - OS versions β€” `Windows NT 10.0`, `Android 15`, `CPU iPhone OS 26_6`,
+ * `Mac OS X 10_15_7`, `CrOS x86_64 14541.0.0`
+ *
+ * What we deliberately keep is everything that identifies the *device* rather
+ * than its patch level: product names (`Chrome`, `CriOS`, `Edg`,
+ * `opgg-electron-app`), form factor (`iPhone`, `iPad`, `Mobile`, `Macintosh`),
+ * architecture (`Win64; x64`, `Intel`), and Android device models
+ * (`SM-S928N`), hardware identifiers that sit where a version usually does
+ * (`FBDV/SM-J320F`, `FBCA/armeabi-v7a`), and two-part marketing model names
+ * (`Nokia 6.1 Plus`) β€” all of which carry digits but never change under the
+ * user.
+
+ * It is a heuristic, and it errs toward *missing* a version rather than
+ * eliding a device token: a miss leaves today's behaviour (identity resets on
+ * that update), while an over-elision actively fuses two people who were
+ * previously counted apart. Some exotic native-app agents still reset β€”
+ * Instagram's trailing bare APK version code, for one β€” which is part of why a
+ * persistent client id (`anonymous_id`) remains the durable fix.
+ *
+ * This trades splitting for merging, the same trade `bucketIpForIdentity`
+ * already makes: visitors who share an IP and a device class collapse into one
+ * user, where before one visitor exploded into several across time. Merging
+ * costs a headline number; splitting corrupts sessions, retention and
+ * acquisition alike.
+ *
+ * Identity only. Reporting keeps parsing the raw user agent, so the browser and
+ * OS *versions* shown in the dashboard are unaffected.
+ */
+
+/**
+ * A slash-delimited *numeric* version: `Chrome/151.0.0.0`, `Version/26.6`,
+ * `AppleWebKit/605.1.15`, `FBAV/440.0.0.32.108`, `MyApp/v2.3.1`.
+ *
+ * Deliberately numeric-only. An earlier draft elided any slash value that
+ * merely *contained* a digit, which silently ate hardware identifiers that sit
+ * in the same position and never change under the user β€” Facebook's
+ * `FBDV/SM-J320F` (the Android `Build.MODEL`) and `FBCA/armeabi-v7a` (the CPU
+ * ABI). Worse, `FBDV/iPhone12,8` became `FBDV/#,8`, collapsing every iPhone
+ * model onto its point release and merging genuinely different phones.
+ * Preserving anything non-numeric costs a few missed version tokens; the
+ * alternative cost was fusing distinct devices, which is the failure this
+ * whole module exists to prevent.
+ */
+const SLASHED_VERSION = /\/v?[0-9]+(?:[._][0-9]+)*/g;
+
+/**
+ * Build identifiers, which are alphanumeric rather than numeric and so fall
+ * outside `SLASHED_VERSION`, but do change on every OS update:
+ * `Build/UP1A.231005.007`, `Mobile/15E148`. Matched by key, because only these
+ * keys are unambiguous β€” a bare alphanumeric token elsewhere is far more likely
+ * to be a model name.
+ */
+const SLASHED_BUILD = /\b(Build|Mobile)\/[0-9A-Za-z._-]+/g;
+
+/** Gecko's `rv:153.0` revision token. */
+const GECKO_REVISION = /\brv:[0-9][0-9._]*/g;
+
+/**
+ * A bare, space-delimited dotted version β€” the trailing `8.0.14` in
+ * `RybbitReactNative/0.1.1 8.0.14`, or Instagram's `76.0.0.15.395`.
+ *
+ * Three numeric groups minimum. Two would also match `Nokia 6.1 Plus` and
+ * `Nokia 8.3 Plus`, whose `6.1` and `8.3` are *model* names β€” eliding them
+ * merges two different handsets. Marketing names stop at two components;
+ * software versions in this position generally have three or more. Applied
+ * last, once the slash and OS rules have claimed the versions they own.
+ */
+const BARE_VERSION = /(?<=^|[ (;])[0-9]+(?:\.[0-9]+){2,}(?=$|[ );])/g;
+
+/**
+ * OS version numbers, matched only where an OS name introduces them so that
+ * device models keep their digits. `_` separators cover Apple's `10_15_7`
+ * style; the trailing `x86_64`-aware form covers ChromeOS.
+ */
+const OS_VERSIONS: RegExp[] = [
+ /\b(Windows NT) [0-9][0-9._]*/g,
+ /\b(Windows Phone(?: OS)?) [0-9][0-9._]*/g,
+ /\b(Android)[ /][0-9][0-9._]*/g,
+ /\b(CPU(?: iPhone)? OS) [0-9][0-9._]*/g,
+ /\b(Mac OS X) [0-9][0-9._]*/g,
+ /\b(CrOS [^ )]+) [0-9][0-9._]*/g,
+];
+
+/** Placeholder standing in for every elided version. */
+const ELIDED = "#";
+
+/**
+ * The identity-bearing view of a user agent: the same string with every version
+ * number replaced by `#`.
+ *
+ * Pure and allocation-light β€” this runs once per ingested event.
+ */
+export function normalizeUserAgentForIdentity(userAgent: string): string {
+ if (!userAgent) return userAgent;
+
+ let normalized = userAgent
+ .replace(SLASHED_VERSION, `/${ELIDED}`)
+ .replace(SLASHED_BUILD, `$1/${ELIDED}`)
+ .replace(GECKO_REVISION, `rv:${ELIDED}`);
+
+ for (const pattern of OS_VERSIONS) {
+ normalized = normalized.replace(pattern, `$1 ${ELIDED}`);
+ }
+
+ return normalized.replace(BARE_VERSION, ELIDED);
+}
diff --git a/server/src/services/userId/userIdService.test.ts b/server/src/services/userId/userIdService.test.ts
index 1017569a9..1324e6b35 100644
--- a/server/src/services/userId/userIdService.test.ts
+++ b/server/src/services/userId/userIdService.test.ts
@@ -130,4 +130,56 @@ describe("userIdService", () => {
expect(dayTwo).toBe(dayOne);
});
+
+ // A browser or app update changes the version tokens in the user agent. Those
+ // are stripped before hashing, so the same machine keeps its identity instead
+ // of being counted as a second visitor.
+ it("keeps one identity across a browser update", async () => {
+ const before = await userIdService.generateUserId(
+ "198.51.100.10",
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/150.0.0.0 Safari/537.36",
+ 42,
+ { saltUserIds: false }
+ );
+ const after = await userIdService.generateUserId(
+ "198.51.100.10",
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36",
+ 42,
+ { saltUserIds: false }
+ );
+
+ expect(after).toBe(before);
+ });
+
+ it("still separates different browsers on one IP", async () => {
+ const chrome = await userIdService.generateUserId(
+ "198.51.100.10",
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36",
+ 42,
+ { saltUserIds: false }
+ );
+ const firefox = await userIdService.generateUserId(
+ "198.51.100.10",
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:153.0) Gecko/20100101 Firefox/153.0",
+ 42,
+ { saltUserIds: false }
+ );
+
+ expect(firefox).not.toBe(chrome);
+ });
+
+ // Sticky re-attachment keys its candidate pool on the user agent it is given,
+ // and it keeps receiving the raw string. Handing it the normalized one would
+ // pool every version variant together, which cuts both ways: a pool that was
+ // empty can become a single candidate (a new, unreviewed re-attachment) just
+ // as easily as a single candidate can become several (an abstention). Sticky
+ // is a separate merge decision with its own evidence bar, so it stays on the
+ // exact string it was designed and measured against.
+ it("hands sticky re-attachment the raw user agent, not the normalized one", async () => {
+ const userAgent =
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36";
+ await userIdService.generateUserId("198.51.100.10", userAgent, 42, { saltUserIds: false });
+
+ expect(mocks.resolveStickyUserId).toHaveBeenCalledWith(expect.objectContaining({ userAgent }));
+ });
});
diff --git a/server/src/services/userId/userIdService.ts b/server/src/services/userId/userIdService.ts
index d55b78169..f8c71b582 100644
--- a/server/src/services/userId/userIdService.ts
+++ b/server/src/services/userId/userIdService.ts
@@ -4,6 +4,7 @@ import { SECRET } from "../../lib/const.js";
import { siteConfig } from "../../lib/siteConfig.js";
import { isDatacenterAsn } from "../tracker/botBlocking/datacenterAsns.js";
import { bucketIpForIdentity } from "./identityIpBucket.js";
+import { normalizeUserAgentForIdentity } from "./normalizeUserAgent.js";
import { resolveStickyUserId } from "./stickyUserId.js";
export interface UserIdOptions {
@@ -80,6 +81,12 @@ class UserIdService {
* Generate a user ID based on IP and user agent
* If the site has salting enabled, also includes a daily rotating salt
*
+ * The user agent is version-stripped before hashing, so a browser or app
+ * update doesn't mint a new identity for the same machine β€” see
+ * `normalizeUserAgentForIdentity`. The raw string is still what reporting
+ * parses, and still what sticky re-attachment matches on, so only the
+ * fingerprint changes.
+ *
* @param ip User's IP address
* @param userAgent User's user agent string
* @param siteId The site ID to check for salting configuration
@@ -94,12 +101,17 @@ class UserIdService {
// between requests; hash a coarse bucket so one visitor stays one user.
const identityIp = bucketIpForIdentity(ip, isDatacenterEgress);
+ // Version tokens change under the user on every browser or app update, so
+ // they are stripped before hashing β€” otherwise an update splits one visitor
+ // into two, all at once when the update is a synchronised app rollout.
+ const identityUserAgent = normalizeUserAgentForIdentity(userAgent);
+
// The event's own day, fixed before anything is hashed against it.
const saltDay = utcDayOf(options.receivedAt ?? new Date());
const salted = await this.isSalted(siteId, options);
const rawUserId = crypto
.createHash("sha256")
- .update(identityIp + userAgent + (salted ? this.getDailySalt(saltDay) : ""))
+ .update(identityIp + identityUserAgent + (salted ? this.getDailySalt(saltDay) : ""))
.digest("hex")
.substring(0, 12);