feat(server): Send feature flags on event if sendFeatureFlags is set

posthog-samples/posthog-java-sample/src/main/java/com/posthog/java/sample/PostHogJavaExample.java

@@ -1,26 +1,31 @@
 package com.posthog.java.sample;
 
+import com.posthog.server.PostHog;
 import com.posthog.server.PostHogCaptureOptions;
 import com.posthog.server.PostHogConfig;
-import com.posthog.server.PostHog;
+import com.posthog.server.PostHogFeatureFlagOptions;
 import com.posthog.server.PostHogInterface;
-
+import com.posthog.server.PostHogSendFeatureFlagOptions;
 import java.util.HashMap;
-import java.util.Map;
 
 /**
  * Simple Java 1.8 example demonstrating PostHog usage
  */
 public class PostHogJavaExample {
+
     public static void main(String[] args) {
         PostHogConfig config = PostHogConfig
-                .builder("phc_wz4KZkikEluCCdfY2B2h7MXYygNGdTqFgjbU7I1ZdVR")
+                .builder("phc_wxtaSxv9yC8UYxUAxNojluoAf41L8p6SJZmiTMtS8jA")
+                .personalApiKey("phs_DuaFTmUtxQNj5R2W03emB1jMLIX5XwDvrt3DKfi5uYNcxzd")
+                .host("http://localhost:8010")
+                .localEvaluation(true)
+                .debug(true)
                 .build();
 
-        PostHogInterface postHog = PostHog.with(config);
+        PostHogInterface posthog = PostHog.with(config);
 
-        postHog.group("distinct-id", "company", "some-company-id");
-        postHog.capture(
+        posthog.group("distinct-id", "company", "some-company-id");
+        posthog.capture(
                 "distinct-id",
                 "new-purchase",
                 PostHogCaptureOptions
@@ -31,29 +36,54 @@ public static void main(String[] args) {
 
         HashMap<String, Object> userProperties = new HashMap<>();
         userProperties.put("email", "user@example.com");
-        postHog.identify("distinct-id", userProperties);
+        posthog.identify("distinct-id", userProperties);
 
         // AVOID - Anonymous inner class holds reference to outer class.
         // The following won't serialize properly.
-        // postHog.identify("user-123", new HashMap<String, Object>() {{
-        //      put("key", "value");
+        // posthog.identify("user-123", new HashMap<String, Object>() {{
+        // put("key", "value");
         // }});
 
-        postHog.alias("distinct-id", "alias-id");
+        posthog.alias("distinct-id", "alias-id");
 
-
-        if (postHog.isFeatureEnabled("distinct-id", "beta-feature", false)) {
+        // Feature flag examples with local evaluation
+        if (posthog.isFeatureEnabled("distinct-id", "beta-feature", false)) {
             System.out.println("The feature is enabled.");
         }
 
-        Object flagValue = postHog.getFeatureFlag("distinct-id", "multi-variate-flag", "default");
+        Object flagValue = posthog.getFeatureFlag("distinct-id", "multi-variate-flag", "default");
         String flagVariate = flagValue instanceof String ? (String) flagValue : "default";
-        Object flagPayload = postHog.getFeatureFlagPayload("distinct-id", "multi-variate-flag");
+        Object flagPayload = posthog.getFeatureFlagPayload("distinct-id", "multi-variate-flag");
 
         System.out.println("The flag variant was: " + flagVariate);
         System.out.println("Received flag payload: " + flagPayload);
 
-        postHog.flush();
-        postHog.close();
+        Boolean hasFilePreview = posthog.isFeatureEnabled(
+                "distinct-id",
+                "file-previews",
+                PostHogFeatureFlagOptions
+                        .builder()
+                        .defaultValue(false)
+                        .personProperty("email", "example@example.com")
+                        .build());
+
+        System.out.println("File previews enabled: " + hasFilePreview);
+
+        posthog.capture(
+                "distinct-id",
+                "file_uploaded",
+                PostHogCaptureOptions
+                        .builder()
+                        .property("file_name", "document.pdf")
+                        .property("file_size", 123456)
+                        .sendFeatureFlags(PostHogSendFeatureFlagOptions
+                                .builder()
+                                .personProperty("email", "example@example.com")
+                                .onlyEvaluateLocally(true)
+                                .build())
+                        .build());
+
+        posthog.flush();
+        posthog.close();
     }
 }

posthog-server/CHANGELOG.md

@@ -1,6 +1,7 @@
 ## Next
 
 - fix!: Restructured `groupProperties` and `userProperties` types to match the API and other SDKs
+- feat: Add local evaluation for feature flags ([#299](https://github.com/PostHog/posthog-android/issues/299))
 
 ## 1.1.0 - 2025-10-03
 

posthog-server/USAGE.md

@@ -92,6 +92,9 @@ PostHogConfig config = PostHogConfig.builder("phc_your_api_key_here")
 - `flushIntervalSeconds`: Interval between automatic flushes (default: `30`)
 - `featureFlagCacheSize`: The maximum number of feature flags results to cache (default: `1000`)
 - `featureFlagCacheMaxAgeMs`: The maximum age of a feature flag cache record in memory in milliseconds (default: `300000` or five minutes)
+- `localEvaluation`: Enable local evaluation of feature flags (default: `false`)
+- `personalApiKey`: Personal API key required for local evaluation (default: `null`)
+- `pollIntervalSeconds`: Interval for polling flag definitions for local evaluation (default: `30`)
 
 ## Capturing Events
 
@@ -202,6 +205,58 @@ postHog.identify("user123", userProperties, userPropertiesSetOnce);
 
 ## Feature Flags
 
+### Local Evaluation (Experimental)
+
+Local evaluation allows the SDK to evaluate feature flags locally without making API calls for each flag check. This reduces latency and API costs.
+
+**How it works:**
+
+1. The SDK periodically polls for flag definitions from PostHog (every 30 seconds by default)
+2. Flags are evaluated locally using cached definitions and properties provided by the caller
+3. If evaluation is inconclusive (missing properties, etc.), the SDK falls back to the API
+
+**Requirements:**
+
+- A feature flags secure API key _or_ a personal API key
+  - A feature flags secure API key can be obtained via PostHog → Settings → Project → Feature Flags → Feature Flags Secure API key
+  - A personal API key can be generated via PostHog → Settings → Account → Personal API Keys
+- The `localEvaluation` config option set to `true`
+
+#### Kotlin
+
+```kotlin
+val config = PostHogConfig(
+    apiKey = "phc_your_api_key_here",
+    host = "https://your-posthog-instance.com",
+    localEvaluation = true,
+    personalApiKey = "phx_your_personal_api_key_here",
+    pollIntervalSeconds = 30  // Optional: customize polling interval
+)
+```
+
+#### Java
+
+```java
+PostHogConfig config = PostHogConfig.builder("phc_your_api_key_here")
+    .host("https://your-posthog-instance.com")
+    .localEvaluation(true)
+    .personalApiKey("phx_your_personal_api_key_here")
+    .pollIntervalSeconds(30)  // Optional: customize polling interval
+    .build();
+```
+
+**Benefits:**
+
+- **Reduced latency**: No API call needed for most flag evaluations
+- **Lower costs**: Fewer API requests in most cases
+- **Offline support**: Flags continue to work with cached definitions
+
+**Limitations:**
+
+- Requires person/group properties to be provided with each call
+- Falls back to API for cohort-based flags without local cohort data
+- May not reflect real-time flag changes (respects polling interval)
+
 ### Check if Feature is Enabled
 
 #### Kotlin