fix(core): keep session-attribution props on minimal $feature_flag_called events

.changeset/tidy-flags-keep-utm.md

@@ -0,0 +1,7 @@
+---
+'@posthog/core': patch
+'posthog-js': patch
+'posthog-node': patch
+---
+
+Keep `$referring_domain` and canonical `utm_*`/campaign parameters on minimal `$feature_flag_called` events. Previously the minimal allowlist stripped every campaign parameter, so a flag-called event landing first in a session could set the session's UTM attribution and channel type to NULL in web analytics.

packages/browser/src/__tests__/featureflags.test.ts

@@ -8,11 +8,12 @@ import {
 } from '../posthog-featureflags'
 import { PostHogPersistence } from '../posthog-persistence'
 import { RequestRouter } from '../utils/request-router'
-import { isUndefined } from '@posthog/core'
+import { isUndefined, MINIMAL_FLAG_CALLED_EVENT_CAMPAIGN_PROPERTIES } from '@posthog/core'
 import { PostHogConfig } from '../types'
 import { createMockPostHog, createPosthogInstance } from './helpers/posthog-instance'
 import { SimpleEventEmitter } from '@posthog/browser-common/utils/simple-event-emitter'
 import { uuidv7 } from '@posthog/browser-common/utils/uuidv7'
+import { CAMPAIGN_PARAMS } from '@posthog/browser-common/utils/event-utils'
 
 jest.useFakeTimers()
 jest.spyOn(global, 'setTimeout')
