feat(flags): add $feature_flag_has_experiment to $feature_flag_called events (#261)

* Add $feature_flag_has_experiment to $feature_flag_called events

* Omit $feature_flag_has_experiment when the server does not report it

Author: haacked

.changeset/tall-cows-attend.md

@@ -0,0 +1,5 @@
+---
+"PostHog": minor
+---
+
+Add a `$feature_flag_has_experiment` boolean property to `$feature_flag_called` events when the server reports whether the flag is linked to an experiment. The property is omitted when the server does not report it (older deployments and legacy response formats).

src/PostHog/Api/FeatureFlagWithMetadata.cs

@@ -84,4 +84,11 @@ internal record FeatureFlagMetadata
     /// A description of the feature flag.
     /// </summary>
     public string? Description { get; init; }
+
+    /// <summary>
+    /// Whether the feature flag is linked to an experiment. <c>null</c> when the server does not
+    /// report the field (older deployments).
+    /// </summary>
+    [JsonPropertyName("has_experiment")]
+    public bool? HasExperiment { get; init; }
 }

src/PostHog/Api/LocalEvaluationApiResult.cs

@@ -107,6 +107,13 @@ internal record LocalFeatureFlag
     /// </summary>
     [JsonPropertyName("ensure_experience_continuity")]
     public bool EnsureExperienceContinuity { get; init; }
+
+    /// <summary>
+    /// Whether the feature flag is linked to an experiment. <c>null</c> when the server does not
+    /// report the field (older deployments).
+    /// </summary>
+    [JsonPropertyName("has_experiment")]
+    public bool? HasExperiment { get; init; }
 }
 
 /// <summary>

src/PostHog/Features/FeatureFlag.cs

@@ -31,6 +31,12 @@ public record FeatureFlag
     /// </summary>
     public bool IsEnabled { get; init; } = true;
 
+    /// <summary>
+    /// Whether this feature flag is linked to an experiment, as reported by the server.
+    /// <c>null</c> when the server does not report it (older deployments).
+    /// </summary>
+    public bool? HasExperiment { get; init; }
+
     /// <summary>
     /// Creates a <see cref="FeatureFlag"/> instance from the <c>/flags</c> endpoint response. Since payloads are
     /// already calculated, we can look them up by the feature key.
