Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions acceptance/public/capture.feature
Original file line number Diff line number Diff line change
Expand Up @@ -252,3 +252,17 @@ Feature: Capture
| property | value |
| $process_person_profile | false |
| $is_identified | false |

# The value "" is the empty string, a variant PostHog no longer accepts for new flags.
@client
Scenario: Empty variant flag is left out of active feature flags
Given the SDK is initialized with token "test-token"
And cached feature flags are:
| key | value |
| beta-ui | true |
| legacy-ui | "" |
When capture is called with event "Signed Up"
Then one event named "Signed Up" should be enqueued
And the enqueued event property "$active_feature_flags" should contain "beta-ui"
And the enqueued event property "$active_feature_flags" should not contain "legacy-ui"
And the enqueued event property "$feature/legacy-ui" should equal ""
16 changes: 16 additions & 0 deletions acceptance/public/get-feature-flag-result.feature
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,22 @@ Feature: Get Feature Flag Result
When get feature flag result "missing-flag" is called
Then no feature flag result should be returned

# The value "" is the empty string, a variant PostHog no longer accepts for new flags.
@both
Scenario: Empty variant flag result is disabled
Given the SDK is initialized with token "test-token"
And cached feature flags are:
| key | value |
| legacy-ui | "" |
When get feature flag result "legacy-ui" is called
Then the returned feature flag result should include:
| field | value |
| key | legacy-ui |
| enabled | false |
And its variant should equal the JSON value ""
When is feature enabled "legacy-ui" is called
Then the returned enabled state should be false

# serialized_payload_json encodes the serialized input as a JSON string.
@client
Scenario Outline: Invalid cached payload does not change the flag result
Expand Down
16 changes: 16 additions & 0 deletions acceptance/public/get-feature-flags.feature
Original file line number Diff line number Diff line change
Expand Up @@ -42,3 +42,19 @@ Feature: Get Feature Flags
| beta-ui | true |
When get feature flags is called with tracking disabled
Then no event named "$feature_flag_called" should be enqueued

# Only SDKs whose getAllFeatureFlags() returns flag result objects (iOS 4.0+, Android 4.0+, Flutter 6.0+, KMP).
# The value "" is the empty string, a variant PostHog no longer accepts for new flags.
@client @flag_result_list_capable
Scenario: Flag result list reads an empty variant as disabled
Given the SDK is initialized with token "test-token"
And cached feature flags are:
| key | value |
| beta-ui | true |
| legacy-ui | "" |
When get all feature flag results is called
Then the returned feature flag results should include:
| key | enabled |
| beta-ui | true |
| legacy-ui | false |
And the returned feature flag result for "legacy-ui" should have variant equal to the JSON value ""
14 changes: 14 additions & 0 deletions acceptance/public/on-feature-flags.feature
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,17 @@ Feature: On Feature Flags
| key | value |
| beta-ui | true |
And payload-carrying feature flag listeners should be told that loading flags errored

# The value "" is the empty string, a variant PostHog no longer accepts for new flags.
Scenario: Listener does not receive an empty variant flag
Given the SDK is initialized with token "test-token"
And a feature flag listener is registered
When feature flags are loaded with values:
| key | value |
| beta-ui | true |
| legacy-ui | "" |
Then the feature flag listener should be invoked
And payload-carrying feature flag listeners should receive flags:
| key | value |
| beta-ui | true |
And payload-carrying feature flag listeners should not receive flag "legacy-ui"
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-06
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
## Why

