feat(posthog-server): Add sendFeatureFlags option to capture (#347)

* feat(posthog-server): Add `sendFeatureFlags` option to capture

* docs(posthog-server): Update CHANGELOG

* docs(posthog-server): Add `sendFeatureFlags` usage to USAGE.md

* chore(posthog-server): Update API dump

* Update posthog-server/CHANGELOG.md

Co-authored-by: Phil Haack <[email protected]>

* Rename `sendFeatureFlags` -> `appendFeatureFlags`

---------

Co-authored-by: Phil Haack <[email protected]>

Author: dustinbyrne

posthog-server/CHANGELOG.md

@@ -1,8 +1,7 @@
 ## Next
 
-## 2.2.0 - 2025-12-01
-
-- feat: include `evaluated_at` properties in `$feature_flag_called` events ([#321](https://github.com/PostHog/posthog-android/pull/321))
+- feat: Include `evaluated_at` properties in `$feature_flag_called` events ([#321](https://github.com/PostHog/posthog-android/pull/321))
+- feat: Add `appendFeatureFlags` optional boolean to `capture` ([#347](https://github.com/PostHog/posthog-android/pull/347))
 
 ## 2.0.1 - 2025-11-24
 

posthog-server/USAGE.md

@@ -175,6 +175,39 @@ postHog.capture(
 )
 ```
 
+### Enriching Events with Feature Flags
+
+You can automatically enrich captured events with the user's current feature flag values by setting `appendFeatureFlags` to `true`. This adds `$feature/flag_name` properties for each flag and an `$active_feature_flags` array containing all enabled flags.
+
+This is useful for analyzing how feature flags correlate with user behavior without manually tracking flag states.
+
+#### Kotlin
+
+```kotlin
+postHog.capture(
+    distinctId = "user123",
+    event = "purchase_completed",
+    properties = mapOf("amount" to 99.99),
+    appendFeatureFlags = true
+)
+```
+
+#### Java
+
+```java
+postHog.capture(
+    "user123",
+    "purchase_completed",
+    PostHogCaptureOptions
+        .builder()
+        .property("amount", 99.99)
+        .appendFeatureFlags(true)
+        .build()
+);
+```
+
+When `appendFeatureFlags` is `true`, the SDK will fetch feature flags for the user (or use locally evaluated flags if local evaluation is enabled) and include them in the event properties.
+
 ## Error Tracking
 
 PostHog provides error tracking to help you monitor and debug errors in your application. Use the `captureException` API to log exceptions to PostHog.

posthog-server/api/posthog-server.api

@@ -4,7 +4,7 @@ public final class com/posthog/server/PostHog : com/posthog/PostHogStateless, co
 	public fun alias (Ljava/lang/String;Ljava/lang/String;)V
 	public fun capture (Ljava/lang/String;Ljava/lang/String;)V
 	public fun capture (Ljava/lang/String;Ljava/lang/String;Lcom/posthog/server/PostHogCaptureOptions;)V
-	public fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;)V
+	public fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Z)V
 	public fun captureException (Ljava/lang/Throwable;)V
 	public fun captureException (Ljava/lang/Throwable;Ljava/lang/String;)V
 	public fun captureException (Ljava/lang/Throwable;Ljava/lang/String;Ljava/util/Map;)V
@@ -40,8 +40,9 @@ public final class com/posthog/server/PostHog$Companion {
 
 public final class com/posthog/server/PostHogCaptureOptions {
 	public static final field Companion Lcom/posthog/server/PostHogCaptureOptions$Companion;
-	public synthetic fun <init> (Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public synthetic fun <init> (Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;ZLkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public static final fun builder ()Lcom/posthog/server/PostHogCaptureOptions$Builder;
+	public final fun getAppendFeatureFlags ()Z
 	public final fun getGroups ()Ljava/util/Map;
 	public final fun getProperties ()Ljava/util/Map;
 	public final fun getTimestamp ()Ljava/util/Date;
@@ -51,7 +52,9 @@ public final class com/posthog/server/PostHogCaptureOptions {
 
 public final class com/posthog/server/PostHogCaptureOptions$Builder {
 	public fun <init> ()V
+	public final fun appendFeatureFlags (Z)Lcom/posthog/server/PostHogCaptureOptions$Builder;
 	public final fun build ()Lcom/posthog/server/PostHogCaptureOptions;
+	public final fun getAppendFeatureFlags ()Z
 	public final fun getGroups ()Ljava/util/Map;
 	public final fun getProperties ()Ljava/util/Map;
 	public final fun getTimestamp ()Ljava/util/Date;
@@ -61,6 +64,7 @@ public final class com/posthog/server/PostHogCaptureOptions$Builder {
 	public final fun groups (Ljava/util/Map;)Lcom/posthog/server/PostHogCaptureOptions$Builder;
 	public final fun properties (Ljava/util/Map;)Lcom/posthog/server/PostHogCaptureOptions$Builder;
 	public final fun property (Ljava/lang/String;Ljava/lang/Object;)Lcom/posthog/server/PostHogCaptureOptions$Builder;
+	public final fun setAppendFeatureFlags (Z)V
 	public final fun setGroups (Ljava/util/Map;)V
 	public final fun setProperties (Ljava/util/Map;)V
 	public final fun setTimestamp (Ljava/util/Date;)V
@@ -203,7 +207,7 @@ public abstract interface class com/posthog/server/PostHogInterface {
 	public abstract fun alias (Ljava/lang/String;Ljava/lang/String;)V
 	public abstract fun capture (Ljava/lang/String;Ljava/lang/String;)V
 	public abstract fun capture (Ljava/lang/String;Ljava/lang/String;Lcom/posthog/server/PostHogCaptureOptions;)V
-	public abstract synthetic fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;)V
+	public abstract synthetic fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Z)V
 	public abstract fun captureException (Ljava/lang/Throwable;)V
 	public abstract fun captureException (Ljava/lang/Throwable;Ljava/lang/String;)V
 	public abstract fun captureException (Ljava/lang/Throwable;Ljava/lang/String;Ljava/util/Map;)V
@@ -235,7 +239,7 @@ public abstract interface class com/posthog/server/PostHogInterface {
 public final class com/posthog/server/PostHogInterface$DefaultImpls {
 	public static fun capture (Lcom/posthog/server/PostHogInterface;Ljava/lang/String;Ljava/lang/String;)V
 	public static fun capture (Lcom/posthog/server/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Lcom/posthog/server/PostHogCaptureOptions;)V
-	public static synthetic fun capture$default (Lcom/posthog/server/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;ILjava/lang/Object;)V
+	public static synthetic fun capture$default (Lcom/posthog/server/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;ZILjava/lang/Object;)V
 	public static fun captureException (Lcom/posthog/server/PostHogInterface;Ljava/lang/Throwable;)V
 	public static fun captureException (Lcom/posthog/server/PostHogInterface;Ljava/lang/Throwable;Ljava/lang/String;)V
 	public static fun captureException (Lcom/posthog/server/PostHogInterface;Ljava/lang/Throwable;Ljava/util/Map;)V

posthog-server/src/main/java/com/posthog/server/PostHog.kt

@@ -41,11 +41,25 @@ public class PostHog : PostHogStateless(), PostHogInterface {
         userPropertiesSetOnce: Map<String, Any>?,
         groups: Map<String, String>?,
         timestamp: java.util.Date?,
+        appendFeatureFlags: Boolean,
     ) {
+        val mergedProperties =
+            if (appendFeatureFlags) {
+                mergeFeatureFlagProperties(
+                    distinctId = distinctId,
+                    groups = groups,
+                    userProperties = userProperties,
+                    groupProperties = null,
+                    properties = properties,
+                )
+            } else {
+                properties
+            }
+
         super.captureStateless(
             event,
             distinctId,
-            properties,
+            mergedProperties,
             userProperties,
             userPropertiesSetOnce,
             groups,
@@ -147,6 +161,45 @@ public class PostHog : PostHogStateless(), PostHogInterface {
         )
     }
 
+    private fun mergeFeatureFlagProperties(
+        distinctId: String,
+        groups: Map<String, String>?,
+        userProperties: Map<String, Any>?,
+        groupProperties: Map<String, Map<String, Any>>?,
+        properties: Map<String, Any>?,
+    ): Map<String, Any> {
+        val props = properties?.toMutableMap() ?: mutableMapOf()
+        val flags =
+            (featureFlags as? PostHogFeatureFlags)?.getFeatureFlags(
+                distinctId = distinctId,
+                groups = groups,
+                groupProperties = groupProperties,
+                personProperties = userProperties,
+            )
+
+        if (flags != null && flags.isNotEmpty()) {
+            val activeFlags = mutableListOf<String>()
+
+            for ((key, flag) in flags) {
+                val flagValue: Any = flag.variant ?: flag.enabled
+                props["\$feature/$key"] = flagValue
+                val isActive =
+                    when (flagValue) {
+                        is Boolean -> flagValue
+                        is String -> flagValue.isNotEmpty()
+                        else -> true
+                    }
+                if (isActive) {
+                    activeFlags.add(key)
+                }
+            }
+
+            props["\$active_feature_flags"] = activeFlags
+        }
+
+        return props
+    }
+
     public companion object {
         /**
          * Set up the SDK and returns an instance that you can hold and pass it around

posthog-server/src/main/java/com/posthog/server/PostHogCaptureOptions.kt

@@ -14,13 +14,15 @@ public class PostHogCaptureOptions private constructor(
     public val userPropertiesSetOnce: Map<String, Any>?,
     public val groups: Map<String, String>?,
     public val timestamp: Date? = null,
+    public val appendFeatureFlags: Boolean = false,
 ) {
     public class Builder {
         public var properties: MutableMap<String, Any>? = null
         public var userProperties: MutableMap<String, Any>? = null
         public var userPropertiesSetOnce: MutableMap<String, Any>? = null
         public var groups: MutableMap<String, String>? = null
         public var timestamp: Date? = null
+        public var appendFeatureFlags: Boolean = false
 
         /**
          * Add a single custom property to the capture options
@@ -155,13 +157,25 @@ public class PostHogCaptureOptions private constructor(
             return this
         }
 
+        /**
+         * When true, enriches the event with all evaluated feature flags.
+         * Adds `$feature/{flagName}` properties for each flag and
+         * `$active_feature_flags` array containing names of all truthy flags.
+         * @see <a href="https://posthog.com/docs/feature-flags">Documentation: Feature Flags</a>
+         */
+        public fun appendFeatureFlags(appendFeatureFlags: Boolean): Builder {
+            this.appendFeatureFlags = appendFeatureFlags
+            return this
+        }
+
         public fun build(): PostHogCaptureOptions =
             PostHogCaptureOptions(
                 properties,
                 userProperties,
                 userPropertiesSetOnce,
                 groups,
                 timestamp,
+                appendFeatureFlags,
             )
     }
 

posthog-server/src/main/java/com/posthog/server/PostHogInterface.kt

@@ -70,10 +70,13 @@ public sealed interface PostHogInterface {
     /**
      * Captures events
      * @param distinctId the distinctId of the user performing the event
+     * @param event the event name
      * @param properties the custom properties
      * @param userProperties the user properties, set as a "$set" property, Docs https://posthog.com/docs/product-analytics/user-properties
      * @param userPropertiesSetOnce the user properties to set only once, set as a "$set_once" property, Docs https://posthog.com/docs/product-analytics/user-properties
      * @param groups the groups, set as a "$groups" property, Docs https://posthog.com/docs/product-analytics/group-analytics
+     * @param timestamp the timestamp for the event
+     * @param appendFeatureFlags when true, enriches the event with feature flag properties
      */
     @JvmSynthetic
     public fun capture(
@@ -84,13 +87,14 @@ public sealed interface PostHogInterface {
         userPropertiesSetOnce: Map<String, Any>? = null,
         groups: Map<String, String>? = null,
         timestamp: Date? = null,
+        appendFeatureFlags: Boolean = false,
     )
 
     /**
      * Captures events
-     * @param event the event name
      * @param distinctId the distinctId
-     * @param options the capture options containing properties, userProperties, userPropertiesSetOnce, and groups
+     * @param event the event name
+     * @param options the capture options containing properties, userProperties, userPropertiesSetOnce, groups, and appendFeatureFlags
      */
     public fun capture(
         distinctId: String,
@@ -105,6 +109,7 @@ public sealed interface PostHogInterface {
             options.userPropertiesSetOnce,
             options.groups,
             options.timestamp,
+            options.appendFeatureFlags,
         )
     }
 

posthog-server/src/test/java/com/posthog/server/PostHogCaptureOptionsTest.kt

@@ -581,4 +581,43 @@ internal class PostHogCaptureOptionsTest {
         assertEquals(date, optionsFromLong.timestamp)
         assertEquals(date, optionsFromInstant.timestamp)
     }
+
+    @Test
+    fun `appendFeatureFlags defaults to false`() {
+        val options = PostHogCaptureOptions.builder().build()
+
+        assertEquals(false, options.appendFeatureFlags)
+    }
+
+    @Test
+    fun `appendFeatureFlags can be set to true`() {
+        val options =
+            PostHogCaptureOptions.builder()
+                .appendFeatureFlags(true)
+                .build()
+
+        assertEquals(true, options.appendFeatureFlags)
+    }
+
+    @Test
+    fun `appendFeatureFlags returns builder for chaining`() {
+        val builder = PostHogCaptureOptions.builder()
+        val result = builder.appendFeatureFlags(true)
+
+        assertEquals(builder, result)
+    }
+
+    @Test
+    fun `appendFeatureFlags can be combined with other options`() {
+        val options =
+            PostHogCaptureOptions.builder()
+                .property("key", "value")
+                .appendFeatureFlags(true)
+                .timestamp(Date(1234567890L))
+                .build()
+
+        assertEquals(mapOf("key" to "value"), options.properties)
+        assertEquals(true, options.appendFeatureFlags)
+        assertEquals(Date(1234567890L), options.timestamp)
+    }
 }