feat(feature-flag-called-tracker): document minimal event mode for non-experiment flags - #16
Merged
dustinbyrne merged 1 commit intoJul 29, 2026
Conversation
…n-experiment flags Nearly every SDK has shipped a server-gated "minimal event" mode for $feature_flag_called that this spec previously said nothing about. Add a requirement documenting the gate signals, the has_experiment condition, the allowlisted property categories, and the fail-safe-to-full-event behavior. Generated-By: PostHog Code Task-Id: 1712e846-7728-47a7-980b-6899ff320a2a
dustinbyrne
reviewed
Jul 28, 2026
dustinbyrne
marked this pull request as ready for review
July 29, 2026 14:23
dustinbyrne
self-requested a review
July 29, 2026 14:23
dustinbyrne
approved these changes
Jul 29, 2026
posthog Bot
added a commit
that referenced
this pull request
Aug 5, 2026
…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
pushed a commit
that referenced
this pull request
Aug 6, 2026
…to minimal-event allowlist (#26) ## 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 Co-authored-by: posthog[bot] <206114724+posthog[bot]@users.noreply.github.com>
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
1 participant
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
Nearly every SDK has shipped a server-gated "minimal event" mode for
$feature_flag_calledthat this spec previously said nothing about — a pure gap, not a divergence from an existing requirement. The rollout originated in posthog-python#748 (merged 2026-07-18) and has since landed, each PR describing itself as "part of a cross-SDK rollout", in:@posthog/core)sdk_compliance_adaptertest harness, not the shippingposthog_flutterpackage (it delegates flag-called capture to the wrapped native/web SDKs)posthog-android has only shipped the precursor
$feature_flag_has_experimentproperty (#621); the minimization itself hasn't landed there yet. posthog-java had no relevant activity in the lookback window.What changed
When the server enables a per-team gate (
minimalFlagCalledEventson/flagsv2, orminimal_flag_called_eventson the local-evaluation definitions payload) and the evaluated flag is not linked to an experiment (has_experiment === false),$feature_flag_calledevents are trimmed from the full enriched properties dict down to a fixed allowlist (flag identity/outcome, evaluation debug scalars, group/session context, SDK identity, and each SDK's own static platform fields). Any missing/unknown/experiment-linked signal keeps the full event unchanged — minimization fails safe.What this PR does
Adds one new requirement, Minimal event mode for non-experiment flags, to
openspec/specs/feature-flag-called-tracker/spec.md, plus the matching OpenSpec change folder (openspec/changes/archive/2026-07-27-minimize-feature-flag-called-events/) per this repo's propose→apply→archive convention.openspec validate --specs --strictpasses.The allowlist is stated at the category level rather than one fixed literal list, since SDKs differ slightly in which static platform fields they keep — posthog-python's list is used as the illustrative reference implementation.
Uncertain / flagged for reviewer attention
Created with PostHog Code