fix: carry incoming campaign attribution into the Google Play Store link (#678)

braianj · web-flow · commit 5eeb0149a967 · 2026-07-09T15:59:04.000-03:00
* fix: carry incoming campaign attribution into the Google Play Store link

* fix: mirror campaign attribution into the Play Install Referrer param
diff --git a/src/components/DownloadOptions/DownloadOptions.spec.tsx b/src/components/DownloadOptions/DownloadOptions.spec.tsx
@@ -6,7 +6,6 @@ import { DOWNLOAD_URLS } from '../../modules/downloadConstants'
 import { getDownloadLinkWithIdentity } from '../../modules/downloadWithIdentity'
 import { postSegmentEvent } from '../../modules/segmentBeacon'
 import type { DownloadOptionProps } from '../../types/download.types'
-import { GOOGLE_PLAY_DESKTOP_URL } from '../Home/shared/googlePlay'
 import { DownloadOptions, handleDownloadOptionClick } from './DownloadOptions'
 
 // Keep ../../modules/url REAL so the actual /download_success URL is built and
@@ -253,7 +252,7 @@ describe('DownloadOptions', () => {
       const googlePlay = screen.getByLabelText('Google Play')
       expect(googlePlay).toHaveAttribute('data-download-target', 'google_play')
       expect(googlePlay).toHaveAttribute('data-os', 'Android')
-      expect(googlePlay).toHaveAttribute('href', GOOGLE_PLAY_DESKTOP_URL)
+      expect(googlePlay).toHaveAttribute('href', DOWNLOAD_URLS.googlePlay)
     })
 
     it('should fire the tracker when a store badge is clicked (unload-safe path handled by useDownloadClick)', async () => {
diff --git a/src/components/DownloadOptions/DownloadOptions.tsx b/src/components/DownloadOptions/DownloadOptions.tsx
@@ -20,7 +20,6 @@ import { Architecture, DownloadOptionProps, OperativeSystem } from '../../types/
 import { assetUrl } from '../../utils/assetUrl'
 import { DownloadButton, EpicButton } from '../Home/Hero/Hero.styled'
 import { EPIC_GAMES_URL } from '../Home/shared/epicGames'
-import { GOOGLE_PLAY_DESKTOP_URL } from '../Home/shared/googlePlay'
 import { VerifiedIcon } from '../Icon/VerifiedIcon'
 import {
   AlternativeButton,
@@ -302,7 +301,7 @@ const DownloadOptions = memo(({ hideDownloadCounts, downloadOnClick }: DownloadO
               <AlternativeButton
                 variant="text"
                 color="inherit"
-                href={GOOGLE_PLAY_DESKTOP_URL}
+                href={DOWNLOAD_URLS.googlePlay}
                 {...{ target: '_blank', rel: 'noopener noreferrer' }}
                 aria-label="Google Play"
                 data-place={DownloadPlace.DOWNLOAD_PAGE}
diff --git a/src/components/Home/ComeHangOut/ComeHangOut.tsx b/src/components/Home/ComeHangOut/ComeHangOut.tsx
@@ -17,7 +17,7 @@ import { OperativeSystem } from '../../../types/download.types'
 import { assetUrl } from '../../../utils/assetUrl'
 import { VerifiedIcon } from '../../Icon/VerifiedIcon'
 import { DownloadButton, EpicButton } from '../Hero/Hero.styled'
-import { GOOGLE_PLAY_MOBILE_URL, googlePlayBadge } from '../shared/googlePlay'
+import { googlePlayBadge } from '../shared/googlePlay'
 import {
   AvatarsImage,
   ComeHangOutContainer,
@@ -58,7 +58,7 @@ const ComeHangOut = memo(() => {
     if (isMobileAndroid) {
       return (
         <GooglePlayButton
-          href={GOOGLE_PLAY_MOBILE_URL}
+          href={DOWNLOAD_URLS.googlePlay}
           target="_blank"
           rel="noopener noreferrer"
           data-event={SegmentEvent.DOWNLOAD}
diff --git a/src/components/Home/Hero/Hero.tsx b/src/components/Home/Hero/Hero.tsx
@@ -18,7 +18,7 @@ import { OperativeSystem } from '../../../types/download.types'
 import { assetUrl } from '../../../utils/assetUrl'
 import { type ScheduledHandle, cancelScheduledIdleCall, scheduleWhenIdle } from '../../../utils/scheduleWhenIdle'
 import { VerifiedIcon } from '../../Icon/VerifiedIcon'
-import { GOOGLE_PLAY_MOBILE_URL, googlePlayBadge } from '../shared/googlePlay'
+import { googlePlayBadge } from '../shared/googlePlay'
 import {
   DownloadButton,
   EpicButton,
@@ -204,7 +204,7 @@ const Hero = memo(({ isDesktop }: { isDesktop: boolean }) => {
           <MobileHeroTitle>{l('page.home.hero.mobile_android_title')}</MobileHeroTitle>
           <MobileHeroSubtitle>{l('page.home.hero.mobile_android_subtitle')}</MobileHeroSubtitle>
           <GooglePlayButton
-            href={GOOGLE_PLAY_MOBILE_URL}
+            href={DOWNLOAD_URLS.googlePlay}
             target="_blank"
             rel="noopener noreferrer"
             data-event={SegmentEvent.DOWNLOAD}
diff --git a/src/components/Home/shared/googlePlay.ts b/src/components/Home/shared/googlePlay.ts
@@ -1,11 +1,5 @@
 import { assetUrl } from '../../../utils/assetUrl'
 
-const GOOGLE_PLAY_MOBILE_URL =
-  'https://play.google.com/store/apps/details?id=org.decentraland.godotexplorer&utm_org=dclrgl&utm_source=fdn&utm_medium=qr&utm_campaign=dclpage&utm_content=android'
-
-const GOOGLE_PLAY_DESKTOP_URL =
-  'https://play.google.com/store/apps/details?id=org.decentraland.godotexplorer&utm_org=dclrgl&utm_source=fdn&utm_medium=qr&utm_campaign=dclpage&utm_content=android'
-
 const googlePlayBadge = assetUrl('/google_play_cta.svg')
 
-export { GOOGLE_PLAY_DESKTOP_URL, GOOGLE_PLAY_MOBILE_URL, googlePlayBadge }
+export { googlePlayBadge }
diff --git a/src/components/Layout/DownloadLayout.spec.tsx b/src/components/Layout/DownloadLayout.spec.tsx
@@ -3,7 +3,6 @@ import { render, screen, waitFor } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import { useAdvancedUserAgentData } from '@dcl/hooks'
 import { launchDesktopApp } from 'decentraland-ui2'
-import { GOOGLE_PLAY_MOBILE_URL } from '../../components/Home/shared/googlePlay'
 import { useGetProfileQuery } from '../../features/profile/profile.client'
 import { useDownloadPageExit } from '../../hooks/useDownloadPageExit'
 import { useWalletAddress } from '../../hooks/useWalletAddress'
@@ -347,7 +346,7 @@ describe('DownloadLayout', () => {
       >)
       render(<DownloadLayout title={TITLE} />)
       const anchor = screen.getByAltText('Get it on Google Play').closest('a') as HTMLAnchorElement
-      expect(anchor).toHaveAttribute('href', GOOGLE_PLAY_MOBILE_URL)
+      expect(anchor).toHaveAttribute('href', DOWNLOAD_URLS.googlePlay)
       expect(anchor.getAttribute('href')).not.toContain('/download_success')
     })
 
diff --git a/src/components/Layout/DownloadLayout.tsx b/src/components/Layout/DownloadLayout.tsx
@@ -17,7 +17,7 @@ import { DOWNLOAD_URLS } from '../../modules/downloadConstants'
 import { DownloadPlace, DownloadTarget, SegmentEvent } from '../../modules/segment'
 import { assetUrl } from '../../utils/assetUrl'
 import { DownloadOptions } from '../DownloadOptions'
-import { GOOGLE_PLAY_MOBILE_URL, googlePlayBadge } from '../Home/shared/googlePlay'
+import { googlePlayBadge } from '../Home/shared/googlePlay'
 import { GooglePlayButton, GooglePlayImage } from '../Home/shared/MobileCTA.styled'
 import { LandingFooter } from '../LandingFooter'
 import { LandingNavbarConnected } from '../LandingNavbar'
@@ -236,7 +236,7 @@ const DownloadLayout = memo((props: DownloadLayoutProps) => {
                 historical from when they were Google-Play–only. Reused here for both OSes. */}
             {isMobileAndroid ? (
               <GooglePlayButton
-                href={GOOGLE_PLAY_MOBILE_URL}
+                href={DOWNLOAD_URLS.googlePlay}
                 target="_blank"
                 rel="noopener noreferrer"
                 data-place={DownloadPlace.DOWNLOAD_PAGE}
diff --git a/src/modules/campaignParams.spec.ts b/src/modules/campaignParams.spec.ts
@@ -1,4 +1,4 @@
-import { collectCampaignParams, withCampaignParams } from './campaignParams'
+import { collectCampaignParams, withCampaignParams, withCampaignParamsOverlay } from './campaignParams'
 
 // Mirrors the module-private cap in campaignParams.ts; asserted here as the
 // documented, stable public behavior (a partner cannot flood the warehouse).
@@ -98,3 +98,37 @@ describe('withCampaignParams', () => {
     })
   })
 })
+
+describe('withCampaignParamsOverlay', () => {
+  afterEach(() => {
+    window.history.pushState({}, '', '/')
+  })
+
+  describe('when the current URL has no campaign params', () => {
+    it('should return the base URL unchanged', () => {
+      const baseUrl = 'https://play.google.com/store/apps/details?id=org.decentraland.godotexplorer&utm_source=fdn'
+      expect(withCampaignParamsOverlay(baseUrl)).toBe(baseUrl)
+    })
+  })
+
+  describe('when the current URL carries campaign params', () => {
+    beforeEach(() => {
+      window.history.pushState({}, '', '/?utm_source=x&utm_medium=paid&utm_campaign=ad')
+    })
+
+    it('should override same-named params already present on the base URL', () => {
+      const baseUrl =
+        'https://play.google.com/store/apps/details?id=org.decentraland.godotexplorer&utm_org=dclrgl&utm_source=fdn&utm_medium=qr&utm_campaign=dclpage&utm_content=android'
+      const result = new URL(withCampaignParamsOverlay(baseUrl))
+      expect(result.searchParams.get('utm_source')).toBe('x')
+      expect(result.searchParams.get('utm_medium')).toBe('paid')
+      expect(result.searchParams.get('utm_campaign')).toBe('ad')
+    })
+
+    it('should preserve params not part of the campaign allowlist', () => {
+      const baseUrl = 'https://play.google.com/store/apps/details?id=org.decentraland.godotexplorer&utm_source=fdn'
+      const result = new URL(withCampaignParamsOverlay(baseUrl))
+      expect(result.searchParams.get('id')).toBe('org.decentraland.godotexplorer')
+    })
+  })
+})
diff --git a/src/modules/campaignParams.ts b/src/modules/campaignParams.ts
@@ -61,6 +61,12 @@ function collectCampaignParams(source?: URLSearchParams): Record<string, string>
   return collected
 }
 
+/** Shared empty-guard for the two `with*` builders below. */
+function collectNonEmptyCampaignParams(): Record<string, string> | null {
+  const collected = collectCampaignParams()
+  return Object.keys(collected).length === 0 ? null : collected
+}
+
 /**
  * Appends the current URL's campaign params to an internal path, preserving
  * partner attribution across a plain navigation. Used by the `'/download'`
@@ -69,10 +75,28 @@ function collectCampaignParams(source?: URLSearchParams): Record<string, string>
  * with the utm params stripped, silently losing the whole funnel attribution.
  */
 function withCampaignParams(path: string): string {
-  const collected = collectCampaignParams()
-  if (Object.keys(collected).length === 0) return path
+  const collected = collectNonEmptyCampaignParams()
+  if (!collected) return path
   const params = new URLSearchParams(collected)
   return `${path}${path.includes('?') ? '&' : '?'}${params.toString()}`
 }
 
-export { collectCampaignParams, withCampaignParams }
+/**
+ * Overlays the visitor's incoming campaign params (if any) onto a base URL's
+ * own query string, overriding same-named params the base URL already
+ * carries. For URLs that ship a baked-in default attribution (e.g. the Play
+ * Store listing's own "QR code" campaign tag), this lets a live incoming
+ * campaign win instead of being silently discarded at the store handoff.
+ * Falls back to the base URL untouched when no campaign params are present.
+ */
+function withCampaignParamsOverlay(baseUrl: string): string {
+  const collected = collectNonEmptyCampaignParams()
+  if (!collected) return baseUrl
+  const url = new URL(baseUrl)
+  for (const [key, value] of Object.entries(collected)) {
+    url.searchParams.set(key, value)
+  }
+  return url.toString()
+}
+
+export { collectCampaignParams, withCampaignParams, withCampaignParamsOverlay }
diff --git a/src/modules/downloadConstants.spec.ts b/src/modules/downloadConstants.spec.ts
@@ -10,6 +10,44 @@ describe('downloadConstants', () => {
       expect(DOWNLOAD_URLS.googlePlay).toContain('play.google.com')
       expect(DOWNLOAD_URLS.appStore).toContain('apps.apple.com')
     })
+
+    describe('googlePlay', () => {
+      afterEach(() => {
+        window.history.pushState({}, '', '/')
+      })
+
+      it('should default to the static QR-code campaign tag when no campaign params are present', () => {
+        expect(DOWNLOAD_URLS.googlePlay).toContain('utm_source=fdn')
+        expect(DOWNLOAD_URLS.googlePlay).toContain('utm_medium=qr')
+        expect(DOWNLOAD_URLS.googlePlay).toContain('utm_campaign=dclpage')
+      })
+
+      it('should carry the visitor incoming campaign instead of the default tag when present', () => {
+        window.history.pushState({}, '', '/?utm_source=x&utm_medium=paid&utm_campaign=ad')
+        const url = new URL(DOWNLOAD_URLS.googlePlay)
+        expect(url.searchParams.get('utm_source')).toBe('x')
+        expect(url.searchParams.get('utm_medium')).toBe('paid')
+        expect(url.searchParams.get('utm_campaign')).toBe('ad')
+        expect(url.searchParams.get('id')).toBe('org.decentraland.godotexplorer')
+      })
+
+      it('should mirror the default utm set into the Install Referrer param when no campaign is present', () => {
+        const referrer = new URLSearchParams(new URL(DOWNLOAD_URLS.googlePlay).searchParams.get('referrer') ?? '')
+        expect(referrer.get('utm_source')).toBe('fdn')
+        expect(referrer.get('utm_medium')).toBe('qr')
+        expect(referrer.get('utm_campaign')).toBe('dclpage')
+      })
+
+      it('should mirror the incoming campaign into the Install Referrer param when present', () => {
+        window.history.pushState({}, '', '/?utm_source=x&utm_medium=paid&utm_campaign=ad')
+        const referrer = new URLSearchParams(new URL(DOWNLOAD_URLS.googlePlay).searchParams.get('referrer') ?? '')
+        expect(referrer.get('utm_source')).toBe('x')
+        expect(referrer.get('utm_medium')).toBe('paid')
+        expect(referrer.get('utm_campaign')).toBe('ad')
+        // Non-utm routing params never leak into the referrer payload.
+        expect(referrer.get('id')).toBeNull()
+      })
+    })
   })
 
   describe('detectDownloadOS', () => {
diff --git a/src/modules/downloadConstants.ts b/src/modules/downloadConstants.ts
@@ -1,3 +1,40 @@
+import { withCampaignParamsOverlay } from './campaignParams'
+
+/**
+ * Default Play Store campaign tag (the site's own "QR code" attribution),
+ * used when the visitor didn't arrive via a live campaign. See
+ * `DOWNLOAD_URLS.googlePlay` below.
+ */
+const GOOGLE_PLAY_DEFAULT_URL =
+  'https://play.google.com/store/apps/details?id=org.decentraland.godotexplorer&utm_org=dclrgl&utm_source=fdn&utm_medium=qr&utm_campaign=dclpage&utm_content=android'
+
+/**
+ * Builds the effective Play Store URL: incoming campaign params overlaid on
+ * the default tag, plus a `referrer` param mirroring the final utm_* set.
+ *
+ * The bare utm_* params only tag the store-page visit (Play Console
+ * acquisition reports). Campaign attribution for the INSTALL travels through
+ * the Play Install Referrer API, which reads the `referrer` query param —
+ * without it, no install can ever be joined back to a campaign, no matter
+ * what the URL's utm_* say. The mobile client still has to read its install
+ * referrer and forward it to analytics for the loop to close; this makes the
+ * data available at the store handoff so that work is unblocked.
+ */
+function buildGooglePlayUrl(): string {
+  const url = new URL(withCampaignParamsOverlay(GOOGLE_PLAY_DEFAULT_URL))
+  const referrer = new URLSearchParams()
+  for (const [key, value] of url.searchParams.entries()) {
+    if (key.startsWith('utm_')) {
+      referrer.append(key, value)
+    }
+  }
+  // URLSearchParams.set percent-encodes the nested query string on
+  // serialization (`utm_source%3D…%26utm_medium%3D…`), matching the format
+  // the Install Referrer API expects.
+  url.searchParams.set('referrer', referrer.toString())
+  return url.toString()
+}
+
 /**
  * Centralized download URLs.
  * Mirrors decentraland-ui2/modules/downloadUrls but avoids deep imports
@@ -7,8 +44,17 @@ const DOWNLOAD_URLS = {
   windows: 'https://decentraland.org/download',
   apple: 'https://decentraland.org/download',
   epic: 'https://store.epicgames.com/en-US/p/decentraland-b692fb',
-  googlePlay:
-    'https://play.google.com/store/apps/details?id=org.decentraland.godotexplorer&utm_org=dclrgl&utm_source=fdn&utm_medium=qr&utm_campaign=dclpage&utm_content=android',
+  // Getter (not a plain string) so it's computed fresh on every read: overlays
+  // the visitor's incoming campaign params onto the default QR-code
+  // attribution, so a click that arrived via a live campaign carries that
+  // campaign into the Play Store handoff instead of always reporting
+  // "fdn/qr/dclpage". Without this, no Play Store install can ever be
+  // attributed to a dynamic campaign — the store link always shipped the same
+  // static tag regardless of how the visitor actually landed. See
+  // buildGooglePlayUrl for the `referrer` install-attribution mirror.
+  get googlePlay(): string {
+    return buildGooglePlayUrl()
+  },
   appStore: 'https://apps.apple.com/app/apple-store/id6478403840?pt=126284288&ct=Decentraland%20Home%20iOS&mt=8'
 } as const
 
diff --git a/src/pages/play/PlayPage.tsx b/src/pages/play/PlayPage.tsx
@@ -1,7 +1,7 @@
 import { memo, useCallback } from 'react'
 import { useAdvancedUserAgentData } from '@dcl/hooks'
 import { AnimatedBackground, useDesktopMediaQuery } from 'decentraland-ui2'
-import { GOOGLE_PLAY_MOBILE_URL, googlePlayBadge } from '../../components/Home/shared/googlePlay'
+import { googlePlayBadge } from '../../components/Home/shared/googlePlay'
 import { GooglePlayButton, GooglePlayImage } from '../../components/Home/shared/MobileCTA.styled'
 import { VerifiedIcon } from '../../components/Icon/VerifiedIcon'
 import { getEnv } from '../../config/env'
@@ -85,7 +85,7 @@ const PlayPage = memo(() => {
           </PlayTitleGroup>
 
           <GooglePlayButton
-            href={isMobileAndroid ? GOOGLE_PLAY_MOBILE_URL : DOWNLOAD_URLS.appStore}
+            href={isMobileAndroid ? DOWNLOAD_URLS.googlePlay : DOWNLOAD_URLS.appStore}
             target="_blank"
             rel="noopener noreferrer"
             data-place={isMobileAndroid ? DownloadPlace.PLAY_HERO_GOOGLE_PLAY : DownloadPlace.PLAY_HERO_APP_STORE}
@@ -178,7 +178,7 @@ const PlayPage = memo(() => {
               <PlayBadgeImage src={assetUrl('/app-store-badge.svg')} alt="Download on the App Store" />
             </PlayBadgeLink>
             <PlayBadgeLink
-              href={GOOGLE_PLAY_MOBILE_URL}
+              href={DOWNLOAD_URLS.googlePlay}
               target="_blank"
               rel="noopener noreferrer"
               data-place={DownloadPlace.PLAY_HERO_GOOGLE_PLAY}