@@ -4582,6 +4583,9 @@ describe('minimal $feature_flag_called events', () => {
                 '$groups',
                 '$current_url',
                 '$pathname',
+                // session-level attribution props survive minimization so a flag-called
+                // event firing first doesn't null out the session's UTM/channel
+                '$referring_domain',
                 '$session_id',
                 '$window_id',
                 '$lib',
@@ -4602,6 +4606,36 @@ describe('minimal $feature_flag_called events', () => {
         expect(event.$set_once).toBeUndefined()
     })
 
+    it('keeps every canonical session-attribution campaign param without widening the minimal event', async () => {
+        const { posthog, events } = await createInstanceWithCapturedEvents()
+        const campaignProperties = Object.fromEntries(CAMPAIGN_PARAMS.map((key) => [key, `value-for-${key}`]))
+
+        // Keep the shared minimal-event set exhaustively synchronized with the canonical
+        // browser campaign set without copying that list into this test.
+        expect(MINIMAL_FLAG_CALLED_EVENT_CAMPAIGN_PROPERTIES).toEqual(CAMPAIGN_PARAMS)
+
+        posthog.register({
+            ...campaignProperties,
+            $referring_domain: 'referring.example',
+            $referrer: 'https://referring.example/path?private=value',
+            unrelated_superproperty: 'must-be-stripped',
+        })
+        posthog.featureFlags.receivedFeatureFlags(
+            gatedFlagsResponse({ minimalFlagCalledEvents: true, hasExperiment: false })
+        )
+
+        expect(posthog.getFeatureFlag('test-flag')).toBe(true)
+
+        const event = findFlagCalledEvent(events)
+        expect(event).toBeDefined()
+        expect(event.properties).toMatchObject({
+            ...campaignProperties,
+            $referring_domain: 'referring.example',
+        })
+        expect(event.properties).not.toHaveProperty('$referrer')
+        expect(event.properties).not.toHaveProperty('unrelated_superproperty')
+    })
+
     it('strips the timestamp-override props when captured with an explicit timestamp', async () => {
         const { posthog, events } = await createInstanceWithCapturedEvents()
         posthog.featureFlags.receivedFeatureFlags(
@@ -4629,6 +4663,7 @@ describe('minimal $feature_flag_called events', () => {
                 '$feature_flag_request_id',
                 '$current_url',
                 '$pathname',
+                '$referring_domain',
                 '$session_id',
                 '$window_id',
                 '$lib',

packages/core/src/featureFlagUtils.ts

@@ -189,6 +189,33 @@ export const flagDetailsToResults = (flagDetails: Record<string, FeatureFlagDeta
  * The list is the union across client and server SDKs; entries are inert where an
  * SDK never sets them.
  */
+export const MINIMAL_FLAG_CALLED_EVENT_CAMPAIGN_PROPERTIES = [
+  'utm_source',
+  'utm_medium',
+  'utm_campaign',
+  'utm_content',
+  'utm_term',
+  'gad_source',
+  'mc_cid',
+  'gclid',
+  'gclsrc',
+  'dclid',
+  'gbraid',
+  'wbraid',
+  'fbclid',
+  'msclkid',
+  'twclid',
+  'li_fat_id',
+  'igshid',
+  'ttclid',
+  'rdt_cid',
+  'epik',
+  'qclid',
+  'sccid',
+  'irclid',
+  '_kx',
+] as const
+
 export const MINIMAL_FLAG_CALLED_EVENT_PROPERTIES: readonly string[] = [
   // Flag identity
   '$feature_flag',
@@ -209,6 +236,14 @@ export const MINIMAL_FLAG_CALLED_EVENT_PROPERTIES: readonly string[] = [
   // Debug location
   '$current_url',
   '$pathname',
+  // Session-level attribution. The server session table derives session-initial UTM
+  // and channel type from whichever event lands first in a session, so these keys must
+  // survive minimization. The full `$referrer` URL is intentionally excluded.
+  '$referring_domain',
+  // Campaign params are stored as super properties under their bare names (no `$`
+  // prefix). This list is kept in sync with the browser SDK's canonical `CAMPAIGN_PARAMS`
+  // by an exhaustive browser regression test. Entries are inert on SDKs that never set them.
+  ...MINIMAL_FLAG_CALLED_EVENT_CAMPAIGN_PROPERTIES,
   // Linkage / SDK identity
   '$session_id',
   '$window_id',

packages/core/src/index.ts

@@ -4,6 +4,7 @@ export {
   getVariantFromValue,
   parsePayload,
   flagDetailsToResults,
+  MINIMAL_FLAG_CALLED_EVENT_CAMPAIGN_PROPERTIES,
   minimizeFlagCalledEventProperties,
 } from './featureFlagUtils'
 export {

packages/node/src/__tests__/feature-flags.flags.spec.ts

@@ -1,7 +1,7 @@
 import { PostHog } from '@/entrypoints/index.node'
 import { PostHogOptions } from '@/types'
 import { apiImplementation, apiImplementationV4, waitForPromises } from './utils'
-import { PostHogV2FlagsResponse, FeatureFlagError } from '@posthog/core'
+import { PostHogV2FlagsResponse, FeatureFlagError, MINIMAL_FLAG_CALLED_EVENT_CAMPAIGN_PROPERTIES } from '@posthog/core'
 
 jest.spyOn(console, 'debug').mockImplementation()
 
@@ -1278,6 +1278,36 @@ describe('minimal $feature_flag_called events', () => {
       await posthog.shutdown()
     })
 
+    it('keeps every campaign attribution property on the remote-evaluation minimization path', async () => {
+      mockedFetch.mockImplementation(
+        apiImplementationV4(remoteFlagsResponse({ minimalFlagCalledEvents: true, hasExperiment: false }))
+      )
+      const { posthog, captured } = createClient()
+      const campaignProperties = Object.fromEntries(
+        MINIMAL_FLAG_CALLED_EVENT_CAMPAIGN_PROPERTIES.map((key) => [key, `value-for-${key}`])
+      )
+      await posthog.register({
+        ...campaignProperties,
+        $referring_domain: 'referring.example',
+        $referrer: 'https://referring.example/path?private=value',
+        unrelated_superproperty: 'must-be-stripped',
+      })
+
+      await posthog.getFeatureFlagResult('test-flag', 'some-distinct-id')
+      await waitForPromises()
+
+      const message = findFlagCalledEvent(captured)
+      expect(message).toBeDefined()
+      expect(message.properties).toMatchObject({
+        ...campaignProperties,
+        $referring_domain: 'referring.example',
+      })
+      expect(message.properties).not.toHaveProperty('$referrer')
+      expect(message.properties).not.toHaveProperty('unrelated_superproperty')
+
+      await posthog.shutdown()
+    })
+
     it('sends the full event when gated but the flag has an experiment', async () => {
       mockedFetch.mockImplementation(
         apiImplementationV4(remoteFlagsResponse({ minimalFlagCalledEvents: true, hasExperiment: true }))