Skip to content

fix(feature-flag-called-tracker): add session-attribution properties to minimal-event allowlist - #26

Merged
dustinbyrne merged 1 commit into
mainfrom
posthog-code/document-flag-called-session-attribution-props
Aug 6, 2026
Merged

fix(feature-flag-called-tracker): add session-attribution properties to minimal-event allowlist#26
dustinbyrne merged 1 commit into
mainfrom
posthog-code/document-flag-called-session-attribution-props

Conversation

@posthog

@posthog posthog Bot commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Why

posthog-js#4287 ("keep session-attribution props on minimal $feature_flag_called events") fixed a web-analytics data-correctness bug: the minimal-event allowlist added by posthog-js#4172 (documented here in #16) stripped every referrer and campaign/click-id super property (utm_source, gclid, $referring_domain, etc.). Web-analytics session-initial UTM attribution and channel-type grouping are read from the first event in a session, and a minimized $feature_flag_called event can be that first event — so a flag call landing first in a session silently nulled out the session's whole attribution.

openspec/specs/feature-flag-called-tracker/spec.md's "Minimal event mode for non-experiment flags" requirement lists allowlist categories at a category level but never mentions referrer or campaign/UTM properties anywhere — not in the category list, the posthog-python reference literal, or the "everything else... SHALL be stripped" clause. This is a real spec gap: an SDK implementing minimal-event-mode strictly per the current text would (correctly, per the spec) strip these and reproduce the same bug.

What this PR does

  • Adds a "Session-attribution properties" category to the minimal-event allowlist — $referring_domain and canonical campaign/click-id super properties (utm_source, utm_medium, utm_campaign, utm_content, utm_term, gad_source, mc_cid, gclid/fbclid-style ids) — noting that full $referrer remains excluded (only $referring_domain and bare campaign-param keys survive), preserving the minimal event's privacy/payload-size intent.
  • Adds one new @client scenario asserting session-attribution properties are retained while $referrer itself is still stripped.
  • Change proposed and archived on this branch per this repo's one-PR-per-change convention (openspec/changes/archive/2026-08-05-fix-flag-called-session-attribution/).
  • openspec validate --specs --strict passes (59/59).

Uncertain / flagged for reviewer attention

  • Only posthog-js/posthog-node (the shared @posthog/core implementation) were confirmed to have shipped this bug and fix. No other in-scope SDK currently ships a minimal-event mode per feat(feature-flag-called-tracker): document minimal event mode for non-experiment flags #16's own audit, so this is a documentation-only correction, not a new cross-platform parity gap — flagged as a follow-up check in tasks.md §3.1 for if/when another SDK adds minimal-event mode.

Created with PostHog Code

…to minimal-event allowlist

## Why

[posthog-js#4287](PostHog/posthog-js#4287) ("keep session-attribution
props on minimal $feature_flag_called events") fixed a web-analytics data-correctness bug: the
minimal-event allowlist added by posthog-js#4172 (documented here in
[#16](#16)) stripped every referrer and campaign/click-id
super property (`utm_source`, `gclid`, `$referring_domain`, etc.). Web-analytics session-initial
UTM attribution and channel-type grouping are read from the **first event in a session**, and a
minimized `$feature_flag_called` event can be that first event — so a flag call landing first in a
session silently nulled out the session's whole attribution.

`openspec/specs/feature-flag-called-tracker/spec.md`'s "Minimal event mode for non-experiment
flags" requirement lists allowlist categories at a category level but never mentions referrer or
campaign/UTM properties anywhere — not in the category list, the posthog-python reference literal,
or the "everything else... SHALL be stripped" clause. This is a real spec gap: an SDK implementing
minimal-event-mode strictly per the current text would (correctly, per the spec) strip these and
reproduce the same bug.

## What this PR does

- Adds a "Session-attribution properties" category to the minimal-event allowlist —
  `$referring_domain` and canonical campaign/click-id super properties (`utm_source`, `utm_medium`,
  `utm_campaign`, `utm_content`, `utm_term`, `gad_source`, `mc_cid`, `gclid`/`fbclid`-style ids) —
  noting that full `$referrer` remains excluded (only `$referring_domain` and bare campaign-param
  keys survive), preserving the minimal event's privacy/payload-size intent.
- Adds one new `@client` scenario asserting session-attribution properties are retained while
  `$referrer` itself is still stripped.
- Change proposed and archived on this branch per this repo's one-PR-per-change convention
  (`openspec/changes/archive/2026-08-05-fix-flag-called-session-attribution/`).
- `openspec validate --specs --strict` passes (59/59).

## Uncertain / flagged for reviewer attention

- Only posthog-js/posthog-node (the shared `@posthog/core` implementation) were confirmed to have
  shipped this bug and fix. No other in-scope SDK currently ships a minimal-event mode per #16's
  own audit, so this is a documentation-only correction, not a new cross-platform parity gap —
  flagged as a follow-up check in `tasks.md` §3.1 for if/when another SDK adds minimal-event mode.


Generated-By: PostHog Code
Task-Id: 457dcd47-67c0-4fb7-830b-c3d13a790c8d
@dustinbyrne
dustinbyrne marked this pull request as ready for review August 5, 2026 16:56
@marandaneto

Copy link
Copy Markdown
Member

@dustinbyrne should we merge this?

@dustinbyrne
dustinbyrne merged commit b59e8b4 into main Aug 6, 2026
10 checks passed
@dustinbyrne
dustinbyrne deleted the posthog-code/document-flag-called-session-attribution-props branch August 6, 2026 18:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants