feat(flags): Include version and other feature flag details in `/decide?v=4` response

[haacked]

Feature request

Right now, it can be difficult for users to understand why a flag evaluated the way it did. It's especially difficult because a flag may have changed since the $feature_flag_called event. Anything we can do to provide more information is helpful.

We plan to add the following properties to the $feature_flag_called event:

Property Name	Descirption
$feature_flag_version	The version of the feature flag. This is visible in the diffs of the feature flag activity log.
$feature_flag_reason	The reason the feature flag matched or didn't match.
$feature_flag_id	The database id of the feature flag (Just in case a flag was deleted and then recreated with the same key, we can determine the difference.

Describe the solution you'd like

Today, feature flag information is in two different top-level properties of the /decide response body.

{
  ...
  "featureFlags" : {
    "hogtied_got_character" : "danaerys",
    "hogtied-homepage-user" : true,
    "hogtied-homepage-bonanza" : true
  },
  ...
 "featureFlagPayloads" : {
    "hogtied_got_character" : "{\"role\": \"khaleesi\"}",
    "hogtied-homepage-user" : "{\"is_cool\": true}"
  }
}

I propose we implement version 4 of the API like so:

"flags" : {
    "hogtied_got_character" : {
        "enabled": true,
        "variant": "danaerys",
        "reason": {
            "code": "matched_condition",
            "condition_index": 0,
            "description": "Matched condition set 1"
        },
        "metadata": {
            "id": 100,
            "version": 42
            "description": "The character path the user will take",
            "payload": "{\"role\": \"khaleesi\"}"
         }
     },
    ...
  },

I modeled this new dictionary after the OpenFeature API. I'm not by any means suggesting we adopt it 100% right now. But no harm in moving to a format that OpenFeature clients will have an easier time with.

Second, our clients that understand this new format will have an easier time parsing this format and getting the info they need.

For example, down the road, we could add a posthog.getFeatureFlagDetail(...) method to each client that just grabs a node from this new /decide response. This can reduce the requests that server-side clients need to make compared to calling getFeatureFlag and then getFeatureFlagPayload.

Lastly, this format is scalable for new changes. For example, when we want to add a reason for a flag evaluation, we don't need to add a top-level featureFlagReasons property to the JSON.

Client support

The work on the server is done, but there's still work to do to support this in each client.

• JavaScript Web and posthog-react - fix(flags): Enjoy the benefits of /decide?v=4 posthog-js#1843
• posthog-node: feat(flags): Add feature flag version info, evaluation reason, and id to $feature_flag_called event posthog-js-lite#427
• posthog-rn: Done, but needs testing.
• posthog-python: feat(flags): Add more details such as version, id, and reason to $feature_flag_called events posthog-python#207
• posthog-go
• posthog-ruby
• posthog-dotnet
• posthog-php
• posthog-ios
• posthog-flutter
• posthog-android
• posthog-java
• posthog-elixir

[haacked]

In keeping with OpenFeature, I may name the top-level property flags instead of featureFlagDetails.