wip: Local evaluation

Author: dustinbyrne

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

@@ -1,59 +1,78 @@
 package com.posthog.java.sample;
 
-import com.posthog.server.PostHogCaptureOptions;
-import com.posthog.server.PostHogConfig;
 import com.posthog.server.PostHog;
+import com.posthog.server.PostHogConfig;
 import com.posthog.server.PostHogInterface;
-
-import java.util.HashMap;
-import java.util.Map;
+import com.posthog.server.PostHogFeatureFlagOptions;
 
 /**
  * Simple Java 1.8 example demonstrating PostHog usage
  */
 public class PostHogJavaExample {
+    private static PostHogInterface postHog;
+
     public static void main(String[] args) {
         PostHogConfig config = PostHogConfig
-                .builder("phc_wz4KZkikEluCCdfY2B2h7MXYygNGdTqFgjbU7I1ZdVR")
-                .build();
-
-        PostHogInterface postHog = PostHog.with(config);
+                .builder("phc_qYXiHw5odMiVWF7Dwh2sHWS7Hj6FsutBNp2SEaMqS0A")
+                .personalApiKey("phx_dQE4l5QTFXeQhgc0JNlMVndF8N713TYIfpNhdw0sftX6KG9")
+                .host("http://localhost:8010")
+                .localEvaluation(true)
+                .debug(true)
+                .onLocalEvaluationReady(() -> {
+                    if (postHog.isFeatureEnabled("distinct-id", "beta-feature", false)) {
+                        System.out.println("The feature is enabled.");
+                    }
 
-        postHog.group("distinct-id", "company", "some-company-id");
-        postHog.capture(
-                "distinct-id",
-                "new-purchase",
-                PostHogCaptureOptions
-                        .builder()
-                        .property("item", "SKU-0000")
-                        .property("sale", false)
-                        .build());
+                    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");
 
-        HashMap<String, Object> userProperties = new HashMap<>();
-        userProperties.put("email", "[email protected]");
-        postHog.identify("distinct-id", userProperties);
+                    System.out.println("The flag variant was: " + flagVariate);
+                    System.out.println("Received flag payload: " + flagPayload);
 
-        // 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");
-        // }});
+                    Boolean hasFilePreview = postHog.isFeatureEnabled(
+                            "distinct-id",
+                            "file-previews",
+                            PostHogFeatureFlagOptions
+                                    .builder()
+                                    .defaultValue(false)
+                                    .personProperty("email", "[email protected]")
+                                    .build());
 
-        postHog.alias("distinct-id", "alias-id");
+                    System.out.println("File previews enabled: " + hasFilePreview);
 
+                    postHog.flush();
+                    postHog.close();
 
-        if (postHog.isFeatureEnabled("distinct-id", "beta-feature", false)) {
-            System.out.println("The feature is enabled.");
-        }
+                    return null;
+                })
+                .build();
 
-        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");
+        postHog = PostHog.with(config);
 
-        System.out.println("The flag variant was: " + flagVariate);
-        System.out.println("Received flag payload: " + flagPayload);
+        /*
+         * postHog.group("distinct-id", "company", "some-company-id");
+         * postHog.capture(
+         * "distinct-id",
+         * "new-purchase",
+         * PostHogCaptureOptions
+         * .builder()
+         * .property("item", "SKU-0000")
+         * .property("sale", false)
+         * .build());
+         *
+         * HashMap<String, Object> userProperties = new HashMap<>();
+         * userProperties.put("email", "[email protected]");
+         * 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.alias("distinct-id", "alias-id");
+         */
 
-        postHog.flush();
-        postHog.close();
     }
 }

