Bug Description

In most of the SDKs, the method to retrieve a feature flag payload is a standalone method. This method does not raise the $feature_flag_called event, which is a source of confusion for folks. The reason it doesn't is because we expect a pattern like so:

if is_feature_enabled('key'): # Raises event
    payload = get_feature_flag_payload('key') # Does not raise event

If get_feature_flag_payload raised the $feature_flag_called event, we'd double count here.

Problem

The problem is that get_feature_flag_payload(...) doesn't require that you call is_feature_enabled or get_feature_flag first. It can be called independently:

payload = get_feature_flag_payload('key')

Every SDK except Unity/.NET follows this problematic pattern:

1. getFeatureFlag() → raises $feature_flag_called event
2. getFeatureFlagPayload() → NO event raised

Why customers complain: If they only call getFeatureFlagPayload(), they get zero analytics about feature flag usage. This is confusing because:

• The name suggests it's checking a feature flag
• They expect it to behave similarly to getFeatureFlag()
• There's no documentation making it clear this is a "silent" method

This sadly does not lead customers into the pit of success.

Solution

For each SDK, we should deprecate/obsolete the standalone method to retrieve the payload in favor of a pattern that leads into the pit of success.

Ideal API Pattern

Strongly-typed languages (Unity/.NET style):

flag = client.getFeatureFlag("my-flag", distinctId)  // raises event, returns wrapper
flag.isEnabled      // boolean
flag.variant        // string or null  
flag.getPayload<T>() // deserializes payload, NO additional event

• How it works: GetFeatureFlag() returns a PostHogFeatureFlag wrapper that contains both value and payload
• Event: Raised once when GetFeatureFlag() is called
• Payload: Accessed via .GetPayload<T>() on the returned object - no additional event. Also accessible via GetPayloadJson() which returns a dictionary style JSON object.

Dynamic languages:

result = client.get_feature_flag_result("my-flag", distinctId)  // raises event
result.value   // boolean or variant string
result.payload // the payload object

Additional Context

Feature Flag Payload Catalog Across PostHog SDKs

Migration Path

Debug info

- [ ] PostHog Cloud, Debug information: [please copy/paste from https://us.posthog.com/settings/project-details#variables or https://eu.posthog.com/settings/project-details#variables]
- [ ] PostHog Hobby self-hosted with `docker compose`, version/commit: [please provide]
- [ ] PostHog self-hosted with Kubernetes (deprecated, see [`Sunsetting Kubernetes support`](https://posthog.com/blog/sunsetting-helm-support-posthog)), version/commit: [please provide]