fix(feature-flag-called-tracker): add session-attribution properties to minimal-event allowlist - #26
Merged
dustinbyrne merged 1 commit intoAug 6, 2026
Conversation
…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
approved these changes
Aug 5, 2026
dustinbyrne
marked this pull request as ready for review
August 5, 2026 16:56
Member
|
@dustinbyrne should we merge this? |
dustinbyrne
deleted the
posthog-code/document-flag-called-session-attribution-props
branch
August 6, 2026 18:23
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
posthog-js#4287 ("keep session-attribution props on minimal
$feature_flag_calledevents") 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_calledevent 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
$referring_domainand 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$referrerremains excluded (only$referring_domainand bare campaign-param keys survive), preserving the minimal event's privacy/payload-size intent.@clientscenario asserting session-attribution properties are retained while$referreritself is still stripped.openspec/changes/archive/2026-08-05-fix-flag-called-session-attribution/).openspec validate --specs --strictpasses (59/59).Uncertain / flagged for reviewer attention
@posthog/coreimplementation) 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 intasks.md§3.1 for if/when another SDK adds minimal-event mode.Created with PostHog Code