posthog-server/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - feat: `timestamp` can now be overridden when capturing an event ([#297](https://github.com/PostHog/posthog-android/issues/297))
 - feat: Add `groups`, `groupProperties`, `personProperties` overrides to feature flag methods ([#298](https://github.com/PostHog/posthog-android/issues/298))
+- feat: Add local evaluation for feature flags
 
 ## 1.0.3 - 2025-10-01
 

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)
+- `enableLocalEvaluation`: Enable local evaluation of feature flags (default: `false`) **(Experimental)**
+- `personalApiKey`: Personal API key required for local evaluation (default: `null`) **(Experimental)**
+- `pollIntervalSeconds`: Interval for polling flag definitions for local evaluation (default: `30`) **(Experimental)**
 
 ## Capturing Events
 
@@ -202,6 +205,52 @@ 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
+3. If evaluation is inconclusive (missing properties, etc.), the SDK falls back to the API
+
+**Requirements:**
+- A Personal API Key (get one from PostHog → Settings → User → Personal API Keys)
+- The `enableLocalEvaluation` config option set to `true`
+
+#### Kotlin
+
+```kotlin
+val config = PostHogConfig(
+    apiKey = "phc_your_api_key_here",
+    host = "https://your-posthog-instance.com",
+    enableLocalEvaluation = 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")
+    .enableLocalEvaluation(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
+- **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

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

@@ -11,6 +11,8 @@ import com.posthog.server.internal.PostHogMemoryQueue
 import com.posthog.server.internal.PostHogServerContext
 import java.net.Proxy
 
+internal typealias NullaryCallback = () -> Unit
+
 /**
  * The SDK Config
  */
@@ -106,6 +108,31 @@ public open class PostHogConfig constructor(
      * Defaults to 1000
      */
     public var featureFlagCalledCacheSize: Int = DEFAULT_FEATURE_FLAG_CALLED_CACHE_SIZE,
+    /**
+     * Enable local evaluation of feature flags
+     * When enabled, the SDK periodically fetches flag definitions and evaluates flags locally
+     * without making API calls for each flag check. Falls back to API if evaluation is inconclusive.
+     * Requires personalApiKey to be set.
+     * Defaults to false
+     */
+    public var enableLocalEvaluation: Boolean = false,
+    /**
+     * Personal API key for local evaluation
+     * Required when enableLocalEvaluation is true.
+     * Get your personal API key from PostHog -> Settings -> User -> Personal API Keys
+     * Defaults to null
+     */
+    public var personalApiKey: String? = null,
+    /**
+     * Interval in seconds for polling feature flag definitions for local evaluation
+     * Defaults to 30 seconds
+     */
+    public var pollIntervalSeconds: Int = DEFAULT_POLL_INTERVAL_SECONDS,
+    /**
+     * Callback when local evaluation is ready
+     */
+    public var onLocalEvaluationReady: NullaryCallback? = null
+
 ) {
     private val beforeSendCallbacks = mutableListOf<PostHogBeforeSend>()
     private val integrations = mutableListOf<PostHogIntegration>()
@@ -145,6 +172,10 @@ public open class PostHogConfig constructor(
                         api,
                         cacheMaxAgeMs = featureFlagCacheMaxAgeMs,
                         cacheMaxSize = featureFlagCacheSize,
+                        enableLocalEvaluation = enableLocalEvaluation,
+                        personalApiKey = personalApiKey,
+                        pollIntervalSeconds = pollIntervalSeconds,
+                        onLocalEvaluationReady = onLocalEvaluationReady,
                     )
                 },
                 queueProvider = { config, api, endpoint, _, executor ->
@@ -181,6 +212,7 @@ public open class PostHogConfig constructor(
         public const val DEFAULT_FEATURE_FLAG_CACHE_SIZE: Int = 1000
         public const val DEFAULT_FEATURE_FLAG_CACHE_MAX_AGE_MS: Int = 5 * 60 * 1000 // 5 minutes
         public const val DEFAULT_FEATURE_FLAG_CALLED_CACHE_SIZE: Int = 1000
+        public const val DEFAULT_POLL_INTERVAL_SECONDS: Int = 30
 
         @JvmStatic
         public fun builder(apiKey: String): Builder = Builder(apiKey)
@@ -202,39 +234,64 @@ public open class PostHogConfig constructor(
         private var featureFlagCacheSize: Int = DEFAULT_FEATURE_FLAG_CACHE_SIZE
         private var featureFlagCacheMaxAgeMs: Int = DEFAULT_FEATURE_FLAG_CACHE_MAX_AGE_MS
         private var featureFlagCalledCacheSize: Int = DEFAULT_FEATURE_FLAG_CALLED_CACHE_SIZE
+        private var enableLocalEvaluation: Boolean = false
+        private var personalApiKey: String? = null
+        private var pollIntervalSeconds: Int = DEFAULT_POLL_INTERVAL_SECONDS
+        private var onLocalEvaluationReady: NullaryCallback? = null
 
         public fun host(host: String): Builder = apply { this.host = host }
 
         public fun debug(debug: Boolean): Builder = apply { this.debug = debug }
 
-        public fun sendFeatureFlagEvent(sendFeatureFlagEvent: Boolean): Builder = apply { this.sendFeatureFlagEvent = sendFeatureFlagEvent }
+        public fun sendFeatureFlagEvent(sendFeatureFlagEvent: Boolean): Builder =
+            apply { this.sendFeatureFlagEvent = sendFeatureFlagEvent }
 
-        public fun preloadFeatureFlags(preloadFeatureFlags: Boolean): Builder = apply { this.preloadFeatureFlags = preloadFeatureFlags }
+        public fun preloadFeatureFlags(preloadFeatureFlags: Boolean): Builder =
+            apply { this.preloadFeatureFlags = preloadFeatureFlags }
 
-        public fun remoteConfig(remoteConfig: Boolean): Builder = apply { this.remoteConfig = remoteConfig }
+        public fun remoteConfig(remoteConfig: Boolean): Builder =
+            apply { this.remoteConfig = remoteConfig }
 
         public fun flushAt(flushAt: Int): Builder = apply { this.flushAt = flushAt }
 
-        public fun maxQueueSize(maxQueueSize: Int): Builder = apply { this.maxQueueSize = maxQueueSize }
+        public fun maxQueueSize(maxQueueSize: Int): Builder =
+            apply { this.maxQueueSize = maxQueueSize }
 
-        public fun maxBatchSize(maxBatchSize: Int): Builder = apply { this.maxBatchSize = maxBatchSize }
+        public fun maxBatchSize(maxBatchSize: Int): Builder =
+            apply { this.maxBatchSize = maxBatchSize }
 
-        public fun flushIntervalSeconds(flushIntervalSeconds: Int): Builder = apply { this.flushIntervalSeconds = flushIntervalSeconds }
+        public fun flushIntervalSeconds(flushIntervalSeconds: Int): Builder =
+            apply { this.flushIntervalSeconds = flushIntervalSeconds }
 
-        public fun encryption(encryption: PostHogEncryption?): Builder = apply { this.encryption = encryption }
+        public fun encryption(encryption: PostHogEncryption?): Builder =
+            apply { this.encryption = encryption }
 
-        public fun onFeatureFlags(onFeatureFlags: PostHogOnFeatureFlags?): Builder = apply { this.onFeatureFlags = onFeatureFlags }
+        public fun onFeatureFlags(onFeatureFlags: PostHogOnFeatureFlags?): Builder =
+            apply { this.onFeatureFlags = onFeatureFlags }
 
         public fun proxy(proxy: Proxy?): Builder = apply { this.proxy = proxy }
 
-        public fun featureFlagCacheSize(featureFlagCacheSize: Int): Builder = apply { this.featureFlagCacheSize = featureFlagCacheSize }
+        public fun featureFlagCacheSize(featureFlagCacheSize: Int): Builder =
+            apply { this.featureFlagCacheSize = featureFlagCacheSize }
 
         public fun featureFlagCacheMaxAgeMs(featureFlagCacheMaxAgeMs: Int): Builder =
             apply { this.featureFlagCacheMaxAgeMs = featureFlagCacheMaxAgeMs }
 
         public fun featureFlagCalledCacheSize(featureFlagCalledCacheSize: Int): Builder =
             apply { this.featureFlagCalledCacheSize = featureFlagCalledCacheSize }
 
+        public fun localEvaluation(enableLocalEvaluation: Boolean): Builder =
+            apply { this.enableLocalEvaluation = enableLocalEvaluation }
+
+        public fun personalApiKey(personalApiKey: String?): Builder =
+            apply { this.personalApiKey = personalApiKey }
+
+        public fun pollIntervalSeconds(pollIntervalSeconds: Int): Builder =
+            apply { this.pollIntervalSeconds = pollIntervalSeconds }
+
+        public fun onLocalEvaluationReady(onLocalEvaluationReady: NullaryCallback?): Builder =
+            apply { this.onLocalEvaluationReady = onLocalEvaluationReady }
+
         public fun build(): PostHogConfig =
             PostHogConfig(
                 apiKey = apiKey,
@@ -253,6 +310,10 @@ public open class PostHogConfig constructor(
                 featureFlagCacheSize = featureFlagCacheSize,
                 featureFlagCacheMaxAgeMs = featureFlagCacheMaxAgeMs,
                 featureFlagCalledCacheSize = featureFlagCalledCacheSize,
+                enableLocalEvaluation = enableLocalEvaluation,
+                personalApiKey = personalApiKey,
+                pollIntervalSeconds = pollIntervalSeconds,
+                onLocalEvaluationReady = onLocalEvaluationReady,
             )
     }
 }