feat(flags): minimize $feature_flag_called events for non-experiment flags

[haacked]

💡 Motivation and Context

$feature_flag_called events carry the full enriched properties (context envelope, super properties, $active_feature_flags, the $feature/<key> enumeration) on every flag call, even for flags not linked to an experiment. This PR trims those events to a strict allowlist iff the server-controlled gate is on (top-level minimalFlagCalledEvents in the v2 /flags response) AND the flag's has_experiment is exactly false. Any missing signal (field absent, legacy response shape, cached state without it, has_experiment unknown) sends the full legacy shape unchanged, and experiment-linked flags always send the full envelope. Server-gated because rolling this out unconditionally could break existing insights; announcement/comms come before enablement.

Implementation notes:

• All changes live in the pure-JVM posthog core module.
• The gate is persisted in preferences alongside the cached flags so it survives app restarts; the key is in ALL_INTERNAL_KEYS, so it cannot leak into events via registered super properties.
• The gate is parsed overwrite-not-merge: a response without the field flips it off, so full events resume as soon as the server stops sending it. It is also cleared on reset()/identity change.
• The allowlist is applied at the single capture choke point (captureStateless) after property assembly, building the minimal property set from the allowlist rather than deleting from the full set.
• On a real Android cold restart, cached flag details deserialize without has_experiment, so events stay full until the first fresh /flags response of the session (fail-safe, bounded staleness).

Part of a cross-SDK rollout; reference implementation and fuller context: PostHog/posthog-python#748

💚 How did you test it?

Ran locally:

• ./gradlew :posthog:test — 805 tests including the new ones: gated + no experiment → exact allowlist key set (super props, context envelope, $feature/<key>, $active_feature_flags stripped); gated + experiment → full; ungated / field absent → full; gate + minimal shape persist across a simulated SDK restart; gate parse/persist/flip-off/clear at the PostHogRemoteConfig level.
• ./gradlew :posthog-server:test
• ./gradlew spotlessCheck
• ./gradlew :posthog:apiCheck :posthog-server:apiCheck (after apiDump)

Could not run :posthog-android:testDebugUnitTest or Android lint in the authoring environment (no Android SDK available) — no Android-module sources changed, but CI must confirm.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

---

Created with PostHog Code

[github-actions]

posthog-android Compliance Report

Date: 2026-07-31 00:38:00 UTC
Duration: 118419ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	356ms
Format Validation.Event Has Uuid	✅	30ms
Format Validation.Event Has Lib Properties	✅	30ms
Format Validation.Distinct Id Is String	✅	28ms
Format Validation.Token Is Present	✅	28ms
Format Validation.Custom Properties Preserved	✅	28ms
Format Validation.Event Has Timestamp	✅	31ms
Retry Behavior.Retries On 503	✅	7028ms
Retry Behavior.Does Not Retry On 400	✅	4023ms
Retry Behavior.Does Not Retry On 401	✅	4024ms
Retry Behavior.Respects Retry After Header	✅	7024ms
Retry Behavior.Implements Backoff	✅	17037ms
Retry Behavior.Retries On 500	✅	7018ms
Retry Behavior.Retries On 502	✅	7019ms
Retry Behavior.Retries On 504	✅	7018ms
Retry Behavior.Max Retries Respected	✅	17035ms
Deduplication.Generates Unique Uuids	✅	41ms
Deduplication.Preserves Uuid On Retry	✅	7014ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	12028ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7017ms
Deduplication.No Duplicate Events In Batch	✅	36ms
Deduplication.Different Events Have Different Uuids	✅	24ms
Compression.Sends Gzip When Enabled	✅	20ms
Batch Format.Uses Proper Batch Structure	✅	18ms
Batch Format.Flush With No Events Sends Nothing	✅	11ms
Batch Format.Multiple Events Batched Together	✅	33ms
Error Handling.Does Not Retry On 403	✅	4021ms
Error Handling.Does Not Retry On 413	✅	4020ms
Error Handling.Retries On 408	✅	5027ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	34ms
Request Payload.Flags Request Uses V2 Query Param	✅	24ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	26ms
Request Payload.Flags Request Omits Authorization Header	✅	28ms
Request Payload.Token In Flags Body Matches Init	✅	26ms
Request Payload.Groups Round Trip	✅	25ms
Request Payload.Groups Default To Empty Object	✅	25ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	26ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	23ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	33ms
Request Lifecycle.No Flags Request On Init Alone	✅	11ms
Request Lifecycle.No Flags Request On Normal Capture	✅	32ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	38ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	25ms
Retry Behavior.Retries Flags On 502	✅	323ms
Retry Behavior.Retries Flags On 504	✅	323ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	21ms

[dustinbyrne]

this definition would enable minimal flag called events for Android - should posthog-android be listed in the changeset?

or is there something else missing?

[haacked]

Yep, posthog-android belongs in there. Added it.

Nothing is missing on the Android side. PostHogAndroid.setup() builds the core PostHog, so this override is the Android implementation, and PostHogSharedPreferences filters on the shared ALL_INTERNAL_KEYS, which already includes the new preference key.

The gap is in releasing. posthog-android re-exports core via api(project(":posthog")) and pins the core version in its published POM, so shipping core alone would leave Android consumers on the old core. That's what forced the re-pin releases in #611 and #625. Bumped it as a minor rather than a patch since the event shape changes for Android users.

Left posthog-server out: its PostHogFeatureFlags doesn't override isMinimalFlagCalledEventsEnabled(), so it keeps the false default and nothing changes for it.

[github-actions]

This PR hasn't seen activity in a week! Should it be merged, closed, or further worked on? If you want to keep it open, post a comment or remove the stale label – otherwise this will be closed in another week.