feat(analytics): add UTM suite and instance id to on-ramp outbound links (#2075)

* refactor(hooks): extract useInstanceId into a shared hook

The react-query call that fetches the instance id from the main
process was inlined in useHubSpotForm. Lift it into a dedicated
renderer/src/common/hooks/use-instance-id.ts so other renderer
surfaces (on-ramp links, analytics) can share the cached value
without duplicating the queryKey.

* feat(analytics): add buildOnrampDocsUrl helper for on-ramp outbound links

Small builder that emits docs URLs with the full UTM suite
(utm_source, utm_medium, utm_campaign, utm_content) plus an
optional tdi param populated from the instance id. Params are
emitted in a stable, documented order; tdi is omitted when the
instance id query has not yet resolved so the link remains
clickable during the first render.

* feat(nav): attach full UTM suite and instance id to Enterprise upgrade link

The header "Upgrade to Enterprise" button now routes through
buildOnrampDocsUrl with campaign=enterprise-upgrade and
content=app-header, and carries the instance id as tdi, so the
marketing site can attribute clicks back to the app surface and
to the user's install.

* feat(registry): attach full UTM suite and instance id to custom registry promo link

The "Build a custom registry" promo tile now uses the shared
on-ramp URL builder with campaign=custom-registry and
content=registry-view-tile, including the instance id as tdi for
attribution parity with the Enterprise upgrade CTA.

* refactor(hooks): cache useInstanceId for a few days

The instance id is stable across restarts but the IPC itself is
cheap, so pinning the cache forever is overkill. Set staleTime
to three days — enough to avoid the per-mount refetch without
locking the value in the client cache for the lifetime of the
app.

* refactor(nav): scope instance-id fetch to the Enterprise upgrade button

Extract the upgrade CTA into its own small component that owns
the useInstanceId call. In enterprise builds the button is not
rendered, so the hook (and its IPC) no longer runs at all.

* refactor(analytics): use URLSearchParams in buildOnrampDocsUrl

Replace the hand-rolled map/join serialization with
URLSearchParams. For the real UTM values the output is
byte-for-byte identical; only the edge-case encoding test needs
an update since spaces now serialize as \`+\` instead of \`%20\`
per application/x-www-form-urlencoded.

Author: samuv

renderer/src/common/components/layout/top-nav/__tests__/top-nav.test.tsx

@@ -108,7 +108,7 @@ describe('TopNav', () => {
         })
         expect(link).toHaveAttribute(
           'href',
-          `${DOCS_BASE_URL}/enterprise?utm_source=${APP_IDENTIFIER}`
+          `${DOCS_BASE_URL}/enterprise?utm_source=${APP_IDENTIFIER}&utm_medium=app&utm_campaign=enterprise-upgrade&utm_content=app-header&tdi=test-instance-id`
         )
       })
     })

renderer/src/common/components/layout/top-nav/index.tsx

@@ -32,7 +32,8 @@ import { useFeatureFlag } from '@/common/hooks/use-feature-flag'
 import { featureFlagKeys } from '@utils/feature-flags'
 import { usePermissions } from '@/common/contexts/permissions'
 import { PERMISSION_KEYS } from '@/common/contexts/permissions/permission-keys'
-import { APP_IDENTIFIER, DOCS_BASE_URL } from '@common/app-info'
+import { buildOnrampDocsUrl } from '@/common/lib/onramp-url'
+import { useInstanceId } from '@/common/hooks/use-instance-id'
 
 interface NavButtonProps {
   to: string
@@ -119,6 +120,34 @@ function TopNavLinks() {
   )
 }
 
+function EnterpriseUpgradeButton() {
+  const { instanceId } = useInstanceId()
+  const href = buildOnrampDocsUrl('/enterprise', {
+    campaign: 'enterprise-upgrade',
+    content: 'app-header',
+    instanceId,
+  })
+
+  return (
+    <Button
+      variant="success"
+      className="app-region-no-drag rounded-full font-normal"
+      size="sm"
+      asChild
+    >
+      <a
+        href={href}
+        target="_blank"
+        rel="noopener noreferrer"
+        onClick={() => trackEvent('Onramp: Upgrade to Enterprise clicked')}
+      >
+        <PackageOpen className="size-4" />
+        Upgrade to Enterprise
+      </a>
+    </Button>
+  )
+}
+
 interface TopNavProps extends HTMLProps<HTMLElement> {
   isEnterprise?: boolean
 }
@@ -166,26 +195,7 @@ export function TopNav({ isEnterprise = false, ...props }: TopNavProps) {
       <div
         className="app-region-no-drag flex h-full items-center justify-self-end"
       >
-        {!isEnterprise && (
-          <Button
-            variant="success"
-            className="app-region-no-drag rounded-full font-normal"
-            size="sm"
-            asChild
-          >
-            <a
-              href={`${DOCS_BASE_URL}/enterprise?utm_source=${APP_IDENTIFIER}`}
-              target="_blank"
-              rel="noopener noreferrer"
-              onClick={() =>
-                trackEvent('Onramp: Upgrade to Enterprise clicked')
-              }
-            >
-              <PackageOpen className="size-4" />
-              Upgrade to Enterprise
-            </a>
-          </Button>
-        )}
+        {!isEnterprise && <EnterpriseUpgradeButton />}
         <div className="flex h-full items-center gap-1 pl-2">
           {canShow(PERMISSION_KEYS.HELP_MENU) && (
             <HelpDropdown

renderer/src/common/hooks/use-hubspot-form.ts

@@ -1,14 +1,11 @@
 import { useState } from 'react'
-import { useQuery } from '@tanstack/react-query'
 import { submitToHubSpot } from '../lib/hubspot'
+import { useInstanceId } from './use-instance-id'
 
 export function useHubSpotForm(formId: string, pageName: string) {
   const [consentToProcess, setConsentToProcess] = useState(false)
 
-  const { data: instanceId, isFetched } = useQuery({
-    queryKey: ['instance-id'],
-    queryFn: () => window.electronAPI.getInstanceId(),
-  })
+  const { instanceId, isFetched } = useInstanceId()
 
   const isReady = isFetched && !!instanceId
 

renderer/src/common/hooks/use-instance-id.ts

@@ -0,0 +1,13 @@
+import { useQuery } from '@tanstack/react-query'
+
+const THREE_DAYS_MS = 1000 * 60 * 60 * 24 * 3
+
+export function useInstanceId() {
+  const { data: instanceId, isFetched } = useQuery({
+    queryKey: ['instance-id'],
+    queryFn: () => window.electronAPI.getInstanceId(),
+    staleTime: THREE_DAYS_MS,
+  })
+
+  return { instanceId, isFetched }
+}

renderer/src/common/lib/__tests__/onramp-url.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+import { APP_IDENTIFIER, DOCS_BASE_URL } from '@common/app-info'
+import { buildOnrampDocsUrl } from '../onramp-url'
+
+describe('buildOnrampDocsUrl', () => {
+  it('emits utm params in the documented order with tdi when instanceId is provided', () => {
+    const url = buildOnrampDocsUrl('/enterprise', {
+      campaign: 'enterprise-upgrade',
+      content: 'app-header',
+      instanceId: 'abc-123',
+    })
+
+    expect(url).toBe(
+      `${DOCS_BASE_URL}/enterprise?utm_source=${APP_IDENTIFIER}&utm_medium=app&utm_campaign=enterprise-upgrade&utm_content=app-header&tdi=abc-123`
+    )
+  })
+
+  it('omits the tdi param when instanceId is undefined', () => {
+    const url = buildOnrampDocsUrl('/guides-registry/', {
+      campaign: 'custom-registry',
+      content: 'registry-view-tile',
+    })
+
+    expect(url).toBe(
+      `${DOCS_BASE_URL}/guides-registry/?utm_source=${APP_IDENTIFIER}&utm_medium=app&utm_campaign=custom-registry&utm_content=registry-view-tile`
+    )
+    expect(url).not.toContain('tdi=')
+  })
+
+  it('omits the tdi param when instanceId is an empty string', () => {
+    const url = buildOnrampDocsUrl('/enterprise', {
+      campaign: 'enterprise-upgrade',
+      content: 'app-header',
+      instanceId: '',
+    })
+
+    expect(url).not.toContain('tdi=')
+  })
+
+  it('url-encodes param values using application/x-www-form-urlencoded', () => {
+    const url = buildOnrampDocsUrl('/enterprise', {
+      campaign: 'enterprise upgrade',
+      content: 'app/header',
+      instanceId: 'id with space',
+    })
+
+    expect(url).toContain('utm_campaign=enterprise+upgrade')
+    expect(url).toContain('utm_content=app%2Fheader')
+    expect(url).toContain('tdi=id+with+space')
+  })
+})

renderer/src/common/lib/onramp-url.ts

@@ -0,0 +1,25 @@
+import { APP_IDENTIFIER, DOCS_BASE_URL } from '@common/app-info'
+
+type OnrampUrlOptions = {
+  campaign: string
+  content: string
+  instanceId?: string
+}
+
+export function buildOnrampDocsUrl(
+  path: string,
+  { campaign, content, instanceId }: OnrampUrlOptions
+): string {
+  const params = new URLSearchParams([
+    ['utm_source', APP_IDENTIFIER],
+    ['utm_medium', 'app'],
+    ['utm_campaign', campaign],
+    ['utm_content', content],
+  ])
+
+  if (instanceId) {
+    params.append('tdi', instanceId)
+  }
+
+  return `${DOCS_BASE_URL}${path}?${params.toString()}`
+}

renderer/src/features/registry-servers/components/card-registry-promo.tsx

@@ -7,11 +7,17 @@ import {
 } from '@/common/components/ui/card'
 import { Button } from '@/common/components/ui/button'
 import { trackEvent } from '@/common/lib/analytics'
-import { APP_IDENTIFIER, DOCS_BASE_URL } from '@common/app-info'
-
-const REGISTRY_DOCS_URL = `${DOCS_BASE_URL}/guides-registry/?utm_source=${APP_IDENTIFIER}`
+import { buildOnrampDocsUrl } from '@/common/lib/onramp-url'
+import { useInstanceId } from '@/common/hooks/use-instance-id'
 
 export function CardRegistryPromo() {
+  const { instanceId } = useInstanceId()
+  const registryDocsUrl = buildOnrampDocsUrl('/guides-registry/', {
+    campaign: 'custom-registry',
+    content: 'registry-view-tile',
+    instanceId,
+  })
+
   return (
     <Card className="bg-brand-green-mid gap-0 border-none p-4">
       <CardHeader className="px-0">
@@ -36,7 +42,7 @@ export function CardRegistryPromo() {
             hover:bg-brand-green-dark/90 rounded-full p-4 font-medium"
         >
           <a
-            href={REGISTRY_DOCS_URL}
+            href={registryDocsUrl}
             target="_blank"
             rel="noopener noreferrer"
             onClick={() => trackEvent('Onramp: custom registry docs clicked')}

renderer/src/routes/__tests__/registry.test.tsx

@@ -108,11 +108,13 @@ describe('Promo Card', () => {
       expect(screen.getByText('Build a custom registry')).toBeVisible()
     })
 
-    const link = screen.getByRole('link', { name: /learn how/i })
-    expect(link).toHaveAttribute(
-      'href',
-      `${DOCS_BASE_URL}/guides-registry/?utm_source=${APP_IDENTIFIER}`
-    )
+    await waitFor(() => {
+      const link = screen.getByRole('link', { name: /learn how/i })
+      expect(link).toHaveAttribute(
+        'href',
+        `${DOCS_BASE_URL}/guides-registry/?utm_source=${APP_IDENTIFIER}&utm_medium=app&utm_campaign=custom-registry&utm_content=registry-view-tile&tdi=test-instance-id`
+      )
+    })
   })
 
   it('tracks event when CTA is clicked', async () => {