A flag whose variant is the empty string `""` reads as disabled from `isFeatureEnabled` in posthog-js (browser) and posthog-android, and in posthog-ios since [posthog-ios#1001](https://github.com/PostHog/posthog-ios/pull/1001). The same SDKs still report it as `enabled: true` from `getFeatureFlagResult`, and some include it in the flags-loaded callback, so one flag reads as both enabled and disabled depending on the call ([review thread](https://github.com/PostHog/posthog-ios/pull/1001#discussion_r4449050127)). posthog-js (browser) is consistent: `""` is disabled everywhere.

PostHog has rejected new `""` variant keys since [PostHog/posthog#118803](https://github.com/PostHog/posthog/pull/118803) (2026-10-16), so only flags created earlier through the API, MCP or Terraform can hit this.

The client-side flow of `is-feature-enabled` already says only a non-empty variant string is `true`. The server-side flow, `get-feature-flag-result`, `on-feature-flags` and the `$active_feature_flags` event property don't say what an empty variant is.

## What Changes

- **`is-feature-enabled`.** The server-side flow treats only a non-empty variant string as `true`, matching the client-side flow.
- **`get-feature-flag-result`.** A new requirement: a flag whose variant is `""` returns `enabled: false` with `variant: ""`, and `is-feature-enabled` returns `false` for it. Both flow descriptions say so.
- **`on-feature-flags`.** A new requirement: payload-carrying listeners leave a `""` flag out of the keys and variants they receive.
- **`get-feature-flags`.** A new requirement: where `getAllFeatureFlags()` returns flag result objects, a `""` flag stays in the list with `enabled: false`, matching `get-feature-flag-result`.
- **`capture`.** A new requirement: client SDKs leave a `""` flag out of `$active_feature_flags`; `$feature/<key>` still carries `""`.
- **Stale surface notes.** `reload-feature-flags` lists the Android 4.0 and Flutter 6.0 signatures, and `feature-flag-called-tracker` says Flutter 6.0 adds `sendFeatureFlagEvent` to `getFeatureFlag` and `isFeatureEnabled`. No requirement changes.
- **Acceptance.** Matching scenarios in `acceptance/public/get-feature-flag-result.feature`, `on-feature-flags.feature`, `get-feature-flags.feature` and `capture.feature`.

## Capabilities

### New Capabilities

_None._

### Modified Capabilities

- `get-feature-flag-result`: new **Empty variant reads as disabled** requirement, and the client and server flow descriptions.
- `on-feature-flags`: new **Empty variant is left out of the flags a listener receives** requirement.
- `get-feature-flags`: new **Flag result list reads an empty variant as disabled** requirement.
- `capture`: new **Empty variant is not an active feature flag** requirement.
- `is-feature-enabled`: the server-side flow description only (recorded in the `get-feature-flag-result` delta, since it has no requirement changes).

## Impact

- posthog-ios 4.0, posthog-android 4.0 and posthog-flutter 6.0 change `getFeatureFlagResult().enabled` and the `enabled` of each `getAllFeatureFlags()` entry (and Flutter desktop also `isFeatureEnabled`) to `false` for an empty variant in their major releases. posthog-ios 4.0 and posthog-android 4.0 also leave it out of `PostHogFeatureFlagsLoaded` (the `onFeatureFlags` and `reloadFeatureFlags` callback payload) and `$active_feature_flags`.
- posthog-kmp treats an empty variant as disabled in `isFeatureEnabled()`, `FeatureFlagResult.enabled`, `getAllFeatureFlags()` and `$active_feature_flags` on every platform, in the release that adopts posthog-ios 4.0 and posthog-android 4.0.
Comment thread
turnipdabeets marked this conversation as resolved.
Resolved
- Known gap: posthog-js core and react-native still return `enabled: true` from `getFeatureFlagResult` (`getEnabledFromValue` reads any string as enabled), still pass `""` to `onFeatureFlags` listeners, and still list it in `$active_feature_flags`, while their `isFeatureEnabled` returns `false`. A follow-up should align them.
- `getFeatureFlag` and the `$feature_flag_called` response keep reporting `""`.
- Server SDKs were not audited for this case.
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
## ADDED Requirements

### Requirement: Empty variant is not an active feature flag

When a client SDK stamps cached feature flags onto a captured event, a flag whose value is the empty string `""` SHALL NOT be listed in `$active_feature_flags`. Its `$feature/<key>` property SHALL still carry `""`.

Known gap: posthog-js core and react-native list every cached flag key in `$active_feature_flags`, including one whose value is `""`. A follow-up should leave it out there.

#### Scenario: Empty variant flag is left out of active feature flags (@client)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **AND** cached feature flags are:
| key | value |
| beta-ui | true |
| legacy-ui | "" |
- **WHEN** capture is called with event "Signed Up"
- **THEN** one event named "Signed Up" should be enqueued
- **AND** the enqueued event property "$active_feature_flags" should contain "beta-ui"
- **AND** the enqueued event property "$active_feature_flags" should not contain "legacy-ui"
- **AND** the enqueued event property "$feature/legacy-ui" should equal ""
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
## ADDED Requirements

### Requirement: Empty variant reads as disabled

A flag whose value is the empty string `""` SHALL read as disabled. The SDK SHALL return a result with `enabled: false` and `variant: ""`, and `is-feature-enabled` SHALL return `false` for it, whether or not the caller supplies a default.

Known gap: posthog-js core and react-native still return `enabled: true` from `getFeatureFlagResult` for `""`, because `getEnabledFromValue` reads any string as enabled, while their `isFeatureEnabled` returns `false`. A follow-up should make `getFeatureFlagResult` match.

#### Scenario: Empty variant flag result is disabled (@both)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **AND** cached feature flags are:
| key | value |
| legacy-ui | "" |
- **WHEN** get feature flag result "legacy-ui" is called
- **THEN** the returned feature flag result should include:
| field | value |
| key | legacy-ui |
| enabled | false |
- **AND** its variant should equal the JSON value ""
- **WHEN** is feature enabled "legacy-ui" is called
- **THEN** the returned enabled state should be false

## Narrative alignment

When syncing this delta, in both the client-side and server-side flows, replace "Multivariate flag → `enabled = true`, `variant = '<variant>'`" with "Multivariate flag with a non-empty variant → `enabled = true`, `variant = '<variant>'`" and add "Empty variant `''` → `enabled = false`, `variant = ''`".

Also sync `is-feature-enabled`: in its server-side flow replace "variant string → `true`" with "non-empty variant string → `true`", matching its client-side flow. No `is-feature-enabled` requirement changes.
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
## ADDED Requirements

### Requirement: Flag result list reads an empty variant as disabled

On SDKs where `getAllFeatureFlags()` returns a list of flag result objects (iOS 4.0+, Android 4.0+, Flutter 6.0+, KMP), each entry SHALL match what `get-feature-flag-result` returns for that key. A flag whose value is the empty string `""` SHALL stay in the list with `enabled: false` and `variant: ""`. SDKs that return a key → value map keep reporting `""`, as `get-feature-flag` does.

#### Scenario: Flag result list reads an empty variant as disabled
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **AND** cached feature flags are:
| key | value |
| beta-ui | true |
| legacy-ui | "" |
- **WHEN** get all feature flag results is called
- **THEN** the returned feature flag results should include:
| key | enabled |
| beta-ui | true |
| legacy-ui | false |
- **AND** the returned feature flag result for "legacy-ui" should have variant equal to the JSON value ""
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
## ADDED Requirements

### Requirement: Empty variant is left out of the flags a listener receives

A payload-carrying listener SHALL treat a flag whose value is the empty string `""` as disabled and leave it out of the flag keys and variants it receives, like a flag whose value is `false`. Readiness-only listeners are not affected.

Known gap: posthog-js core and react-native pass the raw flag map, which still contains the `""` entry. A follow-up should drop it there.

#### Scenario: Listener does not receive an empty variant flag
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **AND** a feature flag listener is registered
- **WHEN** feature flags are loaded with values:
| key | value |
| beta-ui | true |
| legacy-ui | "" |
- **THEN** the feature flag listener should be invoked
- **AND** payload-carrying feature flag listeners should receive flags:
| key | value |
| beta-ui | true |
- **AND** payload-carrying feature flag listeners should not receive flag "legacy-ui"
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
## 1. Spec delta

- [x] 1.1 Add the **Empty variant reads as disabled** requirement to `get-feature-flag-result`, and describe empty variants in its client and server flows
- [x] 1.2 Say "non-empty variant string" in the `is-feature-enabled` server-side flow
- [x] 1.3 Add the scenario to `acceptance/public/get-feature-flag-result.feature`
- [x] 1.4 Add the **Empty variant is left out of the flags a listener receives** requirement to `on-feature-flags` and its scenario to `acceptance/public/on-feature-flags.feature`
- [x] 1.5 Add the **Empty variant is not an active feature flag** requirement to `capture` and its scenario to `acceptance/public/capture.feature`
- [x] 1.6 Add the **Flag result list reads an empty variant as disabled** requirement to `get-feature-flags` and its scenario to `acceptance/public/get-feature-flags.feature`

## 2. Validation

- [x] 2.1 Run `openspec validate --strict`
- [x] 2.2 Sync the delta into `specs/` and archive the change
22 changes: 22 additions & 0 deletions openspec/specs/capture/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -622,3 +622,25 @@ A backward clock change SHALL only pause refill until the clock catches up. It S
- **AND** no event named "Four" should be enqueued
- **AND** one event named "Five" should be enqueued


### Requirement: Empty variant is not an active feature flag

When a client SDK stamps cached feature flags onto a captured event, a flag whose value is the empty string `""` SHALL NOT be listed in `$active_feature_flags`. Its `$feature/<key>` property SHALL still carry `""`.

Known gap: posthog-js core and react-native list every cached flag key in `$active_feature_flags`, including one whose value is `""`. A follow-up should leave it out there.

#### Scenario: Empty variant flag is left out of active feature flags (@client)
- **GIVEN** a fresh SDK acceptance test harness
- **AND** the SDK clock is fixed at "2025-01-01T00:00:00Z"
- **AND** persistent storage is empty
- **AND** the mock PostHog server is reset
- **GIVEN** the SDK is initialized with token "test-token"
- **AND** cached feature flags are:
| key | value |
| beta-ui | true |
| legacy-ui | "" |
- **WHEN** capture is called with event "Signed Up"
- **THEN** one event named "Signed Up" should be enqueued
- **AND** the enqueued event property "$active_feature_flags" should contain "beta-ui"
- **AND** the enqueued event property "$active_feature_flags" should not contain "legacy-ui"
- **AND** the enqueued event property "$feature/legacy-ui" should equal ""
2 changes: 1 addition & 1 deletion openspec/specs/feature-flag-called-tracker/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ In some SDKs, `shouldTrack` and `markSeen` are combined into one atomic "add if
3. **Suppress duplicate tracking events.** If the same combination has already been seen, do not emit another `$feature_flag_called` event.
4. **Allow new tracking when the response or evaluation context changes.** If a flag's value changes for the same key, or if a server-side call evaluates the same flag/value for a different `distinct_id` or group context, allow a new `$feature_flag_called` event.
5. **Reset on flag change and lifecycle boundaries.** When feature flag state changes, caches are reset, identity is reset, or the SDK is closed/shut down, clear the dedupe tracker so post-reset/reloaded SDK state can emit fresh tracking events and shutdown state cannot leak across SDK lifetimes. On client-side flag reloads, SDKs MAY retain the tracker if they can reliably compare the complete relevant flag state before and after reload (including flag keys, values, payloads, and other cached flag metadata used by accessors) and determine it is unchanged; otherwise, they SHOULD clear the tracker after reload.
6. **Expose tracking controls unevenly at the wrapper layer when applicable.** For example, Flutter delegates to the underlying native/browser trackers and only exposes a per-call suppression flag on `getFeatureFlagResult(sendFeatureFlagEvent: ...)` (named `sendEvent` before 6.0), while `getFeatureFlag(...)` and `isFeatureEnabled(...)` always use the default tracking path.
6. **Expose tracking controls unevenly at the wrapper layer when applicable.** For example, Flutter delegates to the underlying native/browser trackers. Flutter 6.0 exposes a per-call `sendFeatureFlagEvent` option on `getFeatureFlag(...)`, `isFeatureEnabled(...)` and `getFeatureFlagResult(...)`; before 6.0 only `getFeatureFlagResult(sendEvent: ...)` had one, and `getFeatureFlag(...)` and `isFeatureEnabled(...)` always used the default tracking path.
7. **Cap memory usage where needed.** Larger-scale implementations evict old entries using bounded maps or LRU-style caches. When a bounded tracker reaches its capacity, it SHOULD evict the oldest or least-recently-used entries incrementally. Capacity pressure SHOULD NOT clear the entire tracker, because doing so can flood analytics with duplicate `$feature_flag_called` events. Full tracker clears are reserved for explicit lifecycle/context boundaries such as observed flag-state change/cache reset, identity reset, or SDK close/shutdown.

## State & lifecycle
Expand Down
Loading
Loading