feat: enrich segment download events with client fingerprint signals (#448)

juanmahidalgo · web-flow · commit 7e25bf9372f6 · 2026-05-11T14:27:12.000+02:00
diff --git a/src/modules/fingerprint.test.ts b/src/modules/fingerprint.test.ts
@@ -0,0 +1,90 @@
+// Asserts the snake_case analytics field names produced by the module.
+/* eslint-disable @typescript-eslint/naming-convention */
+import { collectClientFingerprint } from './fingerprint'
+
+describe('collectClientFingerprint', () => {
+  let originalScreen: PropertyDescriptor | undefined
+  let originalDpr: PropertyDescriptor | undefined
+  let originalNavigatorLanguage: PropertyDescriptor | undefined
+  let originalHardwareConcurrency: PropertyDescriptor | undefined
+  let originalPlatform: PropertyDescriptor | undefined
+
+  beforeEach(() => {
+    originalScreen = Object.getOwnPropertyDescriptor(window, 'screen')
+    originalDpr = Object.getOwnPropertyDescriptor(window, 'devicePixelRatio')
+    originalNavigatorLanguage = Object.getOwnPropertyDescriptor(window.navigator, 'language')
+    originalHardwareConcurrency = Object.getOwnPropertyDescriptor(window.navigator, 'hardwareConcurrency')
+    originalPlatform = Object.getOwnPropertyDescriptor(window.navigator, 'platform')
+  })
+
+  afterEach(() => {
+    if (originalScreen) Object.defineProperty(window, 'screen', originalScreen)
+    if (originalDpr) Object.defineProperty(window, 'devicePixelRatio', originalDpr)
+    if (originalNavigatorLanguage) Object.defineProperty(window.navigator, 'language', originalNavigatorLanguage)
+    if (originalHardwareConcurrency) Object.defineProperty(window.navigator, 'hardwareConcurrency', originalHardwareConcurrency)
+    if (originalPlatform) Object.defineProperty(window.navigator, 'platform', originalPlatform)
+  })
+
+  describe('when called in a normal browser environment', () => {
+    beforeEach(() => {
+      Object.defineProperty(window, 'screen', {
+        configurable: true,
+        value: { width: 1920, height: 1080, colorDepth: 24 }
+      })
+      Object.defineProperty(window, 'devicePixelRatio', { configurable: true, value: 2 })
+      Object.defineProperty(window.navigator, 'language', { configurable: true, value: 'en-US' })
+      Object.defineProperty(window.navigator, 'hardwareConcurrency', { configurable: true, value: 8 })
+      Object.defineProperty(window.navigator, 'platform', { configurable: true, value: 'MacIntel' })
+    })
+
+    it('should populate every field from the browser primitives', () => {
+      const fp = collectClientFingerprint()
+
+      expect(fp).not.toBeNull()
+      expect(fp).toMatchObject({
+        screen_width: 1920,
+        screen_height: 1080,
+        device_pixel_ratio: 2,
+        color_depth: 24,
+        hardware_concurrency: 8,
+        language: 'en-US',
+        platform: 'MacIntel'
+      })
+    })
+
+    it('should include the IANA timezone when Intl exposes it', () => {
+      const fp = collectClientFingerprint()
+      // jsdom resolves to a real timezone (host's). We just assert it's a string.
+      expect(typeof fp?.timezone).toBe('string')
+      expect(fp?.timezone?.length ?? 0).toBeGreaterThan(0)
+    })
+
+    it('should report the timezone offset as a number', () => {
+      const fp = collectClientFingerprint()
+      expect(typeof fp?.timezone_offset_minutes).toBe('number')
+      expect(Number.isFinite(fp?.timezone_offset_minutes)).toBe(true)
+    })
+  })
+
+  describe('when individual browser fields are missing', () => {
+    it('should fall back to safe defaults rather than crashing', () => {
+      Object.defineProperty(window, 'screen', { configurable: true, value: undefined })
+      Object.defineProperty(window, 'devicePixelRatio', { configurable: true, value: undefined })
+      Object.defineProperty(window.navigator, 'hardwareConcurrency', { configurable: true, value: undefined })
+      Object.defineProperty(window.navigator, 'language', { configurable: true, value: undefined })
+      Object.defineProperty(window.navigator, 'platform', { configurable: true, value: undefined })
+
+      const fp = collectClientFingerprint()
+
+      expect(fp).toMatchObject({
+        screen_width: 0,
+        screen_height: 0,
+        device_pixel_ratio: 1,
+        color_depth: 0,
+        hardware_concurrency: 0,
+        language: null,
+        platform: null
+      })
+    })
+  })
+})
diff --git a/src/modules/fingerprint.ts b/src/modules/fingerprint.ts
@@ -0,0 +1,81 @@
+// Field names are deliberately snake_case to match the analytics event
+// contract used end-to-end (Segment events, data warehouse columns, the
+// Rust launcher's emitter). The `naming-convention` rule is camelCase by
+// default in this repo; opt out for this module so we don't keep adding
+// per-line eslint-disable comments.
+/* eslint-disable @typescript-eslint/naming-convention */
+
+/**
+ * Stable signals about the user's environment that the launcher (running
+ * as a desktop app on the same machine) can also read from the OS, so a
+ * data warehouse can join landing-site events with launcher install events
+ * without an embedded user-level identifier.
+ *
+ * We don't try to be unique per user — we collect a handful of features
+ * that, combined with the user's IP and event timestamp, narrow down the
+ * matching window to a manageable set of candidates. The actual scoring
+ * lives in the data team's Segment Functions / SQL join.
+ *
+ * Field names use snake_case to match the convention used by the launcher
+ * Segment client (Rust / `analytics_queue.db`), so the join columns line
+ * up without renaming.
+ */
+interface ClientFingerprint {
+  /** Primary monitor width in CSS pixels. */
+  screen_width: number
+  /** Primary monitor height in CSS pixels. */
+  screen_height: number
+  /** Device pixel ratio (e.g. `2` on Retina, `1` on standard). */
+  device_pixel_ratio: number
+  /** Bits per pixel for the primary display. */
+  color_depth: number
+  /** Logical CPU cores reported by the browser, capped at 8 by some browsers. */
+  hardware_concurrency: number
+  /** IANA timezone name when available (e.g. `America/Argentina/Buenos_Aires`). */
+  timezone: string | null
+  /** Minutes offset from UTC at the moment of the call (negative for east of UTC). */
+  timezone_offset_minutes: number
+  /** Primary `navigator.language` (e.g. `en-US`). */
+  language: string | null
+  /**
+   * `navigator.platform` value. Deprecated and increasingly browser-locked,
+   * but still a useful low-cardinality signal (`Win32`, `MacIntel`, `Linux x86_64`).
+   * Fall back to `null` if unavailable.
+   */
+  platform: string | null
+}
+
+/**
+ * Returns a snapshot of the current browser/device fingerprint signals.
+ * Safe to call from anywhere in the page lifecycle — no I/O, no async.
+ *
+ * Returns `null` only if `window`/`navigator` are unavailable (SSR / unit
+ * tests); callers should be tolerant of that case rather than crashing.
+ */
+function collectClientFingerprint(): ClientFingerprint | null {
+  if (typeof window === 'undefined' || typeof navigator === 'undefined') {
+    return null
+  }
+
+  let timezone: string | null = null
+  try {
+    timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || null
+  } catch {
+    // Old browsers / locked-down environments may throw — falls back to null.
+  }
+
+  return {
+    screen_width: window.screen?.width ?? 0,
+    screen_height: window.screen?.height ?? 0,
+    device_pixel_ratio: window.devicePixelRatio ?? 1,
+    color_depth: window.screen?.colorDepth ?? 0,
+    hardware_concurrency: navigator.hardwareConcurrency ?? 0,
+    timezone,
+    timezone_offset_minutes: new Date().getTimezoneOffset(),
+    language: navigator.language ?? null,
+    platform: navigator.platform ?? null
+  }
+}
+
+export { collectClientFingerprint }
+export type { ClientFingerprint }
diff --git a/src/pages/DownloadSuccess/DownloadSuccess.spec.tsx b/src/pages/DownloadSuccess/DownloadSuccess.spec.tsx
@@ -93,26 +93,53 @@ describe('when DownloadSuccess mounts with os, place, and a successful url resol
     render(<DownloadSuccess />)
 
     await waitFor(() => {
-      expect(mockTrack).toHaveBeenCalledWith('download_started', {
-        place: 'landing-hero',
-        href: 'https://cdn.decentraland.org/launcher/Install-Decentraland.exe',
-
-        auth_state: 'anonymous'
-      })
+      expect(mockTrack).toHaveBeenCalledWith(
+        'download_started',
+        expect.objectContaining({
+          place: 'landing-hero',
+          href: 'https://cdn.decentraland.org/launcher/Install-Decentraland.exe',
+          auth_state: 'anonymous'
+        })
+      )
     })
   })
 
   it('should fire download_success with place, the resolved href, and filename', async () => {
     render(<DownloadSuccess />)
 
     await waitFor(() => {
-      expect(mockTrack).toHaveBeenCalledWith('download_success', {
-        place: 'landing-hero',
-        href: 'https://cdn.decentraland.org/launcher/signed/Install-Decentraland.exe?sig=abc',
-        filename: 'Install-Decentraland.exe',
+      expect(mockTrack).toHaveBeenCalledWith(
+        'download_success',
+        expect.objectContaining({
+          place: 'landing-hero',
+          href: 'https://cdn.decentraland.org/launcher/signed/Install-Decentraland.exe?sig=abc',
+          filename: 'Install-Decentraland.exe',
+          auth_state: 'anonymous'
+        })
+      )
+    })
+  })
 
-        auth_state: 'anonymous'
-      })
+  it('should include the client fingerprint fields on download_success for server-side attribution', async () => {
+    render(<DownloadSuccess />)
+
+    await waitFor(() => {
+      expect(mockTrack).toHaveBeenCalledWith(
+        'download_success',
+        expect.objectContaining({
+          screen_width: expect.any(Number),
+
+          screen_height: expect.any(Number),
+
+          device_pixel_ratio: expect.any(Number),
+
+          color_depth: expect.any(Number),
+
+          hardware_concurrency: expect.any(Number),
+
+          timezone_offset_minutes: expect.any(Number)
+        })
+      )
     })
   })
 