@@ -44,10 +50,11 @@ internal static FeatureFlag CreateFromFlagsApi(
         FlagsApiResult apiResult)
     {
         var payload = NotNull(apiResult).FeatureFlagPayloads?.GetValueOrDefault(key);
+        var flag = apiResult.Flags?.GetValueOrDefault(key);
 
-        var featureFlag = apiResult.Flags is not null && apiResult.Flags.TryGetValue(key, out var flag)
-                                                      && flag.Metadata is { Id: { } id, Version: { } version }
-                                                      && flag.Reason?.Description is { } reason
+        var featureFlag = flag is not null
+                          && flag.Metadata is { Id: { } id, Version: { } version }
+                          && flag.Reason?.Description is { } reason
             ? new FeatureFlagWithMetadata
             {
                 Key = flag.Key,
@@ -65,7 +72,8 @@ internal static FeatureFlag CreateFromFlagsApi(
         {
             IsEnabled = value.IsString ? value.StringValue is not null : value.Value,
             VariantKey = value.StringValue,
-            Payload = payload is null ? null : JsonDocument.Parse(payload)
+            Payload = payload is null ? null : JsonDocument.Parse(payload),
+            HasExperiment = flag?.Metadata?.HasExperiment
         };
     }
 
@@ -90,7 +98,8 @@ internal static FeatureFlag CreateFromLocalEvaluation(
             Key = key,
             IsEnabled = value.IsString ? value.StringValue is not null : value.Value,
             VariantKey = value.StringValue,
-            Payload = payloadJsonString is null ? null : JsonDocument.Parse(payloadJsonString)
+            Payload = payloadJsonString is null ? null : JsonDocument.Parse(payloadJsonString),
+            HasExperiment = localFeatureFlag.HasExperiment
         };
     }
 
@@ -104,13 +113,14 @@ other is not null
         && Key == other.Key
         && IsEnabled == other.IsEnabled
         && VariantKey == other.VariantKey
+        && HasExperiment == other.HasExperiment
         && JsonEqual(Payload, other.Payload);
 
     /// <summary>
     /// Serves as the default hash function.
     /// </summary>
     /// <returns>A hash code for the current <see cref="FeatureFlag"/>.</returns>
-    public override int GetHashCode() => HashCode.Combine(Key, IsEnabled, VariantKey, Payload);
+    public override int GetHashCode() => HashCode.Combine(Key, IsEnabled, VariantKey, HasExperiment, Payload);
 
     static bool JsonEqual(JsonDocument? source, JsonDocument? comparand) =>
         JsonNode.DeepEquals(ToJsonNode(source), ToJsonNode(comparand));

src/PostHog/PostHogClient.cs

@@ -811,6 +811,13 @@ static Dictionary<string, object> BuildFeatureFlagCalledProperties(
             ["locally_evaluated"] = locallyEvaluated,
             [$"$feature/{featureKey}"] = flag.ToResponseObject()
         };
+
+        // Tri-state: only sent when the server explicitly reported has_experiment; omitted when
+        // unknown (older deployments, legacy response formats, or missing flags).
+        if (flag?.HasExperiment is { } hasExperiment)
+        {
+            properties["$feature_flag_has_experiment"] = hasExperiment;
+        }
         if (locallyEvaluated)
         {
             properties["$feature_flag_reason"] = "Evaluated locally";

src/PostHog/PublicAPI.Unshipped.txt

@@ -1,6 +1,8 @@
 #nullable enable
 PostHog.AllFeatureFlagsOptions.DisableGeoIp.get -> bool
 PostHog.AllFeatureFlagsOptions.DisableGeoIp.init -> void
+PostHog.Features.FeatureFlag.HasExperiment.get -> bool?
+PostHog.Features.FeatureFlag.HasExperiment.init -> void
 PostHog.PostHogOptions.BeforeSend.get -> System.Func<PostHog.Api.CapturedEvent!, PostHog.Api.CapturedEvent?>?
 PostHog.PostHogOptions.BeforeSend.set -> void
 PostHog.PostHogOptions.FeatureFlagRequestMaxRetries.get -> int

tests/UnitTests/Features/FeatureFlagsTests.cs

@@ -748,6 +748,115 @@ public async Task CapturesFeatureFlagCalledEventWithAdditionalMetadataIdWhenPres
               """
             , received);
     }
+
+    [Theory]
+    [InlineData("\"has_experiment\": true,", true)]
+    [InlineData("\"has_experiment\": false,", false)]
+    [InlineData("", null)] // Older deployments don't report the field, so the property is omitted.
+    public async Task CapturesFeatureFlagCalledEventWithHasExperimentFromFlagsMetadata(
+        string hasExperimentJson,
+        bool? expected)
+    {
+        var container = new TestContainer();
+        var messageHandler = container.FakeHttpMessageHandler;
+        messageHandler.AddFlagsResponse(
+            $$"""
+              {
+                  "flags": {
+                      "flag-key": {
+                          "key": "flag-key",
+                          "enabled": true,
+                          "variant": null,
+                          "reason": {
+                            "code": "condition_match",
+                            "description": "Matched conditions set 1",
+                            "condition_index": 0
+                          },
+                          "metadata": {
+                            "id": 1,
+                            "version": 2,
+                            {{hasExperimentJson}}
+                            "description": "A flag"
+                          }
+                      }
+                  }
+              }
+              """
+        );
+        var captureRequestHandler = messageHandler.AddBatchResponse();
+        var client = container.Activate<PostHogClient>();
+
+        Assert.True(await client.IsFeatureEnabledAsync("flag-key", "a-distinct-id"));
+
+        await client.FlushAsync();
+        using var document = JsonDocument.Parse(captureRequestHandler.GetReceivedRequestBody(indented: false));
+        var properties = document.RootElement.GetProperty("batch")
+            .EnumerateArray()
+            .Single()
+            .GetProperty("properties");
+        if (expected is { } expectedValue)
+        {
+            Assert.Equal(expectedValue, properties.GetProperty("$feature_flag_has_experiment").GetBoolean());
+        }
+        else
+        {
+            Assert.False(properties.TryGetProperty("$feature_flag_has_experiment", out _));
+        }
+    }
+
+    [Theory]
+    [InlineData("\"has_experiment\": true,", true)]
+    [InlineData("\"has_experiment\": false,", false)]
+    [InlineData("", null)] // Older deployments don't report the field, so the property is omitted.
+    public async Task CapturesFeatureFlagCalledEventWithHasExperimentFromLocalEvaluation(
+        string hasExperimentJson,
+        bool? expected)
+    {
+        var container = new TestContainer(personalApiKey: "fake-personal-api-key");
+        var messageHandler = container.FakeHttpMessageHandler;
+        messageHandler.AddLocalEvaluationResponse(
+            $$"""
+              {
+                "flags": [
+                  {
+                      "id": 1,
+                      "key": "flag-key",
+                      "active": true,
+                      {{hasExperimentJson}}
+                      "filters": {
+                          "groups": [
+                              {
+                                  "properties": [],
+                                  "rollout_percentage": 100
+                              }
+                          ]
+                      }
+                  }
+                ]
+              }
+              """
+        );
+        var captureRequestHandler = messageHandler.AddBatchResponse();
+        var client = container.Activate<PostHogClient>();
+
+        Assert.True(await client.IsFeatureEnabledAsync("flag-key", "a-distinct-id"));
+
+        await client.FlushAsync();
+        using var document = JsonDocument.Parse(captureRequestHandler.GetReceivedRequestBody(indented: false));
+        var properties = document.RootElement.GetProperty("batch")
+            .EnumerateArray()
+            .Single()
+            .GetProperty("properties");
+        if (expected is { } expectedValue)
+        {
+            Assert.Equal(expectedValue, properties.GetProperty("$feature_flag_has_experiment").GetBoolean());
+        }
+        else
+        {
+            Assert.False(properties.TryGetProperty("$feature_flag_has_experiment", out _));
+        }
+        Assert.True(properties.GetProperty("locally_evaluated").GetBoolean());
+    }
 }
 
 public class TheGetFeatureFlagAsyncMethod