@@ -238,12 +265,14 @@ describe('when DownloadSuccess mounts and the url resolution rejects', () => {
     render(<DownloadSuccess />)
 
     await waitFor(() => {
-      expect(mockTrack).toHaveBeenCalledWith('download_failed', {
-        place: 'download-page',
-        href: 'https://cdn.decentraland.org/launcher/Install-Decentraland.exe',
-
-        auth_state: 'anonymous'
-      })
+      expect(mockTrack).toHaveBeenCalledWith(
+        'download_failed',
+        expect.objectContaining({
+          place: 'download-page',
+          href: 'https://cdn.decentraland.org/launcher/Install-Decentraland.exe',
+          auth_state: 'anonymous'
+        })
+      )
     })
   })
 })
diff --git a/src/pages/DownloadSuccess/DownloadSuccess.tsx b/src/pages/DownloadSuccess/DownloadSuccess.tsx
@@ -15,6 +15,7 @@ import windowsLaunchingDecentraland from '../../images/download/windows_launchin
 import windowsSetup from '../../images/download/windows_setup.webp'
 import microsoftLogo from '../../images/microsoft-logo.svg'
 import { calculateDownloadUrl } from '../../modules/downloadWithIdentity'
+import { collectClientFingerprint } from '../../modules/fingerprint'
 import { DownloadPlace, SectionViewedTrack, SegmentEvent, resolveDownloadPlace } from '../../modules/segment'
 import { streamOrFallback } from '../../modules/streamOrFallback'
 import { FALLBACK_CDN_RELEASE_LINKS, addQueryParamsToUrlString } from '../../modules/url'
@@ -221,23 +222,30 @@ const DownloadSuccess = memo(() => {
       // "the file finished downloading" rather than "the user clicked".
       // If the transfer fails the .catch() below fires DOWNLOAD_FAILED
       // instead, so success/failed are mutually exclusive.
+      //
+      // The `fingerprint` payload below is what the data team's server-side
+      // join uses to match this download with the launcher's first-run
+      // event from the same machine — see the IP + heuristic fingerprint
+      // attribution doc.
+      const fingerprint = collectClientFingerprint()
       await waitForAnalytics()
       if (signal.aborted || !isInitializedRef.current) return
       // eslint-disable-next-line @typescript-eslint/naming-convention
-      trackRef.current(SegmentEvent.DOWNLOAD_STARTED, { place, href: osLink, auth_state: authStateRef.current })
+      trackRef.current(SegmentEvent.DOWNLOAD_STARTED, { place, href: osLink, auth_state: authStateRef.current, ...fingerprint })
       // eslint-disable-next-line @typescript-eslint/naming-convention
-      trackRef.current(SegmentEvent.DOWNLOAD_SUCCESS, { place, href: url, filename, auth_state: authStateRef.current })
+      trackRef.current(SegmentEvent.DOWNLOAD_SUCCESS, { place, href: url, filename, auth_state: authStateRef.current, ...fingerprint })
     }
 
     startDownload()
       .catch(async error => {
         if (signal.aborted) return
         console.error('Download error:', error)
         setDownloadError(error instanceof Error ? error.message : 'Download failed')
+        const fingerprint = collectClientFingerprint()
         await waitForAnalytics()
         if (signal.aborted || !isInitializedRef.current) return
         // eslint-disable-next-line @typescript-eslint/naming-convention
-        trackRef.current(SegmentEvent.DOWNLOAD_FAILED, { place, href: osLink, auth_state: authStateRef.current })
+        trackRef.current(SegmentEvent.DOWNLOAD_FAILED, { place, href: osLink, auth_state: authStateRef.current, ...fingerprint })
       })
       .finally(() => {
         if (!signal.aborted) {
@@ -267,9 +275,10 @@ const DownloadSuccess = memo(() => {
       const footerPlace = DownloadPlace.DOWNLOAD_SUCCESS_FOOTER
       // Re-download from the footer link is its own funnel event so analytics
       // can distinguish it from the auto-download that fires on page mount.
+      const fingerprint = collectClientFingerprint()
       if (isInitializedRef.current) {
         // eslint-disable-next-line @typescript-eslint/naming-convention
-        trackRef.current(SegmentEvent.DOWNLOAD_STARTED, { place: footerPlace, href: osLink, auth_state: authState })
+        trackRef.current(SegmentEvent.DOWNLOAD_STARTED, { place: footerPlace, href: osLink, auth_state: authState, ...fingerprint })
       }
 
       try {
@@ -297,16 +306,23 @@ const DownloadSuccess = memo(() => {
           // DOWNLOAD_SUCCESS only fires after streamOrFallback has resolved,
           // i.e. the bytes have effectively landed (Windows) or the
           // fallback hold elapsed (macOS / Windows fetch failure).
-          // eslint-disable-next-line @typescript-eslint/naming-convention
-          trackRef.current(SegmentEvent.DOWNLOAD_SUCCESS, { place: footerPlace, href: downloadUrl, filename, auth_state: authState })
+
+          trackRef.current(SegmentEvent.DOWNLOAD_SUCCESS, {
+            place: footerPlace,
+            href: downloadUrl,
+            filename,
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            auth_state: authState,
+            ...fingerprint
+          })
         }
       } catch (error) {
         if (signal.aborted) return
         console.error('Download error:', error)
         setDownloadError(error instanceof Error ? error.message : 'Download failed')
         if (isInitializedRef.current) {
           // eslint-disable-next-line @typescript-eslint/naming-convention
-          trackRef.current(SegmentEvent.DOWNLOAD_FAILED, { place: footerPlace, href: osLink, auth_state: authState })
+          trackRef.current(SegmentEvent.DOWNLOAD_FAILED, { place: footerPlace, href: osLink, auth_state: authState, ...fingerprint })
         }
       } finally {
         downloadingRef.current = false
