From caf64bdbdeba83c86e7162c8e83ddb1763a0674e Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 22 Oct 2026 11:55:01 -0400 Subject: [PATCH 01/49] chore!: remove deprecated APIs for posthog-android 4.0 Remove the public APIs already marked deprecated: apiKey and the apiKey factories, propertiesSanitizer and PostHogPropertiesSanitizer, evaluationEnvironments, getFeatureFlagPayload, and the replay debouncerDelayMs. remoteConfig moves to its own change because setting it to false still changes setup behavior. Co-Authored-By: Claude Opus 5.5 (1M context) --- .changeset/android-v4-major.md | 10 ++ posthog-android/api/posthog-android.api | 13 +- .../posthog/android/PostHogAndroidConfig.kt | 36 ----- .../replay/PostHogSessionReplayConfig.kt | 17 --- .../android/PostHogAndroidConfigTest.kt | 12 -- posthog/api/posthog.api | 20 +-- posthog/src/main/java/com/posthog/PostHog.kt | 22 --- .../main/java/com/posthog/PostHogConfig.kt | 132 ------------------ .../main/java/com/posthog/PostHogInterface.kt | 16 --- .../com/posthog/PostHogPropertiesSanitizer.kt | 13 -- .../main/java/com/posthog/PostHogStateless.kt | 5 +- .../java/com/posthog/PostHogConfigTest.kt | 11 -- .../com/posthog/PostHogFeatureFlagsTest.kt | 2 - .../java/com/posthog/PostHogStatelessTest.kt | 35 ----- .../src/test/java/com/posthog/PostHogTest.kt | 49 +------ .../java/com/posthog/PostHogFake.kt | 8 -- 16 files changed, 17 insertions(+), 384 deletions(-) create mode 100644 .changeset/android-v4-major.md delete mode 100644 posthog/src/main/java/com/posthog/PostHogPropertiesSanitizer.kt diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md new file mode 100644 index 000000000..1b6846771 --- /dev/null +++ b/.changeset/android-v4-major.md @@ -0,0 +1,10 @@ +--- +'posthog': major +'posthog-android': major +--- + +- **Breaking:** remove the deprecated `apiKey` property and the `PostHogConfig(apiKey = …)` and `PostHogAndroidConfig(apiKey = …)` factories; use `projectToken` instead +- **Breaking:** remove the deprecated `propertiesSanitizer` config option and the `PostHogPropertiesSanitizer` interface; use `addBeforeSend` instead +- **Breaking:** remove the deprecated `evaluationEnvironments` config option; use `evaluationContexts` instead +- **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key)?.payload` instead +- **Breaking:** remove the deprecated `PostHogSessionReplayConfig.debouncerDelayMs`; use `throttleDelayMs` instead diff --git a/posthog-android/api/posthog-android.api b/posthog-android/api/posthog-android.api index 71c9f8c4a..ee90e68c6 100644 --- a/posthog-android/api/posthog-android.api +++ b/posthog-android/api/posthog-android.api @@ -17,7 +17,6 @@ public final class com/posthog/android/PostHogAndroid$Companion { } public class com/posthog/android/PostHogAndroidConfig : com/posthog/PostHogConfig { - public static final field Companion Lcom/posthog/android/PostHogAndroidConfig$Companion; public fun (Ljava/lang/String;)V public fun (Ljava/lang/String;Ljava/lang/String;)V public fun (Ljava/lang/String;Ljava/lang/String;Z)V @@ -47,11 +46,6 @@ public class com/posthog/android/PostHogAndroidConfig : com/posthog/PostHogConfi public final fun setSessionReplayConfig (Lcom/posthog/android/replay/PostHogSessionReplayConfig;)V } -public final class com/posthog/android/PostHogAndroidConfig$Companion { - public final synthetic fun invoke (Ljava/lang/String;Ljava/lang/String;ZZZLcom/posthog/android/replay/PostHogSessionReplayConfig;ZZ)Lcom/posthog/android/PostHogAndroidConfig; - public static synthetic fun invoke$default (Lcom/posthog/android/PostHogAndroidConfig$Companion;Ljava/lang/String;Ljava/lang/String;ZZZLcom/posthog/android/replay/PostHogSessionReplayConfig;ZZILjava/lang/Object;)Lcom/posthog/android/PostHogAndroidConfig; -} - public final class com/posthog/android/PostHogAutocaptureModifierKt { public static final fun postHogAutocaptureNoCapture (Landroidx/compose/ui/Modifier;Z)Landroidx/compose/ui/Modifier; public static synthetic fun postHogAutocaptureNoCapture$default (Landroidx/compose/ui/Modifier;ZILjava/lang/Object;)Landroidx/compose/ui/Modifier; @@ -130,12 +124,10 @@ public final class com/posthog/android/replay/PostHogSessionReplayConfig { public fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;)V public fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;Z)V public fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJ)V - public fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJJ)V - public fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJJLjava/lang/Double;)V - public synthetic fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJJLjava/lang/Double;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJLjava/lang/Double;)V + public synthetic fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJLjava/lang/Double;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun getCaptureLogcat ()Z public final fun getCaptureTouches ()Z - public final fun getDebouncerDelayMs ()J public final fun getDrawableConverter ()Lcom/posthog/android/replay/PostHogDrawableConverter; public final fun getMaskAllImages ()Z public final fun getMaskAllTextInputs ()Z @@ -148,7 +140,6 @@ public final class com/posthog/android/replay/PostHogSessionReplayConfig { public final fun getVerifyScreenshotMaskAlignment ()Z public final fun setCaptureLogcat (Z)V public final fun setCaptureTouches (Z)V - public final fun setDebouncerDelayMs (J)V public final fun setDrawableConverter (Lcom/posthog/android/replay/PostHogDrawableConverter;)V public final fun setMaskAllImages (Z)V public final fun setMaskAllTextInputs (Z)V diff --git a/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt b/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt index 3d188f772..7d406922e 100644 --- a/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt +++ b/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt @@ -96,40 +96,4 @@ public open class PostHogAndroidConfig public var captureDeadClicks: Boolean = false internal var replayQueueHolder: PostHogReplayQueue? = null - - public companion object { - /** - * Deprecated form of the [PostHogAndroidConfig] constructor that takes `apiKey` instead - * of `projectToken`, kept so Kotlin calls such as `PostHogAndroidConfig(apiKey = "phc_...")` - * still compile. Every other parameter and default matches the constructor. - * - * ```kotlin - * val config = PostHogAndroidConfig(projectToken = "phc_your_project_token") // instead of apiKey = - * ``` - */ - @Deprecated( - "Deprecated in favor of projectToken. This will be removed in the next major version.", - ) - @JvmSynthetic - public operator fun invoke( - apiKey: String, - host: String = PostHogConfig.DEFAULT_HOST, - captureApplicationLifecycleEvents: Boolean = true, - captureDeepLinks: Boolean = true, - captureScreenViews: Boolean = true, - sessionReplayConfig: PostHogSessionReplayConfig = PostHogSessionReplayConfig(), - capturePushNotificationSubscriptions: Boolean = true, - capturePushNotificationOpened: Boolean = true, - ): PostHogAndroidConfig = - PostHogAndroidConfig( - projectToken = apiKey, - host = host, - captureApplicationLifecycleEvents = captureApplicationLifecycleEvents, - captureDeepLinks = captureDeepLinks, - captureScreenViews = captureScreenViews, - sessionReplayConfig = sessionReplayConfig, - capturePushNotificationSubscriptions = capturePushNotificationSubscriptions, - capturePushNotificationOpened = capturePushNotificationOpened, - ) - } } diff --git a/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt b/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt index bc3c492a8..8590f86ec 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt +++ b/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt @@ -38,15 +38,6 @@ public class PostHogSessionReplayConfig * The screenshot may contain sensitive information, use with caution. */ public var screenshot: Boolean = false, - /** - * Debouncer delay used to reduce the number of snapshots captured and reduce performance impact. - * This is used for capturing the view as a wireframe or screenshot. - * The lower the number, the more snapshots are captured and the higher the performance impact. - * Defaults to 1000ms = 1s. - * Ps: it was 500ms by default until version 3.8.2. - */ - @Deprecated("Use throttleDelayMs instead") - public var debouncerDelayMs: Long = 1000, /** * Throttling delay used to reduce the number of snapshots captured and reduce performance impact. * This is used for capturing the view as a wireframe or screenshot. @@ -118,12 +109,4 @@ public class PostHogSessionReplayConfig @PostHogExperimental @Volatile public var screenshotColorMode: PostHogScreenshotColorMode = PostHogScreenshotColorMode.ARGB_8888 - - init { - // for keeping back compatibility - @Suppress("DEPRECATION") - if (debouncerDelayMs != 1000L) { - throttleDelayMs = debouncerDelayMs - } - } } diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidConfigTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidConfigTest.kt index 23d74cd34..ac6bc81c1 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidConfigTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidConfigTest.kt @@ -21,18 +21,6 @@ internal class PostHogAndroidConfigTest { assertEquals(PROJECT_TOKEN, config.projectToken) } - @Suppress("DEPRECATION") - @Test - fun `deprecated apiKey factory and getter alias projectToken`() { - val config = PostHogAndroidConfig(apiKey = " $PROJECT_TOKEN ", captureDeepLinks = false, capturePushNotificationOpened = false) - - assertEquals(PROJECT_TOKEN, config.projectToken) - assertEquals(PROJECT_TOKEN, config.apiKey) - assertFalse(config.captureDeepLinks) - assertFalse(config.capturePushNotificationOpened) - assertTrue(config.captureScreenViews) - } - @Test fun `captureApplicationLifecycleEvents should be enabled by default`() { assertTrue(config.captureApplicationLifecycleEvents) diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index 77e664f61..c744204de 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -39,7 +39,6 @@ public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posth public fun getConfig ()Lcom/posthog/PostHogConfig; public fun getDeviceId ()Ljava/lang/String; public fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Object;Ljava/lang/Boolean;)Ljava/lang/Object; - public fun getFeatureFlagPayload (Ljava/lang/String;Ljava/lang/Object;)Ljava/lang/Object; public fun getFeatureFlagResult (Ljava/lang/String;Ljava/lang/Boolean;)Lcom/posthog/FeatureFlagResult; public fun getLogger ()Lcom/posthog/logs/PostHogLogger; public fun getSessionId ()Ljava/util/UUID; @@ -88,7 +87,6 @@ public final class com/posthog/PostHog$Companion : com/posthog/PostHogInterface public fun getConfig ()Lcom/posthog/PostHogConfig; public fun getDeviceId ()Ljava/lang/String; public fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Object;Ljava/lang/Boolean;)Ljava/lang/Object; - public fun getFeatureFlagPayload (Ljava/lang/String;Ljava/lang/Object;)Ljava/lang/Object; public fun getFeatureFlagResult (Ljava/lang/String;Ljava/lang/Boolean;)Lcom/posthog/FeatureFlagResult; public fun getLogger ()Lcom/posthog/logs/PostHogLogger; public fun getSessionId ()Ljava/util/UUID; @@ -158,11 +156,10 @@ public class com/posthog/PostHogConfig { public static final field DEFAULT_MAX_QUEUE_SIZE I public static final field DEFAULT_US_ASSETS_HOST Ljava/lang/String; public static final field DEFAULT_US_HOST Ljava/lang/String; - public fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLcom/posthog/PostHogPropertiesSanitizer;Lkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLcom/posthog/PostHogPropertiesSanitizer;Lkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;IILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun addBeforeSend (Lcom/posthog/PostHogBeforeSend;)V public final fun addIntegration (Lcom/posthog/PostHogIntegration;)V - public final fun getApiKey ()Ljava/lang/String; public final fun getBeforeSendList ()Ljava/util/List; public final fun getBootstrap ()Lcom/posthog/PostHogBootstrapConfig; public final fun getCachePreferences ()Lcom/posthog/internal/PostHogPreferences; @@ -173,7 +170,6 @@ public class com/posthog/PostHogConfig { public final fun getEncryption ()Lcom/posthog/PostHogEncryption; public final fun getErrorTrackingConfig ()Lcom/posthog/errortracking/PostHogErrorTrackingConfig; public final fun getEvaluationContexts ()Ljava/util/List; - public final fun getEvaluationEnvironments ()Ljava/util/List; public final fun getFeatureFlagCalledCacheSize ()I public final fun getFeatureFlagRequestMaxRetries ()I public final fun getFlushAt ()I @@ -196,7 +192,6 @@ public class com/posthog/PostHogConfig { public final fun getPersonProfiles ()Lcom/posthog/PersonProfiles; public final fun getPreloadFeatureFlags ()Z public final fun getProjectToken ()Ljava/lang/String; - public final fun getPropertiesSanitizer ()Lcom/posthog/PostHogPropertiesSanitizer; public final fun getProxy ()Ljava/net/Proxy; public final fun getPushIdentityProvider ()Lkotlin/jvm/functions/Function3; public final fun getQueueProvider ()Lkotlin/jvm/functions/Function5; @@ -229,7 +224,6 @@ public class com/posthog/PostHogConfig { public final fun setDebug (Z)V public final fun setEncryption (Lcom/posthog/PostHogEncryption;)V public final fun setEvaluationContexts (Ljava/util/List;)V - public final fun setEvaluationEnvironments (Ljava/util/List;)V public final fun setFeatureFlagCalledCacheSize (I)V public final fun setFeatureFlagRequestMaxRetries (I)V public final fun setFlushAt (I)V @@ -249,7 +243,6 @@ public class com/posthog/PostHogConfig { public final fun setPersistOptOut (Z)V public final fun setPersonProfiles (Lcom/posthog/PersonProfiles;)V public final fun setPreloadFeatureFlags (Z)V - public final fun setPropertiesSanitizer (Lcom/posthog/PostHogPropertiesSanitizer;)V public final fun setProxy (Ljava/net/Proxy;)V public final fun setPushIdentityProvider (Lkotlin/jvm/functions/Function3;)V public final fun setReleaseIdentifier (Ljava/lang/String;)V @@ -272,8 +265,6 @@ public class com/posthog/PostHogConfig { } public final class com/posthog/PostHogConfig$Companion { - public final synthetic fun invoke (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLcom/posthog/PostHogPropertiesSanitizer;Lkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;)Lcom/posthog/PostHogConfig; - public static synthetic fun invoke$default (Lcom/posthog/PostHogConfig$Companion;Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLcom/posthog/PostHogPropertiesSanitizer;Lkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;IILjava/lang/Object;)Lcom/posthog/PostHogConfig; } public abstract interface class com/posthog/PostHogCoreInterface { @@ -395,8 +386,6 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public abstract fun getDeviceId ()Ljava/lang/String; public abstract fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Object;Ljava/lang/Boolean;)Ljava/lang/Object; public static synthetic fun getFeatureFlag$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/Boolean;ILjava/lang/Object;)Ljava/lang/Object; - public abstract fun getFeatureFlagPayload (Ljava/lang/String;Ljava/lang/Object;)Ljava/lang/Object; - public static synthetic fun getFeatureFlagPayload$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Object;ILjava/lang/Object;)Ljava/lang/Object; public abstract fun getFeatureFlagResult (Ljava/lang/String;Ljava/lang/Boolean;)Lcom/posthog/FeatureFlagResult; public static synthetic fun getFeatureFlagResult$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Lcom/posthog/FeatureFlagResult; public abstract fun getLogger ()Lcom/posthog/logs/PostHogLogger; @@ -441,7 +430,6 @@ public final class com/posthog/PostHogInterface$DefaultImpls { public static synthetic fun captureLog$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Lcom/posthog/logs/PostHogLogSeverity;Ljava/util/Map;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;ILjava/lang/Object;)V public static synthetic fun capturePushNotificationOpened$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/lang/String;ILjava/lang/Object;)V public static synthetic fun getFeatureFlag$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/Boolean;ILjava/lang/Object;)Ljava/lang/Object; - public static synthetic fun getFeatureFlagPayload$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Object;ILjava/lang/Object;)Ljava/lang/Object; public static synthetic fun getFeatureFlagResult$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Lcom/posthog/FeatureFlagResult; public static synthetic fun group$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V public static synthetic fun isFeatureEnabled$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZLjava/lang/Boolean;ILjava/lang/Object;)Z @@ -475,10 +463,6 @@ public abstract interface class com/posthog/PostHogOptInReceiver { public abstract fun onOptIn ()V } -public abstract interface class com/posthog/PostHogPropertiesSanitizer { - public abstract fun sanitize (Ljava/util/Map;)Ljava/util/Map; -} - public class com/posthog/PostHogStateless : com/posthog/PostHogStatelessInterface { public static final field Companion Lcom/posthog/PostHogStateless$Companion; protected field config Lcom/posthog/PostHogConfig; diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 281503ecb..6bd98ff1e 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -2100,18 +2100,6 @@ public class PostHog private constructor( return results } - @Deprecated( - message = "Use getFeatureFlagResult() instead; note it sends the \$feature_flag_called event by default.", - replaceWith = ReplaceWith("getFeatureFlagResult(key)?.payload"), - ) - public override fun getFeatureFlagPayload( - key: String, - defaultValue: Any?, - ): Any? { - if (!isEnabled()) return defaultValue - return getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload ?: defaultValue - } - public override fun getFeatureFlagResult( key: String, sendFeatureFlagEvent: Boolean?, @@ -2748,16 +2736,6 @@ public class PostHog private constructor( return shared.getAllFeatureFlags() } - @Deprecated( - message = "Use getFeatureFlagResult() instead; note it sends the \$feature_flag_called event by default.", - replaceWith = ReplaceWith("getFeatureFlagResult(key)?.payload"), - ) - @Suppress("DEPRECATION") - public override fun getFeatureFlagPayload( - key: String, - defaultValue: Any?, - ): Any? = shared.getFeatureFlagPayload(key, defaultValue = defaultValue) - public override fun getFeatureFlagResult( key: String, sendFeatureFlagEvent: Boolean?, diff --git a/posthog/src/main/java/com/posthog/PostHogConfig.kt b/posthog/src/main/java/com/posthog/PostHogConfig.kt index eb730adab..c01078500 100644 --- a/posthog/src/main/java/com/posthog/PostHogConfig.kt +++ b/posthog/src/main/java/com/posthog/PostHogConfig.kt @@ -173,12 +173,6 @@ public open class PostHogConfig( * Defaults to false */ public var sessionReplay: Boolean = false, - /** - * Hook that allows to sanitize the event properties - * The hook is called before the event is cached or sent over the wire - */ - @Deprecated("Use beforeSendList instead") - public var propertiesSanitizer: PostHogPropertiesSanitizer? = null, /** * Hook that allows for modification of the default mechanism for * generating anonymous id (which as of now is just random UUID v7) @@ -446,20 +440,6 @@ public open class PostHogConfig( */ public val projectToken: String = projectToken.trim() - /** - * Deprecated alias for [projectToken]; returns the same trimmed value. - * - * ```kotlin - * val token = config.projectToken // instead of config.apiKey - * ``` - */ - @Deprecated( - "Deprecated in favor of projectToken. This will be removed in the next major version.", - ReplaceWith("projectToken"), - ) - public val apiKey: String - get() = projectToken - /** * The PostHog Host * Defaults to https://us.i.posthog.com @@ -602,20 +582,6 @@ public open class PostHogConfig( } } - /** - * Optional list of evaluation environment tags for feature flag evaluation - * @deprecated Use evaluationContexts instead. This property will be removed in a future version. - */ - @Deprecated( - message = "Use evaluationContexts instead. This property will be removed in a future version.", - replaceWith = ReplaceWith("evaluationContexts"), - ) - public var evaluationEnvironments: List? - get() = evaluationContexts - set(value) { - evaluationContexts = value - } - public companion object { /** Shared default for [flushAt] and [PostHogLogsConfig.flushAt]. */ public const val DEFAULT_FLUSH_AT: Int = 20 @@ -639,104 +605,6 @@ public open class PostHogConfig( public const val DEFAULT_EU_ASSETS_HOST: String = "https://eu-assets.i.posthog.com" public const val DEFAULT_FEATURE_FLAG_CALLED_CACHE_SIZE: Int = 1000 - - /** - * Deprecated form of the [PostHogConfig] constructor that takes `apiKey` instead of - * `projectToken`, kept so Kotlin calls such as `PostHogConfig(apiKey = "phc_...")` still - * compile. Every other parameter and default matches the constructor. - * - * ```kotlin - * val config = PostHogConfig(projectToken = "phc_your_project_token") // instead of apiKey = - * ``` - */ - @Deprecated( - "Deprecated in favor of projectToken. This will be removed in the next major version.", - ) - @Suppress("DEPRECATION") - @JvmSynthetic - public operator fun invoke( - apiKey: String, - host: String = DEFAULT_HOST, - debug: Boolean = false, - optOut: Boolean = false, - sendFeatureFlagEvent: Boolean = true, - featureFlagCalledCacheSize: Int = DEFAULT_FEATURE_FLAG_CALLED_CACHE_SIZE, - preloadFeatureFlags: Boolean = true, - evaluationContexts: List? = null, - setDefaultPersonProperties: Boolean = true, - remoteConfig: Boolean = true, - flushAt: Int = DEFAULT_FLUSH_AT, - maxQueueSize: Int = DEFAULT_MAX_QUEUE_SIZE, - maxBatchSize: Int = DEFAULT_MAX_BATCH_SIZE, - maxRetries: Int = 3, - featureFlagRequestMaxRetries: Int = 1, - flushIntervalSeconds: Int = DEFAULT_FLUSH_INTERVAL_SECONDS, - encryption: PostHogEncryption? = null, - onFeatureFlags: PostHogOnFeatureFlags? = null, - sessionReplay: Boolean = false, - propertiesSanitizer: PostHogPropertiesSanitizer? = null, - getAnonymousId: ((UUID) -> UUID) = { it }, - reuseAnonymousId: Boolean = false, - personProfiles: PersonProfiles = PersonProfiles.IDENTIFIED_ONLY, - surveys: Boolean = false, - proxy: Proxy? = null, - surveysConfig: PostHogSurveysConfig = PostHogSurveysConfig(), - logs: PostHogLogsConfig = PostHogLogsConfig(), - remoteConfigProvider: ( - PostHogConfig, - PostHogApi, - ExecutorService, - PostHogDefaultPersonPropertiesProvider?, - PostHogOnRemoteConfigLoaded?, - PostHogFeatureFlagCalledProvider?, - ) -> PostHogFeatureFlagsInterface = DEFAULT_REMOTE_CONFIG_PROVIDER, - queueProvider: ( - PostHogConfig, - PostHogApi, - PostHogApiEndpoint, - String?, - ExecutorService, - ) -> PostHogQueueInterface = DEFAULT_QUEUE_PROVIDER, - errorTrackingConfig: PostHogErrorTrackingConfig = PostHogErrorTrackingConfig(), - releaseIdentifier: String? = null, - bootstrap: PostHogBootstrapConfig? = null, - pushIdentityProvider: ((distinctId: String, appId: String, completion: (String?) -> Unit) -> Unit)? = null, - ): PostHogConfig = - PostHogConfig( - projectToken = apiKey, - host = host, - debug = debug, - optOut = optOut, - sendFeatureFlagEvent = sendFeatureFlagEvent, - featureFlagCalledCacheSize = featureFlagCalledCacheSize, - preloadFeatureFlags = preloadFeatureFlags, - evaluationContexts = evaluationContexts, - setDefaultPersonProperties = setDefaultPersonProperties, - remoteConfig = remoteConfig, - flushAt = flushAt, - maxQueueSize = maxQueueSize, - maxBatchSize = maxBatchSize, - maxRetries = maxRetries, - featureFlagRequestMaxRetries = featureFlagRequestMaxRetries, - flushIntervalSeconds = flushIntervalSeconds, - encryption = encryption, - onFeatureFlags = onFeatureFlags, - sessionReplay = sessionReplay, - propertiesSanitizer = propertiesSanitizer, - getAnonymousId = getAnonymousId, - reuseAnonymousId = reuseAnonymousId, - personProfiles = personProfiles, - surveys = surveys, - proxy = proxy, - surveysConfig = surveysConfig, - logs = logs, - remoteConfigProvider = remoteConfigProvider, - queueProvider = queueProvider, - errorTrackingConfig = errorTrackingConfig, - releaseIdentifier = releaseIdentifier, - bootstrap = bootstrap, - pushIdentityProvider = pushIdentityProvider, - ) } } diff --git a/posthog/src/main/java/com/posthog/PostHogInterface.kt b/posthog/src/main/java/com/posthog/PostHogInterface.kt index 126d09734..50e76b49b 100644 --- a/posthog/src/main/java/com/posthog/PostHogInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogInterface.kt @@ -163,22 +163,6 @@ public interface PostHogInterface : PostHogCoreInterface { */ public fun getAllFeatureFlags(): List? - /** - * Returns the feature flag payload - * Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments - * @param key the Key - * @param defaultValue the default value if not found - * @return The feature flag payload, or [defaultValue] if not found. - */ - @Deprecated( - message = "Use getFeatureFlagResult() instead; note it sends the \$feature_flag_called event by default.", - replaceWith = ReplaceWith("getFeatureFlagResult(key)?.payload"), - ) - public fun getFeatureFlagPayload( - key: String, - defaultValue: Any? = null, - ): Any? - /** * Returns the feature flag result containing both value and payload. * This is the recommended way to access feature flags when you need both diff --git a/posthog/src/main/java/com/posthog/PostHogPropertiesSanitizer.kt b/posthog/src/main/java/com/posthog/PostHogPropertiesSanitizer.kt deleted file mode 100644 index 8d4f0d5f1..000000000 --- a/posthog/src/main/java/com/posthog/PostHogPropertiesSanitizer.kt +++ /dev/null @@ -1,13 +0,0 @@ -package com.posthog - -/** - * Hook to sanitize the event properties - */ -public fun interface PostHogPropertiesSanitizer { - /** - * Sanitizes the event properties - * @param properties the event properties to sanitize - * @return the sanitized properties - */ - public fun sanitize(properties: MutableMap): Map -} diff --git a/posthog/src/main/java/com/posthog/PostHogStateless.kt b/posthog/src/main/java/com/posthog/PostHogStateless.kt index bc54145ad..bd6505876 100644 --- a/posthog/src/main/java/com/posthog/PostHogStateless.kt +++ b/posthog/src/main/java/com/posthog/PostHogStateless.kt @@ -292,20 +292,17 @@ public open class PostHogStateless protected constructor( } } - @Suppress("DEPRECATION") protected fun buildEvent( event: String, distinctId: String, properties: MutableMap, timestamp: Date? = null, ): PostHogEvent? { - // sanitize the properties or fallback to the original properties - val sanitizedProperties = config?.propertiesSanitizer?.sanitize(properties)?.toMutableMap() ?: properties val postHogEvent = PostHogEvent( event, distinctId, - properties = sanitizedProperties, + properties = properties, timestamp = timestamp ?: config?.dateProvider?.currentDate() ?: Date(), ) var eventChecked: PostHogEvent = postHogEvent diff --git a/posthog/src/test/java/com/posthog/PostHogConfigTest.kt b/posthog/src/test/java/com/posthog/PostHogConfigTest.kt index e650bb8a6..7903540c3 100644 --- a/posthog/src/test/java/com/posthog/PostHogConfigTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogConfigTest.kt @@ -23,17 +23,6 @@ internal class PostHogConfigTest { assertEquals("https://eu.i.posthog.com/", config.host) } - @Suppress("DEPRECATION") - @Test - fun `deprecated apiKey factory and getter alias projectToken`() { - val config = PostHogConfig(apiKey = " $PROJECT_TOKEN ", host = "https://eu.i.posthog.com", flushAt = 7) - - assertEquals(PROJECT_TOKEN, config.projectToken) - assertEquals(PROJECT_TOKEN, config.apiKey) - assertEquals("https://eu.i.posthog.com", config.host) - assertEquals(7, config.flushAt) - } - @Test fun `defaults a blank host after trimming whitespace`() { val config = PostHogConfig(PROJECT_TOKEN, " \n\t ") diff --git a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt index 9019adae7..82575e966 100644 --- a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt @@ -54,7 +54,6 @@ internal class PostHogFeatureFlagsTest { integration: PostHogIntegration? = null, remoteConfig: Boolean = false, cachePreferences: PostHogMemoryPreferences = PostHogMemoryPreferences(), - propertiesSanitizer: PostHogPropertiesSanitizer? = null, beforeSend: PostHogBeforeSend? = null, evaluationContexts: List? = null, context: PostHogContext? = null, @@ -73,7 +72,6 @@ internal class PostHogFeatureFlagsTest { this.sendFeatureFlagEvent = sendFeatureFlagEvent this.reuseAnonymousId = reuseAnonymousId this.cachePreferences = cachePreferences - this.propertiesSanitizer = propertiesSanitizer this.evaluationContexts = evaluationContexts this.remoteConfig = remoteConfig if (beforeSend != null) { diff --git a/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt b/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt index d6c754195..00dddfffb 100644 --- a/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt @@ -1087,41 +1087,6 @@ internal class PostHogStatelessTest { assertTrue(mockLogger.messages.any { it.contains("Error in beforeSend function") }) } - @Test - fun `properties sanitizer is applied to events`() { - val mockQueue = MockQueue() - sut = createStatelessInstance() - config = - createConfig().apply { - @Suppress("DEPRECATION") - propertiesSanitizer = - PostHogPropertiesSanitizer { properties -> - properties.apply { - remove("sensitive") - put("sanitized", true) - } - } - } - - sut.setup(config) - sut.setMockQueue(mockQueue) - - sut.captureStateless( - "test", - "user123", - mapOf( - "safe" to "value", - "sensitive" to "secret", - ), - ) - - assertEquals(1, mockQueue.events.size) - val event = mockQueue.events.first() - assertEquals("value", event.properties!!["safe"]) - assertNull(event.properties!!["sensitive"]) - assertEquals(true, event.properties!!["sanitized"]) - } - @Test fun `feature flag called events are sent when feature flags accessed`() { val mockQueue = MockQueue() diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index 01286caba..5ce8ff3be 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -97,7 +97,6 @@ internal class PostHogTest { remoteConfig: Boolean = false, surveys: Boolean = false, cachePreferences: PostHogPreferences? = PostHogMemoryPreferences(), - propertiesSanitizer: PostHogPropertiesSanitizer? = null, beforeSend: PostHogBeforeSend? = null, evaluationContexts: List? = null, context: PostHogContext? = null, @@ -121,7 +120,6 @@ internal class PostHogTest { this.sendFeatureFlagEvent = sendFeatureFlagEvent this.reuseAnonymousId = reuseAnonymousId this.cachePreferences = cachePreferences - this.propertiesSanitizer = propertiesSanitizer this.evaluationContexts = evaluationContexts this.remoteConfig = remoteConfig this.surveys = surveys @@ -1009,8 +1007,7 @@ internal class PostHogTest { } @Test - @Suppress("DEPRECATION") - fun `getFeatureFlagPayload returns the value after reloaded`() { + fun `getFeatureFlagResult returns the payload after reloaded`() { val http = mockHttp( response = @@ -1025,7 +1022,7 @@ internal class PostHogTest { remoteConfigExecutor.shutdownAndAwaitTermination() - assertTrue(sut.getFeatureFlagPayload("4535-funnel-bar-viz") as Boolean) + assertTrue(sut.getFeatureFlagResult("4535-funnel-bar-viz", sendFeatureFlagEvent = false)?.payload as Boolean) sut.close() } @@ -3068,48 +3065,6 @@ internal class PostHogTest { assertFalse(config.debug) } - @Suppress("DEPRECATION") - @Test - fun `sanitize properties`() { - val http = mockHttp() - val url = http.url("/") - - val propertiesSanitizer = - PostHogPropertiesSanitizer { properties -> - properties.apply { - remove("prop") - } - } - - val sut = getSut(url.toString(), preloadFeatureFlags = false, propertiesSanitizer = propertiesSanitizer) - - sut.capture( - EVENT, - DISTINCT_ID, - // contains "prop" - props, - userProperties = userProps, - userPropertiesSetOnce = userPropsOnce, - groups = groups, - ) - - queueExecutor.shutdownAndAwaitTermination() - - val request = http.takeRequest() - - assertEquals(1, http.requestCount) - val content = request.body.unGzip() - val batch = serializer.deserialize(content.reader()) - - assertEquals(PROJECT_TOKEN, batch.projectToken) - assertNotNull(batch.sentAt) - - val theEvent = batch.batch.first() - assertNull(theEvent.properties!!["prop"]) - - sut.close() - } - @Test fun `reset preserves the push dedupe id`() { val http = mockHttp() diff --git a/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt b/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt index 603a469b8..b76f57c4e 100644 --- a/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt +++ b/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt @@ -98,14 +98,6 @@ public class PostHogFake : PostHogInterface { return null } - @Deprecated("Use getFeatureFlagResult() instead, which returns the flag value and payload from a single evaluation") - override fun getFeatureFlagPayload( - key: String, - defaultValue: Any?, - ): Any? { - return null - } - override fun getFeatureFlagResult( key: String, sendFeatureFlagEvent: Boolean?, From 4d7c1fd4271e57ea5ebaa8b480166b05ed028850 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 26 Oct 2026 19:09:44 -0400 Subject: [PATCH 02/49] chore!: return null for malformed feature flag payloads (#889) Matches posthog-ios 4.0 and the sdk-specs payload decoding contract. --- .changeset/android-v4-major.md | 1 + .../posthog/internal/PostHogRemoteConfig.kt | 40 ++++--- .../internal/PostHogFeatureFlagsTest.kt | 6 +- .../internal/PostHogFeatureFlagsV1Test.kt | 4 +- .../internal/PostHogRemoteConfigTest.kt | 101 ++++++++++++++++++ 5 files changed, 130 insertions(+), 22 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 1b6846771..e50a3684b 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -8,3 +8,4 @@ - **Breaking:** remove the deprecated `evaluationEnvironments` config option; use `evaluationContexts` instead - **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key)?.payload` instead - **Breaking:** remove the deprecated `PostHogSessionReplayConfig.debouncerDelayMs`; use `throttleDelayMs` instead +- **Breaking:** return `null` instead of the raw string for a malformed, empty or whitespace-only feature flag payload from `getFeatureFlagResult(key)?.payload`; payloads must be valid JSON (a JSON `null` payload now also reads as `null` instead of the string `"null"`) diff --git a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt index 03ba9946a..af4d05fc0 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt @@ -1,5 +1,8 @@ package com.posthog.internal +import com.google.gson.stream.JsonReader +import com.google.gson.stream.JsonToken +import com.google.gson.stream.MalformedJsonException import com.posthog.FeatureFlagResult import com.posthog.PostHogConfig import com.posthog.PostHogInternal @@ -17,6 +20,7 @@ import com.posthog.internal.PostHogPreferences.Companion.PUSH import com.posthog.internal.PostHogPreferences.Companion.SESSION_REPLAY import com.posthog.internal.PostHogPreferences.Companion.SURVEYS import com.posthog.surveys.Survey +import java.io.StringReader import java.util.concurrent.ExecutorService import java.util.concurrent.atomic.AtomicBoolean @@ -1198,26 +1202,28 @@ public class PostHogRemoteConfig( } } - private fun normalizePayloads(featureFlagPayloads: Map?): Map { - val parsedPayloads = (featureFlagPayloads ?: mapOf()).toMutableMap() - - for (item in parsedPayloads) { - val value = item.value + private fun normalizePayloads(featureFlagPayloads: Map?): Map = + (featureFlagPayloads ?: mapOf()).mapValues { (key, value) -> + // payloads arrive as serialized JSON strings; other values are already decoded + if (value is String) decodePayload(key, value) else value + } - try { - // only try to parse if its a String, since the JSON values are stringified - if (value is String) { - // try to deserialize as Any? - config.serializer.deserializeString(value)?.let { - parsedPayloads[item.key] = it - } - } - } catch (ignored: Throwable) { - // if it fails, we keep the original value + // Strict JSON, so a malformed, empty or whitespace-only payload is no payload (null), never the raw string. + private fun decodePayload( + key: String, + serialized: String, + ): Any? = + try { + val reader = JsonReader(StringReader(serialized)) + val decoded = config.serializer.gson.getAdapter(Any::class.java).read(reader) + if (reader.peek() != JsonToken.END_DOCUMENT) { + throw MalformedJsonException("Unexpected data after the JSON value") } + decoded + } catch (e: Throwable) { + config.logger.log("Ignoring malformed payload for feature flag $key: $e") + null } - return parsedPayloads - } private fun normalizeFlagsResponse(flagsResponse: PostHogFlagsResponse): PostHogFlagsResponse { val flags = flagsResponse.flags diff --git a/posthog/src/test/java/com/posthog/internal/PostHogFeatureFlagsTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogFeatureFlagsTest.kt index eec9f7337..a03b735b5 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogFeatureFlagsTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogFeatureFlagsTest.kt @@ -407,7 +407,7 @@ internal class PostHogFeatureFlagsTest { assertTrue(sut.getFeatureFlagPayload("theBoolean", defaultValue = null) as Boolean) assertNull(sut.getFeatureFlagPayload("theNull", defaultValue = null)) - assertEquals("[1, 2", sut.getFeatureFlagPayload("theBroken", defaultValue = null) as String) + assertNull(sut.getFeatureFlagPayload("theBroken", defaultValue = null)) } @Test @@ -465,7 +465,7 @@ internal class PostHogFeatureFlagsTest { """ { "featureFlags": {"flag1": true}, - "featureFlagPayloads": {"flag1": "payload1"} + "featureFlagPayloads": {"flag1": "\"payload1\""} } """.trimIndent(), ), @@ -515,7 +515,7 @@ internal class PostHogFeatureFlagsTest { """ { "featureFlags": {"flag1": true}, - "featureFlagPayloads": {"flag1": "payload1"} + "featureFlagPayloads": {"flag1": "\"payload1\""} } """.trimIndent(), ), diff --git a/posthog/src/test/java/com/posthog/internal/PostHogFeatureFlagsV1Test.kt b/posthog/src/test/java/com/posthog/internal/PostHogFeatureFlagsV1Test.kt index 7cb40c827..fd2fa4220 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogFeatureFlagsV1Test.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogFeatureFlagsV1Test.kt @@ -270,7 +270,7 @@ internal class PostHogFeatureFlagsV1Test { assertTrue(sut.getFeatureFlagPayload("theBoolean", defaultValue = null) as Boolean) assertNull(sut.getFeatureFlagPayload("theNull", defaultValue = null)) - assertEquals("[1, 2", sut.getFeatureFlagPayload("theBroken", defaultValue = null) as String) + assertNull(sut.getFeatureFlagPayload("theBroken", defaultValue = null)) } @Test @@ -328,7 +328,7 @@ internal class PostHogFeatureFlagsV1Test { """ { "featureFlags": {"flag1": true}, - "featureFlagPayloads": {"flag1": "payload1"} + "featureFlagPayloads": {"flag1": "\"payload1\""} } """.trimIndent(), ), diff --git a/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt index 5701d46e4..0d9249fc1 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt @@ -3084,4 +3084,105 @@ internal class PostHogRemoteConfigTest { sut.clear() http.shutdown() } + + private fun loadFlagsWithPayloads( + payloads: Map, + logs: MutableList = mutableListOf(), + ): PostHogRemoteConfig { + val serializedPayloads = payloads.entries.joinToString(",") { (key, value) -> "\"$key\":${jsonString(value)}" } + val flags = payloads.keys.joinToString(",") { "\"$it\":\"blue\"" } + val http = + mockHttp( + response = + MockResponse().setBody( + """{"errorsWhileComputingFlags":false,"featureFlags":{$flags,"beta-ui":true},""" + + """"featureFlagPayloads":{$serializedPayloads,"beta-ui":"{\"color\":\"green\"}"}}""", + ), + ) + val sut = getSut(host = http.url("/").toString()) + config!!.logger = + object : PostHogLogger { + override fun log(message: String) { + logs.add(message) + } + + override fun isEnabled(): Boolean = true + } + + val latch = CountDownLatch(1) + sut.loadFeatureFlags( + "my_identify", + anonymousId = "anonId", + emptyMap(), + onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + ) + assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") + http.shutdown() + return sut + } + + private fun jsonString(value: String): String = PostHogSerializer(PostHogConfig(PROJECT_TOKEN)).gson.toJson(value) + + @Test + fun `malformed, empty or whitespace payloads are null and keep the flag and sibling payloads`() { + for (input in listOf("{broken", "", " ", "hello", "{\"a\":1} trailing")) { + preferences.clear() + val logs = mutableListOf() + val sut = loadFlagsWithPayloads(mapOf("checkout" to input), logs) + + assertNull(sut.getFeatureFlagPayload("checkout"), "payload for input '$input'") + val result = sut.getFeatureFlagResult("checkout") + assertNotNull(result) + assertTrue(result.enabled) + assertEquals("blue", result.variant) + assertNull(result.payload) + assertEquals(mapOf("checkout" to "blue", "beta-ui" to true), sut.getFeatureFlags()) + assertEquals(mapOf("color" to "green"), sut.getFeatureFlagPayload("beta-ui")) + assertTrue(logs.any { "checkout" in it && "malformed" in it }, "logs for input '$input': $logs") + + // the cache holds no raw string either, so a later launch reads no payload + assertNull(getSut(host = "http://127.0.0.1:1/").getFeatureFlagPayload("checkout")) + } + } + + @Test + fun `valid JSON payloads keep their decoded value`() { + val sut = + loadFlagsWithPayloads( + mapOf( + "string" to "\"hello\"", + "empty" to "\"\"", + "false" to "false", + "zero" to "0", + "null" to "null", + "object" to "{\"color\":\"green\"}", + "array" to "[1,false]", + ), + ) + + assertEquals("hello", sut.getFeatureFlagPayload("string")) + assertEquals("", sut.getFeatureFlagPayload("empty")) + assertEquals(false, sut.getFeatureFlagPayload("false")) + assertEquals(0, sut.getFeatureFlagPayload("zero")) + assertNull(sut.getFeatureFlagPayload("null")) + assertEquals(mapOf("color" to "green"), sut.getFeatureFlagPayload("object")) + assertEquals(listOf(1, false), sut.getFeatureFlagPayload("array")) + } + + @Test + fun `bootstrapped string payloads are not JSON-decoded again`() { + for (payload in listOf("hello", "123", "true")) { + val sut = + getSut( + host = "http://127.0.0.1:1/", + bootstrap = + PostHogBootstrapConfig( + featureFlags = mapOf("beta-ui" to "variant-a"), + featureFlagPayloads = mapOf("beta-ui" to payload), + ), + ) + + assertEquals(payload, sut.getFeatureFlagResult("beta-ui")?.payload) + } + } } From ec06e867c6dae6181dce9bb9ab648ac01bc017fc Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 27 Oct 2026 12:06:10 -0400 Subject: [PATCH 03/49] chore!: make SDK-internal helpers non-public (#872) * chore!: make SDK-internal helpers non-public for posthog-android 4.0 Make internal the public declarations that no other module in this repo and no wrapper (Flutter, React Native, KMP) uses. LogLine and LogcatParser are Java, so they become package-private. Co-Authored-By: Claude Opus 5.5 (1M context) * fix: keep GzipRequestInterceptor public for the compliance adapter sdk_compliance_adapter is a separate Gradle module, only included by its Dockerfile, and constructs GzipRequestInterceptor directly. Co-Authored-By: Claude Opus 5.5 (1M context) --------- Co-authored-by: Claude Opus 5.5 (1M context) --- .changeset/android-v4-major.md | 1 + posthog-android/api/posthog-android.api | 19 -------- .../android/internal/PostHogAndroidUtils.kt | 6 +-- .../android/replay/internal/LogLine.java | 4 +- .../android/replay/internal/LogcatParser.java | 4 +- posthog/api/posthog.api | 45 ------------------- .../internal/CustomHeadersInterceptor.kt | 4 +- .../com/posthog/internal/PostHogContext.kt | 3 +- .../PostHogLocalEvaluationDeserializers.kt | 7 +-- .../posthog/internal/PostHogPreferences.kt | 3 +- .../posthog/internal/PostHogPrintLogger.kt | 4 +- .../errortracking/ThrowableCoercer.kt | 4 +- .../posthog/internal/replay/RRDocumentNode.kt | 5 +-- .../replay/RRDomContentLoadedEvent.kt | 5 +-- .../posthog/internal/replay/RRLoadedEvent.kt | 5 +-- .../surveys/SurveyLanguageDetection.kt | 3 +- 16 files changed, 16 insertions(+), 106 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index e50a3684b..5a2892275 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -9,3 +9,4 @@ - **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key)?.payload` instead - **Breaking:** remove the deprecated `PostHogSessionReplayConfig.debouncerDelayMs`; use `throttleDelayMs` instead - **Breaking:** return `null` instead of the raw string for a malformed, empty or whitespace-only feature flag payload from `getFeatureFlagResult(key)?.payload`; payloads must be valid JSON (a JSON `null` payload now also reads as `null` instead of the string `"null"`) +- **Breaking:** make SDK-internal helpers in the `com.posthog.internal` and `com.posthog.android.replay.internal` packages non-public diff --git a/posthog-android/api/posthog-android.api b/posthog-android/api/posthog-android.api index ee90e68c6..1749b4128 100644 --- a/posthog-android/api/posthog-android.api +++ b/posthog-android/api/posthog-android.api @@ -70,9 +70,6 @@ public final class com/posthog/android/internal/PostHogAndroidUtilsKt { public static final fun base64 (Landroid/graphics/Bitmap;Landroid/graphics/Bitmap$CompressFormat;I)Ljava/lang/String; public static synthetic fun base64$default (Landroid/graphics/Bitmap;Landroid/graphics/Bitmap$CompressFormat;IILjava/lang/Object;)Ljava/lang/String; public static final fun getApplicationInfo (Landroid/content/Context;)Landroid/content/pm/ApplicationInfo; - public static final fun isValid (Landroid/graphics/Bitmap;)Z - public static final fun webpBase64 (Landroid/graphics/Bitmap;I)Ljava/lang/String; - public static synthetic fun webpBase64$default (Landroid/graphics/Bitmap;IILjava/lang/Object;)Ljava/lang/String; } public abstract interface class com/posthog/android/replay/PostHogDrawableConverter { @@ -152,22 +149,6 @@ public final class com/posthog/android/replay/PostHogSessionReplayConfig { public final fun setVerifyScreenshotMaskAlignment (Z)V } -public class com/posthog/android/replay/internal/LogLine { - public field level Ljava/lang/String; - public field tag Ljava/lang/String; - public field text Ljava/lang/String; - public field time Ljava/util/GregorianCalendar; - public fun ()V -} - -public class com/posthog/android/replay/internal/LogcatParser { - public static final field BUFFER_BEGIN_RE Ljava/util/regex/Pattern; - public static final field DATE_TIME_MS_PATTERN Ljava/lang/String; - public static final field UTC Ljava/util/TimeZone; - public fun ()V - public fun parse (Ljava/lang/String;)Lcom/posthog/android/replay/internal/LogLine; -} - public final class com/posthog/android/surveys/PostHogSurveysIntegration : com/posthog/PostHogIntegration, com/posthog/internal/surveys/PostHogSurveysHandler { public fun (Landroid/content/Context;Lcom/posthog/PostHogConfig;)V public fun install (Lcom/posthog/PostHogInterface;)V diff --git a/posthog-android/src/main/java/com/posthog/android/internal/PostHogAndroidUtils.kt b/posthog-android/src/main/java/com/posthog/android/internal/PostHogAndroidUtils.kt index fd065353f..2468c870f 100644 --- a/posthog-android/src/main/java/com/posthog/android/internal/PostHogAndroidUtils.kt +++ b/posthog-android/src/main/java/com/posthog/android/internal/PostHogAndroidUtils.kt @@ -196,8 +196,7 @@ public fun getApplicationInfo(context: Context): ApplicationInfo = .getApplicationInfo(context.packageName, GET_META_DATA) } -@PostHogInternal -public fun Bitmap.isValid(): Boolean { +internal fun Bitmap.isValid(): Boolean { return !isRecycled && width > 0 && height > 0 @@ -225,9 +224,8 @@ private fun Bitmap.base64BufferSize(): Int = .coerceAtLeast(4L * 1024) .toInt() -@PostHogInternal @Suppress("DEPRECATION") -public fun Bitmap.webpBase64(quality: Int = 30): String? { +internal fun Bitmap.webpBase64(quality: Int = 30): String? { if (!isValid()) { return null } diff --git a/posthog-android/src/main/java/com/posthog/android/replay/internal/LogLine.java b/posthog-android/src/main/java/com/posthog/android/replay/internal/LogLine.java index b85e3c251..249b00b79 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/internal/LogLine.java +++ b/posthog-android/src/main/java/com/posthog/android/replay/internal/LogLine.java @@ -2,15 +2,13 @@ package com.posthog.android.replay.internal; -import com.posthog.PostHogInternal; import java.util.GregorianCalendar; /** * A log line. */ -@PostHogInternal -public class LogLine { +class LogLine { /** * The timestamp of the event, parsed directly from Unix epoch time and represented in UTC. */ diff --git a/posthog-android/src/main/java/com/posthog/android/replay/internal/LogcatParser.java b/posthog-android/src/main/java/com/posthog/android/replay/internal/LogcatParser.java index 69c1d2e7a..b2cc5a9aa 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/internal/LogcatParser.java +++ b/posthog-android/src/main/java/com/posthog/android/replay/internal/LogcatParser.java @@ -2,7 +2,6 @@ package com.posthog.android.replay.internal; -import com.posthog.PostHogInternal; import java.util.GregorianCalendar; import java.util.TimeZone; @@ -10,8 +9,7 @@ import java.util.regex.Pattern; /** Parses logcat output formatted with {@code -v epoch}. */ -@PostHogInternal -public class LogcatParser { +class LogcatParser { /** UTC Time Zone. */ public static final TimeZone UTC = TimeZone.getTimeZone("UTC"); diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index c744204de..1d18f638e 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -606,11 +606,6 @@ public final class com/posthog/errortracking/PostHogExceptionStepsConfig { public final fun setMaxBytes (I)V } -public final class com/posthog/internal/CustomHeadersInterceptor : okhttp3/Interceptor { - public fun (Lcom/posthog/PostHogConfig;)V - public fun intercept (Lokhttp3/Interceptor$Chain;)Lokhttp3/Response; -} - public final class com/posthog/internal/EndpointSpec { public static final field Companion Lcom/posthog/internal/EndpointSpec$Companion; public static final fun batch (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; @@ -827,10 +822,6 @@ public abstract interface class com/posthog/internal/PostHogContext { public abstract fun getStaticContext ()Ljava/util/Map; } -public final class com/posthog/internal/PostHogContextKt { - public static final fun personPropertiesContext (Lcom/posthog/internal/PostHogContext;)Ljava/util/Map; -} - public abstract interface class com/posthog/internal/PostHogDateProvider { public abstract fun addSecondsToCurrentDate (I)Ljava/util/Date; public abstract fun currentDate ()Ljava/util/Date; @@ -963,7 +954,6 @@ public abstract interface class com/posthog/internal/PostHogPreferences { public static final field GROUPS Ljava/lang/String; public static final field LAST_SEEN_SURVEY_DATE Ljava/lang/String; public static final field PUSH_OPENED_MESSAGE_IDS Ljava/lang/String; - public static final field PUSH_SUBSCRIPTION_REJECTED Ljava/lang/String; public static final field STRINGIFIED_KEYS Ljava/lang/String; public static final field SURVEY_PROGRESS Ljava/lang/String; public static final field SURVEY_SEEN Ljava/lang/String; @@ -986,7 +976,6 @@ public final class com/posthog/internal/PostHogPreferences$Companion { public static final field GROUPS Ljava/lang/String; public static final field LAST_SEEN_SURVEY_DATE Ljava/lang/String; public static final field PUSH_OPENED_MESSAGE_IDS Ljava/lang/String; - public static final field PUSH_SUBSCRIPTION_REJECTED Ljava/lang/String; public static final field STRINGIFIED_KEYS Ljava/lang/String; public static final field SURVEY_PROGRESS Ljava/lang/String; public static final field SURVEY_SEEN Ljava/lang/String; @@ -1000,13 +989,6 @@ public final class com/posthog/internal/PostHogPreferences$DefaultImpls { public static fun isAvailable (Lcom/posthog/internal/PostHogPreferences;)Z } -public final class com/posthog/internal/PostHogPrintLogger : com/posthog/internal/PostHogLogger { - public fun (Lcom/posthog/PostHogConfig;)V - public fun isEnabled ()Z - public fun log (Ljava/lang/String;)V - public fun logWarning (Ljava/lang/String;)V -} - public final class com/posthog/internal/PostHogQueue : com/posthog/internal/PostHogQueueInterface { public fun (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/EndpointSpec;Ljava/util/concurrent/ExecutorService;)V public fun add (Ljava/lang/Object;)V @@ -1151,12 +1133,6 @@ public final class com/posthog/internal/PropertyGroup { public fun toString ()Ljava/lang/String; } -public final class com/posthog/internal/PropertyGroupDeserializer : com/google/gson/JsonDeserializer { - public fun ()V - public fun deserialize (Lcom/google/gson/JsonElement;Ljava/lang/reflect/Type;Lcom/google/gson/JsonDeserializationContext;)Lcom/posthog/internal/PropertyGroup; - public synthetic fun deserialize (Lcom/google/gson/JsonElement;Ljava/lang/reflect/Type;Lcom/google/gson/JsonDeserializationContext;)Ljava/lang/Object; -} - public final class com/posthog/internal/PropertyOperator : java/lang/Enum { public static final field Companion Lcom/posthog/internal/PropertyOperator$Companion; public static final field ENDS_WITH Lcom/posthog/internal/PropertyOperator; @@ -1242,12 +1218,6 @@ public final class com/posthog/internal/PropertyValue$PropertyGroups : com/posth public fun toString ()Ljava/lang/String; } -public final class com/posthog/internal/PropertyValueDeserializer : com/google/gson/JsonDeserializer { - public fun ()V - public fun deserialize (Lcom/google/gson/JsonElement;Ljava/lang/reflect/Type;Lcom/google/gson/JsonDeserializationContext;)Lcom/posthog/internal/PropertyValue; - public synthetic fun deserialize (Lcom/google/gson/JsonElement;Ljava/lang/reflect/Type;Lcom/google/gson/JsonDeserializationContext;)Ljava/lang/Object; -} - public final class com/posthog/internal/VariantDefinition { public fun (Ljava/lang/String;D)V public final fun getKey ()Ljava/lang/String; @@ -1260,8 +1230,6 @@ public final class com/posthog/internal/errortracking/ThrowableCoercer { public static final field MAX_EXCEPTION_LIST_SIZE I public static final field MAX_FRAMES_PER_STACKTRACE I public fun ()V - public final fun fromThrowableToPostHogProperties (Ljava/lang/Throwable;Ljava/util/List;Ljava/lang/String;Ljava/util/List;)Ljava/util/Map; - public static synthetic fun fromThrowableToPostHogProperties$default (Lcom/posthog/internal/errortracking/ThrowableCoercer;Ljava/lang/Throwable;Ljava/util/List;Ljava/lang/String;Ljava/util/List;ILjava/lang/Object;)Ljava/util/Map; } public abstract interface class com/posthog/internal/replay/PostHogSessionReplayHandler { @@ -1282,14 +1250,6 @@ public final class com/posthog/internal/replay/RRCustomEvent : com/posthog/inter public fun (Ljava/lang/String;Ljava/lang/Object;J)V } -public final class com/posthog/internal/replay/RRDocumentNode : com/posthog/internal/replay/RREvent { - public fun (Ljava/lang/String;Ljava/lang/Object;J)V -} - -public final class com/posthog/internal/replay/RRDomContentLoadedEvent : com/posthog/internal/replay/RREvent { - public fun (J)V -} - public class com/posthog/internal/replay/RREvent { public fun (Lcom/posthog/internal/replay/RREventType;JLjava/lang/Object;)V public synthetic fun (Lcom/posthog/internal/replay/RREventType;JLjava/lang/Object;ILkotlin/jvm/internal/DefaultConstructorMarker;)V @@ -1382,10 +1342,6 @@ public final class com/posthog/internal/replay/RRIncrementalSource$Companion { public final fun fromValue (I)Lcom/posthog/internal/replay/RRIncrementalSource; } -public final class com/posthog/internal/replay/RRLoadedEvent : com/posthog/internal/replay/RREvent { - public fun (J)V -} - public final class com/posthog/internal/replay/RRMetaEvent : com/posthog/internal/replay/RREvent { public fun (IIJLjava/lang/String;)V } @@ -1582,7 +1538,6 @@ public final class com/posthog/internal/surveys/ResolvedSurveyTranslations { public final class com/posthog/internal/surveys/SurveyLanguageDetectionKt { public static final fun detectSurveyLanguage (Ljava/lang/String;Ljava/util/Map;Ljava/lang/String;)Ljava/lang/String; - public static final fun findBestTranslationMatch (Ljava/util/Map;Ljava/lang/String;)Ljava/lang/String; } public final class com/posthog/internal/surveys/SurveyTranslationApplierKt { diff --git a/posthog/src/main/java/com/posthog/internal/CustomHeadersInterceptor.kt b/posthog/src/main/java/com/posthog/internal/CustomHeadersInterceptor.kt index 498937756..74cd4b3ef 100644 --- a/posthog/src/main/java/com/posthog/internal/CustomHeadersInterceptor.kt +++ b/posthog/src/main/java/com/posthog/internal/CustomHeadersInterceptor.kt @@ -1,7 +1,6 @@ package com.posthog.internal import com.posthog.PostHogConfig -import com.posthog.PostHogInternal import okhttp3.HttpUrl.Companion.toHttpUrlOrNull import okhttp3.Interceptor import okhttp3.Request @@ -13,8 +12,7 @@ import java.io.IOException * reverse proxy) to every request the SDK sends. * @property config The Config */ -@PostHogInternal -public class CustomHeadersInterceptor(private val config: PostHogConfig) : Interceptor { +internal class CustomHeadersInterceptor(private val config: PostHogConfig) : Interceptor { private companion object { // SDK-managed headers that custom values can't override (compared lowercase). private val RESERVED_HEADERS = setOf("content-type", "user-agent", "accept-encoding", "content-encoding") diff --git a/posthog/src/main/java/com/posthog/internal/PostHogContext.kt b/posthog/src/main/java/com/posthog/internal/PostHogContext.kt index f0377d21d..ab7a528e8 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogContext.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogContext.kt @@ -19,8 +19,7 @@ public interface PostHogContext { * Returns person properties context by extracting relevant properties from static context. * This centralizes the logic for determining which properties should be used as person properties. */ -@PostHogInternal -public fun PostHogContext.personPropertiesContext(): Map { +internal fun PostHogContext.personPropertiesContext(): Map { val sdkInfo = getSdkInfo() val staticCtx = getStaticContext() val personProperties = mutableMapOf() diff --git a/posthog/src/main/java/com/posthog/internal/PostHogLocalEvaluationDeserializers.kt b/posthog/src/main/java/com/posthog/internal/PostHogLocalEvaluationDeserializers.kt index 2b5ec9df4..00117cbbc 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogLocalEvaluationDeserializers.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogLocalEvaluationDeserializers.kt @@ -6,14 +6,12 @@ import com.google.gson.JsonElement import com.google.gson.JsonSerializationContext import com.google.gson.JsonSerializer import com.google.gson.stream.MalformedJsonException -import com.posthog.PostHogInternal import java.lang.reflect.Type /** * Gson deserializer for PropertyGroup */ -@PostHogInternal -public class PropertyGroupDeserializer : JsonDeserializer { +internal class PropertyGroupDeserializer : JsonDeserializer { override fun deserialize( json: JsonElement, typeOfT: Type, @@ -43,8 +41,7 @@ public class PropertyGroupDeserializer : JsonDeserializer { * Gson deserializer for PropertyValue sealed interface * Determines whether to deserialize as PropertyGroups or FlagProperties based on structure */ -@PostHogInternal -public class PropertyValueDeserializer : JsonDeserializer { +internal class PropertyValueDeserializer : JsonDeserializer { override fun deserialize( json: JsonElement, typeOfT: Type, diff --git a/posthog/src/main/java/com/posthog/internal/PostHogPreferences.kt b/posthog/src/main/java/com/posthog/internal/PostHogPreferences.kt index 84cf4d343..9d29d9f99 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogPreferences.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogPreferences.kt @@ -56,8 +56,7 @@ public interface PostHogPreferences { @PostHogInternal public const val PUSH_OPENED_MESSAGE_IDS: String = "pushOpenedMessageIds" - @PostHogInternal - public const val PUSH_SUBSCRIPTION_REJECTED: String = "pushSubscriptionRejected" + internal const val PUSH_SUBSCRIPTION_REJECTED: String = "pushSubscriptionRejected" internal const val PERSON_PROPERTIES_FOR_FLAGS = "personPropertiesForFlags" internal const val GROUP_PROPERTIES_FOR_FLAGS = "groupPropertiesForFlags" public const val SURVEY_PROGRESS: String = "surveyProgress" diff --git a/posthog/src/main/java/com/posthog/internal/PostHogPrintLogger.kt b/posthog/src/main/java/com/posthog/internal/PostHogPrintLogger.kt index babf8f72d..4c2d1f643 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogPrintLogger.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogPrintLogger.kt @@ -1,14 +1,12 @@ package com.posthog.internal import com.posthog.PostHogConfig -import com.posthog.PostHogInternal /** * Logs the messages using System.out only if config.debug is enabled * @property config the Config */ -@PostHogInternal -public class PostHogPrintLogger(private val config: PostHogConfig) : PostHogLogger { +internal class PostHogPrintLogger(private val config: PostHogConfig) : PostHogLogger { override fun log(message: String) { // isEnabled can be abstracted in another class (refactor needed). if (isEnabled()) { diff --git a/posthog/src/main/java/com/posthog/internal/errortracking/ThrowableCoercer.kt b/posthog/src/main/java/com/posthog/internal/errortracking/ThrowableCoercer.kt index 89b18a828..fb67d2880 100644 --- a/posthog/src/main/java/com/posthog/internal/errortracking/ThrowableCoercer.kt +++ b/posthog/src/main/java/com/posthog/internal/errortracking/ThrowableCoercer.kt @@ -244,9 +244,7 @@ public class ThrowableCoercer { return exception } - // `inAppExcludes` is appended after `releaseIdentifier` so existing positional Kotlin calls stay - // valid. This is a `@PostHogInternal` entry point, so the JVM descriptor change is fine. - public fun fromThrowableToPostHogProperties( + internal fun fromThrowableToPostHogProperties( throwable: Throwable, inAppIncludes: List = listOf(), releaseIdentifier: String? = null, diff --git a/posthog/src/main/java/com/posthog/internal/replay/RRDocumentNode.kt b/posthog/src/main/java/com/posthog/internal/replay/RRDocumentNode.kt index d45502d16..c635252d3 100644 --- a/posthog/src/main/java/com/posthog/internal/replay/RRDocumentNode.kt +++ b/posthog/src/main/java/com/posthog/internal/replay/RRDocumentNode.kt @@ -1,9 +1,6 @@ package com.posthog.internal.replay -import com.posthog.PostHogInternal - -@PostHogInternal -public class RRDocumentNode(tag: String, payload: Any, timestamp: Long) : RREvent( +internal class RRDocumentNode(tag: String, payload: Any, timestamp: Long) : RREvent( type = RREventType.Custom, data = mapOf( diff --git a/posthog/src/main/java/com/posthog/internal/replay/RRDomContentLoadedEvent.kt b/posthog/src/main/java/com/posthog/internal/replay/RRDomContentLoadedEvent.kt index 6b550d57d..275be367f 100644 --- a/posthog/src/main/java/com/posthog/internal/replay/RRDomContentLoadedEvent.kt +++ b/posthog/src/main/java/com/posthog/internal/replay/RRDomContentLoadedEvent.kt @@ -1,9 +1,6 @@ package com.posthog.internal.replay -import com.posthog.PostHogInternal - -@PostHogInternal -public class RRDomContentLoadedEvent(timestamp: Long) : RREvent( +internal class RRDomContentLoadedEvent(timestamp: Long) : RREvent( type = RREventType.DomContentLoaded, timestamp = timestamp, ) diff --git a/posthog/src/main/java/com/posthog/internal/replay/RRLoadedEvent.kt b/posthog/src/main/java/com/posthog/internal/replay/RRLoadedEvent.kt index 31508abd4..3b02f7844 100644 --- a/posthog/src/main/java/com/posthog/internal/replay/RRLoadedEvent.kt +++ b/posthog/src/main/java/com/posthog/internal/replay/RRLoadedEvent.kt @@ -1,9 +1,6 @@ package com.posthog.internal.replay -import com.posthog.PostHogInternal - -@PostHogInternal -public class RRLoadedEvent(timestamp: Long) : RREvent( +internal class RRLoadedEvent(timestamp: Long) : RREvent( type = RREventType.Load, timestamp = timestamp, ) diff --git a/posthog/src/main/java/com/posthog/internal/surveys/SurveyLanguageDetection.kt b/posthog/src/main/java/com/posthog/internal/surveys/SurveyLanguageDetection.kt index 9f2186e7b..a8f3814f9 100644 --- a/posthog/src/main/java/com/posthog/internal/surveys/SurveyLanguageDetection.kt +++ b/posthog/src/main/java/com/posthog/internal/surveys/SurveyLanguageDetection.kt @@ -36,8 +36,7 @@ public fun detectSurveyLanguage( * Returns the original-cased key from [translations] (so it can be reported verbatim * as `$survey_language`), or `null` if no match. */ -@PostHogInternal -public fun findBestTranslationMatch( +internal fun findBestTranslationMatch( translations: Map?, targetLanguage: String?, ): String? { From ead5a23ce12b90c2d886535dba48458149a2718e Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 27 Oct 2026 12:24:57 -0400 Subject: [PATCH 04/49] chore!: remove the deprecated remoteConfig option (#874) Setup now always loads /config. With remoteConfig = false, setup used to skip /config, which left remote settings unloaded since /flags stopped returning config. Co-authored-by: Claude Opus 5.5 (1M context) --- .changeset/android-v4-major.md | 1 + .../compose/internal/PostHogSurveyHostTest.kt | 1 - .../replay/PostHogReplayIntegration.kt | 10 +--- .../android/PostHogAndroidAppVersionTest.kt | 3 +- .../PostHogAndroidEventSnapshotsTest.kt | 12 +++-- .../internal/InteractionActivityTest.kt | 4 +- .../InteractionDetectorActivityTest.kt | 3 +- .../InteractionDetectorIntegrationTest.kt | 6 +-- .../replay/PostHogReplayIntegrationTest.kt | 51 +------------------ .../surveys/PostHogSurveysRestartTest.kt | 1 - .../java/com/posthog/server/PostHogConfig.kt | 1 - .../com/posthog/server/PostHogConfigTest.kt | 1 - posthog/api/posthog.api | 6 +-- posthog/src/main/java/com/posthog/PostHog.kt | 14 ++--- .../main/java/com/posthog/PostHogConfig.kt | 9 ---- .../java/com/posthog/PostHogBeforeSendTest.kt | 1 - .../java/com/posthog/PostHogBootstrapTest.kt | 9 ++-- .../com/posthog/PostHogFeatureFlagsTest.kt | 5 +- .../posthog/PostHogIntegrationChangeTest.kt | 3 +- .../PostHogIntegrationInstallFailureTest.kt | 3 +- .../posthog/PostHogOkHttpInterceptorTest.kt | 1 - .../src/test/java/com/posthog/PostHogTest.kt | 48 ++++++++--------- 22 files changed, 51 insertions(+), 142 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 5a2892275..e89b373a7 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -10,3 +10,4 @@ - **Breaking:** remove the deprecated `PostHogSessionReplayConfig.debouncerDelayMs`; use `throttleDelayMs` instead - **Breaking:** return `null` instead of the raw string for a malformed, empty or whitespace-only feature flag payload from `getFeatureFlagResult(key)?.payload`; payloads must be valid JSON (a JSON `null` payload now also reads as `null` instead of the string `"null"`) - **Breaking:** make SDK-internal helpers in the `com.posthog.internal` and `com.posthog.android.replay.internal` packages non-public +- **Breaking:** remove the deprecated `remoteConfig` config option; the SDK now always loads remote config at setup diff --git a/posthog-android-surveys-compose/src/testDebug/java/com/posthog/android/surveys/compose/internal/PostHogSurveyHostTest.kt b/posthog-android-surveys-compose/src/testDebug/java/com/posthog/android/surveys/compose/internal/PostHogSurveyHostTest.kt index 16b3ee565..fe5b5a8a1 100644 --- a/posthog-android-surveys-compose/src/testDebug/java/com/posthog/android/surveys/compose/internal/PostHogSurveyHostTest.kt +++ b/posthog-android-surveys-compose/src/testDebug/java/com/posthog/android/surveys/compose/internal/PostHogSurveyHostTest.kt @@ -279,7 +279,6 @@ internal class PostHogSurveyHostTest { PostHogConfig("host-reset", "http://127.0.0.1:1").apply { cachePreferences = PostHogMemoryPreferences() preloadFeatureFlags = false - remoteConfig = false reuseAnonymousId = true } } diff --git a/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt b/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt index daec3775b..46af13767 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt +++ b/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt @@ -3054,15 +3054,9 @@ public class PostHogReplayIntegration( } // Whether to buffer until the live remote config resolves: only when a remote config holder - // exists and hasn't resolved yet, AND a fetch will actually be attempted at setup. If neither - // remoteConfig nor preloadFeatureFlags is enabled, PostHog.setup dispatches no /config or /flags - // request, so no onRemoteConfig callback ever arrives to disarm the gate — - // buffering would then grow unbounded for the whole session. Don't arm in that case. + // exists and hasn't resolved yet. PostHog.setup always requests /config, so the + // onRemoteConfig callback disarms the gate. private fun shouldAwaitFirstRemoteConfig(): Boolean { - @Suppress("DEPRECATION") - if (!config.remoteConfig && !config.preloadFeatureFlags) { - return false - } return config.remoteConfigHolder?.let { !it.hasRemoteConfigFetched() } ?: false } diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidAppVersionTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidAppVersionTest.kt index 9b16bcb53..68518c7df 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidAppVersionTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidAppVersionTest.kt @@ -43,10 +43,9 @@ internal class PostHogAndroidAppVersionTest { events: MutableList, configure: PostHogAndroidConfig.() -> Unit = {}, ): PostHogAndroidConfig = - PostHogAndroidConfig(projectToken).apply { + PostHogAndroidConfig(projectToken, "http://127.0.0.1:1").apply { cachePreferences = preferences captureApplicationLifecycleEvents = captureLifecycle - remoteConfig = false preloadFeatureFlags = false configure() addBeforeSend { diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt index e59c0977c..ae466718a 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt @@ -94,7 +94,7 @@ internal class PostHogAndroidEventSnapshotsTest { sut.captureException(fixedThrowable(), mapOf("handled" to true, "component" to "checkout")) sut.flush() - val request = fixture.server.takeRequests("/flags/?v=2", "/batch").single { it.path == "/batch" } + val request = fixture.server.takeRequests(CONFIG_PATH, "/flags/?v=2", "/batch").single { it.path == "/batch" } val snapshot = requestSnapshot(request, fixture.config) normalizeBatchVolatileFields(snapshot) @@ -118,7 +118,7 @@ internal class PostHogAndroidEventSnapshotsTest { fixture.client.reloadFeatureFlags(PostHogOnFeatureFlags { loaded.countDown() }) assertTrue(loaded.await(10, TimeUnit.SECONDS), "Feature flags request did not finish") - val request = fixture.server.takeRequests("/flags/?v=2").single() + val request = fixture.server.takeRequests(CONFIG_PATH, "/flags/?v=2").single { it.path == "/flags/?v=2" } assertSnapshot("flags-request.json", requestSnapshot(request, fixture.config), fixture.config) } @@ -152,7 +152,7 @@ internal class PostHogAndroidEventSnapshotsTest { ) fixture.client.flush() - val request = fixture.server.takeRequests("/s/").single() + val request = fixture.server.takeRequests(CONFIG_PATH, "/s/").single { it.path == "/s/" } val snapshot = requestSnapshot(request, fixture.config) normalizeReplayVolatileFields(snapshot) @@ -163,6 +163,8 @@ internal class PostHogAndroidEventSnapshotsTest { mockContextAppStart(context, tmpDir) val server = MockWebServer().apply { + // setup always requests /config first + enqueue(MockResponse().setBody(CONFIG_RESPONSE).setHeader("Content-Type", "application/json")) repeat(10) { enqueue(MockResponse().setBody(FLAGS_RESPONSE).setHeader("Content-Type", "application/json")) } @@ -185,8 +187,6 @@ internal class PostHogAndroidEventSnapshotsTest { flushIntervalSeconds = 60 maxBatchSize = 20 preloadFeatureFlags = false - @Suppress("DEPRECATION") - remoteConfig = false captureApplicationLifecycleEvents = false captureDeepLinks = false captureScreenViews = false @@ -412,6 +412,8 @@ internal class PostHogAndroidEventSnapshotsTest { private val FIXED_DATE = Date(FIXED_MILLIS) private val SESSION_ID = UUID.fromString("018bcfe5-687b-7abc-8def-0123456789ab") private const val FIXED_TIMESTAMP = "2023-11-14T22:13:20.123Z" + private const val CONFIG_PATH = "/array/$PROJECT_TOKEN/config" + private const val CONFIG_RESPONSE = """{"hasFeatureFlags":true}""" private const val FLAGS_RESPONSE = """{ "flags": { diff --git a/posthog-android/src/test/java/com/posthog/android/internal/InteractionActivityTest.kt b/posthog-android/src/test/java/com/posthog/android/internal/InteractionActivityTest.kt index 9e7a8dc2b..f888f61e3 100644 --- a/posthog-android/src/test/java/com/posthog/android/internal/InteractionActivityTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/internal/InteractionActivityTest.kt @@ -46,7 +46,7 @@ internal class InteractionActivityTest { fun `real Compose and embedded Views capture through window with replay off`() { val events = CopyOnWriteArrayList() val config = - PostHogAndroidConfig("test").apply { + PostHogAndroidConfig("test", "http://127.0.0.1:1").apply { captureElementInteractions = true sessionReplay = false captureApplicationLifecycleEvents = false @@ -54,8 +54,6 @@ internal class InteractionActivityTest { captureDeepLinks = false capturePushNotificationOpened = false capturePushNotificationSubscriptions = false - @Suppress("DEPRECATION") // Test isolation: do not fetch remote configuration. - remoteConfig = false preloadFeatureFlags = false addBeforeSend { event -> events += event diff --git a/posthog-android/src/test/java/com/posthog/android/internal/InteractionDetectorActivityTest.kt b/posthog-android/src/test/java/com/posthog/android/internal/InteractionDetectorActivityTest.kt index a380c5325..7091f75f4 100644 --- a/posthog-android/src/test/java/com/posthog/android/internal/InteractionDetectorActivityTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/internal/InteractionDetectorActivityTest.kt @@ -53,7 +53,7 @@ internal class InteractionDetectorActivityTest { @Suppress("DEPRECATION") private fun setup() { val config = - PostHogAndroidConfig("test").apply { + PostHogAndroidConfig("test", "http://127.0.0.1:1").apply { captureRageClicks = true captureDeadClicks = true sessionReplay = false @@ -62,7 +62,6 @@ internal class InteractionDetectorActivityTest { captureDeepLinks = false capturePushNotificationOpened = false capturePushNotificationSubscriptions = false - remoteConfig = false preloadFeatureFlags = false addBeforeSend { event -> events += event diff --git a/posthog-android/src/test/java/com/posthog/android/internal/InteractionDetectorIntegrationTest.kt b/posthog-android/src/test/java/com/posthog/android/internal/InteractionDetectorIntegrationTest.kt index 90d2b7c89..730e1d45f 100644 --- a/posthog-android/src/test/java/com/posthog/android/internal/InteractionDetectorIntegrationTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/internal/InteractionDetectorIntegrationTest.kt @@ -48,12 +48,11 @@ internal class InteractionDetectorIntegrationTest { @Suppress("DEPRECATION") private val config = - PostHogAndroidConfig(PROJECT_TOKEN).apply { + PostHogAndroidConfig(PROJECT_TOKEN, "http://127.0.0.1:1").apply { captureRageClicks = true captureDeadClicks = true sessionReplay = false cachePreferences = PostHogMemoryPreferences() - remoteConfig = false preloadFeatureFlags = false addBeforeSend { event -> if (event.event in listOf("\$rageclick", "\$dead_click", "\$autocapture")) events += event @@ -253,9 +252,8 @@ internal class InteractionDetectorIntegrationTest { fun `secondary session changes use normal capture context when owner is not notified`() { val secondary = PostHog.with( - PostHogAndroidConfig("secondary-test-key").apply { + PostHogAndroidConfig("secondary-test-key", "http://127.0.0.1:1").apply { cachePreferences = PostHogMemoryPreferences() - remoteConfig = false preloadFeatureFlags = false addBeforeSend { null } }, diff --git a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt index fcf0b0a72..a4571077a 100644 --- a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt @@ -2127,53 +2127,6 @@ internal class PostHogReplayIntegrationTest { } } - @Test - fun `gate does not arm when neither remoteConfig nor preloadFeatureFlags will fetch`() { - // With both remoteConfig and preloadFeatureFlags disabled, setup dispatches no /config or - // /flags request, so no onRemoteConfig callback arrives to disarm the gate. Arming it would - // buffer every snapshot for the whole session; instead it must stay disarmed and persist. - val remoteConfigMock = - mock { - on { isSessionReplayFlagActive() } doReturn true - on { hasRemoteConfigFetched() } doReturn false - on { makeSamplingDecision(any()) } doReturn true - on { getEventTriggers() } doReturn emptySet() - on { getRecordingMinimumDurationMs() } doReturn null - } - val config = - PostHogAndroidConfig(PROJECT_TOKEN).apply { - remoteConfigHolder = remoteConfigMock - sessionReplay = true - @Suppress("DEPRECATION") - remoteConfig = false - preloadFeatureFlags = false - } - val storagePrefix = tmpDir.newFolder().absolutePath - val executor = createReplayExecutor() - val innerQueue = - PostHogQueue( - config, - EndpointSpec.snapshot(config, PostHogApi(config), storagePrefix), - executor, - ) - val replayQueue = PostHogReplayQueue(config, innerQueue, storagePrefix, executor) - config.replayQueueHolder = replayQueue - val sut = PostHogReplayIntegration(mock(), config, MainHandler()) - val postHog = mock() - whenever(postHog.getSessionId()).thenReturn(UUID.randomUUID()) - sut.install(postHog) - sut.start(resumeCurrent = true) - try { - // No remote-config callback will ever fire, so buffering must not be armed. - replayQueue.add(createTestEvent("snapshot_1")) - awaitCondition { replayQueue.depth == 1 } - assertEquals(0, replayQueue.bufferDepth) - assertEquals(1, replayQueue.depth) - } finally { - sut.uninstall() - } - } - @Test fun `mid-session resume forces a fresh keyframe by clearing per-view snapshot state`() { // A mid-session flag-on resume must emit a fresh full snapshot: while stopped, per-view state @@ -2599,9 +2552,7 @@ internal class PostHogReplayIntegrationTest { @Test @Config(sdk = [26], shadows = [SnapshotBoundaryShadowPixelCopy::class]) fun `committed snapshot keeps its session when rotation precedes core enrichment`() { - val config = PostHogAndroidConfig(PROJECT_TOKEN) - @Suppress("DEPRECATION") - config.remoteConfig = false + val config = PostHogAndroidConfig(PROJECT_TOKEN, "http://127.0.0.1:1") config.preloadFeatureFlags = false var captured: PostHogEvent? = null config.addBeforeSend { event -> diff --git a/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysRestartTest.kt b/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysRestartTest.kt index cb2c57ea5..16521bde8 100644 --- a/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysRestartTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysRestartTest.kt @@ -139,7 +139,6 @@ internal class PostHogSurveysRestartTest { PostHogAndroidConfig(projectToken), ) preloadFeatureFlags = false - remoteConfig = false surveys = true surveysConfig.surveysDelegate = renderer surveysConfig.overrideDisplayLanguage = language diff --git a/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt b/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt index 264e46bee..e0adad853 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt @@ -306,7 +306,6 @@ public open class PostHogConfig constructor( debug = debug, sendFeatureFlagEvent = sendFeatureFlagEvent, preloadFeatureFlags = preloadFeatureFlags, - remoteConfig = remoteConfig, flushAt = flushAt, maxQueueSize = maxQueueSize, maxBatchSize = maxBatchSize, diff --git a/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt b/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt index 6d36783ea..b68787d37 100644 --- a/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt +++ b/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt @@ -175,7 +175,6 @@ internal class PostHogConfigTest { assertEquals(true, coreConfig.debug) assertEquals(false, coreConfig.sendFeatureFlagEvent) assertEquals(false, coreConfig.preloadFeatureFlags) - assertEquals(false, coreConfig.remoteConfig) assertEquals(15, coreConfig.flushAt) assertEquals(750, coreConfig.maxQueueSize) assertEquals(30, coreConfig.maxBatchSize) diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index 1d18f638e..d515cea20 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -156,8 +156,8 @@ public class com/posthog/PostHogConfig { public static final field DEFAULT_MAX_QUEUE_SIZE I public static final field DEFAULT_US_ASSETS_HOST Ljava/lang/String; public static final field DEFAULT_US_HOST Ljava/lang/String; - public fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun addBeforeSend (Lcom/posthog/PostHogBeforeSend;)V public final fun addIntegration (Lcom/posthog/PostHogIntegration;)V public final fun getBeforeSendList ()Ljava/util/List; @@ -196,7 +196,6 @@ public class com/posthog/PostHogConfig { public final fun getPushIdentityProvider ()Lkotlin/jvm/functions/Function3; public final fun getQueueProvider ()Lkotlin/jvm/functions/Function5; public final fun getReleaseIdentifier ()Ljava/lang/String; - public final fun getRemoteConfig ()Z public final fun getRemoteConfigHolder ()Lcom/posthog/internal/PostHogRemoteConfig; public final fun getRemoteConfigProvider ()Lkotlin/jvm/functions/Function6; public final fun getReplayStoragePrefix ()Ljava/lang/String; @@ -246,7 +245,6 @@ public class com/posthog/PostHogConfig { public final fun setProxy (Ljava/net/Proxy;)V public final fun setPushIdentityProvider (Lkotlin/jvm/functions/Function3;)V public final fun setReleaseIdentifier (Ljava/lang/String;)V - public final fun setRemoteConfig (Z)V public final fun setRemoteConfigHolder (Lcom/posthog/internal/PostHogRemoteConfig;)V public final fun setReplayStoragePrefix (Ljava/lang/String;)V public final fun setRequestHeaders (Ljava/util/Map;)V diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 6bd98ff1e..a616e878c 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -393,7 +393,6 @@ public class PostHog private constructor( } // only because of testing in isolation, this flag is always enabled - @Suppress("DEPRECATION") if (reloadFeatureFlags) { // Bootstrap already seeded the flags in RemoteConfig's init; fire the flags-loaded // callbacks now so listeners aren't blocked on the first network response. @@ -401,15 +400,10 @@ public class PostHog private constructor( notifyFeatureFlagsCallback(internalOnFeatureFlagsLoaded) notifyFeatureFlagsCallback(config.onFeatureFlags) } - when { - config.remoteConfig -> - loadRemoteConfigRequest( - internalOnFeatureFlagsLoaded, - config.onFeatureFlags, - ) - - config.preloadFeatureFlags -> reloadFeatureFlags(config.onFeatureFlags) - } + loadRemoteConfigRequest( + internalOnFeatureFlagsLoaded, + config.onFeatureFlags, + ) } // Reconcile a differing identified bootstrap after the setup reload is dispatched. diff --git a/posthog/src/main/java/com/posthog/PostHogConfig.kt b/posthog/src/main/java/com/posthog/PostHogConfig.kt index c01078500..c72ffa1e4 100644 --- a/posthog/src/main/java/com/posthog/PostHogConfig.kt +++ b/posthog/src/main/java/com/posthog/PostHogConfig.kt @@ -108,15 +108,6 @@ public open class PostHogConfig( * Default: true */ public var setDefaultPersonProperties: Boolean = true, - /** - * Preload PostHog remote config automatically - * Defaults to true - */ - @Deprecated( - message = "Remote config is now always enabled. This option is a no-op and will be removed in a future version.", - level = DeprecationLevel.WARNING, - ) - public var remoteConfig: Boolean = true, /** * Number of minimum events before they are sent over the wire * Defaults to 20 diff --git a/posthog/src/test/java/com/posthog/PostHogBeforeSendTest.kt b/posthog/src/test/java/com/posthog/PostHogBeforeSendTest.kt index 454282022..e4bbba3c1 100644 --- a/posthog/src/test/java/com/posthog/PostHogBeforeSendTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogBeforeSendTest.kt @@ -34,7 +34,6 @@ internal class PostHogBeforeSendTest { storagePrefix = tmpDir.newFolder().absolutePath replayStoragePrefix = tmpDir.newFolder().absolutePath preloadFeatureFlags = false - remoteConfig = false cachePreferences = PostHogMemoryPreferences() hooks.forEach { addBeforeSend(it) } } diff --git a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt index b4d4c80b1..214256e76 100644 --- a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt @@ -30,13 +30,13 @@ internal class PostHogBootstrapTest { private val serializer = PostHogSerializer(PostHogConfig(PROJECT_TOKEN)) private lateinit var config: PostHogConfig - @Suppress("DEPRECATION") private fun getSut( host: String = PostHogConfig.DEFAULT_HOST, bootstrap: PostHogBootstrapConfig? = null, cachePreferences: PostHogMemoryPreferences = PostHogMemoryPreferences(), preloadFeatureFlags: Boolean = false, - reloadFeatureFlags: Boolean = true, + // setup always requests /config; skip it when the test doesn't preload flags + reloadFeatureFlags: Boolean = preloadFeatureFlags, sendFeatureFlagEvent: Boolean = true, flushAt: Int = 1, storagePrefix: String = tmpDir.newFolder().absolutePath, @@ -52,8 +52,6 @@ internal class PostHogBootstrapTest { this.preloadFeatureFlags = preloadFeatureFlags this.sendFeatureFlagEvent = sendFeatureFlagEvent this.cachePreferences = cachePreferences - // keep setup on the single /flags path instead of the /config + /flags path - this.remoteConfig = false this.bootstrap = bootstrap this.optOut = optOut this.onFeatureFlags = onFeatureFlags @@ -370,6 +368,9 @@ internal class PostHogBootstrapTest { var loaded = false val sut = getSut( + host = "http://127.0.0.1:1", + // the callback fires from setup's flag loading, before /config answers + reloadFeatureFlags = true, bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("beta-ui" to true)), onFeatureFlags = PostHogOnFeatureFlags { loaded = true }, ) diff --git a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt index 82575e966..15122e4fe 100644 --- a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt @@ -48,11 +48,11 @@ internal class PostHogFeatureFlagsTest { storagePrefix: String = tmpDir.newFolder().absolutePath, optOut: Boolean = false, preloadFeatureFlags: Boolean = true, - reloadFeatureFlags: Boolean = true, + // setup always requests /config; skip it when the test doesn't preload flags + reloadFeatureFlags: Boolean = preloadFeatureFlags, sendFeatureFlagEvent: Boolean = true, reuseAnonymousId: Boolean = false, integration: PostHogIntegration? = null, - remoteConfig: Boolean = false, cachePreferences: PostHogMemoryPreferences = PostHogMemoryPreferences(), beforeSend: PostHogBeforeSend? = null, evaluationContexts: List? = null, @@ -73,7 +73,6 @@ internal class PostHogFeatureFlagsTest { this.reuseAnonymousId = reuseAnonymousId this.cachePreferences = cachePreferences this.evaluationContexts = evaluationContexts - this.remoteConfig = remoteConfig if (beforeSend != null) { addBeforeSend(beforeSend) } diff --git a/posthog/src/test/java/com/posthog/PostHogIntegrationChangeTest.kt b/posthog/src/test/java/com/posthog/PostHogIntegrationChangeTest.kt index 041a7548e..258cc39ea 100644 --- a/posthog/src/test/java/com/posthog/PostHogIntegrationChangeTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogIntegrationChangeTest.kt @@ -26,9 +26,8 @@ internal class PostHogIntegrationChangeTest { @Suppress("DEPRECATION") private val client = PostHog.with( - PostHogConfig(PROJECT_TOKEN).apply { + PostHogConfig(PROJECT_TOKEN, "http://127.0.0.1:1").apply { cachePreferences = PostHogMemoryPreferences() - remoteConfig = false preloadFeatureFlags = false addBeforeSend { null } addIntegration(integration) diff --git a/posthog/src/test/java/com/posthog/PostHogIntegrationInstallFailureTest.kt b/posthog/src/test/java/com/posthog/PostHogIntegrationInstallFailureTest.kt index d5a3717b8..93dd6f259 100644 --- a/posthog/src/test/java/com/posthog/PostHogIntegrationInstallFailureTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogIntegrationInstallFailureTest.kt @@ -27,10 +27,9 @@ internal class PostHogIntegrationInstallFailureTest { @Suppress("DEPRECATION") client = PostHog.with( - PostHogConfig(PROJECT_TOKEN).apply { + PostHogConfig(PROJECT_TOKEN, "http://127.0.0.1:1").apply { logger = testLogger cachePreferences = PostHogMemoryPreferences() - remoteConfig = false preloadFeatureFlags = false addBeforeSend { null } addIntegration(broken) diff --git a/posthog/src/test/java/com/posthog/PostHogOkHttpInterceptorTest.kt b/posthog/src/test/java/com/posthog/PostHogOkHttpInterceptorTest.kt index 09467943a..d91a9b2c3 100644 --- a/posthog/src/test/java/com/posthog/PostHogOkHttpInterceptorTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogOkHttpInterceptorTest.kt @@ -194,7 +194,6 @@ internal class PostHogOkHttpInterceptorTest { this.replayStoragePrefix = tmpDir.newFolder().absolutePath this.cachePreferences = PostHogMemoryPreferences() this.preloadFeatureFlags = false - this.remoteConfig = false } val postHog = diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index 5ce8ff3be..22176defb 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -90,11 +90,11 @@ internal class PostHogTest { optOut: Boolean = false, persistOptOut: Boolean = true, preloadFeatureFlags: Boolean = true, - reloadFeatureFlags: Boolean = true, + // setup always requests /config; skip it when the test doesn't preload flags + reloadFeatureFlags: Boolean = preloadFeatureFlags, sendFeatureFlagEvent: Boolean = true, reuseAnonymousId: Boolean = false, integration: PostHogIntegration? = null, - remoteConfig: Boolean = false, surveys: Boolean = false, cachePreferences: PostHogPreferences? = PostHogMemoryPreferences(), beforeSend: PostHogBeforeSend? = null, @@ -121,7 +121,6 @@ internal class PostHogTest { this.reuseAnonymousId = reuseAnonymousId this.cachePreferences = cachePreferences this.evaluationContexts = evaluationContexts - this.remoteConfig = remoteConfig this.surveys = surveys if (beforeSend != null) { addBeforeSend(beforeSend) @@ -368,22 +367,6 @@ internal class PostHogTest { sut.close() } - @Test - fun `preload feature flags if enabled`() { - val http = mockHttp() - val url = http.url("/") - - val sut = getSut(url.toString()) - - remoteConfigExecutor.shutdownAndAwaitTermination() - - val request = http.takeRequest() - assertEquals(1, http.requestCount) - assertEquals("/flags/?v=2", request.path) - - sut.close() - } - @Test fun `reload feature flags and call the callback`() { val http = mockHttp() @@ -409,7 +392,7 @@ internal class PostHogTest { val http = mockHttp() val url = http.url("/") - val sut = getSut(url.toString(), remoteConfig = true, preloadFeatureFlags = false) + val sut = getSut(url.toString(), preloadFeatureFlags = false, reloadFeatureFlags = true) remoteConfigExecutor.shutdownAndAwaitTermination() @@ -437,7 +420,7 @@ internal class PostHogTest { ) val url = http.url("/") - val sut = getSut(url.toString(), remoteConfig = true) + val sut = getSut(url.toString()) remoteConfigExecutor.shutdownAndAwaitTermination() @@ -469,7 +452,7 @@ internal class PostHogTest { ) val url = http.url("/") - val sut = getSut(url.toString(), remoteConfig = true) + val sut = getSut(url.toString()) remoteConfigExecutor.shutdownAndAwaitTermination() @@ -1665,7 +1648,7 @@ internal class PostHogTest { override fun onSurveysLoaded(surveys: List) {} } - val sut = getSut(url.toString(), remoteConfig = true, integration = surveysIntegration) + val sut = getSut(url.toString(), integration = surveysIntegration) http.takeRequest() http.takeRequest() @@ -1690,7 +1673,7 @@ internal class PostHogTest { val url = http.url("/") val integration = FakePostHogIntegration() - val sut = getSut(url.toString(), remoteConfig = true, integration = integration) + val sut = getSut(url.toString(), integration = integration) remoteConfigExecutor.shutdownAndAwaitTermination() assertEquals(1, integration.remoteConfigCount) @@ -3207,17 +3190,25 @@ internal class PostHogTest { @Test fun `reset reloads flags as anon user`() { - val http = mockHttp() + // setup's /config reports no flags, so the only /flags request comes from reset + val http = + mockHttp( + response = + MockResponse() + .setBody(File("src/test/resources/json/basic-remote-config-no-flags.json").readText()), + ) + http.enqueue(MockResponse().setBody(responseFlagsApi)) val url = http.url("/") - val sut = getSut(url.toString(), preloadFeatureFlags = false) + val sut = getSut(url.toString(), preloadFeatureFlags = false, reloadFeatureFlags = true) sut.reset() remoteConfigExecutor.shutdownAndAwaitTermination() + assertEquals("/array/${PROJECT_TOKEN}/config", http.takeRequest().path) val request = http.takeRequest() - assertEquals(1, http.requestCount) + assertEquals(2, http.requestCount) assertEquals("/flags/?v=2", request.path) sut.close() @@ -4465,8 +4456,9 @@ internal class PostHogTest { mockHttp( response = MockResponse() - .setBody(responseFlagsApi), + .setBody(File("src/test/resources/json/basic-remote-config.json").readText()), ) + http.enqueue(MockResponse().setBody(responseFlagsApi)) val url = http.url("/") val sut = getSut(url.toString(), preloadFeatureFlags = true, context = TestPostHogContext()) From b2361cd2da7b7722dd4121472d30f98aa4176169 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Wed, 28 Oct 2026 16:38:37 -0400 Subject: [PATCH 05/49] chore!: pass the load result to the feature flags callback (#877) * chore!: pass the load result to the feature flags callback PostHogConfig.onFeatureFlags and reloadFeatureFlags() now take a PostHogFeatureFlagsCallback, whose loaded() receives a PostHogFeatureFlagsLoaded with the enabled flags, their values, and errorsLoading, matching posthog-ios 4.0. Every path that invoked the callback passes an accurate result, including failures, a disabled SDK, and bootstrap. PostHogOnFeatureFlags moves to posthog-server under the same name, so the server's API is unchanged and it can drop the type in its own major. * chore: drop the unused server callback wrapper posthog-server calls its own PostHogOnFeatureFlags directly, and the core stateless client never calls config.onFeatureFlags. Bump posthog-server to minor since it now depends on core 7.0, and document that a bootstrapped onFeatureFlags runs on the setup() thread. * fix: report persisted flags when the first flags load fails Co-Authored-By: Claude Opus 5.5 * fix: isolate the bootstrap internal flags callback from setup Co-Authored-By: Claude Opus 5.5 * fix: keep loaded flags when a flags reload fails Co-Authored-By: Claude Opus 5.5 * fix: retry flag cache hydration while storage is unreadable A failed load now hydrates the flag cache before the callback. Under Direct Boot that read returned empty values and latched, so persisted flags stayed hidden after unlock. Only latch once the preferences are readable. Co-Authored-By: Claude Opus 5.5 * fix: skip flag cache reads while storage is unreadable Every flag getter retried hydration under Direct Boot and re-read each cached key, each read failing against locked preferences. Check availability once and skip the reads until storage is readable. Co-Authored-By: Claude Opus 5.5 * fix: don't let cache hydration undo a concurrent reset Hydration reads the cache off the flags lock, so a reset() landing between the read and the commit had the previous identity's flags restored. clear() now bumps a generation and hydration drops a commit from an older one. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/android-v4-major.md | 1 + .changeset/server-keep-on-feature-flags.md | 5 + .../PostHogAndroidEventSnapshotsTest.kt | 6 +- .../java/com/posthog/android/sample/MyApp.kt | 4 +- posthog-server/api/posthog-server.api | 4 + .../java/com/posthog/PostHogOnFeatureFlags.kt | 0 .../java/com/posthog/server/PostHogConfig.kt | 1 - .../com/posthog/server/PostHogConfigTest.kt | 2 +- posthog/api/posthog.api | 41 +-- posthog/src/main/java/com/posthog/PostHog.kt | 36 ++- .../main/java/com/posthog/PostHogConfig.kt | 5 +- .../posthog/PostHogFeatureFlagsCallback.kt | 27 ++ .../com/posthog/PostHogFeatureFlagsLoaded.kt | 47 ++++ .../main/java/com/posthog/PostHogInterface.kt | 17 +- .../posthog/internal/PostHogRemoteConfig.kt | 82 ++++-- .../java/com/posthog/PostHogBootstrapTest.kt | 11 +- .../com/posthog/PostHogFeatureFlagsTest.kt | 8 +- .../src/test/java/com/posthog/PostHogTest.kt | 5 +- .../internal/PostHogRemoteConfigTest.kt | 255 +++++++++++++++--- .../java/com/posthog/PostHogFake.kt | 2 +- 20 files changed, 446 insertions(+), 113 deletions(-) create mode 100644 .changeset/server-keep-on-feature-flags.md rename {posthog => posthog-server}/src/main/java/com/posthog/PostHogOnFeatureFlags.kt (100%) create mode 100644 posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt create mode 100644 posthog/src/main/java/com/posthog/PostHogFeatureFlagsLoaded.kt diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index e89b373a7..fc2077550 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -11,3 +11,4 @@ - **Breaking:** return `null` instead of the raw string for a malformed, empty or whitespace-only feature flag payload from `getFeatureFlagResult(key)?.payload`; payloads must be valid JSON (a JSON `null` payload now also reads as `null` instead of the string `"null"`) - **Breaking:** make SDK-internal helpers in the `com.posthog.internal` and `com.posthog.android.replay.internal` packages non-public - **Breaking:** remove the deprecated `remoteConfig` config option; the SDK now always loads remote config at setup +- **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `PostHogConfig.onFeatureFlags` and `reloadFeatureFlags()`; it receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values, and `errorsLoading` diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md new file mode 100644 index 000000000..ca5fb7278 --- /dev/null +++ b/.changeset/server-keep-on-feature-flags.md @@ -0,0 +1,5 @@ +--- +'posthog-server': minor +--- + +Move `PostHogOnFeatureFlags` into `posthog-server`; its API is unchanged diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt index ae466718a..a29635090 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt @@ -3,8 +3,8 @@ package com.posthog.android import android.content.Context import androidx.test.ext.junit.runners.AndroidJUnit4 import com.google.gson.GsonBuilder +import com.posthog.PostHogFeatureFlagsCallback import com.posthog.PostHogInterface -import com.posthog.PostHogOnFeatureFlags import com.posthog.internal.PostHogContext import com.posthog.internal.PostHogDateProvider import com.posthog.internal.PostHogDeviceDateProvider @@ -67,7 +67,7 @@ internal class PostHogAndroidEventSnapshotsTest { fun `batch request and enriched event shapes match snapshot`() { val fixture = createFixture() val flagsLoaded = CountDownLatch(1) - fixture.config.onFeatureFlags = PostHogOnFeatureFlags { flagsLoaded.countDown() } + fixture.config.onFeatureFlags = PostHogFeatureFlagsCallback { flagsLoaded.countDown() } val sut = fixture.client sut.capture( @@ -115,7 +115,7 @@ internal class PostHogAndroidEventSnapshotsTest { mapOf("industry" to "analytics"), reloadFeatureFlags = false, ) - fixture.client.reloadFeatureFlags(PostHogOnFeatureFlags { loaded.countDown() }) + fixture.client.reloadFeatureFlags(PostHogFeatureFlagsCallback { loaded.countDown() }) assertTrue(loaded.await(10, TimeUnit.SECONDS), "Feature flags request did not finish") val request = fixture.server.takeRequests(CONFIG_PATH, "/flags/?v=2").single { it.path == "/flags/?v=2" } diff --git a/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt b/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt index 5b328a9ce..bfdb0e45e 100644 --- a/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt +++ b/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt @@ -2,7 +2,7 @@ package com.posthog.android.sample import android.app.Application import android.os.StrictMode -import com.posthog.PostHogOnFeatureFlags +import com.posthog.PostHogFeatureFlagsCallback import com.posthog.android.PostHogAndroid import com.posthog.android.PostHogAndroidConfig @@ -39,7 +39,7 @@ class MyApp : Application() { sessionReplay = true preloadFeatureFlags = true sendFeatureFlagEvent = false - onFeatureFlags = PostHogOnFeatureFlags { print("feature flags loaded") } + onFeatureFlags = PostHogFeatureFlagsCallback { print("feature flags loaded") } addBeforeSend { event -> if (event.event == "test_event") { null diff --git a/posthog-server/api/posthog-server.api b/posthog-server/api/posthog-server.api index 51421e12d..52a3c305a 100644 --- a/posthog-server/api/posthog-server.api +++ b/posthog-server/api/posthog-server.api @@ -1,3 +1,7 @@ +public abstract interface class com/posthog/PostHogOnFeatureFlags { + public abstract fun loaded ()V +} + public final class com/posthog/server/PostHog : com/posthog/PostHogStateless, com/posthog/server/PostHogInterface { public static final field Companion Lcom/posthog/server/PostHog$Companion; public fun ()V diff --git a/posthog/src/main/java/com/posthog/PostHogOnFeatureFlags.kt b/posthog-server/src/main/java/com/posthog/PostHogOnFeatureFlags.kt similarity index 100% rename from posthog/src/main/java/com/posthog/PostHogOnFeatureFlags.kt rename to posthog-server/src/main/java/com/posthog/PostHogOnFeatureFlags.kt diff --git a/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt b/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt index e0adad853..e0a484bed 100644 --- a/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt +++ b/posthog-server/src/main/java/com/posthog/server/PostHogConfig.kt @@ -311,7 +311,6 @@ public open class PostHogConfig constructor( maxBatchSize = maxBatchSize, flushIntervalSeconds = flushIntervalSeconds, encryption = encryption, - onFeatureFlags = onFeatureFlags, proxy = proxy, remoteConfigProvider = { config, api, _, _, _, _ -> PostHogFeatureFlags( diff --git a/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt b/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt index b68787d37..f77668c76 100644 --- a/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt +++ b/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt @@ -180,7 +180,7 @@ internal class PostHogConfigTest { assertEquals(30, coreConfig.maxBatchSize) assertEquals(45, coreConfig.flushIntervalSeconds) assertEquals(mockEncryption, coreConfig.encryption) - assertEquals(mockOnFeatureFlags, coreConfig.onFeatureFlags) + assertNull(coreConfig.onFeatureFlags) } @Test diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index d515cea20..c949a9dbd 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -52,7 +52,7 @@ public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posth public fun optOut ()V public fun register (Ljava/lang/String;Ljava/lang/Object;)V public fun registerPushNotificationToken (Ljava/lang/String;Ljava/lang/String;)V - public fun reloadFeatureFlags (Lcom/posthog/PostHogOnFeatureFlags;)V + public fun reloadFeatureFlags (Lcom/posthog/PostHogFeatureFlagsCallback;)V public fun reset ()V public fun resetGroupPropertiesForFlags (Ljava/lang/String;Z)V public fun resetPersonPropertiesForFlags (Z)V @@ -101,7 +101,7 @@ public final class com/posthog/PostHog$Companion : com/posthog/PostHogInterface public final fun overrideSharedInstance (Lcom/posthog/PostHogInterface;)V public fun register (Ljava/lang/String;Ljava/lang/Object;)V public fun registerPushNotificationToken (Ljava/lang/String;Ljava/lang/String;)V - public fun reloadFeatureFlags (Lcom/posthog/PostHogOnFeatureFlags;)V + public fun reloadFeatureFlags (Lcom/posthog/PostHogFeatureFlagsCallback;)V public fun reset ()V public fun resetGroupPropertiesForFlags (Ljava/lang/String;Z)V public fun resetPersonPropertiesForFlags (Z)V @@ -156,8 +156,8 @@ public class com/posthog/PostHogConfig { public static final field DEFAULT_MAX_QUEUE_SIZE I public static final field DEFAULT_US_ASSETS_HOST Ljava/lang/String; public static final field DEFAULT_US_HOST Ljava/lang/String; - public fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogOnFeatureFlags;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogFeatureFlagsCallback;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogFeatureFlagsCallback;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun addBeforeSend (Lcom/posthog/PostHogBeforeSend;)V public final fun addIntegration (Lcom/posthog/PostHogIntegration;)V public final fun getBeforeSendList ()Ljava/util/List; @@ -186,7 +186,7 @@ public class com/posthog/PostHogConfig { public final fun getMaxQueueSize ()I public final fun getMaxRetries ()I public final fun getNetworkStatus ()Lcom/posthog/internal/PostHogNetworkStatus; - public final fun getOnFeatureFlags ()Lcom/posthog/PostHogOnFeatureFlags; + public final fun getOnFeatureFlags ()Lcom/posthog/PostHogFeatureFlagsCallback; public final fun getOptOut ()Z public final fun getPersistOptOut ()Z public final fun getPersonProfiles ()Lcom/posthog/PersonProfiles; @@ -237,7 +237,7 @@ public class com/posthog/PostHogConfig { public final fun setMaxQueueSize (I)V public final fun setMaxRetries (I)V public final fun setNetworkStatus (Lcom/posthog/internal/PostHogNetworkStatus;)V - public final fun setOnFeatureFlags (Lcom/posthog/PostHogOnFeatureFlags;)V + public final fun setOnFeatureFlags (Lcom/posthog/PostHogFeatureFlagsCallback;)V public final fun setOptOut (Z)V public final fun setPersistOptOut (Z)V public final fun setPersonProfiles (Lcom/posthog/PersonProfiles;)V @@ -344,6 +344,17 @@ public final class com/posthog/PostHogEventName$Companion { public abstract interface annotation class com/posthog/PostHogExperimental : java/lang/annotation/Annotation { } +public abstract interface class com/posthog/PostHogFeatureFlagsCallback { + public abstract fun loaded (Lcom/posthog/PostHogFeatureFlagsLoaded;)V +} + +public final class com/posthog/PostHogFeatureFlagsLoaded { + public fun (Ljava/util/Map;Z)V + public final fun getErrorsLoading ()Z + public final fun getFlags ()Ljava/util/List; + public final fun getVariants ()Ljava/util/Map; +} + public abstract interface class com/posthog/PostHogIntegration { public fun install (Lcom/posthog/PostHogInterface;)V public fun onChange ()V @@ -396,8 +407,8 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public abstract fun isSessionReplayActive ()Z public abstract fun register (Ljava/lang/String;Ljava/lang/Object;)V public abstract fun registerPushNotificationToken (Ljava/lang/String;Ljava/lang/String;)V - public abstract fun reloadFeatureFlags (Lcom/posthog/PostHogOnFeatureFlags;)V - public static synthetic fun reloadFeatureFlags$default (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogOnFeatureFlags;ILjava/lang/Object;)V + public abstract fun reloadFeatureFlags (Lcom/posthog/PostHogFeatureFlagsCallback;)V + public static synthetic fun reloadFeatureFlags$default (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V public abstract fun reset ()V public abstract fun resetGroupPropertiesForFlags (Ljava/lang/String;Z)V public static synthetic fun resetGroupPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZILjava/lang/Object;)V @@ -431,7 +442,7 @@ public final class com/posthog/PostHogInterface$DefaultImpls { public static synthetic fun getFeatureFlagResult$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Lcom/posthog/FeatureFlagResult; public static synthetic fun group$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V public static synthetic fun isFeatureEnabled$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZLjava/lang/Boolean;ILjava/lang/Object;)Z - public static synthetic fun reloadFeatureFlags$default (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogOnFeatureFlags;ILjava/lang/Object;)V + public static synthetic fun reloadFeatureFlags$default (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V public static synthetic fun resetGroupPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZILjava/lang/Object;)V public static synthetic fun resetPersonPropertiesForFlags$default (Lcom/posthog/PostHogInterface;ZILjava/lang/Object;)V public static synthetic fun screen$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V @@ -453,10 +464,6 @@ public final class com/posthog/PostHogOkHttpInterceptor : okhttp3/Interceptor { public fun intercept (Lokhttp3/Interceptor$Chain;)Lokhttp3/Response; } -public abstract interface class com/posthog/PostHogOnFeatureFlags { - public abstract fun loaded ()V -} - public abstract interface class com/posthog/PostHogOptInReceiver { public abstract fun onOptIn ()V } @@ -1042,10 +1049,10 @@ public final class com/posthog/internal/PostHogRemoteConfig : com/posthog/intern public fun isMinimalFlagCalledEventsEnabled ()Z public final fun isNativeCrashCaptureEnabled ()Z public final fun isSessionReplayFlagActive ()Z - public final fun loadFeatureFlags (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lcom/posthog/PostHogOnFeatureFlags;Lcom/posthog/PostHogOnFeatureFlags;)V - public static synthetic fun loadFeatureFlags$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lcom/posthog/PostHogOnFeatureFlags;Lcom/posthog/PostHogOnFeatureFlags;ILjava/lang/Object;)V - public final fun loadRemoteConfig (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lcom/posthog/PostHogOnFeatureFlags;Lcom/posthog/PostHogOnFeatureFlags;)V - public static synthetic fun loadRemoteConfig$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lcom/posthog/PostHogOnFeatureFlags;Lcom/posthog/PostHogOnFeatureFlags;ILjava/lang/Object;)V + public final fun loadFeatureFlags (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function0;Lcom/posthog/PostHogFeatureFlagsCallback;)V + public static synthetic fun loadFeatureFlags$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function0;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V + public final fun loadRemoteConfig (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function0;Lcom/posthog/PostHogFeatureFlagsCallback;)V + public static synthetic fun loadRemoteConfig$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function0;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V public final fun makeSamplingDecision (Ljava/lang/String;)Z public final fun persistPushConfigCache ()V public final fun resetGroupPropertiesForFlags (Ljava/lang/String;)V diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index a616e878c..63a8c0f65 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -188,8 +188,8 @@ public class PostHog private constructor( private var isPersonProcessingLoaded: Boolean = false // this is called if the feature flags are loaded for the first time and recording isn't started yet - private val internalOnFeatureFlagsLoaded = - PostHogOnFeatureFlags { + private val internalOnFeatureFlagsLoaded: () -> Unit = + { // under setupLock so a concurrent optOut can't uninstall replay between the check and the start synchronized(setupLock) { sessionReplayHandler?.let { @@ -397,8 +397,12 @@ public class PostHog private constructor( // Bootstrap already seeded the flags in RemoteConfig's init; fire the flags-loaded // callbacks now so listeners aren't blocked on the first network response. if (remoteConfig?.hasBootstrapFlags() == true) { - notifyFeatureFlagsCallback(internalOnFeatureFlagsLoaded) - notifyFeatureFlagsCallback(config.onFeatureFlags) + try { + internalOnFeatureFlagsLoaded() + } catch (e: Throwable) { + config.logger.log("Executing the internal feature flags callback failed: $e") + } + notifyFeatureFlagsCallback(config.onFeatureFlags, remoteConfig?.getFeatureFlags(), errorsLoading = false) } loadRemoteConfigRequest( internalOnFeatureFlagsLoaded, @@ -1915,18 +1919,22 @@ public class PostHog private constructor( } // Invokes the feature flags callback, swallowing exceptions like runOnFeatureFlagsCallbacks. - private fun notifyFeatureFlagsCallback(onFeatureFlags: PostHogOnFeatureFlags?) { + private fun notifyFeatureFlagsCallback( + onFeatureFlags: PostHogFeatureFlagsCallback?, + featureFlags: Map?, + errorsLoading: Boolean, + ) { try { - onFeatureFlags?.loaded() + onFeatureFlags?.loaded(PostHogFeatureFlagsLoaded(featureFlags ?: emptyMap(), errorsLoading)) } catch (e: Throwable) { config?.logger?.log("Executing the feature flags callback failed: $e") } } - public override fun reloadFeatureFlags(onFeatureFlags: PostHogOnFeatureFlags?) { + public override fun reloadFeatureFlags(onFeatureFlags: PostHogFeatureFlagsCallback?) { if (!isEnabled()) { // Still invoke the callback so awaiting callers aren't left hanging. - notifyFeatureFlagsCallback(onFeatureFlags) + notifyFeatureFlagsCallback(onFeatureFlags, featureFlags = null, errorsLoading = true) return } loadFeatureFlagsRequest( @@ -1936,8 +1944,8 @@ public class PostHog private constructor( } private fun loadFeatureFlagsRequest( - internalOnFeatureFlags: PostHogOnFeatureFlags, - onFeatureFlags: PostHogOnFeatureFlags? = null, + internalOnFeatureFlags: () -> Unit, + onFeatureFlags: PostHogFeatureFlagsCallback? = null, ) { @Suppress("UNCHECKED_CAST") val groups = getPreferences().getValue(GROUPS) as? Map @@ -1952,7 +1960,7 @@ public class PostHog private constructor( if (distinctId.isBlank()) { config?.logger?.log("Feature flags not loaded, distinctId is invalid: $distinctId") // Still invoke the callback so awaiting callers aren't left hanging. - notifyFeatureFlagsCallback(onFeatureFlags) + notifyFeatureFlagsCallback(onFeatureFlags, remoteConfig?.getFeatureFlags(), errorsLoading = true) return } @@ -1966,8 +1974,8 @@ public class PostHog private constructor( } private fun loadRemoteConfigRequest( - internalOnFeatureFlags: PostHogOnFeatureFlags?, - onFeatureFlags: PostHogOnFeatureFlags?, + internalOnFeatureFlags: (() -> Unit)?, + onFeatureFlags: PostHogFeatureFlagsCallback?, ) { @Suppress("UNCHECKED_CAST") val groups = getPreferences().getValue(GROUPS) as? Map @@ -2705,7 +2713,7 @@ public class PostHog private constructor( ) } - public override fun reloadFeatureFlags(onFeatureFlags: PostHogOnFeatureFlags?) { + public override fun reloadFeatureFlags(onFeatureFlags: PostHogFeatureFlagsCallback?) { shared.reloadFeatureFlags(onFeatureFlags) } diff --git a/posthog/src/main/java/com/posthog/PostHogConfig.kt b/posthog/src/main/java/com/posthog/PostHogConfig.kt index c72ffa1e4..ee45ad3c4 100644 --- a/posthog/src/main/java/com/posthog/PostHogConfig.kt +++ b/posthog/src/main/java/com/posthog/PostHogConfig.kt @@ -154,10 +154,11 @@ public open class PostHogConfig( */ public var encryption: PostHogEncryption? = null, /** - * Hook that is called when feature flags are loaded + * Hook that is called when feature flags are loaded, or loading them failed + * It receives a [PostHogFeatureFlagsLoaded]; see [PostHogFeatureFlagsCallback] for the thread it runs on * Defaults to no callback */ - public var onFeatureFlags: PostHogOnFeatureFlags? = null, + public var onFeatureFlags: PostHogFeatureFlagsCallback? = null, /** * Enable Recording of Session Replays for Android * Requires Record user sessions to be enabled in the PostHog Project Settings diff --git a/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt new file mode 100644 index 000000000..2252f392a --- /dev/null +++ b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt @@ -0,0 +1,27 @@ +package com.posthog + +/** + * Callback invoked when a feature flags load finishes, whether it succeeded or failed. + * + * It's used by `PostHogConfig.onFeatureFlags` and `reloadFeatureFlags`. It runs on a background + * thread, or right away on the calling thread when no load is attempted (for example, the SDK is + * disabled). With bootstrapped flags, `PostHogConfig.onFeatureFlags` also runs once on the thread + * calling `setup()`, before the first load finishes. Hop to the main thread before touching UI. + * + * Example: + * ```kotlin + * config.onFeatureFlags = PostHogFeatureFlagsCallback { loaded -> + * if (!loaded.errorsLoading && "new-checkout" in loaded.flags) { + * // The flag is enabled + * } + * } + * ``` + */ +public fun interface PostHogFeatureFlagsCallback { + /** + * Called when feature flags are loaded, or loading them failed. + * + * @param result the enabled flags, their values, and whether loading failed + */ + public fun loaded(result: PostHogFeatureFlagsLoaded) +} diff --git a/posthog/src/main/java/com/posthog/PostHogFeatureFlagsLoaded.kt b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsLoaded.kt new file mode 100644 index 000000000..095744361 --- /dev/null +++ b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsLoaded.kt @@ -0,0 +1,47 @@ +package com.posthog + +/** + * The feature flags passed to a [PostHogFeatureFlagsCallback] callback. + * + * It holds the enabled flags as they were when the callback was invoked, and whether the latest + * attempt to load them failed. Disabled flags are left out. + * + * Example: + * ```kotlin + * PostHog.reloadFeatureFlags { loaded -> + * if (loaded.errorsLoading) { + * // The values are the last known (cached) flags + * } + * if (loaded.variants["new-checkout"] == "test") { + * // Show the test variant + * } + * } + * ``` + * + * @param featureFlags the flag values, keyed by flag key; disabled flags and non-flag values are dropped + * @property errorsLoading `true` if the latest attempt to load feature flags failed. When it did, + * [flags] and [variants] hold the last known values, which can be empty. It's also `true`, with no + * values, when the SDK isn't set up or is disabled and `reloadFeatureFlags` is called. + */ +public class PostHogFeatureFlagsLoaded + @PostHogInternal + public constructor( + featureFlags: Map, + public val errorsLoading: Boolean, + ) { + /** + * The values of the enabled feature flags, keyed by flag key. + * + * A value is `true` for an enabled boolean flag, or the variant `String` for a multivariate flag. + * Disabled flags are not included. + */ + public val variants: Map = + featureFlags.entries + .mapNotNull { (key, value) -> if (value == true || value is String) key to value else null } + .toMap() + + /** + * The keys of the enabled feature flags. + */ + public val flags: List = variants.keys.toList() + } diff --git a/posthog/src/main/java/com/posthog/PostHogInterface.kt b/posthog/src/main/java/com/posthog/PostHogInterface.kt index 50e76b49b..e56fbf98b 100644 --- a/posthog/src/main/java/com/posthog/PostHogInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogInterface.kt @@ -124,9 +124,22 @@ public interface PostHogInterface : PostHogCoreInterface { /** * Reloads the feature flags - * @param onFeatureFlags the callback to get notified once feature flags is ready to use + * + * The callback is invoked when the reload finishes, on a background thread. If the request fails, + * [PostHogFeatureFlagsLoaded.errorsLoading] is `true` and the values are the last known flags. If + * the SDK isn't set up, it's invoked right away with no flags and `errorsLoading` set to `true`. + * + * ```kotlin + * PostHog.reloadFeatureFlags { loaded -> + * if (loaded.errorsLoading) { + * // The reload failed. loaded.variants holds the last known flags. + * } + * } + * ``` + * + * @param onFeatureFlags the callback to get notified once the reload finishes, defaults to none */ - public fun reloadFeatureFlags(onFeatureFlags: PostHogOnFeatureFlags? = null) + public fun reloadFeatureFlags(onFeatureFlags: PostHogFeatureFlagsCallback? = null) /** * Returns if a feature flag is enabled, the feature flag must be a Boolean diff --git a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt index af4d05fc0..c1091864a 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt @@ -5,8 +5,9 @@ import com.google.gson.stream.JsonToken import com.google.gson.stream.MalformedJsonException import com.posthog.FeatureFlagResult import com.posthog.PostHogConfig +import com.posthog.PostHogFeatureFlagsCallback +import com.posthog.PostHogFeatureFlagsLoaded import com.posthog.PostHogInternal -import com.posthog.PostHogOnFeatureFlags import com.posthog.internal.PostHogPreferences.Companion.CAPTURE_PERFORMANCE import com.posthog.internal.PostHogPreferences.Companion.DEVICE_ID import com.posthog.internal.PostHogPreferences.Companion.ERROR_TRACKING @@ -63,8 +64,8 @@ public class PostHogRemoteConfig( val distinctId: String, val anonymousId: String?, val groups: Map?, - val internalOnFeatureFlags: List, - val onFeatureFlags: List, + val internalOnFeatureFlags: List<() -> Unit>, + val onFeatureFlags: List, ) private var pendingFeatureFlagsRequest: PendingFeatureFlagsRequest? = null @@ -116,6 +117,10 @@ public class PostHogRemoteConfig( @Volatile private var isFeatureFlagsLoaded = false + // Bumped by clear(), so a cache hydration that read the previous identity's flags before a reset + // doesn't commit them after it. Guarded by featureFlagsLock. + private var featureFlagsGeneration = 0 + // Whether a /flags response has been received this session. In-memory and reset each launch // (matching posthog-js), so a returning user still reports $used_bootstrap_value true while served // bootstrap values until this session's own /flags. Distinct from isFeatureFlagsLoaded, which also @@ -251,16 +256,26 @@ public class PostHogRemoteConfig( return recordingActive } - private fun List.asSingleCallback(): PostHogOnFeatureFlags? = + @JvmName("asSingleInternalCallback") + private fun List<() -> Unit>.asSingleCallback(): (() -> Unit)? = + when (size) { + 0 -> null + 1 -> first() + else -> { + { forEach { runSafely(it) } } + } + } + + private fun List.asSingleCallback(): PostHogFeatureFlagsCallback? = when (size) { 0 -> null 1 -> first() - else -> PostHogOnFeatureFlags { forEach { it.runSafely() } } + else -> PostHogFeatureFlagsCallback { result -> forEach { runSafely { it.loaded(result) } } } } - private fun PostHogOnFeatureFlags.runSafely() { + private fun runSafely(callback: () -> Unit) { try { - loaded() + callback() } catch (e: Throwable) { try { config.logger.log("Executing the feature flags callback failed: $e") @@ -271,13 +286,20 @@ public class PostHogRemoteConfig( } private fun runOnFeatureFlagsCallbacks( - internalOnFeatureFlags: PostHogOnFeatureFlags?, - onFeatureFlags: PostHogOnFeatureFlags?, + internalOnFeatureFlags: (() -> Unit)?, + onFeatureFlags: PostHogFeatureFlagsCallback?, + errorsLoading: Boolean, ) { // if we don't load the feature flags (because there are none), we need to call the callback // because the app might be waiting for it. - internalOnFeatureFlags?.runSafely() - onFeatureFlags?.runSafely() + internalOnFeatureFlags?.let { runSafely(it) } + onFeatureFlags?.let { callback -> + runSafely { + // a failed first load still reports the persisted flags, so hydrate them first + loadFeatureFlagsFromCacheIfNeeded() + callback.loaded(PostHogFeatureFlagsLoaded(getFeatureFlags() ?: emptyMap(), errorsLoading)) + } + } } // Notifies that a remote config resolution attempt finished. Callers set @@ -295,8 +317,8 @@ public class PostHogRemoteConfig( distinctId: String, anonymousId: String?, groups: Map?, - internalOnFeatureFlags: PostHogOnFeatureFlags? = null, - onFeatureFlags: PostHogOnFeatureFlags? = null, + internalOnFeatureFlags: (() -> Unit)? = null, + onFeatureFlags: PostHogFeatureFlagsCallback? = null, ) { executor.executeSafely { if (config.networkStatus?.isConnected() == false) { @@ -304,6 +326,7 @@ public class PostHogRemoteConfig( runOnFeatureFlagsCallbacks( internalOnFeatureFlags = internalOnFeatureFlags, onFeatureFlags = onFeatureFlags, + errorsLoading = true, ) if (!remoteConfigHasFetched.get()) { notifyRemoteConfigResolved() @@ -382,6 +405,8 @@ public class PostHogRemoteConfig( runOnFeatureFlagsCallbacks( internalOnFeatureFlags = internalOnFeatureFlags, onFeatureFlags = onFeatureFlags, + // the project has flags, but the distinctId was invalid so none were loaded + errorsLoading = it.hasFeatureFlags == true, ) } @@ -392,6 +417,7 @@ public class PostHogRemoteConfig( runOnFeatureFlagsCallbacks( internalOnFeatureFlags = internalOnFeatureFlags, onFeatureFlags = onFeatureFlags, + errorsLoading = true, ) if (!remoteConfigHasFetched.get()) { notifyRemoteConfigResolved() @@ -405,6 +431,7 @@ public class PostHogRemoteConfig( runOnFeatureFlagsCallbacks( internalOnFeatureFlags = internalOnFeatureFlags, onFeatureFlags = onFeatureFlags, + errorsLoading = true, ) config.logger.log("Loading remote config failed: $e") if (!remoteConfigHasFetched.get()) { @@ -831,8 +858,8 @@ public class PostHogRemoteConfig( distinctId: String, anonymousId: String?, groups: Map?, - internalOnFeatureFlags: PostHogOnFeatureFlags?, - onFeatureFlags: PostHogOnFeatureFlags?, + internalOnFeatureFlags: (() -> Unit)?, + onFeatureFlags: PostHogFeatureFlagsCallback?, notifyRemoteConfigLoaded: Boolean = true, ) { if (config.networkStatus?.isConnected() == false) { @@ -840,6 +867,7 @@ public class PostHogRemoteConfig( runOnFeatureFlagsCallbacks( internalOnFeatureFlags = internalOnFeatureFlags, onFeatureFlags = onFeatureFlags, + errorsLoading = true, ) if (notifyRemoteConfigLoaded && !remoteConfigHasFetched.get()) { notifyRemoteConfigResolved() @@ -879,6 +907,7 @@ public class PostHogRemoteConfig( return } + var errorsLoading = true try { val deviceId = config.cachePreferences?.getValue(DEVICE_ID) as? String @@ -920,6 +949,8 @@ public class PostHogRemoteConfig( // remote config for the current identity — mark fetched + notify (outside the // lock) so the replay buffer-and-decide gate disarms instead of staying stuck. quotaLimited = true + // like posthog-ios, a quota-limited response counts as loaded with the cached flags + errorsLoading = false return@let } @@ -1029,6 +1060,7 @@ public class PostHogRemoteConfig( } isFeatureFlagsLoaded = true setFlagsLoadedFromRemote() + errorsLoading = false if (notifyRemoteConfigLoaded) { // The flags path also resolves the remote config for the current identity (it's @@ -1058,6 +1090,7 @@ public class PostHogRemoteConfig( runOnFeatureFlagsCallbacks( internalOnFeatureFlags = internalOnFeatureFlags, onFeatureFlags = onFeatureFlags, + errorsLoading = errorsLoading, ) } catch (ignored: Throwable) { // never skip the release below: leaving the claim set stops all future flag loads @@ -1088,8 +1121,8 @@ public class PostHogRemoteConfig( distinctId: String, anonymousId: String?, groups: Map?, - internalOnFeatureFlags: PostHogOnFeatureFlags? = null, - onFeatureFlags: PostHogOnFeatureFlags? = null, + internalOnFeatureFlags: (() -> Unit)? = null, + onFeatureFlags: PostHogFeatureFlagsCallback? = null, ) { executor.executeSafely { executeFeatureFlags( @@ -1162,6 +1195,13 @@ public class PostHogRemoteConfig( private fun loadFeatureFlagsFromCache() { config.cachePreferences?.let { preferences -> + // unreadable storage (e.g. Direct Boot) would read as empty: skip the reads and don't latch, + // so a later read retries once it's readable + if (!preferences.isAvailable()) { + return + } + val generation = synchronized(featureFlagsLock) { featureFlagsGeneration } + @Suppress("UNCHECKED_CAST") val flags = preferences.getValue( @@ -1189,6 +1229,9 @@ public class PostHogRemoteConfig( val cachedMinimalFlagCalledEvents = preferences.getValue(MINIMAL_FLAG_CALLED_EVENTS) as? Boolean ?: false synchronized(featureFlagsLock) { + if (generation != featureFlagsGeneration) { + return + } this.flags = flags this.featureFlags = featureFlags this.featureFlagPayloads = payloads @@ -1253,7 +1296,9 @@ public class PostHogRemoteConfig( } private fun loadFeatureFlagsFromCacheIfNeeded() { - if (!isFeatureFlagsLoaded) { + // after a remote load this session the in-memory flags are newest; a failed reload must not + // hydrate over them, which would also reapply bootstrap + if (!isFeatureFlagsLoaded && !flagsLoadedFromRemote) { loadFeatureFlagsFromCache() } } @@ -1705,6 +1750,7 @@ public class PostHogRemoteConfig( sessionReplayLinkedFlagConfigured = false consoleLogRecordingEnabled = false isFeatureFlagsLoaded = false + featureFlagsGeneration++ // Bootstrap is first-session only: drop the retained base layer and the "loaded from // remote" signal so a later identity is never served the previous user's bootstrapped // values and $used_bootstrap_value reports true again until its own /flags response. diff --git a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt index 214256e76..19903d96a 100644 --- a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt @@ -42,7 +42,7 @@ internal class PostHogBootstrapTest { storagePrefix: String = tmpDir.newFolder().absolutePath, logger: TestLogger? = null, optOut: Boolean = false, - onFeatureFlags: PostHogOnFeatureFlags? = null, + onFeatureFlags: PostHogFeatureFlagsCallback? = null, ): PostHogInterface { config = PostHogConfig(PROJECT_TOKEN, host).apply { @@ -365,17 +365,18 @@ internal class PostHogBootstrapTest { @Test fun `bootstrap flags fire the flags-loaded callback immediately`() { - var loaded = false + var loaded: PostHogFeatureFlagsLoaded? = null val sut = getSut( host = "http://127.0.0.1:1", // the callback fires from setup's flag loading, before /config answers reloadFeatureFlags = true, - bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("beta-ui" to true)), - onFeatureFlags = PostHogOnFeatureFlags { loaded = true }, + bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("beta-ui" to true, "checkout" to "test")), + onFeatureFlags = PostHogFeatureFlagsCallback { loaded = it }, ) - assertTrue(loaded) + assertEquals(mapOf("beta-ui" to true, "checkout" to "test"), loaded!!.variants) + assertFalse(loaded!!.errorsLoading) assertEquals(true, sut.getFeatureFlag("beta-ui", sendFeatureFlagEvent = false)) sut.close() diff --git a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt index 15122e4fe..399c7ee79 100644 --- a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt @@ -392,11 +392,13 @@ internal class PostHogFeatureFlagsTest { val sut = getSut(url.toString(), preloadFeatureFlags = false) sut.close() - var called = false - sut.reloadFeatureFlags { called = true } + var result: PostHogFeatureFlagsLoaded? = null + sut.reloadFeatureFlags { result = it } // isEnabled() is false after close(), so reloadFeatureFlags early-returns. The // callback must still fire (synchronously) rather than leave awaiting callers hanging. - assertTrue(called) + assertTrue(result!!.errorsLoading) + assertTrue(result!!.flags.isEmpty()) + assertTrue(result!!.variants.isEmpty()) } } diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index 22176defb..0288881f1 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -1498,10 +1498,11 @@ internal class PostHogTest { val sut = getSut(url.toString(), cachePreferences = myPrefs, preloadFeatureFlags = false, integration = integration) config.sessionReplay = true + @Suppress("UNCHECKED_CAST") val onFlagsLoaded = PostHog::class.java.getDeclaredField("internalOnFeatureFlagsLoaded") .apply { isAccessible = true } - .get(sut) as PostHogOnFeatureFlags + .get(sut) as () -> Unit // optOut runs while the flags-loaded callback is between reading the handler and starting it var optOut: Thread? = null @@ -1515,7 +1516,7 @@ internal class PostHogTest { } } } - onFlagsLoaded.loaded() + onFlagsLoaded() optOut!!.join() assertTrue(sut.isOptOut()) diff --git a/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt index 0d9249fc1..c242f2ecb 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt @@ -3,7 +3,8 @@ package com.posthog.internal import com.posthog.PROJECT_TOKEN import com.posthog.PostHogBootstrapConfig import com.posthog.PostHogConfig -import com.posthog.PostHogOnFeatureFlags +import com.posthog.PostHogFeatureFlagsCallback +import com.posthog.PostHogFeatureFlagsLoaded import com.posthog.TestHttpServers import com.posthog.internal.PostHogPreferences.Companion.CAPTURE_PERFORMANCE import com.posthog.internal.PostHogPreferences.Companion.ERROR_TRACKING @@ -20,6 +21,7 @@ import org.junit.Rule import java.io.File import java.util.concurrent.CountDownLatch import java.util.concurrent.Executors +import java.util.concurrent.LinkedBlockingQueue import java.util.concurrent.TimeUnit import java.util.concurrent.atomic.AtomicInteger import kotlin.test.AfterTest @@ -197,7 +199,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { firstLatch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { firstLatch.countDown() }, ) assertTrue(firstLatch.await(5, TimeUnit.SECONDS), "first flags load should complete") assertTrue(sut.isSessionReplayFlagActive()) @@ -211,7 +213,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { secondLatch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { secondLatch.countDown() }, ) assertTrue(secondLatch.await(5, TimeUnit.SECONDS), "second flags load should complete") @@ -235,7 +237,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -332,7 +334,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { firstLatch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { firstLatch.countDown() }, ) assertTrue(firstLatch.await(5, TimeUnit.SECONDS), "first flags load should complete") assertTrue(sut.hasRemoteConfigFetched()) @@ -346,7 +348,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { secondLatch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { secondLatch.countDown() }, ) assertTrue(secondLatch.await(5, TimeUnit.SECONDS), "second (offline) flags load should complete") @@ -397,7 +399,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -430,7 +432,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -463,7 +465,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -488,7 +490,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -602,7 +604,7 @@ internal class PostHogRemoteConfigTest { "user-in-rollout", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { firstLatch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { firstLatch.countDown() }, ) assertTrue(firstLatch.await(5, TimeUnit.SECONDS), "first flags load should complete") assertTrue(sut.isSessionReplayFlagActive()) @@ -614,7 +616,7 @@ internal class PostHogRemoteConfigTest { "user-outside-rollout", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { secondLatch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { secondLatch.countDown() }, ) assertTrue(secondLatch.await(5, TimeUnit.SECONDS), "second flags load should complete") @@ -747,7 +749,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -824,7 +826,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "quota limited remote config load should complete") @@ -917,15 +919,14 @@ internal class PostHogRemoteConfigTest { var called = false var calledInternal = false - val onFeatureFlags: PostHogOnFeatureFlags = - PostHogOnFeatureFlags { + val onFeatureFlags: PostHogFeatureFlagsCallback = + PostHogFeatureFlagsCallback { called = true } - val internalOnFeatureFlags: PostHogOnFeatureFlags = - PostHogOnFeatureFlags { - calledInternal = true - } + val internalOnFeatureFlags = { + calledInternal = true + } val sut = getSut(host = url.toString()) @@ -1101,12 +1102,12 @@ internal class PostHogRemoteConfigTest { val secondCallbackLatch = CountDownLatch(1) val firstCallback = - PostHogOnFeatureFlags { + PostHogFeatureFlagsCallback { firstCallbackLatch.countDown() } val secondCallback = - PostHogOnFeatureFlags { + PostHogFeatureFlagsCallback { secondCallbackLatch.countDown() } @@ -1180,7 +1181,7 @@ internal class PostHogRemoteConfigTest { anonymousId = "anon_id_for_hash_key", groups = mapOf("company" to "posthog"), onFeatureFlags = - PostHogOnFeatureFlags { + PostHogFeatureFlagsCallback { secondCallbackLatch.countDown() }, ) @@ -1730,7 +1731,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -1764,7 +1765,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -2554,7 +2555,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -2583,7 +2584,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -2620,7 +2621,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -2674,7 +2675,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -2705,7 +2706,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "remote config load should complete") @@ -2757,7 +2758,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -2786,7 +2787,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -2829,7 +2830,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") @@ -2867,7 +2868,7 @@ internal class PostHogRemoteConfigTest { "user-1", anonymousId = "anon-1", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { firstLatch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { firstLatch.countDown() }, ) assertTrue(firstLatch.await(5, TimeUnit.SECONDS), "first flags load should complete") // a complete /flags response replaces the served flags, so the bootstrapped-only key is dropped @@ -2884,7 +2885,7 @@ internal class PostHogRemoteConfigTest { "user-2", anonymousId = "anon-2", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { secondLatch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { secondLatch.countDown() }, ) assertTrue(secondLatch.await(5, TimeUnit.SECONDS), "second flags load should complete") @@ -2950,7 +2951,7 @@ internal class PostHogRemoteConfigTest { anonymousId = "anonId", emptyMap(), onFeatureFlags = - PostHogOnFeatureFlags { + PostHogFeatureFlagsCallback { counts[index].incrementAndGet() fired.countDown() }, @@ -2985,7 +2986,7 @@ internal class PostHogRemoteConfigTest { val invocations = AtomicInteger(0) val completed = CountDownLatch(2) val shared = - PostHogOnFeatureFlags { + PostHogFeatureFlagsCallback { invocations.incrementAndGet() completed.countDown() } @@ -3042,7 +3043,7 @@ internal class PostHogRemoteConfigTest { anonymousId = "anonId", emptyMap(), onFeatureFlags = - PostHogOnFeatureFlags { + PostHogFeatureFlagsCallback { first.countDown() throw IllegalStateException("callback blew up") }, @@ -3055,7 +3056,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { second.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { second.countDown() }, ) assertTrue(second.await(5, TimeUnit.SECONDS), "a later reload never ran - the in-flight claim was stranded") @@ -3065,6 +3066,176 @@ internal class PostHogRemoteConfigTest { http.shutdown() } + @Test + fun `the feature flags callback receives the enabled flags and their values`() { + val flags = File("src/test/resources/json/flags-v1/basic-flags-with-non-active-flags.json").readText() + val http = mockHttp(response = MockResponse().setBody(flags)) + val sut = getSut(host = http.url("/").toString()) + + val results = LinkedBlockingQueue() + sut.loadFeatureFlags("my_identify", anonymousId = "anonId", emptyMap(), onFeatureFlags = { results.add(it) }) + + val loaded = results.poll(5, TimeUnit.SECONDS)!! + assertEquals(mapOf("4535-funnel-bar-viz" to true, "splashScreenName" to "SplashV2"), loaded.variants) + assertEquals(setOf("4535-funnel-bar-viz", "splashScreenName"), loaded.flags.toSet()) + assertFalse(loaded.errorsLoading) + } + + @Test + fun `a failed flags load reports errorsLoading with the last known flags`() { + val http = mockHttp(response = MockResponse().setBody(responseFlagsApi)) + http.enqueue(MockResponse().setResponseCode(500)) + val sut = getSut(host = http.url("/").toString()) + + val results = LinkedBlockingQueue() + sut.loadFeatureFlags("my_identify", anonymousId = "anonId", emptyMap(), onFeatureFlags = { results.add(it) }) + sut.loadFeatureFlags("my_identify", anonymousId = "anonId", emptyMap(), onFeatureFlags = { results.add(it) }) + + assertFalse(results.poll(5, TimeUnit.SECONDS)!!.errorsLoading) + val failed = results.poll(5, TimeUnit.SECONDS)!! + assertTrue(failed.errorsLoading) + assertEquals(mapOf("4535-funnel-bar-viz" to true), failed.variants) + } + + @Test + fun `a failed remote config load reports errorsLoading`() { + val http = mockHttp(response = MockResponse().setResponseCode(500)) + val sut = getSut(host = http.url("/").toString()) + + val results = LinkedBlockingQueue() + sut.loadRemoteConfig("my_identify", anonymousId = "anonId", emptyMap(), onFeatureFlags = { results.add(it) }) + + val loaded = results.poll(5, TimeUnit.SECONDS)!! + assertTrue(loaded.errorsLoading) + assertTrue(loaded.flags.isEmpty()) + } + + @Test + fun `a failed first load reports the persisted flags`() { + preferences.setValue(FEATURE_FLAGS, mapOf("cached-flag" to true)) + val http = mockHttp(response = MockResponse().setResponseCode(500)) + val sut = getSut(host = http.url("/").toString()) + + val results = LinkedBlockingQueue() + sut.loadFeatureFlags("my_identify", anonymousId = "anonId", emptyMap(), onFeatureFlags = { results.add(it) }) + + val loaded = results.poll(5, TimeUnit.SECONDS)!! + assertTrue(loaded.errorsLoading) + assertEquals(mapOf("cached-flag" to true), loaded.variants) + } + + // Unreadable until [available] is set, like Android preferences before first unlock (Direct Boot). + private class LockedPreferences(private val delegate: PostHogPreferences) : PostHogPreferences { + @Volatile + var available = false + val lockedReads = AtomicInteger() + + override fun getValue( + key: String, + defaultValue: Any?, + ): Any? { + if (!available) { + lockedReads.incrementAndGet() + return defaultValue + } + return delegate.getValue(key, defaultValue) + } + + override fun setValue( + key: String, + value: Any, + ) = delegate.setValue(key, value) + + override fun clear(except: List) = delegate.clear(except) + + override fun remove(key: String) = delegate.remove(key) + + override fun getAll(): Map = if (available) delegate.getAll() else emptyMap() + + override fun isAvailable(): Boolean = available + } + + @Test + fun `a failed load while storage is unreadable still serves the persisted flags once readable`() { + val locked = LockedPreferences(PostHogMemoryPreferences().apply { setValue(FEATURE_FLAGS, mapOf("cached-flag" to true)) }) + val offline = + object : PostHogNetworkStatus { + override fun isConnected(): Boolean = false + } + val sut = getSut(host = "http://localhost", networkStatus = offline, cachePreferences = locked) + + val results = LinkedBlockingQueue() + sut.loadRemoteConfig("my_identify", anonymousId = "anonId", emptyMap(), onFeatureFlags = { results.add(it) }) + val loaded = results.poll(5, TimeUnit.SECONDS)!! + assertTrue(loaded.errorsLoading) + assertTrue(loaded.variants.isEmpty()) + + locked.available = true + + assertEquals(true, sut.getFeatureFlag("cached-flag")) + } + + @Test + fun `a reset during cache hydration doesn't restore the previous identity's flags`() { + val stored = PostHogMemoryPreferences().apply { setValue(FEATURE_FLAGS, mapOf("old-user-flag" to true)) } + lateinit var sut: PostHogRemoteConfig + var resetMidRead = false + // stands in for reset() landing between hydration's cache read and its commit + val resetting = + object : PostHogPreferences by stored { + override fun getValue( + key: String, + defaultValue: Any?, + ): Any? { + val value = stored.getValue(key, defaultValue) + if (key == FEATURE_FLAGS && resetMidRead) { + resetMidRead = false + stored.clear() + sut.clear() + } + return value + } + } + sut = getSut(host = "http://localhost", cachePreferences = resetting) + resetMidRead = true + + assertNull(sut.getFeatureFlag("old-user-flag")) + } + + @Test + fun `flag reads while storage is unreadable don't read the flag cache`() { + val locked = LockedPreferences(PostHogMemoryPreferences().apply { setValue(FEATURE_FLAGS, mapOf("cached-flag" to true)) }) + val sut = getSut(host = "http://localhost", cachePreferences = locked) + val readsAtStartup = locked.lockedReads.get() + + repeat(3) { assertNull(sut.getFeatureFlag("cached-flag")) } + + assertEquals(readsAtStartup, locked.lockedReads.get()) + } + + @Test + fun `a failed reload after a successful load reports the loaded flags, not bootstrap`() { + // fixture returns featureFlags {"4535-funnel-bar-viz": true} + val http = mockHttp(response = MockResponse().setBody(responseFlagsApi)) + http.enqueue(MockResponse().setBody("")) + val sut = + getSut( + host = http.url("/").toString(), + bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("4535-funnel-bar-viz" to "variant-old")), + ) + + val results = LinkedBlockingQueue() + sut.loadFeatureFlags("my_identify", anonymousId = "anonId", emptyMap(), onFeatureFlags = { results.add(it) }) + assertEquals(true, results.poll(5, TimeUnit.SECONDS)!!.variants["4535-funnel-bar-viz"]) + + sut.loadFeatureFlags("my_identify", anonymousId = "anonId", emptyMap(), onFeatureFlags = { results.add(it) }) + + val reloaded = results.poll(5, TimeUnit.SECONDS)!! + assertTrue(reloaded.errorsLoading) + assertEquals(true, reloaded.variants["4535-funnel-bar-viz"]) + assertEquals(true, sut.getFeatureFlag("4535-funnel-bar-viz")) + } + @Test fun `a throwing internal callback does not suppress the caller's callback`() { val http = mockHttp(response = MockResponse().setBody(responseFlagsApi)) @@ -3075,8 +3246,8 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - internalOnFeatureFlags = PostHogOnFeatureFlags { throw IllegalStateException("internal blew up") }, - onFeatureFlags = PostHogOnFeatureFlags { userCallbackRan.countDown() }, + internalOnFeatureFlags = { throw IllegalStateException("internal blew up") }, + onFeatureFlags = PostHogFeatureFlagsCallback { userCallbackRan.countDown() }, ) assertTrue(userCallbackRan.await(5, TimeUnit.SECONDS), "the caller's callback was suppressed by the internal one") @@ -3114,7 +3285,7 @@ internal class PostHogRemoteConfigTest { "my_identify", anonymousId = "anonId", emptyMap(), - onFeatureFlags = PostHogOnFeatureFlags { latch.countDown() }, + onFeatureFlags = PostHogFeatureFlagsCallback { latch.countDown() }, ) assertTrue(latch.await(5, TimeUnit.SECONDS), "flags load should complete") http.shutdown() diff --git a/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt b/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt index b76f57c4e..ca61394fe 100644 --- a/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt +++ b/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt @@ -79,7 +79,7 @@ public class PostHogFake : PostHogInterface { ) { } - override fun reloadFeatureFlags(onFeatureFlags: PostHogOnFeatureFlags?) { + override fun reloadFeatureFlags(onFeatureFlags: PostHogFeatureFlagsCallback?) { } override fun isFeatureEnabled( From e6894bf5e21dad640b58576a3bce42f8038586fa Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 29 Oct 2026 17:15:50 -0400 Subject: [PATCH 06/49] feat: add an onFeatureFlags listener you can unsubscribe (#878) * feat: add an onFeatureFlags listener you can unsubscribe Registers a PostHogFeatureFlagsCallback that runs after every feature flags load, replays the current flags to late subscribers, and returns a PostHogFeatureFlagsSubscription, matching posthog-ios onFeatureFlags(_:). * fix: drop flag loads superseded by reset() or close() for listeners A load that started before reset() or close() could finish afterwards, reach listeners, and be replayed to late subscribers, including the previous user's flags after reset(). Each load now captures a generation that reset() and close() bump, and listener updates from an older generation are dropped. * fix: hydrate persisted flags before notifying onFeatureFlags listeners A failed first load built the listener snapshot before the flag cache was hydrated, so listeners and late replays got {} while the completion and getters returned the persisted flags. Hydrate before either callback runs. Co-Authored-By: Claude Opus 5.5 * fix: drop setup's flag load for listeners when the bootstrap callback closes the SDK Co-Authored-By: Claude Opus 5.5 * fix: deliver onFeatureFlags listeners on the main thread on Android Listeners usually update UI. On the remote config thread, a view update hits CalledFromWrongThreadException and LiveData.setValue throws, which the SDK catches, so the update is lost. This matches the on-feature-flags spec and posthog-ios. The config and reload callbacks keep running in the background. Co-Authored-By: Claude Opus 5.5 * fix: drop setup's flag load for listeners when an integration closes the SDK Capture the flags generation right after setup enables the SDK, before any user callout (integration install, session hooks, bootstrap config callback) that could close() it. Co-Authored-By: Claude Opus 5.5 * docs: scope onFeatureFlags threading notes by platform Co-Authored-By: Claude Opus 5.5 * fix: deliver bootstrapped flags to listeners before integrations install An integration that calls reloadFeatureFlags() during install queued its /flags request on the serial remote config executor ahead of setup's bootstrap notification, so onFeatureFlags listeners waited on the network even though bootstrapped flags were ready. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/android-v4-major.md | 1 + .../com/posthog/android/PostHogAndroid.kt | 3 + .../com/posthog/android/PostHogAndroidTest.kt | 19 ++ posthog/api/posthog.api | 18 +- posthog/src/main/java/com/posthog/PostHog.kt | 133 +++++++++++-- .../main/java/com/posthog/PostHogConfig.kt | 8 + .../posthog/PostHogFeatureFlagsCallback.kt | 13 +- .../PostHogFeatureFlagsSubscription.kt | 30 +++ .../main/java/com/posthog/PostHogInterface.kt | 30 +++ .../posthog/internal/PostHogRemoteConfig.kt | 23 ++- .../java/com/posthog/PostHogBootstrapTest.kt | 108 ++++++++++ .../com/posthog/PostHogFeatureFlagsTest.kt | 185 ++++++++++++++++++ .../src/test/java/com/posthog/PostHogTest.kt | 6 +- .../internal/PostHogRemoteConfigTest.kt | 2 +- .../java/com/posthog/PostHogFake.kt | 2 + 15 files changed, 543 insertions(+), 38 deletions(-) create mode 100644 posthog/src/main/java/com/posthog/PostHogFeatureFlagsSubscription.kt diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index fc2077550..b24de8f7e 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -12,3 +12,4 @@ - **Breaking:** make SDK-internal helpers in the `com.posthog.internal` and `com.posthog.android.replay.internal` packages non-public - **Breaking:** remove the deprecated `remoteConfig` config option; the SDK now always loads remote config at setup - **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `PostHogConfig.onFeatureFlags` and `reloadFeatureFlags()`; it receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values, and `errorsLoading` +- Add `onFeatureFlags()` to get notified after every feature flags load (on the main thread on Android), returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` diff --git a/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt b/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt index c6e845b6e..18c407822 100644 --- a/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt +++ b/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt @@ -35,6 +35,7 @@ import com.posthog.internal.PostHogSessionManager import com.posthog.internal.logIntegrationFailure import com.posthog.vendor.uuid.TimeBasedEpochGenerator import java.io.File +import java.util.concurrent.Executor /** * Main entry point for the Android SDK. @@ -236,6 +237,8 @@ public class PostHogAndroid private constructor() { config.sampleRateProvider = { config.sessionReplayConfig.sampleRate } val mainHandler = MainHandler() + // onFeatureFlags listeners usually update UI, so deliver them on the main thread + config.featureFlagsListenerExecutor = Executor { mainHandler.handler.post(it) } config.addIntegrationSafely("PostHogReplayIntegration") { PostHogReplayIntegration(context, config, mainHandler) } diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidTest.kt index 1f2e2de10..d92eae404 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidTest.kt @@ -2,6 +2,7 @@ package com.posthog.android import android.content.Context import android.content.Intent +import android.os.Looper import androidx.test.ext.junit.runners.AndroidJUnit4 import com.posthog.PostHog import com.posthog.android.errortracking.PostHogNativeCrashIntegration @@ -22,6 +23,7 @@ import org.junit.Rule import org.junit.rules.TemporaryFolder import org.junit.runner.RunWith import org.mockito.kotlin.mock +import org.robolectric.Shadows.shadowOf import kotlin.test.AfterTest import kotlin.test.BeforeTest import kotlin.test.Test @@ -145,6 +147,23 @@ internal class PostHogAndroidTest { assertTrue(config.context is PostHogAndroidContext) } + @Test + fun `runs feature flags listeners on the main thread`() { + val config = PostHogAndroidConfig(PROJECT_TOKEN) + + mockContextAppStart(context, tmpDir) + + PostHogAndroid.setup(context, config) + + var ranOn: Thread? = null + val worker = Thread { config.featureFlagsListenerExecutor!!.execute { ranOn = Thread.currentThread() } } + worker.start() + worker.join() + shadowOf(Looper.getMainLooper()).idle() + + assertSame(Looper.getMainLooper().thread, ranOn) + } + @Test fun `sets legacy storage path`() { val config = PostHogAndroidConfig(PROJECT_TOKEN) diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index c949a9dbd..fdf89f65f 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -48,6 +48,7 @@ public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posth public fun isOptOut ()Z public fun isSessionActive ()Z public fun isSessionReplayActive ()Z + public fun onFeatureFlags (Lcom/posthog/PostHogFeatureFlagsCallback;)Lcom/posthog/PostHogFeatureFlagsSubscription; public fun optIn ()V public fun optOut ()V public fun register (Ljava/lang/String;Ljava/lang/Object;)V @@ -96,6 +97,7 @@ public final class com/posthog/PostHog$Companion : com/posthog/PostHogInterface public fun isOptOut ()Z public fun isSessionActive ()Z public fun isSessionReplayActive ()Z + public fun onFeatureFlags (Lcom/posthog/PostHogFeatureFlagsCallback;)Lcom/posthog/PostHogFeatureFlagsSubscription; public fun optIn ()V public fun optOut ()V public final fun overrideSharedInstance (Lcom/posthog/PostHogInterface;)V @@ -172,6 +174,7 @@ public class com/posthog/PostHogConfig { public final fun getEvaluationContexts ()Ljava/util/List; public final fun getFeatureFlagCalledCacheSize ()I public final fun getFeatureFlagRequestMaxRetries ()I + public final fun getFeatureFlagsListenerExecutor ()Ljava/util/concurrent/Executor; public final fun getFlushAt ()I public final fun getFlushIntervalSeconds ()I public final fun getGetAnonymousId ()Lkotlin/jvm/functions/Function1; @@ -225,6 +228,7 @@ public class com/posthog/PostHogConfig { public final fun setEvaluationContexts (Ljava/util/List;)V public final fun setFeatureFlagCalledCacheSize (I)V public final fun setFeatureFlagRequestMaxRetries (I)V + public final fun setFeatureFlagsListenerExecutor (Ljava/util/concurrent/Executor;)V public final fun setFlushAt (I)V public final fun setFlushIntervalSeconds (I)V public final fun setGetAnonymousId (Lkotlin/jvm/functions/Function1;)V @@ -355,6 +359,11 @@ public final class com/posthog/PostHogFeatureFlagsLoaded { public final fun getVariants ()Ljava/util/Map; } +public final class com/posthog/PostHogFeatureFlagsSubscription { + public fun (Lkotlin/jvm/functions/Function0;)V + public final fun unsubscribe ()V +} + public abstract interface class com/posthog/PostHogIntegration { public fun install (Lcom/posthog/PostHogInterface;)V public fun onChange ()V @@ -405,6 +414,7 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public static synthetic fun isFeatureEnabled$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZLjava/lang/Boolean;ILjava/lang/Object;)Z public abstract fun isSessionActive ()Z public abstract fun isSessionReplayActive ()Z + public abstract fun onFeatureFlags (Lcom/posthog/PostHogFeatureFlagsCallback;)Lcom/posthog/PostHogFeatureFlagsSubscription; public abstract fun register (Ljava/lang/String;Ljava/lang/Object;)V public abstract fun registerPushNotificationToken (Ljava/lang/String;Ljava/lang/String;)V public abstract fun reloadFeatureFlags (Lcom/posthog/PostHogFeatureFlagsCallback;)V @@ -1049,10 +1059,10 @@ public final class com/posthog/internal/PostHogRemoteConfig : com/posthog/intern public fun isMinimalFlagCalledEventsEnabled ()Z public final fun isNativeCrashCaptureEnabled ()Z public final fun isSessionReplayFlagActive ()Z - public final fun loadFeatureFlags (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function0;Lcom/posthog/PostHogFeatureFlagsCallback;)V - public static synthetic fun loadFeatureFlags$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function0;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V - public final fun loadRemoteConfig (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function0;Lcom/posthog/PostHogFeatureFlagsCallback;)V - public static synthetic fun loadRemoteConfig$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function0;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V + public final fun loadFeatureFlags (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function1;Lcom/posthog/PostHogFeatureFlagsCallback;)V + public static synthetic fun loadFeatureFlags$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function1;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V + public final fun loadRemoteConfig (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function1;Lcom/posthog/PostHogFeatureFlagsCallback;)V + public static synthetic fun loadRemoteConfig$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function1;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V public final fun makeSamplingDecision (Ljava/lang/String;)Z public final fun persistPushConfigCache ()V public final fun resetGroupPropertiesForFlags (Ljava/lang/String;)V diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 63a8c0f65..6134a2108 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -34,6 +34,7 @@ import com.posthog.internal.PostHogSerializer import com.posthog.internal.PostHogSessionManager import com.posthog.internal.PostHogThreadFactory import com.posthog.internal.errortracking.PostHogExceptionStepsBuffer +import com.posthog.internal.executeSafely import com.posthog.internal.logIntegrationFailure import com.posthog.internal.personPropertiesContext import com.posthog.internal.replay.PostHogSessionReplayHandler @@ -46,6 +47,7 @@ import com.posthog.surveys.Survey import com.posthog.vendor.uuid.TimeBasedEpochGenerator import java.util.Date import java.util.UUID +import java.util.concurrent.CopyOnWriteArrayList import java.util.concurrent.ExecutorService import java.util.concurrent.Executors @@ -187,19 +189,90 @@ public class PostHog private constructor( private var isIdentifiedLoaded: Boolean = false private var isPersonProcessingLoaded: Boolean = false + // Public onFeatureFlags listeners. Owned by this instance rather than the remote config, so + // listeners registered before setup() (or across close()/setup()) keep receiving updates. + private val featureFlagsListeners = CopyOnWriteArrayList() + + // The last update delivered to listeners, replayed to late subscribers. Null until flags load, + // and cleared by reset() and close() so an update they superseded is dropped. + @Volatile + private var lastFeatureFlagsLoaded: PostHogFeatureFlagsLoaded? = null + + // Bumped by reset() and close(), so a flags load that started before them can't reach listeners. + @Volatile + private var featureFlagsGeneration = 0 + private val featureFlagsGenerationLock = Any() + + private class FeatureFlagsListener(val callback: PostHogFeatureFlagsCallback) { + @Volatile + var active = true + + // Only touched on the listener thread (see runFeatureFlagsListener), where every delivery and replay runs. + var lastDelivered: PostHogFeatureFlagsLoaded? = null + } + + // Runs on the remote config thread after every flags load, whether it succeeded or failed. + // Create it when the load starts, so listeners skip a load that reset() or close() superseded. + private fun internalOnFeatureFlagsLoaded(generation: Int = featureFlagsGeneration): (errorsLoading: Boolean) -> Unit { + return { errorsLoading -> + startSessionReplayOnFeatureFlagsLoaded() + notifyFeatureFlagsListeners(errorsLoading, generation) + } + } + + private fun clearFeatureFlagsLoaded() { + synchronized(featureFlagsGenerationLock) { + featureFlagsGeneration++ + lastFeatureFlagsLoaded = null + } + } + // this is called if the feature flags are loaded for the first time and recording isn't started yet - private val internalOnFeatureFlagsLoaded: () -> Unit = - { - // under setupLock so a concurrent optOut can't uninstall replay between the check and the start - synchronized(setupLock) { - sessionReplayHandler?.let { - if (isSessionReplayConfigEnabled()) { - // start will bail if session replay is already active anyway - startSessionReplayInternal(resumeCurrent = true) - } + private fun startSessionReplayOnFeatureFlagsLoaded() { + // under setupLock so a concurrent optOut can't uninstall replay between the check and the start + synchronized(setupLock) { + sessionReplayHandler?.let { + if (isSessionReplayConfigEnabled()) { + // start will bail if session replay is already active anyway + startSessionReplayInternal(resumeCurrent = true) } } } + } + + private fun notifyFeatureFlagsListeners( + errorsLoading: Boolean, + generation: Int, + ) { + val loaded = PostHogFeatureFlagsLoaded(remoteConfig?.getFeatureFlags() ?: emptyMap(), errorsLoading) + synchronized(featureFlagsGenerationLock) { + if (featureFlagsGeneration != generation) return + lastFeatureFlagsLoaded = loaded + } + featureFlagsListeners.forEach { listener -> runFeatureFlagsListener { deliverFeatureFlags(listener, loaded) } } + } + + // Called on the remote config thread. Hands the block to the platform's listener executor (the main + // thread on Android), or runs it right away when there's none. + private fun runFeatureFlagsListener(block: () -> Unit) { + val executor = config?.featureFlagsListenerExecutor ?: return block() + executor.executeSafely(block) + } + + private fun deliverFeatureFlags( + listener: FeatureFlagsListener, + loaded: PostHogFeatureFlagsLoaded, + ) { + // An earlier callback may have unsubscribed this one, or reset()/close() or a newer load + // may have superseded this update. A replay queued next to the same update is skipped too. + if (!listener.active || lastFeatureFlagsLoaded !== loaded || listener.lastDelivered === loaded) return + listener.lastDelivered = loaded + try { + listener.callback.loaded(loaded) + } catch (e: Throwable) { + config?.logger?.log("Executing the feature flags listener failed: $e") + } + } public override fun setup(config: T) { synchronized(setupLock) { @@ -357,6 +430,16 @@ public class PostHog private constructor( super.enabled = true + // Captured before any user callout below (integrations, session hooks, the bootstrap + // config callback), any of which may close() and so supersede setup's flags load. + val generation = featureFlagsGeneration + + // Queued before integrations install, so a reload one starts there can't hold the + // bootstrapped flags behind its network response. Listeners run on the remote config thread. + if (reloadFeatureFlags && remoteConfig?.hasBootstrapFlags() == true) { + remoteConfigExecutor.executeSafely { notifyFeatureFlagsListeners(errorsLoading = false, generation) } + } + // Initialize device_id if not already set. getDeviceId() handles lazy init // by seeding from the anonymous ID, providing a stable identifier for // device-level feature flag bucketing that survives identify() and reset(). @@ -398,14 +481,14 @@ public class PostHog private constructor( // callbacks now so listeners aren't blocked on the first network response. if (remoteConfig?.hasBootstrapFlags() == true) { try { - internalOnFeatureFlagsLoaded() + startSessionReplayOnFeatureFlagsLoaded() } catch (e: Throwable) { config.logger.log("Executing the internal feature flags callback failed: $e") } notifyFeatureFlagsCallback(config.onFeatureFlags, remoteConfig?.getFeatureFlags(), errorsLoading = false) } loadRemoteConfigRequest( - internalOnFeatureFlagsLoaded, + internalOnFeatureFlagsLoaded(generation), config.onFeatureFlags, ) } @@ -631,6 +714,7 @@ public class PostHog private constructor( pushSubscriptionManager = null featureFlagsCalled.clear() + clearFeatureFlagsLoaded() lastScreenName = null synchronized(replayDebugPropertiesLock) { lastReplayDebugPropertiesAt = null @@ -1938,13 +2022,30 @@ public class PostHog private constructor( return } loadFeatureFlagsRequest( - internalOnFeatureFlags = internalOnFeatureFlagsLoaded, + internalOnFeatureFlags = internalOnFeatureFlagsLoaded(), onFeatureFlags = onFeatureFlags, ) } + public override fun onFeatureFlags(callback: PostHogFeatureFlagsCallback): PostHogFeatureFlagsSubscription { + val listener = FeatureFlagsListener(callback) + featureFlagsListeners.add(listener) + + remoteConfigExecutor.executeSafely { + runFeatureFlagsListener { + // Read at delivery time so a delivery already queued can't be followed by an older value. + lastFeatureFlagsLoaded?.let { deliverFeatureFlags(listener, it) } + } + } + + return PostHogFeatureFlagsSubscription { + listener.active = false + featureFlagsListeners.remove(listener) + } + } + private fun loadFeatureFlagsRequest( - internalOnFeatureFlags: () -> Unit, + internalOnFeatureFlags: (errorsLoading: Boolean) -> Unit, onFeatureFlags: PostHogFeatureFlagsCallback? = null, ) { @Suppress("UNCHECKED_CAST") @@ -1974,7 +2075,7 @@ public class PostHog private constructor( } private fun loadRemoteConfigRequest( - internalOnFeatureFlags: (() -> Unit)?, + internalOnFeatureFlags: ((errorsLoading: Boolean) -> Unit)?, onFeatureFlags: PostHogFeatureFlagsCallback?, ) { @Suppress("UNCHECKED_CAST") @@ -2231,6 +2332,7 @@ public class PostHog private constructor( getPreferences().clear(except = except.toList()) } remoteConfig?.clear() + clearFeatureFlagsLoaded() featureFlagsCalled.clear() lastScreenName = null synchronized(cachedPersonPropertiesLock) { @@ -2717,6 +2819,9 @@ public class PostHog private constructor( shared.reloadFeatureFlags(onFeatureFlags) } + public override fun onFeatureFlags(callback: PostHogFeatureFlagsCallback): PostHogFeatureFlagsSubscription = + shared.onFeatureFlags(callback) + public override fun isFeatureEnabled( key: String, defaultValue: Boolean, diff --git a/posthog/src/main/java/com/posthog/PostHogConfig.kt b/posthog/src/main/java/com/posthog/PostHogConfig.kt index ee45ad3c4..f36d38c38 100644 --- a/posthog/src/main/java/com/posthog/PostHogConfig.kt +++ b/posthog/src/main/java/com/posthog/PostHogConfig.kt @@ -24,6 +24,7 @@ import com.posthog.surveys.PostHogSurveysConfig import okhttp3.OkHttpClient import java.net.Proxy import java.util.UUID +import java.util.concurrent.Executor import java.util.concurrent.ExecutorService /** @@ -490,6 +491,13 @@ public open class PostHogConfig( @PostHogInternal public var sampleRateProvider: (() -> Double?)? = null + /** + * Runs the [PostHog.onFeatureFlags] listeners. Set by platform-specific modules (e.g., Android) + * to deliver them on the main thread. When null, they run on the SDK's remote config thread. + */ + @PostHogInternal + public var featureFlagsListenerExecutor: Executor? = null + /** * Reference to the PostHogRemoteConfig instance, set during setup. * Used by integrations to check remote config values. diff --git a/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt index 2252f392a..355b9714f 100644 --- a/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt +++ b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt @@ -3,10 +3,15 @@ package com.posthog /** * Callback invoked when a feature flags load finishes, whether it succeeded or failed. * - * It's used by `PostHogConfig.onFeatureFlags` and `reloadFeatureFlags`. It runs on a background - * thread, or right away on the calling thread when no load is attempted (for example, the SDK is - * disabled). With bootstrapped flags, `PostHogConfig.onFeatureFlags` also runs once on the thread - * calling `setup()`, before the first load finishes. Hop to the main thread before touching UI. + * It's used by `PostHogConfig.onFeatureFlags`, `reloadFeatureFlags` and `onFeatureFlags`. + * + * For `PostHogConfig.onFeatureFlags` and `reloadFeatureFlags`, it runs on a background thread, or right + * away on the calling thread when no load is attempted (for example, the SDK is disabled). With + * bootstrapped flags, `PostHogConfig.onFeatureFlags` also runs once on the thread calling `setup()`, + * before the first load finishes. Hop to the main thread before touching UI. + * + * For `onFeatureFlags`, it runs on the main thread on Android, and on the SDK's background remote + * config thread on the JVM. * * Example: * ```kotlin diff --git a/posthog/src/main/java/com/posthog/PostHogFeatureFlagsSubscription.kt b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsSubscription.kt new file mode 100644 index 000000000..32aa85ec9 --- /dev/null +++ b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsSubscription.kt @@ -0,0 +1,30 @@ +package com.posthog + +/** + * A registration returned by `onFeatureFlags`. + * + * The callback stays registered until you call [unsubscribe]. You don't need to keep a reference + * to this object unless you want to unsubscribe later. + * + * Example: + * ```kotlin + * val subscription = PostHog.onFeatureFlags { loaded -> + * // React to the new flags + * } + * + * // Later, stop listening + * subscription.unsubscribe() + * ``` + */ +public class PostHogFeatureFlagsSubscription + @PostHogInternal + public constructor( + private val onUnsubscribe: () -> Unit, + ) { + /** + * Stops the callback from being invoked. Calling it more than once has no effect. + */ + public fun unsubscribe() { + onUnsubscribe() + } + } diff --git a/posthog/src/main/java/com/posthog/PostHogInterface.kt b/posthog/src/main/java/com/posthog/PostHogInterface.kt index e56fbf98b..cf0dd630f 100644 --- a/posthog/src/main/java/com/posthog/PostHogInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogInterface.kt @@ -141,6 +141,36 @@ public interface PostHogInterface : PostHogCoreInterface { */ public fun reloadFeatureFlags(onFeatureFlags: PostHogFeatureFlagsCallback? = null) + /** + * Registers a callback that's invoked whenever feature flags are loaded or updated. + * + * On Android, the callback runs on the main thread, after the getters already return the new + * values. On the JVM, it runs on the SDK's background remote config thread. It's + * invoked after the SDK loads flags at startup (including from bootstrap values), after + * [reloadFeatureFlags], and after calls that reload flags such as [identify], [group] or [reset]. + * If a load fails, [PostHogFeatureFlagsLoaded.errorsLoading] is `true` and the values are the last + * known flags. If flags have already loaded when you register, it's also invoked with the current + * values shortly afterwards. + * + * You can register before `setup()`, and the callback stays registered across `close()` and + * `setup()`. Treat each invocation as "flags may have changed", not as an exactly-once event. + * + * ```kotlin + * val subscription = PostHog.onFeatureFlags { loaded -> + * if (loaded.variants["new-checkout"] == "test") { + * // Show the test variant + * } + * } + * + * // Later, stop listening + * subscription.unsubscribe() + * ``` + * + * @param callback receives the enabled flags, their values, and whether loading failed + * @return a subscription; call [PostHogFeatureFlagsSubscription.unsubscribe] to stop receiving updates + */ + public fun onFeatureFlags(callback: PostHogFeatureFlagsCallback): PostHogFeatureFlagsSubscription + /** * Returns if a feature flag is enabled, the feature flag must be a Boolean * Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments diff --git a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt index c1091864a..f9bec33c9 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt @@ -64,7 +64,7 @@ public class PostHogRemoteConfig( val distinctId: String, val anonymousId: String?, val groups: Map?, - val internalOnFeatureFlags: List<() -> Unit>, + val internalOnFeatureFlags: List<(errorsLoading: Boolean) -> Unit>, val onFeatureFlags: List, ) @@ -257,13 +257,11 @@ public class PostHogRemoteConfig( } @JvmName("asSingleInternalCallback") - private fun List<() -> Unit>.asSingleCallback(): (() -> Unit)? = + private fun List<(errorsLoading: Boolean) -> Unit>.asSingleCallback(): ((errorsLoading: Boolean) -> Unit)? = when (size) { 0 -> null 1 -> first() - else -> { - { forEach { runSafely(it) } } - } + else -> { errorsLoading -> forEach { runSafely { it(errorsLoading) } } } } private fun List.asSingleCallback(): PostHogFeatureFlagsCallback? = @@ -286,17 +284,18 @@ public class PostHogRemoteConfig( } private fun runOnFeatureFlagsCallbacks( - internalOnFeatureFlags: (() -> Unit)?, + internalOnFeatureFlags: ((errorsLoading: Boolean) -> Unit)?, onFeatureFlags: PostHogFeatureFlagsCallback?, errorsLoading: Boolean, ) { // if we don't load the feature flags (because there are none), we need to call the callback // because the app might be waiting for it. - internalOnFeatureFlags?.let { runSafely(it) } + if (internalOnFeatureFlags == null && onFeatureFlags == null) return + // a failed first load still reports the persisted flags, so hydrate them before either callback + runSafely { loadFeatureFlagsFromCacheIfNeeded() } + internalOnFeatureFlags?.let { runSafely { it(errorsLoading) } } onFeatureFlags?.let { callback -> runSafely { - // a failed first load still reports the persisted flags, so hydrate them first - loadFeatureFlagsFromCacheIfNeeded() callback.loaded(PostHogFeatureFlagsLoaded(getFeatureFlags() ?: emptyMap(), errorsLoading)) } } @@ -317,7 +316,7 @@ public class PostHogRemoteConfig( distinctId: String, anonymousId: String?, groups: Map?, - internalOnFeatureFlags: (() -> Unit)? = null, + internalOnFeatureFlags: ((errorsLoading: Boolean) -> Unit)? = null, onFeatureFlags: PostHogFeatureFlagsCallback? = null, ) { executor.executeSafely { @@ -858,7 +857,7 @@ public class PostHogRemoteConfig( distinctId: String, anonymousId: String?, groups: Map?, - internalOnFeatureFlags: (() -> Unit)?, + internalOnFeatureFlags: ((errorsLoading: Boolean) -> Unit)?, onFeatureFlags: PostHogFeatureFlagsCallback?, notifyRemoteConfigLoaded: Boolean = true, ) { @@ -1121,7 +1120,7 @@ public class PostHogRemoteConfig( distinctId: String, anonymousId: String?, groups: Map?, - internalOnFeatureFlags: (() -> Unit)? = null, + internalOnFeatureFlags: ((errorsLoading: Boolean) -> Unit)? = null, onFeatureFlags: PostHogFeatureFlagsCallback? = null, ) { executor.executeSafely { diff --git a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt index 19903d96a..8fb56afdd 100644 --- a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt @@ -7,16 +7,25 @@ import com.posthog.internal.PostHogPreferences.Companion.DISTINCT_ID import com.posthog.internal.PostHogPreferences.Companion.IS_IDENTIFIED import com.posthog.internal.PostHogSerializer import com.posthog.internal.PostHogThreadFactory +import okhttp3.mockwebserver.Dispatcher import okhttp3.mockwebserver.MockResponse +import okhttp3.mockwebserver.MockWebServer +import okhttp3.mockwebserver.RecordedRequest import org.junit.Rule import org.junit.rules.TemporaryFolder import java.io.File +import java.util.concurrent.CountDownLatch import java.util.concurrent.Executors +import java.util.concurrent.LinkedBlockingQueue +import java.util.concurrent.TimeUnit +import java.util.concurrent.atomic.AtomicBoolean import kotlin.test.AfterTest import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertFalse import kotlin.test.assertNotEquals +import kotlin.test.assertNotNull +import kotlin.test.assertNull import kotlin.test.assertTrue internal class PostHogBootstrapTest { @@ -382,6 +391,105 @@ internal class PostHogBootstrapTest { sut.close() } + @Test + fun `onFeatureFlags replays bootstrapped flags to a listener registered after setup`() { + val sut = + getSut( + host = "http://127.0.0.1:1", + // the replay comes from setup's flag loading, before /config answers + reloadFeatureFlags = true, + bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("beta-ui" to true)), + ) + + val updates = LinkedBlockingQueue() + sut.onFeatureFlags { updates.add(it) } + + // setup's load to the unreachable host may already have failed, which keeps the bootstrapped flags + val loaded = updates.poll(5, TimeUnit.SECONDS)!! + assertEquals(mapOf("beta-ui" to true), loaded.variants) + + sut.close() + } + + @Test + fun `onFeatureFlags delivers bootstrapped flags before a reload an integration starts`() { + val release = CountDownLatch(1) + val http = MockWebServer() + http.dispatcher = + object : Dispatcher() { + override fun dispatch(request: RecordedRequest): MockResponse { + if (request.path!!.contains("/flags")) { + release.await(10, TimeUnit.SECONDS) + return MockResponse().setBody("""{"featureFlags":{"beta-ui":false}}""") + } + return MockResponse().setBody("""{"hasFeatureFlags":true}""") + } + } + http.start() + val config = + PostHogConfig(PROJECT_TOKEN, http.url("/").toString()).apply { + storagePrefix = tmpDir.newFolder().absolutePath + cachePreferences = PostHogMemoryPreferences() + bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("beta-ui" to true)) + addIntegration( + object : PostHogIntegration { + override fun install(postHog: PostHogInterface) { + postHog.reloadFeatureFlags() + } + }, + ) + } + val updates = LinkedBlockingQueue() + val subscription = PostHog.onFeatureFlags { updates.add(it) } + + try { + PostHog.setup(config) + + // the integration's /flags request is held, so this can only be the bootstrap delivery + val loaded = updates.poll(5, TimeUnit.SECONDS) + assertEquals(mapOf("beta-ui" to true), loaded?.variants) + } finally { + subscription.unsubscribe() + release.countDown() + PostHog.close() + http.shutdown() + } + } + + @Test + fun `closing from the bootstrap flags callback drops setup's load for listeners`() { + val http = mockHttp(total = 5, response = MockResponse().setBody("""{"hasFeatureFlags":false}""")) + val completed = LinkedBlockingQueue() + val first = AtomicBoolean(true) + val config = + PostHogConfig(PROJECT_TOKEN, http.url("/").toString()).apply { + storagePrefix = tmpDir.newFolder().absolutePath + cachePreferences = PostHogMemoryPreferences() + bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("beta-ui" to true)) + onFeatureFlags = + PostHogFeatureFlagsCallback { + // the bootstrap delivery closes the SDK; setup's own load completes later + if (first.compareAndSet(true, false)) PostHog.close() else completed.add(it) + } + } + + try { + PostHog.setup(config) + + // setup's load notifies listeners just before this completion + assertNotNull(completed.poll(5, TimeUnit.SECONDS)) + + // close() cleared the snapshot, so only a load it superseded could refill it + val updates = LinkedBlockingQueue() + val subscription = PostHog.onFeatureFlags { updates.add(it) } + assertNull(updates.poll(500, TimeUnit.MILLISECONDS)) + subscription.unsubscribe() + } finally { + PostHog.close() + http.shutdown() + } + } + @Test fun `minimal flag called event strips bootstrap fields even though this SDK sets them`() { // fixture returns minimalFlagCalledEvents: true and IAmInactive with has_experiment: false; diff --git a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt index 399c7ee79..8c02709ce 100644 --- a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt @@ -9,11 +9,17 @@ import okhttp3.mockwebserver.MockResponse import org.junit.Rule import org.junit.rules.TemporaryFolder import java.io.File +import java.util.concurrent.CountDownLatch +import java.util.concurrent.Executor import java.util.concurrent.Executors +import java.util.concurrent.LinkedBlockingQueue +import java.util.concurrent.TimeUnit import kotlin.test.AfterTest import kotlin.test.Test import kotlin.test.assertEquals +import kotlin.test.assertFalse import kotlin.test.assertNotEquals +import kotlin.test.assertNull import kotlin.test.assertTrue internal class PostHogFeatureFlagsTest { @@ -57,6 +63,7 @@ internal class PostHogFeatureFlagsTest { beforeSend: PostHogBeforeSend? = null, evaluationContexts: List? = null, context: PostHogContext? = null, + featureFlagsListenerExecutor: Executor? = null, ): PostHogInterface { config = PostHogConfig(PROJECT_TOKEN, host).apply { @@ -78,6 +85,7 @@ internal class PostHogFeatureFlagsTest { } this.errorTrackingConfig.inAppIncludes.add("com.posthog") this.context = context + this.featureFlagsListenerExecutor = featureFlagsListenerExecutor } return PostHog.withInternal( config, @@ -401,4 +409,181 @@ internal class PostHogFeatureFlagsTest { assertTrue(result!!.flags.isEmpty()) assertTrue(result!!.variants.isEmpty()) } + + @Test + fun `onFeatureFlags listener receives each load until unsubscribed`() { + val flags = File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText() + val http = mockHttp(response = MockResponse().setBody(flags)) + http.enqueue(MockResponse().setResponseCode(500)) + http.enqueue(MockResponse().setBody(flags)) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false) + val enabled = mapOf("4535-funnel-bar-viz" to true, "splashScreenName" to "SplashV2") + + val updates = LinkedBlockingQueue() + val subscription = sut.onFeatureFlags { updates.add(it) } + + sut.reloadFeatureFlags() + val loaded = updates.poll(5, TimeUnit.SECONDS)!! + assertEquals(enabled, loaded.variants) + assertFalse(loaded.errorsLoading) + + sut.reloadFeatureFlags() + val failed = updates.poll(5, TimeUnit.SECONDS)!! + assertEquals(enabled, failed.variants) + assertTrue(failed.errorsLoading) + + subscription.unsubscribe() + val reloaded = CountDownLatch(1) + sut.reloadFeatureFlags { reloaded.countDown() } + assertTrue(reloaded.await(5, TimeUnit.SECONDS)) + assertNull(updates.poll()) + } + + @Test + fun `onFeatureFlags reports and replays the persisted flags when the first load fails`() { + val persisted = mapOf("beta-ui" to true) + val cache = PostHogMemoryPreferences().apply { setValue("featureFlags", persisted) } + val http = mockHttp(response = MockResponse().setResponseCode(500)) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false, cachePreferences = cache) + + val updates = LinkedBlockingQueue() + sut.onFeatureFlags { updates.add(it) } + sut.reloadFeatureFlags() + + val failed = updates.poll(5, TimeUnit.SECONDS)!! + assertTrue(failed.errorsLoading) + assertEquals(persisted, failed.variants) + + val lateUpdates = LinkedBlockingQueue() + sut.onFeatureFlags { lateUpdates.add(it) } + assertEquals(persisted, lateUpdates.poll(5, TimeUnit.SECONDS)!!.variants) + } + + @Test + fun `onFeatureFlags replays loaded flags to a late listener`() { + val flags = File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText() + val http = mockHttp(response = MockResponse().setBody(flags)) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false) + val reloaded = CountDownLatch(1) + sut.reloadFeatureFlags { reloaded.countDown() } + assertTrue(reloaded.await(5, TimeUnit.SECONDS)) + + val updates = LinkedBlockingQueue() + sut.onFeatureFlags { updates.add(it) } + + assertEquals(setOf("4535-funnel-bar-viz", "splashScreenName"), updates.poll(5, TimeUnit.SECONDS)!!.flags.toSet()) + } + + @Test + fun `onFeatureFlags listener survives close and setup`() { + val flags = File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText() + val http = mockHttp(response = MockResponse().setBody(flags)) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false) + val updates = LinkedBlockingQueue() + sut.onFeatureFlags { updates.add(it) } + + sut.close() + sut.setup(config) + sut.reloadFeatureFlags() + + assertFalse(updates.poll(5, TimeUnit.SECONDS)!!.errorsLoading) + } + + @Test + fun `onFeatureFlags drops a load that finishes after close`() { + val flags = File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText() + val http = mockHttp(response = MockResponse().setBody(flags).setHeadersDelay(500, TimeUnit.MILLISECONDS)) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false) + val updates = LinkedBlockingQueue() + sut.onFeatureFlags { updates.add(it) } + val reloaded = CountDownLatch(1) + sut.reloadFeatureFlags { reloaded.countDown() } + http.takeRequest(5, TimeUnit.SECONDS) + + sut.close() + assertTrue(reloaded.await(5, TimeUnit.SECONDS)) + sut.setup(config) + sut.onFeatureFlags { updates.add(it) } + + remoteConfigExecutor.submit {}.get(5, TimeUnit.SECONDS) + assertNull(updates.poll()) + } + + @Test + fun `closing from an integration's install drops setup's load for listeners`() { + val flags = File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText() + val http = mockHttp(total = 2, response = MockResponse().setBody(flags)) + val updates = LinkedBlockingQueue() + val integration = + object : PostHogIntegration { + override fun install(postHog: PostHogInterface) { + postHog.onFeatureFlags { updates.add(it) } + postHog.close() + } + } + val sut = getSut(http.url("/").toString(), integration = integration) + + // setup's load runs on the remote config thread; close() cleared the snapshot it would refill + remoteConfigExecutor.submit {}.get(5, TimeUnit.SECONDS) + sut.onFeatureFlags { updates.add(it) } + remoteConfigExecutor.submit {}.get(5, TimeUnit.SECONDS) + assertNull(updates.poll()) + } + + @Test + fun `onFeatureFlags listener is not invoked by a reload while disabled`() { + val sut = getSut(mockHttp().url("/").toString(), preloadFeatureFlags = false) + val updates = LinkedBlockingQueue() + sut.onFeatureFlags { updates.add(it) } + sut.close() + + var result: PostHogFeatureFlagsLoaded? = null + sut.reloadFeatureFlags { result = it } + + remoteConfigExecutor.submit {}.get(5, TimeUnit.SECONDS) + assertTrue(result!!.errorsLoading) + assertNull(updates.poll()) + } + + @Test + fun `onFeatureFlags listeners run on the listener executor`() { + val flags = File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText() + val http = mockHttp(response = MockResponse().setBody(flags)) + val listenerExecutor = Executors.newSingleThreadExecutor { Thread(it, "listener-thread") } + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false, featureFlagsListenerExecutor = listenerExecutor) + + val threads = LinkedBlockingQueue() + sut.onFeatureFlags { threads.add(Thread.currentThread().name) } + sut.reloadFeatureFlags() + assertEquals("listener-thread", threads.poll(5, TimeUnit.SECONDS)) + + sut.onFeatureFlags { threads.add(Thread.currentThread().name) } + assertEquals("listener-thread", threads.poll(5, TimeUnit.SECONDS)) + listenerExecutor.shutdownAndAwaitTermination() + } + + @Test + fun `onFeatureFlags delivers a queued update once and drops it after unsubscribe`() { + val flags = File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText() + val http = mockHttp(response = MockResponse().setBody(flags)) + val queued = LinkedBlockingQueue() + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false, featureFlagsListenerExecutor = Executor { queued.add(it) }) + + val kept = LinkedBlockingQueue() + val dropped = LinkedBlockingQueue() + sut.onFeatureFlags { kept.add(it) } + val subscription = sut.onFeatureFlags { dropped.add(it) } + val reloaded = CountDownLatch(1) + sut.reloadFeatureFlags { reloaded.countDown() } + assertTrue(reloaded.await(5, TimeUnit.SECONDS)) + remoteConfigExecutor.submit {}.get(5, TimeUnit.SECONDS) + + // Each listener has its replay and the load's delivery queued, both carrying the loaded flags. + subscription.unsubscribe() + generateSequence { queued.poll() }.forEach { it.run() } + + assertEquals(1, kept.size) + assertFalse(kept.single().errorsLoading) + assertTrue(dropped.isEmpty()) + } } diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index 0288881f1..ddb08ed2d 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -1500,9 +1500,9 @@ internal class PostHogTest { config.sessionReplay = true @Suppress("UNCHECKED_CAST") val onFlagsLoaded = - PostHog::class.java.getDeclaredField("internalOnFeatureFlagsLoaded") + PostHog::class.java.getDeclaredMethod("internalOnFeatureFlagsLoaded", Int::class.javaPrimitiveType) .apply { isAccessible = true } - .get(sut) as () -> Unit + .invoke(sut, 0) as (Boolean) -> Unit // optOut runs while the flags-loaded callback is between reading the handler and starting it var optOut: Thread? = null @@ -1516,7 +1516,7 @@ internal class PostHogTest { } } } - onFlagsLoaded() + onFlagsLoaded(false) optOut!!.join() assertTrue(sut.isOptOut()) diff --git a/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt index c242f2ecb..34fcdcd62 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt @@ -924,7 +924,7 @@ internal class PostHogRemoteConfigTest { called = true } - val internalOnFeatureFlags = { + val internalOnFeatureFlags = { _: Boolean -> calledInternal = true } diff --git a/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt b/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt index ca61394fe..dd5f42273 100644 --- a/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt +++ b/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt @@ -82,6 +82,8 @@ public class PostHogFake : PostHogInterface { override fun reloadFeatureFlags(onFeatureFlags: PostHogFeatureFlagsCallback?) { } + override fun onFeatureFlags(callback: PostHogFeatureFlagsCallback): PostHogFeatureFlagsSubscription = PostHogFeatureFlagsSubscription {} + override fun isFeatureEnabled( key: String, defaultValue: Boolean, From 0adff2a91521658a970cc01dc9d95be728acbfb9 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 13:31:12 -0400 Subject: [PATCH 07/49] chore: remove changeset for already released beforeSend fix The fix shipped from main in #885, so keeping the changeset here would release the same entry a second time. Co-Authored-By: Claude Opus 5.5 --- .changeset/before-send-once.md | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 .changeset/before-send-once.md diff --git a/.changeset/before-send-once.md b/.changeset/before-send-once.md deleted file mode 100644 index a64308f68..000000000 --- a/.changeset/before-send-once.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -'posthog': patch -'posthog-android': patch ---- - -Fix `beforeSend` running twice for each captured event, which discarded the hook's changes to `distinctId`, `timestamp` and `uuid` and compounded random sampling From 0e7e28a12862325bd3faf53a098ae90be8a31367 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 18:51:37 -0400 Subject: [PATCH 08/49] docs: consolidate 4.0 changeset and migration guide --- .changeset/android-v4-major.md | 9 +- .changeset/server-keep-on-feature-flags.md | 3 +- README.md | 1 + docs/migration-3.x-to-4.0.md | 251 +++++++++++++++++++++ 4 files changed, 260 insertions(+), 4 deletions(-) create mode 100644 docs/migration-3.x-to-4.0.md diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index b24de8f7e..163e47135 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -1,15 +1,18 @@ --- 'posthog': major 'posthog-android': major +'posthog-android-surveys-compose': minor --- - **Breaking:** remove the deprecated `apiKey` property and the `PostHogConfig(apiKey = …)` and `PostHogAndroidConfig(apiKey = …)` factories; use `projectToken` instead - **Breaking:** remove the deprecated `propertiesSanitizer` config option and the `PostHogPropertiesSanitizer` interface; use `addBeforeSend` instead - **Breaking:** remove the deprecated `evaluationEnvironments` config option; use `evaluationContexts` instead -- **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key)?.payload` instead +- **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload` instead to keep not sending `$feature_flag_called` - **Breaking:** remove the deprecated `PostHogSessionReplayConfig.debouncerDelayMs`; use `throttleDelayMs` instead -- **Breaking:** return `null` instead of the raw string for a malformed, empty or whitespace-only feature flag payload from `getFeatureFlagResult(key)?.payload`; payloads must be valid JSON (a JSON `null` payload now also reads as `null` instead of the string `"null"`) -- **Breaking:** make SDK-internal helpers in the `com.posthog.internal` and `com.posthog.android.replay.internal` packages non-public +- **Breaking:** return `null` instead of the raw string for a malformed, empty, whitespace-only or lenient-only (unquoted or single-quoted) feature flag payload from `getFeatureFlagResult(key)?.payload`; payloads must be valid JSON (a JSON `null` payload now also reads as `null` instead of the string `"null"`) +- **Breaking:** make SDK-internal helpers in the `com.posthog.internal`, `com.posthog.android.internal` and `com.posthog.android.replay.internal` packages non-public - **Breaking:** remove the deprecated `remoteConfig` config option; the SDK now always loads remote config at setup - **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `PostHogConfig.onFeatureFlags` and `reloadFeatureFlags()`; it receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values, and `errorsLoading` +- **Breaking:** add the abstract `onFeatureFlags()` method to `PostHogInterface`; classes that implement it must add the method - Add `onFeatureFlags()` to get notified after every feature flags load (on the main thread on Android), returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` +- See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md) for upgrade steps diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md index ca5fb7278..c39f151bb 100644 --- a/.changeset/server-keep-on-feature-flags.md +++ b/.changeset/server-keep-on-feature-flags.md @@ -2,4 +2,5 @@ 'posthog-server': minor --- -Move `PostHogOnFeatureFlags` into `posthog-server`; its API is unchanged +- Move `PostHogOnFeatureFlags` into `posthog-server`; its API is unchanged +- Bump the `posthog` core dependency to 7.0 diff --git a/README.md b/README.md index 82960687e..cdcbfa1eb 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ SDK usage examples and code snippets live in the official documentation so they - [Android library docs](https://posthog.com/docs/libraries/android) - [Java/JVM library docs](https://posthog.com/docs/libraries/java) +- [Migrating from 3.x to 4.0](docs/migration-3.x-to-4.0.md) ## Required dependencies diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md new file mode 100644 index 000000000..8b8acbb4c --- /dev/null +++ b/docs/migration-3.x-to-4.0.md @@ -0,0 +1,251 @@ +# Migrating from PostHog Android 3.x to 4.0 + +4.0 removes APIs deprecated in 3.x and changes the feature flags callback. +Most changes are compile errors with a direct replacement. Read [Behavior changes](#behavior-changes) carefully: those won't show up at build time. + +For the full list of changes, see the [changelog](../posthog-android/CHANGELOG.md). + +## Requirements and versions + +| Artifact | Upgrade | +| --- | --- | +| `com.posthog:posthog-android` | 3.x to 4.0 | +| `com.posthog:posthog` (core) | 6.x to 7.0 | +| `com.posthog:posthog-android-surveys-compose` | the release that depends on `posthog-android` 4.0 | +| `com.posthog:posthog-server` | see [`posthog-server`](#posthog-server) | + +These are unchanged, so you don't need to change your build for them: + +- Android minimum API level: 23 +- Java bytecode target: Java 8 +- Kotlin language and API compatibility: 2.0 +- `posthog-android-gradle-plugin` + +Upgrade PostHog artifacts together. Core 7.0 is not binary compatible with SDK versions built against core 6.x, and a mismatch fails at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. + +## Removed APIs + +All of these are compile errors. Calling them from an already-compiled library that you haven't updated fails at runtime. + +| Removed | Use instead | +| --- | --- | +| `PostHogConfig.apiKey`, `PostHogConfig(apiKey = …)`, `PostHogAndroidConfig(apiKey = …)` | `projectToken` | +| `PostHogConfig.propertiesSanitizer`, `PostHogPropertiesSanitizer` | `addBeforeSend` | +| `PostHogConfig.evaluationEnvironments` | `evaluationContexts` | +| `getFeatureFlagPayload()`, on the instance and on `PostHog` | `getFeatureFlagResult()` | +| `PostHogSessionReplayConfig.debouncerDelayMs` | `throttleDelayMs` | +| `PostHogConfig.remoteConfig` | nothing; remote config always loads | +| `PostHogOnFeatureFlags` | `PostHogFeatureFlagsCallback` | + +The constructor parameters of `PostHogConfig` and `PostHogSessionReplayConfig` move up where these were removed. If you pass arguments by position, check them, or switch to named arguments. + +### `apiKey` + +```kotlin +// 3.x +val config = PostHogAndroidConfig(apiKey = "phc_your_project_token") +val token = config.apiKey + +// 4.0 +val config = PostHogAndroidConfig(projectToken = "phc_your_project_token") +val token = config.projectToken +``` + +`PostHogAndroidConfig("phc_your_project_token")`, with no parameter name, still works. From Java, replace `getApiKey()` with `getProjectToken()`. + +### `propertiesSanitizer` + +```kotlin +// 3.x +config.propertiesSanitizer = PostHogPropertiesSanitizer { properties -> + properties.apply { remove("email") } +} + +// 4.0 +config.addBeforeSend { event -> + event.properties?.remove("email") + event +} +``` + +`addBeforeSend` gets the whole `PostHogEvent`. Return `null` to drop the event. If the hook throws, the event is dropped. + +### `evaluationEnvironments` + +```kotlin +// 3.x +config.evaluationEnvironments = listOf("production") + +// 4.0 +config.evaluationContexts = listOf("production") +``` + +### `getFeatureFlagPayload()` + +`getFeatureFlagPayload()` never sent `$feature_flag_called`. `getFeatureFlagResult()` sends it by default, following `sendFeatureFlagEvent`, so pass `sendFeatureFlagEvent = false` to keep your event volume and experiment exposures unchanged. If you drop that argument, nothing fails, but you'll send new events. + +The new call has no `defaultValue` parameter, so apply your default with `?:`. + +```kotlin +// 3.x +val payload = PostHog.getFeatureFlagPayload("checkout", defaultValue = "fallback") + +// 4.0 +val payload = PostHog.getFeatureFlagResult("checkout", sendFeatureFlagEvent = false)?.payload ?: "fallback" +``` + +### `debouncerDelayMs` + +```kotlin +// 3.x +PostHogSessionReplayConfig(debouncerDelayMs = 500) + +// 4.0 +PostHogSessionReplayConfig(throttleDelayMs = 500) +``` + +### `remoteConfig` + +Delete the option. Apps that left it at its default of `true` see no behavior change. + +```kotlin +// 3.x +config.remoteConfig = false + +// 4.0: remove the line +``` + +If you set it to `false`, your app's behavior changes: + +- The SDK now requests `/config` at setup, even if `preloadFeatureFlags` is also `false`, when 3.x sent no request at all. +- The settings in `/config` now apply, including the session replay, surveys, error tracking and push settings from your project. +- With `preloadFeatureFlags = true`, the SDK requests `/flags` only if `/config` reports that the project has feature flags. In 3.x it always requested `/flags`. If the project has none, the cached flags are cleared. + +## Feature flags callback + +`PostHogConfig.onFeatureFlags` and `reloadFeatureFlags()` now take a `PostHogFeatureFlagsCallback`, which receives a `PostHogFeatureFlagsLoaded`: + +- `flags`: the keys of the enabled flags +- `variants`: their values, either `true` or the variant string +- `errorsLoading`: whether the latest load failed. The values are then the last known ones, which can be empty + +```kotlin +// 3.x +config.onFeatureFlags = PostHogOnFeatureFlags { + refreshUi() +} + +// 4.0 +config.onFeatureFlags = PostHogFeatureFlagsCallback { loaded -> + if (!loaded.errorsLoading) { + refreshUi() + } +} +``` + +```java +// 3.x +PostHog.Companion.reloadFeatureFlags(() -> refreshUi()); + +// 4.0 +PostHog.Companion.reloadFeatureFlags(loaded -> refreshUi()); +``` + +A Kotlin trailing lambda such as `PostHog.reloadFeatureFlags { refreshUi() }` compiles unchanged, so it won't show up as an error. Check whether it should now read `errorsLoading`: the callback has always also run after a failed load. + +`errorsLoading` is `false` when PostHog answers that the project is over its feature flags quota, and the values are the cached flags. It's `true` when no request was made, such as when the device is offline or the distinct ID is blank, and when the SDK is disabled or isn't set up, with no values in that last case. + +These callbacks still run on a background thread, or right away on the calling thread when no load is attempted, so switch to the main thread before touching UI. With bootstrapped flags, `PostHogConfig.onFeatureFlags` also runs once on the thread calling `setup()`. + +## `PostHogInterface` implementations + +`PostHogInterface` lost `getFeatureFlagPayload()`, gained the abstract `onFeatureFlags()` and changed the callback type of `reloadFeatureFlags()`. Classes that implement it, such as hand-written fakes for tests, no longer compile until they're updated. + +```kotlin +class FakePostHog : PostHogInterface { + override fun reloadFeatureFlags(onFeatureFlags: PostHogFeatureFlagsCallback?) {} + + override fun onFeatureFlags(callback: PostHogFeatureFlagsCallback): PostHogFeatureFlagsSubscription = + TODO("Return a subscription from your own fake") + + // ... +} +``` + +`PostHogFeatureFlagsSubscription` and `PostHogFeatureFlagsLoaded` have constructors marked `@PostHogInternal`, which aren't intended for app code, so prefer a mocking library for these types if you can. + +## Internal APIs + +These helpers were public only by accident and were marked `@PostHogInternal`. They're no longer visible outside the SDK and have no replacement. Apps that don't use `@PostHogInternal` APIs aren't affected. + +- `com.posthog.internal`: `CustomHeadersInterceptor`, `PostHogPrintLogger`, `PropertyGroupDeserializer`, `PropertyValueDeserializer`, `personPropertiesContext()`, `PostHogPreferences.PUSH_SUBSCRIPTION_REJECTED` +- `com.posthog.internal.errortracking`: `ThrowableCoercer.fromThrowableToPostHogProperties()` +- `com.posthog.internal.replay`: `RRDocumentNode`, `RRDomContentLoadedEvent`, `RRLoadedEvent` +- `com.posthog.internal.surveys`: `findBestTranslationMatch()` +- `com.posthog.android.internal`: `Bitmap.isValid()`, `Bitmap.webpBase64()` +- `com.posthog.android.replay.internal`: `LogLine`, `LogcatParser` + +If you call `PostHogRemoteConfig.loadFeatureFlags()` or `loadRemoteConfig()`, their callback parameters changed too. The internal callback is now `(errorsLoading: Boolean) -> Unit`, and the other is a `PostHogFeatureFlagsCallback`. + +## Behavior changes + +### Feature flag payloads must be valid JSON + +A payload that isn't valid JSON now reads as `null` from `getFeatureFlagResult(key)?.payload` and `getAllFeatureFlags()`, instead of the raw string. With `debug` on, the SDK logs the flag key. + +| Payload | 3.x | 4.0 | +| --- | --- | --- | +| Malformed (`{broken`, `[1, 2`), empty or whitespace-only | the raw string | `null` | +| Only valid in lenient mode (unquoted `hello`, single quotes, comments) | decoded leniently | `null` | +| JSON `null` | the string `"null"` | `null` | +| Valid JSON (`"hello"`, `""`, `false`, `0`, objects, arrays) | decoded | decoded, unchanged | +| Bootstrapped payloads | as passed | as passed, unchanged | + +The flag's value, enabled state, variant and any other flag's payload aren't affected. + +If you read a payload as plain text, such as a payload saved as `hello` rather than `"hello"`, update it in PostHog to valid JSON before you upgrade, or your code gets `null`. + +A malformed payload cached by 3.x can still read as the raw string after the upgrade, until the app's first `/flags` response replaces it. + +### Other changes that don't fail the build + +The code you end up with after these two migrations compiles, so they're easy to miss: + +- [`getFeatureFlagResult()` sends `$feature_flag_called` by default](#getfeatureflagpayload), unlike `getFeatureFlagPayload()`. +- [Apps that set `remoteConfig = false` now load `/config`](#remoteconfig) and apply its settings. + +## New: `onFeatureFlags()` + +If you need flag updates outside of `PostHogConfig`, for example from a screen or a library, register a listener you can remove: + +```kotlin +val subscription = PostHog.onFeatureFlags { loaded -> + if (loaded.variants["new-checkout"] == "test") { + showTestVariant() + } +} + +// later +subscription.unsubscribe() +``` + +On Android, listeners run on the main thread. On the JVM, they run on a background thread. If flags have already loaded, a new listener also gets the current values shortly after it registers. You can register before `setup()`, and listeners stay registered across `close()` and `setup()`. + +## `posthog-server` + +`posthog-server` isn't having a major release, and its API is unchanged: it keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` now ships in `posthog-server` itself. None of the changes above apply to its API. + +Its next release depends on core 7.0, so update it if your project also uses core 7.0 or `posthog-android` 4.0. Older `posthog-server` versions aren't compatible with core 7.0 at runtime. + +## Checklist + +- [ ] Update `posthog-android` to 4.0, and `posthog-android-surveys-compose` and `posthog-server` if you use them. +- [ ] Replace `apiKey` with `projectToken`. +- [ ] Replace `propertiesSanitizer` with `addBeforeSend`. +- [ ] Replace `evaluationEnvironments` with `evaluationContexts`. +- [ ] Replace `getFeatureFlagPayload()` with `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload`. +- [ ] Replace `debouncerDelayMs` with `throttleDelayMs`. +- [ ] Remove `remoteConfig`. If it was `false`, expect `/config` requests and its settings to apply. +- [ ] Replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback`, and check existing callbacks for `errorsLoading`. +- [ ] Update any class that implements `PostHogInterface`. +- [ ] Make sure every feature flag payload you read is valid JSON. From 4940963b962ff8f5938f6a05a95f077a09bc67cd Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 21:44:15 -0400 Subject: [PATCH 09/49] docs: merge the server changeset and correct the Android min API --- .changeset/android-v4-major.md | 5 +++++ .changeset/server-keep-on-feature-flags.md | 6 ------ README.md | 2 +- 3 files changed, 6 insertions(+), 7 deletions(-) delete mode 100644 .changeset/server-keep-on-feature-flags.md diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 163e47135..d5c612515 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -2,8 +2,11 @@ 'posthog': major 'posthog-android': major 'posthog-android-surveys-compose': minor +'posthog-server': minor --- +Entries apply to `posthog`, `posthog-android` and `posthog-android-surveys-compose`, which re-exports them. Only entries prefixed `posthog-server:` apply to `posthog-server`, which keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`. + - **Breaking:** remove the deprecated `apiKey` property and the `PostHogConfig(apiKey = …)` and `PostHogAndroidConfig(apiKey = …)` factories; use `projectToken` instead - **Breaking:** remove the deprecated `propertiesSanitizer` config option and the `PostHogPropertiesSanitizer` interface; use `addBeforeSend` instead - **Breaking:** remove the deprecated `evaluationEnvironments` config option; use `evaluationContexts` instead @@ -16,3 +19,5 @@ - **Breaking:** add the abstract `onFeatureFlags()` method to `PostHogInterface`; classes that implement it must add the method - Add `onFeatureFlags()` to get notified after every feature flags load (on the main thread on Android), returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` - See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md) for upgrade steps +- `posthog-server`: Move `PostHogOnFeatureFlags` into `posthog-server`; its API is unchanged +- `posthog-server`: Bump the `posthog` core dependency to 7.0 diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md deleted file mode 100644 index c39f151bb..000000000 --- a/.changeset/server-keep-on-feature-flags.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -'posthog-server': minor ---- - -- Move `PostHogOnFeatureFlags` into `posthog-server`; its API is unchanged -- Bump the `posthog` core dependency to 7.0 diff --git a/README.md b/README.md index cdcbfa1eb..50f723040 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ | Packages | Maven Central | Min Version | |-----------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | -| posthog-android | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android) | Android API 21 | +| posthog-android | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android) | Android API 23 | | posthog-android-surveys-compose | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-surveys-compose/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-surveys-compose) | Android API 23 · `0.x` | | posthog (core) | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog) | Java 8 | | posthog-server | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-server/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-server) | Java 8 | From 81340f3d9ef5a8cfd66c9adaaec38b4c4960b218 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 22:02:50 -0400 Subject: [PATCH 10/49] docs: keep the server changeset separate from Android --- .changeset/android-v4-major.md | 5 ----- .changeset/server-keep-on-feature-flags.md | 6 ++++++ 2 files changed, 6 insertions(+), 5 deletions(-) create mode 100644 .changeset/server-keep-on-feature-flags.md diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index d5c612515..163e47135 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -2,11 +2,8 @@ 'posthog': major 'posthog-android': major 'posthog-android-surveys-compose': minor -'posthog-server': minor --- -Entries apply to `posthog`, `posthog-android` and `posthog-android-surveys-compose`, which re-exports them. Only entries prefixed `posthog-server:` apply to `posthog-server`, which keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`. - - **Breaking:** remove the deprecated `apiKey` property and the `PostHogConfig(apiKey = …)` and `PostHogAndroidConfig(apiKey = …)` factories; use `projectToken` instead - **Breaking:** remove the deprecated `propertiesSanitizer` config option and the `PostHogPropertiesSanitizer` interface; use `addBeforeSend` instead - **Breaking:** remove the deprecated `evaluationEnvironments` config option; use `evaluationContexts` instead @@ -19,5 +16,3 @@ Entries apply to `posthog`, `posthog-android` and `posthog-android-surveys-compo - **Breaking:** add the abstract `onFeatureFlags()` method to `PostHogInterface`; classes that implement it must add the method - Add `onFeatureFlags()` to get notified after every feature flags load (on the main thread on Android), returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` - See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md) for upgrade steps -- `posthog-server`: Move `PostHogOnFeatureFlags` into `posthog-server`; its API is unchanged -- `posthog-server`: Bump the `posthog` core dependency to 7.0 diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md new file mode 100644 index 000000000..c39f151bb --- /dev/null +++ b/.changeset/server-keep-on-feature-flags.md @@ -0,0 +1,6 @@ +--- +'posthog-server': minor +--- + +- Move `PostHogOnFeatureFlags` into `posthog-server`; its API is unchanged +- Bump the `posthog` core dependency to 7.0 From 7e23b1e31ab57d28b1507d6e03683cf5ece2015c Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 30 Oct 2026 22:11:31 -0400 Subject: [PATCH 11/49] docs: leave surveys-compose out of the 4.0 changeset --- .changeset/android-v4-major.md | 1 - docs/migration-3.x-to-4.0.md | 4 ++-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 163e47135..104bc40b3 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -1,7 +1,6 @@ --- 'posthog': major 'posthog-android': major -'posthog-android-surveys-compose': minor --- - **Breaking:** remove the deprecated `apiKey` property and the `PostHogConfig(apiKey = …)` and `PostHogAndroidConfig(apiKey = …)` factories; use `projectToken` instead diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 8b8acbb4c..a6423911a 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -11,7 +11,7 @@ For the full list of changes, see the [changelog](../posthog-android/CHANGELOG.m | --- | --- | | `com.posthog:posthog-android` | 3.x to 4.0 | | `com.posthog:posthog` (core) | 6.x to 7.0 | -| `com.posthog:posthog-android-surveys-compose` | the release that depends on `posthog-android` 4.0 | +| `com.posthog:posthog-android-surveys-compose` | keep your version, and declare `com.posthog:posthog-android:4.+` in your build so Gradle resolves 4.0 instead of the 3.x version it pulls in | | `com.posthog:posthog-server` | see [`posthog-server`](#posthog-server) | These are unchanged, so you don't need to change your build for them: @@ -239,7 +239,7 @@ Its next release depends on core 7.0, so update it if your project also uses cor ## Checklist -- [ ] Update `posthog-android` to 4.0, and `posthog-android-surveys-compose` and `posthog-server` if you use them. +- [ ] Update `posthog-android` to 4.0 and declare it in your build if you only depend on `posthog-android-surveys-compose`, and update `posthog-server` if you use it. - [ ] Replace `apiKey` with `projectToken`. - [ ] Replace `propertiesSanitizer` with `addBeforeSend`. - [ ] Replace `evaluationEnvironments` with `evaluationContexts`. From 9cf154d2482bc8fb2e8d10e66c1f3196c84a67b0 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 2 Nov 2026 10:08:24 -0500 Subject: [PATCH 12/49] feat!: remove defaultValue from getFeatureFlag (#917) The canonical client signature has no default and iOS, Flutter and RN have none. A fallback was also reported as the flag value in $feature_flag_called. A disabled SDK now returns null; isFeatureEnabled keeps its defaultValue. --- .changeset/android-v4-major.md | 1 + docs/migration-3.x-to-4.0.md | 19 +++++ .../PostHogSurveysLinkedFlagVariantTest.kt | 2 +- .../surveys/PostHogSurveysSelectionTest.kt | 2 +- posthog/api/posthog.api | 10 +-- posthog/src/main/java/com/posthog/PostHog.kt | 10 +-- .../main/java/com/posthog/PostHogInterface.kt | 13 ++- .../com/posthog/PostHogFeatureFlagsTest.kt | 84 ++++++++++++------- .../java/com/posthog/PostHogFake.kt | 1 - 9 files changed, 96 insertions(+), 46 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 104bc40b3..71c118432 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -7,6 +7,7 @@ - **Breaking:** remove the deprecated `propertiesSanitizer` config option and the `PostHogPropertiesSanitizer` interface; use `addBeforeSend` instead - **Breaking:** remove the deprecated `evaluationEnvironments` config option; use `evaluationContexts` instead - **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload` instead to keep not sending `$feature_flag_called` +- **Breaking:** remove the `defaultValue` parameter from `getFeatureFlag()`, which returns `null` for a flag with no value or a disabled SDK, so use `getFeatureFlag(key) ?: default` instead; a positional `Boolean` second argument now sets `sendFeatureFlagEvent`, and `$feature_flag_called` no longer reports a fallback from `getFeatureFlag()` or `isFeatureEnabled()` as the flag's value - **Breaking:** remove the deprecated `PostHogSessionReplayConfig.debouncerDelayMs`; use `throttleDelayMs` instead - **Breaking:** return `null` instead of the raw string for a malformed, empty, whitespace-only or lenient-only (unquoted or single-quoted) feature flag payload from `getFeatureFlagResult(key)?.payload`; payloads must be valid JSON (a JSON `null` payload now also reads as `null` instead of the string `"null"`) - **Breaking:** make SDK-internal helpers in the `com.posthog.internal`, `com.posthog.android.internal` and `com.posthog.android.replay.internal` packages non-public diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index a6423911a..bfb553a23 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -33,6 +33,7 @@ All of these are compile errors. Calling them from an already-compiled library t | `PostHogConfig.propertiesSanitizer`, `PostHogPropertiesSanitizer` | `addBeforeSend` | | `PostHogConfig.evaluationEnvironments` | `evaluationContexts` | | `getFeatureFlagPayload()`, on the instance and on `PostHog` | `getFeatureFlagResult()` | +| `defaultValue` on `getFeatureFlag()` | `getFeatureFlag(key) ?: default` | | `PostHogSessionReplayConfig.debouncerDelayMs` | `throttleDelayMs` | | `PostHogConfig.remoteConfig` | nothing; remote config always loads | | `PostHogOnFeatureFlags` | `PostHogFeatureFlagsCallback` | @@ -94,6 +95,24 @@ val payload = PostHog.getFeatureFlagPayload("checkout", defaultValue = "fallback val payload = PostHog.getFeatureFlagResult("checkout", sendFeatureFlagEvent = false)?.payload ?: "fallback" ``` +### `getFeatureFlag()` default value + +```kotlin +// 3.x +val value = PostHog.getFeatureFlag("checkout", defaultValue = "fallback") + +// 4.0 +val value = PostHog.getFeatureFlag("checkout") ?: "fallback" +``` + +The second parameter is now `sendFeatureFlagEvent`, which affects code that still compiles: + +- `getFeatureFlag("checkout", true)` compiles, but `true` now means `sendFeatureFlagEvent` rather than the default value. +- A disabled SDK now returns `null`, not your default. +- `$feature_flag_called` no longer reports a fallback as the flag's value. `isFeatureEnabled("missing", true)` still returns `true`, but its event reports an empty response. + +Classes that implement `PostHogInterface` update the signature. + ### `debouncerDelayMs` ```kotlin diff --git a/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysLinkedFlagVariantTest.kt b/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysLinkedFlagVariantTest.kt index 230796ec2..b7512e36d 100644 --- a/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysLinkedFlagVariantTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysLinkedFlagVariantTest.kt @@ -67,7 +67,7 @@ internal class PostHogSurveysLinkedFlagVariantTest( val value = flagValues[it.getArgument(0)] value == true || value is String } - whenever(postHog.getFeatureFlag(any(), anyOrNull(), anyOrNull())).thenAnswer { + whenever(postHog.getFeatureFlag(any(), anyOrNull())).thenAnswer { flagValues[it.getArgument(0)] } val survey = diff --git a/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysSelectionTest.kt b/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysSelectionTest.kt index 626a0bbc0..2b27a1cbc 100644 --- a/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysSelectionTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysSelectionTest.kt @@ -77,7 +77,7 @@ internal class PostHogSurveysSelectionTest { val value = flags[it.getArgument(0)] value == true || value is String } - whenever(postHog.getFeatureFlag(any(), anyOrNull(), anyOrNull())).thenAnswer { flags[it.getArgument(0)] } + whenever(postHog.getFeatureFlag(any(), anyOrNull())).thenAnswer { flags[it.getArgument(0)] } val integration = PostHogSurveysIntegration(context, config) integration.install(postHog) try { diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index 162a27452..550fa6dd2 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -38,7 +38,7 @@ public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posth public fun getAnonymousId ()Ljava/lang/String; public fun getConfig ()Lcom/posthog/PostHogConfig; public fun getDeviceId ()Ljava/lang/String; - public fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Object;Ljava/lang/Boolean;)Ljava/lang/Object; + public fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)Ljava/lang/Object; public fun getFeatureFlagResult (Ljava/lang/String;Ljava/lang/Boolean;)Lcom/posthog/FeatureFlagResult; public fun getLogger ()Lcom/posthog/logs/PostHogLogger; public fun getSessionId ()Ljava/util/UUID; @@ -88,7 +88,7 @@ public final class com/posthog/PostHog$Companion : com/posthog/PostHogInterface public fun getAnonymousId ()Ljava/lang/String; public fun getConfig ()Lcom/posthog/PostHogConfig; public fun getDeviceId ()Ljava/lang/String; - public fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Object;Ljava/lang/Boolean;)Ljava/lang/Object; + public fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)Ljava/lang/Object; public fun getFeatureFlagResult (Ljava/lang/String;Ljava/lang/Boolean;)Lcom/posthog/FeatureFlagResult; public fun getLogger ()Lcom/posthog/logs/PostHogLogger; public fun getSessionId ()Ljava/util/UUID; @@ -403,8 +403,8 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public abstract fun getAnonymousId ()Ljava/lang/String; public abstract fun getConfig ()Lcom/posthog/PostHogConfig; public abstract fun getDeviceId ()Ljava/lang/String; - public abstract fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Object;Ljava/lang/Boolean;)Ljava/lang/Object; - public static synthetic fun getFeatureFlag$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/Boolean;ILjava/lang/Object;)Ljava/lang/Object; + public abstract fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)Ljava/lang/Object; + public static synthetic fun getFeatureFlag$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Ljava/lang/Object; public abstract fun getFeatureFlagResult (Ljava/lang/String;Ljava/lang/Boolean;)Lcom/posthog/FeatureFlagResult; public static synthetic fun getFeatureFlagResult$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Lcom/posthog/FeatureFlagResult; public abstract fun getLogger ()Lcom/posthog/logs/PostHogLogger; @@ -449,7 +449,7 @@ public final class com/posthog/PostHogInterface$DefaultImpls { public static synthetic fun captureFeatureView$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)V public static synthetic fun captureLog$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Lcom/posthog/logs/PostHogLogSeverity;Ljava/util/Map;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;ILjava/lang/Object;)V public static synthetic fun capturePushNotificationOpened$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/lang/String;ILjava/lang/Object;)V - public static synthetic fun getFeatureFlag$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/Boolean;ILjava/lang/Object;)Ljava/lang/Object; + public static synthetic fun getFeatureFlag$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Ljava/lang/Object; public static synthetic fun getFeatureFlagResult$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Lcom/posthog/FeatureFlagResult; public static synthetic fun group$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V public static synthetic fun isFeatureEnabled$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZLjava/lang/Boolean;ILjava/lang/Object;)Z diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 2f3ef881a..720f1018c 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -2110,7 +2110,7 @@ public class PostHog private constructor( defaultValue: Boolean, sendFeatureFlagEvent: Boolean?, ): Boolean { - val value = getFeatureFlag(key, defaultValue, sendFeatureFlagEvent) + val value = getFeatureFlag(key, sendFeatureFlagEvent) ?: defaultValue if (value is Boolean) { return value @@ -2191,11 +2191,10 @@ public class PostHog private constructor( public override fun getFeatureFlag( key: String, - defaultValue: Any?, sendFeatureFlagEvent: Boolean?, ): Any? { - if (!isEnabled()) return defaultValue - val flagValue = remoteConfig?.getFeatureFlagResult(key)?.value ?: defaultValue + if (!isEnabled()) return null + val flagValue = remoteConfig?.getFeatureFlagResult(key)?.value sendFeatureFlagCalled(key, flagValue, sendFeatureFlagEvent) return flagValue } @@ -2865,9 +2864,8 @@ public class PostHog private constructor( public override fun getFeatureFlag( key: String, - defaultValue: Any?, sendFeatureFlagEvent: Boolean?, - ): Any? = shared.getFeatureFlag(key, defaultValue = defaultValue, sendFeatureFlagEvent) + ): Any? = shared.getFeatureFlag(key, sendFeatureFlagEvent) override fun getAllFeatureFlags(): List? { return shared.getAllFeatureFlags() diff --git a/posthog/src/main/java/com/posthog/PostHogInterface.kt b/posthog/src/main/java/com/posthog/PostHogInterface.kt index f4cbd455c..4e1be761d 100644 --- a/posthog/src/main/java/com/posthog/PostHogInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogInterface.kt @@ -186,16 +186,21 @@ public interface PostHogInterface : PostHogCoreInterface { ): Boolean /** - * Returns the feature flag + * Returns the feature flag value, or null if the flag has no value or the SDK is disabled. + * Use `?:` for a fallback; it is never reported in the $feature_flag_called event. + * + * ```kotlin + * val variant = PostHog.getFeatureFlag("my-flag") ?: "control" + * ``` + * * Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments * @param key the Key - * @param defaultValue the default value if not found * @param sendFeatureFlagEvent (optional) If false, we won't send an $feature_flag_called event to PostHog. - * @return The feature flag value, or [defaultValue] if not found. + * Defaults to [PostHogConfig.sendFeatureFlagEvent]. + * @return The feature flag value, or null if not found. */ public fun getFeatureFlag( key: String, - defaultValue: Any? = null, sendFeatureFlagEvent: Boolean? = null, ): Any? diff --git a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt index 8c02709ce..9da19fd32 100644 --- a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt @@ -348,49 +348,77 @@ internal class PostHogFeatureFlagsTest { sut.close() } - @Test - fun `getFeatureFlag with non-existent flag sends defaultValue in event`() { - val file = File("src/test/resources/json/basic-flags-with-non-active-flags.json") - val responseFlagsApi = file.readText() - + private fun assertMissingFlagReportsNoValue(read: (PostHogInterface) -> Unit) { val http = mockHttp( response = MockResponse() - .setBody(responseFlagsApi), + .setBody(File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText()), ) - http.enqueue( - MockResponse() - .setBody(""), - ) - val url = http.url("/") - val sut = getSut(url.toString(), preloadFeatureFlags = false, sendFeatureFlagEvent = true) + http.enqueue(MockResponse().setBody("")) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false, sendFeatureFlagEvent = true) sut.reloadFeatureFlags() - remoteConfigExecutor.shutdownAndAwaitTermination() - - // remove from the http queue http.takeRequest() - val defaultValue = "my-default" - val result = sut.getFeatureFlag("nonExistentFlag", defaultValue) - + read(sut) queueExecutor.shutdownAndAwaitTermination() - // Function should return the defaultValue - assertEquals(defaultValue, result) + val batch = serializer.deserialize(http.takeRequest().body.unGzip().reader()) + val theEvent = batch.batch.first() + assertEquals("\$feature_flag_called", theEvent.event) + assertEquals("nonExistentFlag", theEvent.properties!!["\$feature_flag"]) + assertEquals("", theEvent.properties!!["\$feature_flag_response"]) + sut.close() + } - val request = http.takeRequest() - val content = request.body.unGzip() - val batch = serializer.deserialize(content.reader()) + @Test + fun `getFeatureFlag returns null and reports no value for a missing flag`() { + assertMissingFlagReportsNoValue { sut -> + assertNull(sut.getFeatureFlag("nonExistentFlag")) + } + } - val theEvent = batch.batch.firstOrNull() - assertEquals("\$feature_flag_called", theEvent?.event) - // The event's $feature_flag_response should be the defaultValue, not null - assertEquals(defaultValue, theEvent?.properties!!["\$feature_flag_response"]) - assertEquals("nonExistentFlag", theEvent.properties!!["\$feature_flag"]) + @Test + fun `isFeatureEnabled returns the default but does not report it for a missing flag`() { + assertMissingFlagReportsNoValue { sut -> + assertTrue(sut.isFeatureEnabled("nonExistentFlag", defaultValue = true)) + } + } + + @Test + fun `isFeatureEnabled prefers a false flag value over the default`() { + val http = + mockHttp( + response = + MockResponse() + .setBody(File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText()), + ) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false) + + sut.reloadFeatureFlags() + remoteConfigExecutor.shutdownAndAwaitTermination() + + assertFalse(sut.isFeatureEnabled("IAmInactive", defaultValue = true)) + } + + @Test + fun `disabled SDK returns null from getFeatureFlag and the default from isFeatureEnabled`() { + val http = + mockHttp( + response = + MockResponse() + .setBody(File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText()), + ) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false) + + sut.reloadFeatureFlags() + remoteConfigExecutor.shutdownAndAwaitTermination() sut.close() + + assertNull(sut.getFeatureFlag("4535-funnel-bar-viz")) + assertTrue(sut.isFeatureEnabled("IAmInactive", defaultValue = true)) } @Test diff --git a/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt b/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt index 6ae4674f0..00a37fcf4 100644 --- a/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt +++ b/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt @@ -96,7 +96,6 @@ public class PostHogFake : PostHogInterface, PostHogPushSubscriptionReceiver { override fun getFeatureFlag( key: String, - defaultValue: Any?, sendFeatureFlagEvent: Boolean?, ): Any? { return null From f106ead016e48ef11c81df2c8c02545868330be4 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 2 Nov 2026 10:09:24 -0500 Subject: [PATCH 13/49] feat!: remove PostHogConfig.onFeatureFlags in favor of the listener (#918) * feat!: remove defaultValue from getFeatureFlag The canonical client signature has no default and iOS, Flutter and RN have none. A fallback was also reported as the flag value in $feature_flag_called. A disabled SDK now returns null; isFeatureEnabled keeps its defaultValue. * feat!: remove PostHogConfig.onFeatureFlags in favor of the listener The onFeatureFlags() listener can be registered before setup(), gets bootstrapped flags, and is removable, so the config field no longer adds anything. iOS and posthog-js only have the listener form. --- .changeset/android-v4-major.md | 3 +- docs/migration-3.x-to-4.0.md | 17 ++++--- .../PostHogAndroidEventSnapshotsTest.kt | 5 ++- .../java/com/posthog/android/sample/MyApp.kt | 2 - .../com/posthog/server/PostHogConfigTest.kt | 1 - posthog/api/posthog.api | 6 +-- posthog/src/main/java/com/posthog/PostHog.kt | 28 +++++------- .../main/java/com/posthog/PostHogConfig.kt | 6 --- .../posthog/PostHogFeatureFlagsCallback.kt | 12 +++-- .../posthog/internal/PostHogRemoteConfig.kt | 6 +-- .../java/com/posthog/PostHogBootstrapTest.kt | 45 +++++-------------- .../java/com/posthog/PostHogConfigTest.kt | 5 --- 12 files changed, 48 insertions(+), 88 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 71c118432..302cf21d5 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -12,7 +12,8 @@ - **Breaking:** return `null` instead of the raw string for a malformed, empty, whitespace-only or lenient-only (unquoted or single-quoted) feature flag payload from `getFeatureFlagResult(key)?.payload`; payloads must be valid JSON (a JSON `null` payload now also reads as `null` instead of the string `"null"`) - **Breaking:** make SDK-internal helpers in the `com.posthog.internal`, `com.posthog.android.internal` and `com.posthog.android.replay.internal` packages non-public - **Breaking:** remove the deprecated `remoteConfig` config option; the SDK now always loads remote config at setup -- **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `PostHogConfig.onFeatureFlags` and `reloadFeatureFlags()`; it receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values, and `errorsLoading` +- **Breaking:** remove `PostHogConfig.onFeatureFlags`; call `PostHog.onFeatureFlags(callback)` before `setup()` instead, which also covers the first load +- **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `reloadFeatureFlags()`; it receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values, and `errorsLoading` - **Breaking:** add the abstract `onFeatureFlags()` method to `PostHogInterface`; classes that implement it must add the method - Add `onFeatureFlags()` to get notified after every feature flags load (on the main thread on Android), returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` - See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md) for upgrade steps diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index bfb553a23..43835e3a7 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -36,6 +36,7 @@ All of these are compile errors. Calling them from an already-compiled library t | `defaultValue` on `getFeatureFlag()` | `getFeatureFlag(key) ?: default` | | `PostHogSessionReplayConfig.debouncerDelayMs` | `throttleDelayMs` | | `PostHogConfig.remoteConfig` | nothing; remote config always loads | +| `PostHogConfig.onFeatureFlags` | `PostHog.onFeatureFlags()` before `setup()` | | `PostHogOnFeatureFlags` | `PostHogFeatureFlagsCallback` | The constructor parameters of `PostHogConfig` and `PostHogSessionReplayConfig` move up where these were removed. If you pass arguments by position, check them, or switch to named arguments. @@ -142,7 +143,7 @@ If you set it to `false`, your app's behavior changes: ## Feature flags callback -`PostHogConfig.onFeatureFlags` and `reloadFeatureFlags()` now take a `PostHogFeatureFlagsCallback`, which receives a `PostHogFeatureFlagsLoaded`: +`PostHogConfig.onFeatureFlags` is removed. Call `PostHog.onFeatureFlags()` before `setup()` instead, which also covers the first load. `reloadFeatureFlags()` now takes a `PostHogFeatureFlagsCallback`. Both callbacks receive a `PostHogFeatureFlagsLoaded`: - `flags`: the keys of the enabled flags - `variants`: their values, either `true` or the variant string @@ -154,14 +155,20 @@ config.onFeatureFlags = PostHogOnFeatureFlags { refreshUi() } -// 4.0 -config.onFeatureFlags = PostHogFeatureFlagsCallback { loaded -> +// 4.0, before PostHogAndroid.setup() +PostHog.onFeatureFlags { loaded -> if (!loaded.errorsLoading) { refreshUi() } } ``` +The listener differs from the removed option in three ways: + +- It runs on the main thread on Android. The option ran on a background thread. +- Bootstrapped flags arrive just after `setup()` is called, not synchronously inside it. +- A reload on a disabled SDK doesn't call listeners. `reloadFeatureFlags(callback)` still gets `errorsLoading = true` in that case. + ```java // 3.x PostHog.Companion.reloadFeatureFlags(() -> refreshUi()); @@ -174,7 +181,7 @@ A Kotlin trailing lambda such as `PostHog.reloadFeatureFlags { refreshUi() }` co `errorsLoading` is `false` when PostHog answers that the project is over its feature flags quota, and the values are the cached flags. It's `true` when no request was made, such as when the device is offline or the distinct ID is blank, and when the SDK is disabled or isn't set up, with no values in that last case. -These callbacks still run on a background thread, or right away on the calling thread when no load is attempted, so switch to the main thread before touching UI. With bootstrapped flags, `PostHogConfig.onFeatureFlags` also runs once on the thread calling `setup()`. +The `reloadFeatureFlags()` callback still runs on a background thread, or right away on the calling thread when no load is attempted, so switch to the main thread before touching UI. ## `PostHogInterface` implementations @@ -235,7 +242,7 @@ The code you end up with after these two migrations compiles, so they're easy to ## New: `onFeatureFlags()` -If you need flag updates outside of `PostHogConfig`, for example from a screen or a library, register a listener you can remove: +`onFeatureFlags()` is now the way to listen for flag loads, for example from a screen or a library. You can remove the listener later: ```kotlin val subscription = PostHog.onFeatureFlags { loaded -> diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt index a29635090..e9912e7dd 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt @@ -24,6 +24,7 @@ import java.util.Date import java.util.TimeZone import java.util.UUID import java.util.concurrent.CountDownLatch +import java.util.concurrent.Executor import java.util.concurrent.TimeUnit import java.util.zip.GZIPInputStream import kotlin.test.AfterTest @@ -67,8 +68,10 @@ internal class PostHogAndroidEventSnapshotsTest { fun `batch request and enriched event shapes match snapshot`() { val fixture = createFixture() val flagsLoaded = CountDownLatch(1) - fixture.config.onFeatureFlags = PostHogFeatureFlagsCallback { flagsLoaded.countDown() } val sut = fixture.client + // this test blocks the main thread, where listeners otherwise run + fixture.config.featureFlagsListenerExecutor = Executor { it.run() } + sut.onFeatureFlags { flagsLoaded.countDown() } sut.capture( event = "checkout completed", diff --git a/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt b/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt index bfdb0e45e..b1ebd89c4 100644 --- a/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt +++ b/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt @@ -2,7 +2,6 @@ package com.posthog.android.sample import android.app.Application import android.os.StrictMode -import com.posthog.PostHogFeatureFlagsCallback import com.posthog.android.PostHogAndroid import com.posthog.android.PostHogAndroidConfig @@ -39,7 +38,6 @@ class MyApp : Application() { sessionReplay = true preloadFeatureFlags = true sendFeatureFlagEvent = false - onFeatureFlags = PostHogFeatureFlagsCallback { print("feature flags loaded") } addBeforeSend { event -> if (event.event == "test_event") { null diff --git a/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt b/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt index f77668c76..f63920e87 100644 --- a/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt +++ b/posthog-server/src/test/java/com/posthog/server/PostHogConfigTest.kt @@ -180,7 +180,6 @@ internal class PostHogConfigTest { assertEquals(30, coreConfig.maxBatchSize) assertEquals(45, coreConfig.flushIntervalSeconds) assertEquals(mockEncryption, coreConfig.encryption) - assertNull(coreConfig.onFeatureFlags) } @Test diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index 550fa6dd2..4c6968839 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -159,8 +159,8 @@ public class com/posthog/PostHogConfig { public static final field DEFAULT_MAX_QUEUE_SIZE I public static final field DEFAULT_US_ASSETS_HOST Ljava/lang/String; public static final field DEFAULT_US_HOST Ljava/lang/String; - public fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogFeatureFlagsCallback;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;Lcom/posthog/PostHogFeatureFlagsCallback;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun addBeforeSend (Lcom/posthog/PostHogBeforeSend;)V public final fun addIntegration (Lcom/posthog/PostHogIntegration;)V public final fun getBeforeSendList ()Ljava/util/List; @@ -190,7 +190,6 @@ public class com/posthog/PostHogConfig { public final fun getMaxQueueSize ()I public final fun getMaxRetries ()I public final fun getNetworkStatus ()Lcom/posthog/internal/PostHogNetworkStatus; - public final fun getOnFeatureFlags ()Lcom/posthog/PostHogFeatureFlagsCallback; public final fun getOptOut ()Z public final fun getPersistOptOut ()Z public final fun getPersonProfiles ()Lcom/posthog/PersonProfiles; @@ -242,7 +241,6 @@ public class com/posthog/PostHogConfig { public final fun setMaxQueueSize (I)V public final fun setMaxRetries (I)V public final fun setNetworkStatus (Lcom/posthog/internal/PostHogNetworkStatus;)V - public final fun setOnFeatureFlags (Lcom/posthog/PostHogFeatureFlagsCallback;)V public final fun setOptOut (Z)V public final fun setPersistOptOut (Z)V public final fun setPersonProfiles (Lcom/posthog/PersonProfiles;)V diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 720f1018c..de65a0ca2 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -431,8 +431,8 @@ public class PostHog private constructor( super.enabled = true - // Captured before any user callout below (integrations, session hooks, the bootstrap - // config callback), any of which may close() and so supersede setup's flags load. + // Captured before any user callout below (integrations, session hooks), any of + // which may close() and so supersede setup's flags load. val generation = featureFlagsGeneration // Queued before integrations install, so a reload one starts there can't hold the @@ -478,20 +478,16 @@ public class PostHog private constructor( // only because of testing in isolation, this flag is always enabled if (reloadFeatureFlags) { - // Bootstrap already seeded the flags in RemoteConfig's init; fire the flags-loaded - // callbacks now so listeners aren't blocked on the first network response. + // Bootstrap already seeded the flags in RemoteConfig's init, so replay can start + // without waiting for the first network response. if (remoteConfig?.hasBootstrapFlags() == true) { try { startSessionReplayOnFeatureFlagsLoaded() } catch (e: Throwable) { config.logger.log("Executing the internal feature flags callback failed: $e") } - notifyFeatureFlagsCallback(config.onFeatureFlags, remoteConfig?.getFeatureFlags(), errorsLoading = false) } - loadRemoteConfigRequest( - internalOnFeatureFlagsLoaded(generation), - config.onFeatureFlags, - ) + loadRemoteConfigRequest(internalOnFeatureFlagsLoaded(generation)) } // Reconcile a differing identified bootstrap after the setup reload is dispatched. @@ -1749,7 +1745,7 @@ public class PostHog private constructor( // only because of testing in isolation, this flag is always enabled if (reloadFeatureFlags) { - reloadFeatureFlags(config?.onFeatureFlags) + reloadFeatureFlags() } // we need to make sure the user props update is for the same user // otherwise they have to reset and identify again @@ -1778,7 +1774,7 @@ public class PostHog private constructor( // The identified state itself is not part of the flags request; reload only when the // caller supplied properties that can affect flag evaluation. if ((userProperties?.isNotEmpty() == true || userPropertiesSetOnce?.isNotEmpty() == true) && reloadFeatureFlags) { - reloadFeatureFlags(config?.onFeatureFlags) + reloadFeatureFlags() } } else if (!hasDifferentDistinctId && (userProperties?.isNotEmpty() == true || userPropertiesSetOnce?.isNotEmpty() == true)) { if (shouldCapturePersonPropertiesEvent( @@ -2006,7 +2002,7 @@ public class PostHog private constructor( // only because of testing in isolation, this flag is always enabled if (reloadFeatureFlags && reloadFeatureFlagsIfNewGroup) { - reloadFeatureFlags(config?.onFeatureFlags) + reloadFeatureFlags() } } @@ -2082,10 +2078,7 @@ public class PostHog private constructor( ) } - private fun loadRemoteConfigRequest( - internalOnFeatureFlags: ((errorsLoading: Boolean) -> Unit)?, - onFeatureFlags: PostHogFeatureFlagsCallback?, - ) { + private fun loadRemoteConfigRequest(internalOnFeatureFlags: ((errorsLoading: Boolean) -> Unit)?) { @Suppress("UNCHECKED_CAST") val groups = getPreferences().getValue(GROUPS) as? Map @@ -2101,7 +2094,6 @@ public class PostHog private constructor( anonymousId = anonymousId, groups, internalOnFeatureFlags, - onFeatureFlags, ) } @@ -2365,7 +2357,7 @@ public class PostHog private constructor( // reload flags as anon user // only because of testing in isolation, this flag is always enabled if (reloadFeatureFlags) { - reloadFeatureFlags(config?.onFeatureFlags) + reloadFeatureFlags() } } diff --git a/posthog/src/main/java/com/posthog/PostHogConfig.kt b/posthog/src/main/java/com/posthog/PostHogConfig.kt index f36d38c38..929b639dd 100644 --- a/posthog/src/main/java/com/posthog/PostHogConfig.kt +++ b/posthog/src/main/java/com/posthog/PostHogConfig.kt @@ -154,12 +154,6 @@ public open class PostHogConfig( * Defaults to no encryption */ public var encryption: PostHogEncryption? = null, - /** - * Hook that is called when feature flags are loaded, or loading them failed - * It receives a [PostHogFeatureFlagsLoaded]; see [PostHogFeatureFlagsCallback] for the thread it runs on - * Defaults to no callback - */ - public var onFeatureFlags: PostHogFeatureFlagsCallback? = null, /** * Enable Recording of Session Replays for Android * Requires Record user sessions to be enabled in the PostHog Project Settings diff --git a/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt index 355b9714f..6c39fc9f7 100644 --- a/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt +++ b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsCallback.kt @@ -3,19 +3,17 @@ package com.posthog /** * Callback invoked when a feature flags load finishes, whether it succeeded or failed. * - * It's used by `PostHogConfig.onFeatureFlags`, `reloadFeatureFlags` and `onFeatureFlags`. - * - * For `PostHogConfig.onFeatureFlags` and `reloadFeatureFlags`, it runs on a background thread, or right - * away on the calling thread when no load is attempted (for example, the SDK is disabled). With - * bootstrapped flags, `PostHogConfig.onFeatureFlags` also runs once on the thread calling `setup()`, - * before the first load finishes. Hop to the main thread before touching UI. + * It's used by `onFeatureFlags` and `reloadFeatureFlags`. * * For `onFeatureFlags`, it runs on the main thread on Android, and on the SDK's background remote * config thread on the JVM. * + * For `reloadFeatureFlags`, it runs on a background thread, or right away on the calling thread when + * no load is attempted (for example, the SDK is disabled). Hop to the main thread before touching UI. + * * Example: * ```kotlin - * config.onFeatureFlags = PostHogFeatureFlagsCallback { loaded -> + * val subscription = PostHog.onFeatureFlags { loaded -> * if (!loaded.errorsLoading && "new-checkout" in loaded.flags) { * // The flag is enabled * } diff --git a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt index f9bec33c9..b63a91e32 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt @@ -889,9 +889,9 @@ public class PostHogRemoteConfig( distinctId = distinctId, anonymousId = anonymousId, groups = groups, - // distinct(): the SDK's own listeners and config.onFeatureFlags are singleton - // instances reused across reloads, so appending each queued reload would fire - // them once per coalesced reload instead of once per response. + // distinct(): the SDK's own listeners are singleton instances reused across reloads, + // so appending each queued reload would fire them once per coalesced reload + // instead of once per response. internalOnFeatureFlags = (displaced?.internalOnFeatureFlags.orEmpty() + listOfNotNull(internalOnFeatureFlags)) .distinct(), diff --git a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt index 8fb56afdd..689411319 100644 --- a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt @@ -18,13 +18,11 @@ import java.util.concurrent.CountDownLatch import java.util.concurrent.Executors import java.util.concurrent.LinkedBlockingQueue import java.util.concurrent.TimeUnit -import java.util.concurrent.atomic.AtomicBoolean import kotlin.test.AfterTest import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertFalse import kotlin.test.assertNotEquals -import kotlin.test.assertNotNull import kotlin.test.assertNull import kotlin.test.assertTrue @@ -51,7 +49,6 @@ internal class PostHogBootstrapTest { storagePrefix: String = tmpDir.newFolder().absolutePath, logger: TestLogger? = null, optOut: Boolean = false, - onFeatureFlags: PostHogFeatureFlagsCallback? = null, ): PostHogInterface { config = PostHogConfig(PROJECT_TOKEN, host).apply { @@ -63,7 +60,6 @@ internal class PostHogBootstrapTest { this.cachePreferences = cachePreferences this.bootstrap = bootstrap this.optOut = optOut - this.onFeatureFlags = onFeatureFlags if (logger != null) { this.logger = logger } @@ -372,25 +368,6 @@ internal class PostHogBootstrapTest { http.shutdown() } - @Test - fun `bootstrap flags fire the flags-loaded callback immediately`() { - var loaded: PostHogFeatureFlagsLoaded? = null - val sut = - getSut( - host = "http://127.0.0.1:1", - // the callback fires from setup's flag loading, before /config answers - reloadFeatureFlags = true, - bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("beta-ui" to true, "checkout" to "test")), - onFeatureFlags = PostHogFeatureFlagsCallback { loaded = it }, - ) - - assertEquals(mapOf("beta-ui" to true, "checkout" to "test"), loaded!!.variants) - assertFalse(loaded!!.errorsLoading) - assertEquals(true, sut.getFeatureFlag("beta-ui", sendFeatureFlagEvent = false)) - - sut.close() - } - @Test fun `onFeatureFlags replays bootstrapped flags to a listener registered after setup`() { val sut = @@ -448,6 +425,7 @@ internal class PostHogBootstrapTest { // the integration's /flags request is held, so this can only be the bootstrap delivery val loaded = updates.poll(5, TimeUnit.SECONDS) assertEquals(mapOf("beta-ui" to true), loaded?.variants) + assertFalse(loaded!!.errorsLoading) } finally { subscription.unsubscribe() release.countDown() @@ -457,29 +435,26 @@ internal class PostHogBootstrapTest { } @Test - fun `closing from the bootstrap flags callback drops setup's load for listeners`() { + fun `closing from an integration drops the bootstrap delivery and setup's load for listeners`() { val http = mockHttp(total = 5, response = MockResponse().setBody("""{"hasFeatureFlags":false}""")) - val completed = LinkedBlockingQueue() - val first = AtomicBoolean(true) val config = PostHogConfig(PROJECT_TOKEN, http.url("/").toString()).apply { storagePrefix = tmpDir.newFolder().absolutePath cachePreferences = PostHogMemoryPreferences() bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("beta-ui" to true)) - onFeatureFlags = - PostHogFeatureFlagsCallback { - // the bootstrap delivery closes the SDK; setup's own load completes later - if (first.compareAndSet(true, false)) PostHog.close() else completed.add(it) - } + addIntegration( + object : PostHogIntegration { + override fun install(postHog: PostHogInterface) { + PostHog.close() + } + }, + ) } try { PostHog.setup(config) + http.takeRequest(5, TimeUnit.SECONDS) - // setup's load notifies listeners just before this completion - assertNotNull(completed.poll(5, TimeUnit.SECONDS)) - - // close() cleared the snapshot, so only a load it superseded could refill it val updates = LinkedBlockingQueue() val subscription = PostHog.onFeatureFlags { updates.add(it) } assertNull(updates.poll(500, TimeUnit.MILLISECONDS)) diff --git a/posthog/src/test/java/com/posthog/PostHogConfigTest.kt b/posthog/src/test/java/com/posthog/PostHogConfigTest.kt index 7903540c3..db419ba18 100644 --- a/posthog/src/test/java/com/posthog/PostHogConfigTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogConfigTest.kt @@ -105,11 +105,6 @@ internal class PostHogConfigTest { assertEquals(listOf("api.example.com"), config.tracingHeaders) } - @Test - fun `onFeatureFlags is not set by default`() { - assertNull(config.onFeatureFlags) - } - @Test fun `logger uses NoOp by default`() { assertTrue(config.logger is PostHogNoOpLogger) From 265ec84f6f71d8fdcf485e4230d58d87b3a29090 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 3 Nov 2026 10:30:35 -0500 Subject: [PATCH 14/49] chore!: remove wireframe session replay capture (#908) * chore!: remove wireframe session replay capture Session replay always records masked screenshots, the mode `screenshot = true` already used. Remove `PostHogSessionReplayConfig.screenshot`, and `drawableConverter` / `PostHogDrawableConverter`, which only the wireframe builder read. Co-Authored-By: Claude Opus 5.5 * chore!: trim RRWireframe to the screenshot fields and drop RRStyle With wireframe capture gone, each window sends a single screenshot node, so the tree fields, RRStyle and the child-flattening diff are unused. Screenshot frames no longer carry an empty `style`, matching iOS 4.0. Co-Authored-By: Claude Opus 5.5 * fix(replay): scan for surfaces only during a legacy capture * fix(replay): discard legacy frames with an unplaceable masked view * style: format after merging main Co-Authored-By: Claude Opus 5.5 * fix(replay): keep Compose mask markers scoped to their subtree Merged semantics promote a child's postHogUnmask to its clickable parent, which skipped masking for every sibling. Read the unmerged tree instead. * fix(replay): mask overflowing and semantics-cleared Compose text Text with TextOverflow.Visible draws past its layout box, and clearAndSetSemantics removes the Text metadata the walk relies on. Both left text unmasked in screenshots. Co-Authored-By: Claude Opus 5.5 * fix(replay): map Compose text mask bounds to window space and include shadows Overflow bounds ignored graphicsLayer transforms, and text shadows could paint readable copies outside the mask. * perf(replay): reuse Compose text layouts across a capture's mask walks Text(String) rebuilds its paragraph on every GetTextLayoutResult call, which the verification and draw-sample walks repeated on the main thread. * fix(replay): refresh cached Compose text bounds on draw, clear once per walk A text style change is invisible until the layout is re-read, so any draw now drops the cached bounds. A walk over several ComposeViews also evicted earlier roots by clearing the shared cache for each one. Co-Authored-By: Claude Opus 5.5 * fix(replay): include text stroke extents in Compose mask bounds Co-Authored-By: Claude Opus 5.5 * fix(replay): measure Compose text hidden by clearAndSetSemantics Cleared semantics wipe the text semantics on the same layout node, so its overflow was masked only to the layout box. Read them from the text's modifier and reuse the painted-bounds measurement. Discard the frame when they can't be read, including on legacy walks. * docs(replay): list Compose masking changes and capture mode in the 4.0 guide Co-Authored-By: Claude Opus 5.5 * fix: log transient-state replay discards again --------- Co-authored-by: Claude Opus 5.5 --- .changeset/android-v4-major.md | 7 + docs/migration-3.x-to-4.0.md | 26 + posthog-android/api/posthog-android.api | 16 +- posthog-android/consumer-rules.pro | 17 + .../replay/PostHogDrawableConverter.kt | 18 - .../replay/PostHogReplayIntegration.kt | 796 +++++------------- .../replay/PostHogSessionReplayConfig.kt | 22 +- .../android/PostHogAndroidConfigTest.kt | 13 - .../PostHogReplayComposeMaskScopeTest.kt | 471 +++++++++++ .../replay/PostHogReplayIntegrationTest.kt | 184 ++-- .../replay/PostHogReplayMaskWalkBenchmark.kt | 1 - .../android/replay/PostHogReplayTestUtils.kt | 5 +- .../json/snapshots/batch-request.json | 2 +- .../java/com/posthog/android/sample/MyApp.kt | 1 - posthog/api/posthog.api | 94 +-- .../com/posthog/internal/replay/RRStyle.kt | 24 - .../posthog/internal/replay/RRWireframe.kt | 17 +- 17 files changed, 793 insertions(+), 921 deletions(-) delete mode 100644 posthog-android/src/main/java/com/posthog/android/replay/PostHogDrawableConverter.kt create mode 100644 posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayComposeMaskScopeTest.kt delete mode 100644 posthog/src/main/java/com/posthog/internal/replay/RRStyle.kt diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 302cf21d5..9d649778f 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -9,6 +9,13 @@ - **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload` instead to keep not sending `$feature_flag_called` - **Breaking:** remove the `defaultValue` parameter from `getFeatureFlag()`, which returns `null` for a flag with no value or a disabled SDK, so use `getFeatureFlag(key) ?: default` instead; a positional `Boolean` second argument now sets `sendFeatureFlagEvent`, and `$feature_flag_called` no longer reports a fallback from `getFeatureFlag()` or `isFeatureEnabled()` as the flag's value - **Breaking:** remove the deprecated `PostHogSessionReplayConfig.debouncerDelayMs`; use `throttleDelayMs` instead +- **Breaking:** remove wireframe session replay; replay always records masked screenshots, the mode `screenshot = true` already used. `PostHogSessionReplayConfig.screenshot` is removed, and so are `drawableConverter` and `PostHogDrawableConverter`, which only wireframe capture read + - Apps that relied on the default now upload screenshots. Masking still covers text inputs, images, `WebView`s, Compose semantics and `ph-no-capture` views and `Modifier.postHogMask()`, but custom-drawn views and other content the SDK doesn't recognize (for example maps or video) can now appear; mask them, or turn replay off with `sessionReplay = false` + - Jetpack Compose screens, which wireframe captured as empty boxes, are now recorded + - Apply `Modifier.postHogMask()` and `Modifier.postHogUnmask()` only to the element and its children, not to siblings merged into the same clickable row + - Compose text that draws past its layout box is masked in full, and nodes using `Modifier.clearAndSetSemantics` are masked while text or image masking is on; use `Modifier.postHogUnmask()` to show them + - `$sdk_debug_replay_capture_mode` is always `screenshot` + - Wrapper SDKs: the internal `RRWireframe` keeps only `id`, `x`, `y`, `width`, `height`, `type` and `base64`, and `RRStyle` is removed; screenshot frames no longer send an empty `style` - **Breaking:** return `null` instead of the raw string for a malformed, empty, whitespace-only or lenient-only (unquoted or single-quoted) feature flag payload from `getFeatureFlagResult(key)?.payload`; payloads must be valid JSON (a JSON `null` payload now also reads as `null` instead of the string `"null"`) - **Breaking:** make SDK-internal helpers in the `com.posthog.internal`, `com.posthog.android.internal` and `com.posthog.android.replay.internal` packages non-public - **Breaking:** remove the deprecated `remoteConfig` config option; the SDK now always loads remote config at setup diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 43835e3a7..8a7cf595a 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -35,6 +35,7 @@ All of these are compile errors. Calling them from an already-compiled library t | `getFeatureFlagPayload()`, on the instance and on `PostHog` | `getFeatureFlagResult()` | | `defaultValue` on `getFeatureFlag()` | `getFeatureFlag(key) ?: default` | | `PostHogSessionReplayConfig.debouncerDelayMs` | `throttleDelayMs` | +| `PostHogSessionReplayConfig.screenshot`, `drawableConverter`, `PostHogDrawableConverter` | nothing; replay always records screenshots | | `PostHogConfig.remoteConfig` | nothing; remote config always loads | | `PostHogConfig.onFeatureFlags` | `PostHog.onFeatureFlags()` before `setup()` | | `PostHogOnFeatureFlags` | `PostHogFeatureFlagsCallback` | @@ -233,6 +234,31 @@ If you read a payload as plain text, such as a payload saved as `hello` rather t A malformed payload cached by 3.x can still read as the raw string after the upgrade, until the app's first `/flags` response replaces it. +### Session replay records screenshots + +4.0 removes wireframe session replay. Replay always records masked screenshots, which is what `screenshot = true` already did. + +```kotlin +// 3.x +config.sessionReplayConfig.screenshot = true + +// 4.0: remove the line +``` + +Apps that relied on the default now upload screenshots: + +- Masking still covers text inputs, images, `WebView`s, Compose semantics, `ph-no-capture` views and `Modifier.postHogMask()`. +- Custom-drawn views and other content the SDK doesn't recognize, such as maps or video, can now appear in recordings. Mask them, or turn replay off with `sessionReplay = false`. +- Jetpack Compose screens, which wireframe captured as empty boxes, are now recorded. + +Compose masking also changed, including for apps that already set `screenshot = true`: + +- `Modifier.postHogMask()` and `Modifier.postHogUnmask()` apply only to the element and its children, not to siblings merged into the same clickable row. +- Text that draws past its layout box is masked in full. +- Nodes using `Modifier.clearAndSetSemantics` are masked while text or image masking is on. Use `Modifier.postHogUnmask()` to show them. + +The `$sdk_debug_replay_capture_mode` property is now always `screenshot`. + ### Other changes that don't fail the build The code you end up with after these two migrations compiles, so they're easy to miss: diff --git a/posthog-android/api/posthog-android.api b/posthog-android/api/posthog-android.api index 282d623b6..6e2efaee4 100644 --- a/posthog-android/api/posthog-android.api +++ b/posthog-android/api/posthog-android.api @@ -72,10 +72,6 @@ public final class com/posthog/android/internal/PostHogAndroidUtilsKt { public static final fun getApplicationInfo (Landroid/content/Context;)Landroid/content/pm/ApplicationInfo; } -public abstract interface class com/posthog/android/replay/PostHogDrawableConverter { - public abstract fun convert (Landroid/graphics/drawable/Drawable;)Landroid/graphics/Bitmap; -} - public abstract interface annotation class com/posthog/android/replay/PostHogInternalReplayApi : java/lang/annotation/Annotation { } @@ -118,18 +114,14 @@ public final class com/posthog/android/replay/PostHogSessionReplayConfig { public fun (Z)V public fun (ZZ)V public fun (ZZZ)V - public fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;)V - public fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;Z)V - public fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJ)V - public fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJLjava/lang/Double;)V - public synthetic fun (ZZZLcom/posthog/android/replay/PostHogDrawableConverter;ZJLjava/lang/Double;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (ZZZJ)V + public fun (ZZZJLjava/lang/Double;)V + public synthetic fun (ZZZJLjava/lang/Double;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun getCaptureLogcat ()Z public final fun getCaptureTouches ()Z - public final fun getDrawableConverter ()Lcom/posthog/android/replay/PostHogDrawableConverter; public final fun getMaskAllImages ()Z public final fun getMaskAllTextInputs ()Z public final fun getSampleRate ()Ljava/lang/Double; - public final fun getScreenshot ()Z public final fun getScreenshotColorMode ()Lcom/posthog/android/replay/PostHogScreenshotColorMode; public final fun getScreenshotCompressionQuality ()I public final fun getScreenshotScale ()Ljava/lang/Float; @@ -137,11 +129,9 @@ public final class com/posthog/android/replay/PostHogSessionReplayConfig { public final fun getVerifyScreenshotMaskAlignment ()Z public final fun setCaptureLogcat (Z)V public final fun setCaptureTouches (Z)V - public final fun setDrawableConverter (Lcom/posthog/android/replay/PostHogDrawableConverter;)V public final fun setMaskAllImages (Z)V public final fun setMaskAllTextInputs (Z)V public final fun setSampleRate (Ljava/lang/Double;)V - public final fun setScreenshot (Z)V public final fun setScreenshotColorMode (Lcom/posthog/android/replay/PostHogScreenshotColorMode;)V public final fun setScreenshotCompressionQuality (I)V public final fun setScreenshotScale (Ljava/lang/Float;)V diff --git a/posthog-android/consumer-rules.pro b/posthog-android/consumer-rules.pro index 162c59271..e3d07a524 100644 --- a/posthog-android/consumer-rules.pro +++ b/posthog-android/consumer-rules.pro @@ -108,6 +108,23 @@ public androidx.compose.ui.node.LayoutNode getLayoutNode(); } +# Read in reflection: added in Compose 1.4, after the version the SDK compiles against. +-keepclassmembers class androidx.compose.ui.text.TextStyle { + public androidx.compose.ui.graphics.drawscope.DrawStyle getDrawStyle(); +} +-keepclassmembers class androidx.compose.ui.text.SpanStyle { + public androidx.compose.ui.graphics.drawscope.DrawStyle getDrawStyle(); +} + +# Read in reflection: text semantics hidden by clearAndSetSemantics, newer than the version the SDK compiles against. +-keepclassmembers class * extends androidx.compose.ui.node.NodeCoordinator { + public androidx.compose.ui.Modifier$Node getTail(); +} +-keepclassmembers class * implements androidx.compose.ui.node.SemanticsModifierNode { + public void applySemantics(androidx.compose.ui.semantics.SemanticsPropertyReceiver); +} +-keepnames class androidx.compose.ui.node.DelegatingNode + # Uncomment this to preserve the line number information for # debugging stack traces. -keepattributes SourceFile,LineNumberTable diff --git a/posthog-android/src/main/java/com/posthog/android/replay/PostHogDrawableConverter.kt b/posthog-android/src/main/java/com/posthog/android/replay/PostHogDrawableConverter.kt deleted file mode 100644 index 7f6a30aa1..000000000 --- a/posthog-android/src/main/java/com/posthog/android/replay/PostHogDrawableConverter.kt +++ /dev/null @@ -1,18 +0,0 @@ -package com.posthog.android.replay - -import android.graphics.Bitmap -import android.graphics.drawable.Drawable - -/** - * Converts Android [Drawable] instances that the SDK cannot render by default into [Bitmap]s for - * session replay screenshots or wireframes. - */ -public fun interface PostHogDrawableConverter { - /** - * Converts [drawable] to a bitmap representation. - * - * @param drawable Drawable to convert. - * @return A bitmap to capture, or `null` when this converter cannot handle the drawable. - */ - public fun convert(drawable: Drawable): Bitmap? -} diff --git a/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt b/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt index 8e863062e..20dc931ff 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt +++ b/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt @@ -2,31 +2,25 @@ package com.posthog.android.replay import android.annotation.SuppressLint import android.content.Context -import android.content.res.Resources import android.graphics.Bitmap import android.graphics.Canvas import android.graphics.Color import android.graphics.Paint import android.graphics.Point -import android.graphics.PorterDuff import android.graphics.Rect import android.graphics.RectF -import android.graphics.Typeface import android.graphics.drawable.BitmapDrawable import android.graphics.drawable.ColorDrawable import android.graphics.drawable.Drawable import android.graphics.drawable.GradientDrawable import android.graphics.drawable.InsetDrawable import android.graphics.drawable.LayerDrawable -import android.graphics.drawable.RippleDrawable import android.graphics.drawable.VectorDrawable import android.os.Build import android.os.Handler import android.os.HandlerThread import android.os.Looper import android.text.InputType -import android.util.TypedValue -import android.view.Gravity import android.view.MotionEvent import android.view.PixelCopy import android.view.SurfaceView @@ -39,22 +33,24 @@ import android.view.WindowManager import android.view.WindowManager.LayoutParams.FLAG_SECURE import android.webkit.WebView import android.widget.Button -import android.widget.CheckBox -import android.widget.CompoundButton import android.widget.EditText import android.widget.ImageView -import android.widget.ProgressBar -import android.widget.RadioButton -import android.widget.RadioGroup -import android.widget.RatingBar import android.widget.Spinner -import android.widget.Switch import android.widget.TextView +import androidx.compose.ui.graphics.drawscope.Stroke import androidx.compose.ui.node.RootForTest +import androidx.compose.ui.semantics.SemanticsActions +import androidx.compose.ui.semantics.SemanticsConfiguration import androidx.compose.ui.semantics.SemanticsNode import androidx.compose.ui.semantics.SemanticsProperties import androidx.compose.ui.semantics.SemanticsPropertyKey +import androidx.compose.ui.semantics.SemanticsPropertyReceiver import androidx.compose.ui.semantics.getAllSemanticsNodes +import androidx.compose.ui.semantics.getOrNull +import androidx.compose.ui.text.AnnotatedString +import androidx.compose.ui.text.TextLayoutResult +import androidx.compose.ui.text.style.TextOverflow +import androidx.compose.ui.unit.IntSize import androidx.core.view.ViewCompat import androidx.core.view.WindowInsetsCompat import com.posthog.PostHogEventName @@ -96,7 +92,6 @@ import com.posthog.internal.replay.RRMetaEvent import com.posthog.internal.replay.RRMouseInteraction import com.posthog.internal.replay.RRMutatedNode import com.posthog.internal.replay.RRRemovedNode -import com.posthog.internal.replay.RRStyle import com.posthog.internal.replay.RRWireframe import com.posthog.internal.replay.capture import curtains.Curtains @@ -116,6 +111,8 @@ import java.util.concurrent.TimeUnit import java.util.concurrent.atomic.AtomicBoolean import kotlin.math.ceil import kotlin.math.floor +import kotlin.math.max +import kotlin.math.min public class PostHogReplayIntegration( private val context: Context, @@ -210,9 +207,6 @@ public class PostHogReplayIntegration( private val isNativeSdk: Boolean get() = (config.sdkName != "posthog-flutter") - private val isScreenshotCapable: Boolean - get() = config.sessionReplayConfig.screenshot || !isNativeSdk - @Volatile private var postHog: PostHogInterface? = null @@ -259,7 +253,7 @@ public class PostHogReplayIntegration( } // Reused across frames; draw-time walks only ever run on the main thread. - private val drawSampleWalk = MaskWalk() + private val drawSampleWalk = MaskWalk(reuseTextLayouts = true) internal fun onDrawCallback( view: View, @@ -267,15 +261,21 @@ public class PostHogReplayIntegration( ) { // Keep this first so a draw that overlaps the verified pre-walk cannot go unnoticed. drawState.recordDraw() + // A text style change only shows up in a new layout result, and it has to draw to reach pixels. + textPaintedBoundsCache.clear() val classifyLegacyDraw = !shouldVerifyMaskAlignment(view, drawState) || drawState.isLegacyCaptureActive if (classifyLegacyDraw) { val isOnlyAnimationRedraw = - isScreenshotCapable && - !drawState.didLayoutSinceReset && - (view.hasTransientState() || view.hasActiveSurfaceRendering()) && + !drawState.didLayoutSinceReset && + // The surface scan walks the whole tree, so it runs only while a legacy + // capture can read the verdict; beginLegacyCapture resets it anyway. + ( + view.hasTransientState() || + (drawState.isLegacyCaptureActive && view.hasActiveSurfaceRendering()) + ) && !view.isAnimationRunning() drawState.recordLegacyAnimationRedraw(isOnlyAnimationRedraw) } @@ -755,7 +755,7 @@ public class PostHogReplayIntegration( } } } - val delivered = generateSnapshot(WeakReference(decorView), WeakReference(window), forceScreenshot = true) + val delivered = generateSnapshot(WeakReference(decorView), WeakReference(window)) if (!delivered) { config.logger.log("Session Replay bridge capture produced no frame (will retry next tick).") } @@ -771,25 +771,12 @@ public class PostHogReplayIntegration( } } - private fun Resources.Theme.toRGBColor(): String? { - val value = TypedValue() - resolveAttribute(android.R.attr.windowBackground, value, true) - return if (value.type >= TypedValue.TYPE_FIRST_COLOR_INT && - value.type <= TypedValue.TYPE_LAST_COLOR_INT - ) { - value.data - } else { - null - }?.toRGBColor() - } - // internal (not private) so tests can drive a snapshot pass directly. // Returns whether a frame was actually produced (false on every early bail), // so the bridge caller can tell "captured" from "silently skipped". internal fun generateSnapshot( viewRef: WeakReference, windowRef: WeakReference, - forceScreenshot: Boolean = false, ): Boolean { if (!isActive()) return false val postHog = postHog ?: return false @@ -808,28 +795,11 @@ public class PostHogReplayIntegration( val timestamp = config.dateProvider.currentTimeMillis() - val useScreenshot = config.sessionReplayConfig.screenshot || forceScreenshot val wireframe = - if (useScreenshot) { - view.toScreenshotWireframe( - window, - status.drawState, - ) ?: return false - } else if (window.isSecure()) { - view.toSecureWireframe() ?: return false - } else { - val tree = view.toWireframe() ?: return false - // The window can turn secure while the tree is walked. - if (window.isSecure()) view.toSecureWireframe() ?: return false else tree - } - - // if the decorView has no backgroundColor, we use the theme color - // no need to do this if we are capturing a screenshot - if (wireframe.style?.backgroundColor == null && !useScreenshot) { - context.theme?.toRGBColor()?.let { - wireframe.style?.backgroundColor = it - } - } + view.toScreenshotWireframe( + window, + status.drawState, + ) ?: return false val events = synchronized(decorViews) { @@ -895,40 +865,21 @@ public class PostHogReplayIntegration( events.add(event) status.sentFullSnapshot = true } else { + // Each window sends one screenshot node, so a frame is an update to that node. val lastSnapshot = status.lastSnapshot - val lastSnapshots = if (lastSnapshot != null) listOf(lastSnapshot) else emptyList() - val (addedItems, removedItems, updatedItems) = - findAddedAndRemovedItems( - lastSnapshots.flattenChildren(), - listOf(wireframe).flattenChildren(), - ) - - val addedNodes = mutableListOf() - addedItems.forEach { - val item = RRMutatedNode(it, parentId = it.parentId) - addedNodes.add(item) - } - - val removedNodes = mutableListOf() - removedItems.forEach { - val item = RRRemovedNode(it.id, parentId = it.parentId) - removedNodes.add(item) - } - - val updatedNodes = mutableListOf() - updatedItems.forEach { - val item = RRMutatedNode(it, parentId = it.parentId) - updatedNodes.add(item) - } - - if (addedNodes.isNotEmpty() || removedNodes.isNotEmpty() || updatedNodes.isNotEmpty()) { - val incrementalMutationData = - RRIncrementalMutationData( - adds = addedNodes.ifEmpty { null }, - removes = removedNodes.ifEmpty { null }, - updates = updatedNodes.ifEmpty { null }, - ) + val incrementalMutationData = + when { + lastSnapshot == null -> RRIncrementalMutationData(adds = listOf(RRMutatedNode(wireframe))) + lastSnapshot.id != wireframe.id -> + RRIncrementalMutationData( + adds = listOf(RRMutatedNode(wireframe)), + removes = listOf(RRRemovedNode(lastSnapshot.id)), + ) + lastSnapshot != wireframe -> RRIncrementalMutationData(updates = listOf(RRMutatedNode(wireframe))) + else -> null + } + if (incrementalMutationData != null) { val incrementalSnapshotEvent = RRIncrementalSnapshotEvent( mutationData = incrementalMutationData, @@ -1003,8 +954,8 @@ public class PostHogReplayIntegration( /** * Checks whether the view has a non-empty visible rect. Walk callers pass their walk so - * its scratch objects are reused; other callers allocate per call (see the wireframe - * vs delayed-screenshot-walk race test). + * its scratch objects are reused; other callers allocate per call (see the concurrent + * capture vs delayed-screenshot-walk race test). */ private fun View.hasGlobalVisibleRect(walk: MaskWalk? = null): Boolean { return if (isViewStateStableForMatrixOperations()) { @@ -1070,7 +1021,11 @@ public class PostHogReplayIntegration( internal class MaskWalk( val failClosed: Boolean = true, private val shouldAbort: (() -> Boolean)? = null, + // True for walks re-checking a capture's first walk; false re-measures text. + val reuseTextLayouts: Boolean = false, ) { + var textLayoutsCleared: Boolean = false + val rects: MutableList = mutableListOf() var poisoned: Boolean = false var aborted: Boolean = false @@ -1347,7 +1302,13 @@ public class PostHogReplayIntegration( config.logger.log("View is not a RootForTest: $view") return@Runnable } - val semanticsNodes = semanticsOwner.getAllSemanticsNodes(true) + // Once per walk: a walk visits every ComposeView, all sharing this cache. + if (!walk.reuseTextLayouts && !walk.textLayoutsCleared) { + textPaintedBoundsCache.clear() + walk.textLayoutsCleared = true + } + // Unmerged: a merged node inherits a child's postHogUnmask, exposing its siblings. + val semanticsNodes = semanticsOwner.getAllSemanticsNodes(false) semanticsNodes.forEach { node -> val hasText = node.config.contains(SemanticsProperties.Text) @@ -1368,7 +1329,7 @@ public class PostHogReplayIntegration( // postHogMask forces masking isMaskEnabled -> { - maskableWidgets.add(node.boundsInWindow.toRect()) + maskableWidgets.add(node.maskBounds()) } // no active modifier, apply default config rules @@ -1376,11 +1337,17 @@ public class PostHogReplayIntegration( when { (hasText || hasEditableText) && (config.sessionReplayConfig.maskAllTextInputs || hasPassword) -> { - maskableWidgets.add(node.boundsInWindow.toRect()) + maskableWidgets.add(node.maskBounds()) } hasImage && config.sessionReplayConfig.maskAllImages -> { - maskableWidgets.add(node.boundsInWindow.toRect()) + maskableWidgets.add(node.maskBounds()) + } + + // clearAndSetSemantics hides what the node draws, so assume it is sensitive. + node.config.isClearingSemantics && + (config.sessionReplayConfig.maskAllTextInputs || config.sessionReplayConfig.maskAllImages) -> { + maskableWidgets.add(node.maskBounds()) } } } @@ -1403,12 +1370,137 @@ public class PostHogReplayIntegration( for (rect in maskableWidgets) { walk.addRect(rect) } - } else if (walk.failClosed) { - // Compose mask rects are missing or incomplete, so fail closed. + } else if (walk.failClosed || completed) { + // Compose mask rects are missing or incomplete, so fail closed. Legacy walks only tolerate a timeout. walk.poisoned = true } } + // Text can draw past its layout box, so cover what it paints, mapped through the node's transforms. + private fun SemanticsNode.maskBounds(): Rect { + val bounds = boundsInWindow.toRect() + val painted = textPaintedBounds() ?: return bounds + val coordinates = layoutInfo.coordinates + if (!coordinates.isAttached) { + return bounds + } + val corners = + listOf(painted.topLeft, painted.topRight, painted.bottomLeft, painted.bottomRight) + .map { coordinates.localToWindow(it) } + bounds.union( + floor(corners.minOf { it.x }).toInt(), + floor(corners.minOf { it.y }).toInt(), + ceil(corners.maxOf { it.x }).toInt(), + ceil(corners.maxOf { it.y }).toInt(), + ) + return bounds + } + + private class CachedTextPaintedBounds( + val text: List?, + val size: IntSize, + val bounds: androidx.compose.ui.geometry.Rect?, + ) + + // clearAndSetSemantics also wipes text semantics on its own layout node, so read them from the text's + // modifier. Throws when that can't be read, which discards the frame. Reflection: these APIs are newer + // than the version the SDK compiles against. + private fun SemanticsNode.textSemantics(): SemanticsConfiguration { + if (!config.isClearingSemantics) { + return config + } + for (info in layoutInfo.getModifierInfo()) { + val coordinates = info.coordinates + val node = coordinates.javaClass.getMethod("getTail").invoke(coordinates) ?: continue + val applySemantics = + try { + node.javaClass.getMethod("applySemantics", SemanticsPropertyReceiver::class.java) + } catch (e: NoSuchMethodException) { + check(!node.isDelegatingNode()) { "Can't read the semantics delegated by $node" } + continue + } + val semantics = SemanticsConfiguration() + applySemantics.invoke(node, semantics) + if (semantics.contains(SemanticsProperties.Text)) { + return semantics + } + } + return config + } + + private fun Any.isDelegatingNode(): Boolean { + return generateSequence>(javaClass) { it.superclass }.any { it.name == "androidx.compose.ui.node.DelegatingNode" } + } + + // Text(String) rebuilds its paragraph on every GetTextLayoutResult call, so a capture's walks + // share the result until the next draw. Main thread only, like the traversal that reads it. + private val textPaintedBoundsCache = HashMap() + + private fun SemanticsNode.textPaintedBounds(): androidx.compose.ui.geometry.Rect? { + val semantics = textSemantics() + if (!semantics.contains(SemanticsProperties.Text) || semantics.contains(SemanticsProperties.EditableText)) { + return null + } + val text = semantics.getOrNull(SemanticsProperties.Text) + textPaintedBoundsCache[id]?.let { + if (it.text == text && it.size == size) { + return it.bounds + } + } + return measureTextPaintedBounds(semantics).also { + textPaintedBoundsCache[id] = CachedTextPaintedBounds(text, size, it) + } + } + + // Local bounds of what the text paints outside its layout box, or null if it stays inside. + private fun SemanticsNode.measureTextPaintedBounds(semantics: SemanticsConfiguration): androidx.compose.ui.geometry.Rect? { + val results = mutableListOf() + if (semantics.getOrNull(SemanticsActions.GetTextLayoutResult)?.action?.invoke(results) != true) { + return null + } + val layout = results.firstOrNull() ?: return null + val input = layout.layoutInput + var glyphs = androidx.compose.ui.geometry.Rect(0f, 0f, size.width.toFloat(), size.height.toFloat()) + var overdraws = false + if (input.overflow == TextOverflow.Visible) { + val paragraph = layout.multiParagraph + // This result is re-wrapped to the box, but softWrap = false draws one unwrapped line. + val width = if (input.softWrap) paragraph.width else max(paragraph.width, paragraph.intrinsics.maxIntrinsicWidth) + glyphs = glyphs.copy(right = max(glyphs.right, width), bottom = max(glyphs.bottom, paragraph.height)) + overdraws = true + } + val strokes = listOfNotNull(input.style.textStroke()) + input.text.spanStyles.mapNotNull { it.item.textStroke() } + strokes.maxOfOrNull { it.width / 2 * max(1f, it.miter) }?.let { + glyphs = glyphs.inflate(it) + overdraws = true + } + var painted = glyphs + val shadows = listOfNotNull(input.style.shadow) + input.text.spanStyles.mapNotNull { it.item.shadow } + for (shadow in shadows) { + // Skia's Gaussian blur reaches about 1.73x the radius. + painted = painted.expandToInclude(glyphs.translate(shadow.offset).inflate(shadow.blurRadius * 2)) + overdraws = true + } + return if (overdraws) painted else null + } + + // drawStyle arrived in Compose 1.4, after the version the SDK compiles against. Older runtimes can't stroke text. + private fun Any.textStroke(): Stroke? { + return try { + javaClass.getMethod("getDrawStyle").invoke(this) as? Stroke + } catch (e: NoSuchMethodException) { + null + } + } + + private fun androidx.compose.ui.geometry.Rect.expandToInclude(other: androidx.compose.ui.geometry.Rect) = + androidx.compose.ui.geometry.Rect( + min(left, other.left), + min(top, other.top), + max(right, other.right), + max(bottom, other.bottom), + ) + private fun androidx.compose.ui.geometry.Rect.toRect(): Rect { return Rect(left.toInt(), top.toInt(), right.toInt(), bottom.toInt()) } @@ -1704,7 +1796,7 @@ public class PostHogReplayIntegration( if (width != sourceWidth || height != sourceHeight) { return@runOnMainThreadBlocking null } - MaskWalk().also { + MaskWalk(reuseTextLayouts = true).also { if (!drawState.isCaptureInvalid(armedCapture.token)) { findMaskableWidgets(this, it) } @@ -1910,7 +2002,6 @@ public class PostHogReplayIntegration( height = height, type = "screenshot", base64 = base64, - style = RRStyle(), ) } @@ -2084,7 +2175,6 @@ public class PostHogReplayIntegration( height = height, type = "screenshot", base64 = base64, - style = RRStyle(), ) } @@ -2097,503 +2187,6 @@ public class PostHogReplayIntegration( return this.isTextInputSensitive(ancestorUnmasked) } - // A FLAG_SECURE window is recorded as one black rectangle, with nothing from its view tree. - private fun View.toSecureWireframe(): RRWireframe? { - if (!isVisible()) { - return null - } - val coordinates = IntArray(2) - if (isViewStateStableForMatrixOperations()) { - getLocationOnScreen(coordinates) - } - return RRWireframe( - id = System.identityHashCode(this), - x = coordinates[0].densityValue(screenDensity), - y = coordinates[1].densityValue(screenDensity), - width = width.densityValue(screenDensity), - height = height.densityValue(screenDensity), - style = RRStyle().apply { backgroundColor = "#000000" }, - ) - } - - private fun View.toWireframe( - parentId: Int? = null, - ancestorUnmasked: Boolean = false, - ): RRWireframe? { - val view = this - if (!view.isVisible()) { - return null - } - - val isUnmasked = ancestorUnmasked || view.isUnmasked() - - val viewId = System.identityHashCode(view) - - val coordinates = IntArray(2) - if (view.isViewStateStableForMatrixOperations()) { - view.getLocationOnScreen(coordinates) - } else { - // Use zero coordinates as fallback when view state is unstable - coordinates[0] = 0 - coordinates[1] = 0 - } - val x = coordinates[0].densityValue(screenDensity) - val y = coordinates[1].densityValue(screenDensity) - val width = view.width.densityValue(screenDensity) - val height = view.height.densityValue(screenDensity) - var base64: String? = null - - var type: String? = null - if (view.id == android.R.id.statusBarBackground) { - type = "status_bar" - } - if (view.id == android.R.id.navigationBarBackground) { - type = "navigation_bar" - } - - val style = RRStyle() - view.background?.let { background -> - background.toRGBColor()?.let { color -> - style.backgroundColor = color - } ?: run { - style.backgroundImage = background.base64(view.width, view.height) - } - } - - var checked: Boolean? = null - - var text: String? = null - var inputType: String? = null - var value: Any? = null - // button inherits from textview - if (view is TextView) { - val viewText = view.text?.toString() - if (!viewText.isNullOrEmpty()) { - text = - if (!view.shouldMaskTextView(isUnmasked)) { - viewText - } else { - viewText.mask() - } - } - - val hint = view.hint?.toString() - if (text.isNullOrEmpty() && !hint.isNullOrEmpty()) { - text = - if (!view.shouldMaskTextView(isUnmasked)) { - hint - } else { - hint.mask() - } - } - - type = "text" - style.color = view.currentTextColor.toRGBColor() - - // CompoundButton is a subclass of CheckBox, RadioButton, Switch, etc - if (view is Button && view !is CompoundButton) { - style.borderWidth = 1 - style.borderColor = "#000000" - type = "input" - inputType = "button" - value = text - text = null - } -// TODO: do this when we upgrade API to 34 -// if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) { -// style.fontFamily = view.typeface?.systemFontFamilyName -// } else { - view.typeface?.let { - when (it) { - Typeface.DEFAULT -> style.fontFamily = "sans-serif" - Typeface.DEFAULT_BOLD -> style.fontFamily = "sans-serif-bold" - Typeface.MONOSPACE -> style.fontFamily = "monospace" - Typeface.SERIF -> style.fontFamily = "serif" - } - } -// } - style.fontSize = view.textSize.toInt().densityValue(screenDensity) - when (view.textAlignment) { - View.TEXT_ALIGNMENT_CENTER -> { - style.verticalAlign = "center" - style.horizontalAlign = "center" - } - View.TEXT_ALIGNMENT_TEXT_END, View.TEXT_ALIGNMENT_VIEW_END -> { - style.verticalAlign = "center" - style.horizontalAlign = "right" - } - View.TEXT_ALIGNMENT_TEXT_START, View.TEXT_ALIGNMENT_VIEW_START -> { - style.verticalAlign = "center" - style.horizontalAlign = "left" - } - View.TEXT_ALIGNMENT_GRAVITY -> { - val horizontalAlignment = - when (view.gravity.and(Gravity.HORIZONTAL_GRAVITY_MASK)) { - Gravity.START, Gravity.LEFT -> "left" - Gravity.END, Gravity.RIGHT -> "right" - Gravity.CENTER, Gravity.CENTER_HORIZONTAL -> "center" - else -> "left" - } - style.horizontalAlign = horizontalAlignment - - val verticalAlignment = - when (view.gravity.and(Gravity.VERTICAL_GRAVITY_MASK)) { - Gravity.TOP -> "top" - Gravity.BOTTOM -> "bottom" - Gravity.CENTER_VERTICAL, Gravity.CENTER -> "center" - else -> "center" - } - style.verticalAlign = verticalAlignment - } - else -> { - style.verticalAlign = "center" - style.horizontalAlign = "left" - } - } - - // left, top, right, bottom - view.compoundDrawables.forEachIndexed { index, drawable -> - drawable?.let { - val drawableBase64 = it.base64(view.width, view.height) - // TODO: the 2 other possible drawables (top and bottom are not common) - when (index) { - 0 -> style.iconLeft = drawableBase64 -// 1 -> style.iconTop = drawableBase64 - 2 -> style.iconRight = drawableBase64 -// 3 -> style.iconBottom = drawableBase64 - } - } - } - - // Do not set padding if the text is centered, otherwise the padding will be off - if (style.verticalAlign != "center") { - style.paddingTop = view.totalPaddingTop.densityValue(screenDensity) - style.paddingBottom = view.totalPaddingBottom.densityValue(screenDensity) - } - if (style.horizontalAlign != "center") { - style.paddingLeft = view.totalPaddingLeft.densityValue(screenDensity) - style.paddingRight = view.totalPaddingRight.densityValue(screenDensity) - } - } - - var label: String? = null - if (view is CheckBox) { - type = "input" - inputType = "checkbox" - label = text - text = null - checked = view.isChecked - } - if (view is RadioGroup) { - type = "radio_group" - } - if (view is RadioButton) { - type = "input" - inputType = "radio" - label = text - text = null - checked = view.isChecked - } - - if (view is EditText) { - type = "input" - inputType = "text_area" - value = text - text = null - } - var options: List? = null - if (view is Spinner) { - type = "input" - inputType = "select" - val mask = view.shouldMaskSpinner(isUnmasked) - view.selectedItem?.let { - val theValue = - if (!mask) { - it.toString() - } else { - it.toString().mask() - } - value = theValue - } - - view.adapter?.let { - val items = mutableListOf() - for (i in 0 until it.count) { - val item = it.getItem(i)?.toString() ?: continue - - val theItem = - if (!mask) { - item - } else { - item.mask() - } - - items.add(theItem) - } - options = items.ifEmpty { null } - } - } - - if (view is ImageView) { - type = "image" - if (!view.shouldMaskImage(isUnmasked)) { - // TODO: we can probably do a LRU caching here for already captured images - view.drawable?.let { drawable -> - base64 = drawable.base64(view.width, view.height) -// style.paddingTop = view.paddingTop.densityValue(screenDensity) -// style.paddingBottom = view.paddingBottom.densityValue(screenDensity) -// style.paddingLeft = view.paddingLeft.densityValue(screenDensity) -// style.paddingRight = view.paddingRight.densityValue(screenDensity) - } - } - } - - var max: Int? = null // can be a Int or Float - if (view is ProgressBar) { - inputType = "progress" - type = "input" - val bar = - if (view.isIndeterminate) { - "circular" - } else { - max = view.max - value = view.progress - "horizontal" - } - style.bar = bar - } - if (view is RatingBar) { - style.bar = "rating" - - // since stars allow half stars, we need to divide the max by 2, because - // 5 stars is 10 - max = (view.max / 2) - value = view.rating - } - - if (view is Switch) { - type = "input" - inputType = "toggle" - checked = view.isChecked - label = text - text = null - } - - // TODO: people might be used androidx.webkit:webkit though - if (view is WebView) { - type = "web_view" - } - - val children = mutableListOf() - if (view is ViewGroup && view.childCount > 0) { - for (i in 0 until view.childCount) { - val viewChild = view.getChildAt(i) ?: continue - viewChild.toWireframe(parentId = viewId, ancestorUnmasked = isUnmasked)?.let { - children.add(it) - } - } - } - - return RRWireframe( - id = viewId, - x = x, - y = y, - width = width, - height = height, - text = text, - type = type, - style = style, - childWireframes = children.ifEmpty { null }, - base64 = base64, - parentId = parentId, - disabled = !view.isEnabled, - checked = checked, - inputType = inputType, - value = value, - label = label, - options = options, - max = max, - ) - } - - private fun runDrawableConverter(drawable: Drawable): Bitmap? { - return config.sessionReplayConfig.drawableConverter?.convert(drawable) - } - - @SuppressLint("NewApi") - private fun Drawable.toRGBColor(): String? { - when (this) { - is ColorDrawable -> { - return color.toRGBColor() - } - - is RippleDrawable -> { - try { - return getFirstDrawable()?.toRGBColor() - } catch (e: Throwable) { - // ignore - } - } - - is InsetDrawable -> { - return drawable?.toRGBColor() - } - - is GradientDrawable -> { - colors?.let { rgcColors -> - if (rgcColors.isNotEmpty()) { - // Get the first color from the array - val color = rgcColors[0] - - // Extract RGB values - val red = Color.red(color) - val green = Color.green(color) - val blue = Color.blue(color) - - // Construct the RGB color - val rgb = Color.rgb(red, green, blue) - return rgb.toRGBColor() - } - } - color?.let { - if (it.defaultColor != -1) { - return it.defaultColor.toRGBColor() - } - } - } - } - return null - } - - private fun Drawable.base64( - width: Int, - height: Int, - cloned: Boolean = false, - ): String? { - val convertedBitmap = runDrawableConverter(this) - if (convertedBitmap != null) { - return convertedBitmap.webpBase64() - } - - var clonedDrawable = this - if (!cloned) { - clonedDrawable = copy() ?: return null - } - - when (clonedDrawable) { - is BitmapDrawable -> { - try { - return clonedDrawable.bitmap.webpBase64() - } catch (_: Throwable) { - // ignore - } - } - - is LayerDrawable -> { - clonedDrawable.getFirstDrawable()?.let { - return it.base64(width, height) - } - } - - is InsetDrawable -> { - clonedDrawable.drawable?.let { - return it.base64(width, height) - } - } - } - - try { - val bitmap = clonedDrawable.toBitmap(width, height) - val base64 = bitmap.webpBase64() - bitmap.recycle() - return base64 - } catch (_: Throwable) { - // ignore - } - return null - } - - private fun LayerDrawable.getFirstDrawable(): Drawable? { - for (i in 0 until numberOfLayers) { - getDrawable(i)?.let { - return it - } - } - - return null - } - - private fun Int.toRGBColor(): String { - // TODO: missing alpha - return String.format("#%06X", (0xFFFFFF and this)) - } - - private fun List.flattenChildren(): List { - val result = mutableListOf() - - for (item in this) { - result.add(item) - - item.childWireframes?.let { - result.addAll(it.flattenChildren()) - } - } - - return result - } - - private fun findAddedAndRemovedItems( - oldItems: List, - newItems: List, - ): Triple, List, List> { - val oldMap = oldItems.associateBy { it.id } - val newMap = newItems.associateBy { it.id } - - // Create HashSet to track unique IDs - val oldItemIds = HashSet(oldItems.map { it.id }) - val newItemIds = HashSet(newItems.map { it.id }) - - // Find added items by subtracting oldItemIds from newItemIds - val addedIds = newItemIds - oldItemIds - val addedItems = newItems.filter { it.id in addedIds } - - // Find removed items by subtracting newItemIds from oldItemIds - val removedIds = oldItemIds - newItemIds - val removedItems = oldItems.filter { it.id in removedIds } - - val updatedItems = mutableListOf() - - // Find updated items by finding the intersection of oldItemIds and newItemIds - val sameItems = oldItemIds.intersect(newItemIds) - - for (id in sameItems) { - // we have to copy without the childWireframes, otherwise they all would be different - // if one of the child is different, but we only wanna compare the parent - val oldItem = oldMap[id]?.copy(childWireframes = null) ?: continue - val newItem = newMap[id] ?: continue - val newItemCopy = newItem.copy(childWireframes = null) - - // If the items are different (any property has a different value), add the new item to the updatedItems list - if (oldItem != newItemCopy) { - updatedItems.add(newItem) - } - } - - return Triple(addedItems, removedItems, updatedItems) - } - - private fun Drawable.toBitmap( - width: Int, - height: Int, - ): Bitmap { - val bitmap = Bitmap.createBitmap(displayMetrics, width, height, Bitmap.Config.ARGB_8888) - val canvas = Canvas(bitmap) - canvas.drawColor(Color.TRANSPARENT, PorterDuff.Mode.MULTIPLY) - setBounds(0, 0, canvas.width, canvas.height) - draw(canvas) - return bitmap - } - private fun MotionEvent.getRawXCompat(index: Int): Float { return if (index < 0 || index >= pointerCount) { rawX // Fallback to single-touch `rawX` to prevent crashes @@ -2628,14 +2221,6 @@ public class PostHogReplayIntegration( contentDescription?.toString()?.contains(PH_NO_MASK_LABEL, ignoreCase = true) == true } - private fun Drawable.copy(): Drawable? { - return constantState?.newDrawable() - } - - private fun String.mask(): String { - return "*".repeat(length) - } - @SuppressLint("AnnotateVersionCheck") private fun isSupported(): Boolean { return Build.VERSION.SDK_INT >= Build.VERSION_CODES.O @@ -2776,8 +2361,7 @@ public class PostHogReplayIntegration( props["\$sdk_debug_replay_pending_trigger_conditions"] = pendingConditions } - val captureMode = if (isScreenshotCapable) "screenshot" else "wireframe" - props["\$sdk_debug_replay_capture_mode"] = captureMode + props["\$sdk_debug_replay_capture_mode"] = "screenshot" props["\$sdk_debug_replay_internal_buffer_length"] = if (buffering) replayQueue?.bufferDepth ?: 0 else replayQueue?.size ?: 0 diff --git a/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt b/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt index 1d59c7b2e..2667e72f0 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt +++ b/posthog-android/src/main/java/com/posthog/android/replay/PostHogSessionReplayConfig.kt @@ -9,6 +9,8 @@ import com.posthog.android.replay.internal.MIN_SCREENSHOT_SCALE * * Use this as `PostHogAndroidConfig.sessionReplayConfig` when enabling session replay through * `PostHogConfig.sessionReplay`. + * + * Windows that set `FLAG_SECURE` are recorded as a solid black frame, and their touches are not recorded. */ public class PostHogSessionReplayConfig @JvmOverloads @@ -28,22 +30,8 @@ public class PostHogSessionReplayConfig * Defaults to true */ public var captureLogcat: Boolean = true, - /** - * Converts custom Drawable to Bitmap - * By default PostHog tries to convert the Drawable to Bitmap, the supported types are - * BitmapDrawable, ColorDrawable, GradientDrawable, InsetDrawable, LayerDrawable, RippleDrawable - */ - public var drawableConverter: PostHogDrawableConverter? = null, - /** - * By default Session replay will capture all the views on the screen as a wireframe, - * By enabling this option, PostHog will capture the screenshot of the screen. - * The screenshot may contain sensitive information, use with caution. - * In both modes, windows that set `FLAG_SECURE` are recorded as a solid black frame, and their touches are not recorded. - */ - public var screenshot: Boolean = false, /** * Throttling delay used to reduce the number of snapshots captured and reduce performance impact. - * This is used for capturing the view as a wireframe or screenshot. * The lower the number, the more snapshots are captured and the higher the performance impact. * Defaults to 1000ms = 1s. */ @@ -79,7 +67,7 @@ public class PostHogSessionReplayConfig * Higher values generally retain more detail and produce larger payloads. * Compression is lossy, except on Android 10 (API 29), where the platform's legacy * WebP encoder uses lossless compression at quality 100. - * Does not change screenshot resolution or enable screenshot capture. + * Does not change screenshot resolution. */ @PostHogExperimental @Volatile @@ -94,7 +82,7 @@ public class PostHogSessionReplayConfig * less capture at full resolution. For example, 0.5 captures half the width and height. * Dimensions are rounded up to at least one pixel; the logical replay viewport is unchanged. * NaN and infinite values reset the scale to `null`. - * Does not change compression quality, color mode, or enable screenshot capture. + * Does not change compression quality or color mode. */ @PostHogExperimental @Volatile @@ -108,7 +96,7 @@ public class PostHogSessionReplayConfig * to preserve alpha and color precision before lossy WebP compression. * [PostHogScreenshotColorMode.RGB_565] uses less bitmap memory but reduces color precision * and removes alpha, making transparent window regions appear black. Devices that reject - * RGB_565 fall back to ARGB_8888. Does not enable screenshot capture. + * RGB_565 fall back to ARGB_8888. */ @PostHogExperimental @Volatile diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidConfigTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidConfigTest.kt index 1aa4837d8..261ed9384 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidConfigTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidConfigTest.kt @@ -42,19 +42,6 @@ internal class PostHogAndroidConfigTest { assertEquals(30, config.sessionReplayConfig.screenshotCompressionQuality) assertNull(config.sessionReplayConfig.screenshotScale) assertEquals(PostHogScreenshotColorMode.ARGB_8888, config.sessionReplayConfig.screenshotColorMode) - assertFalse(config.sessionReplayConfig.screenshot) - } - - @Test - fun `screenshot settings are independent of capture enablement`() { - config.sessionReplayConfig.screenshotScale = 0.5f - config.sessionReplayConfig.screenshotCompressionQuality = 60 - config.sessionReplayConfig.screenshotColorMode = PostHogScreenshotColorMode.RGB_565 - - assertEquals(0.5f, config.sessionReplayConfig.screenshotScale) - assertEquals(60, config.sessionReplayConfig.screenshotCompressionQuality) - assertEquals(PostHogScreenshotColorMode.RGB_565, config.sessionReplayConfig.screenshotColorMode) - assertFalse(config.sessionReplayConfig.screenshot) } @Test diff --git a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayComposeMaskScopeTest.kt b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayComposeMaskScopeTest.kt new file mode 100644 index 000000000..533f210d6 --- /dev/null +++ b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayComposeMaskScopeTest.kt @@ -0,0 +1,471 @@ +package com.posthog.android.replay + +import android.graphics.Rect +import android.view.View +import android.view.ViewGroup +import android.widget.LinearLayout +import androidx.activity.compose.setContent +import androidx.compose.foundation.clickable +import androidx.compose.foundation.layout.Box +import androidx.compose.foundation.layout.Row +import androidx.compose.foundation.layout.fillMaxWidth +import androidx.compose.foundation.layout.padding +import androidx.compose.foundation.layout.size +import androidx.compose.foundation.text.BasicText +import androidx.compose.foundation.text.BasicTextField +import androidx.compose.foundation.text.selection.SelectionContainer +import androidx.compose.runtime.Composable +import androidx.compose.runtime.getValue +import androidx.compose.runtime.mutableStateOf +import androidx.compose.runtime.setValue +import androidx.compose.ui.Modifier +import androidx.compose.ui.geometry.Offset +import androidx.compose.ui.graphics.Shadow +import androidx.compose.ui.graphics.TransformOrigin +import androidx.compose.ui.graphics.drawscope.Stroke +import androidx.compose.ui.graphics.graphicsLayer +import androidx.compose.ui.platform.ComposeView +import androidx.compose.ui.platform.testTag +import androidx.compose.ui.semantics.clearAndSetSemantics +import androidx.compose.ui.semantics.contentDescription +import androidx.compose.ui.semantics.getTextLayoutResult +import androidx.compose.ui.semantics.semantics +import androidx.compose.ui.semantics.text +import androidx.compose.ui.test.junit4.v2.createAndroidComposeRule +import androidx.compose.ui.test.onNodeWithTag +import androidx.compose.ui.text.AnnotatedString +import androidx.compose.ui.text.SpanStyle +import androidx.compose.ui.text.TextStyle +import androidx.compose.ui.text.buildAnnotatedString +import androidx.compose.ui.text.input.PasswordVisualTransformation +import androidx.compose.ui.text.style.TextOverflow +import androidx.compose.ui.text.withStyle +import androidx.compose.ui.unit.dp +import com.posthog.android.PROJECT_TOKEN +import com.posthog.android.PostHogAndroidConfig +import com.posthog.android.internal.InteractionActivity +import com.posthog.android.internal.InteractionTestApplication +import com.posthog.android.internal.MainHandler +import com.posthog.android.replay.PostHogMaskModifier.postHogMask +import com.posthog.android.replay.PostHogMaskModifier.postHogUnmask +import com.posthog.android.replay.internal.WindowDrawState +import org.junit.Rule +import org.junit.Test +import org.junit.runner.RunWith +import org.robolectric.RobolectricTestRunner +import org.robolectric.annotation.Config +import org.robolectric.annotation.GraphicsMode +import kotlin.test.assertEquals +import kotlin.test.assertFalse +import kotlin.test.assertTrue + +@RunWith(RobolectricTestRunner::class) +@Config(application = InteractionTestApplication::class, sdk = [35]) +@GraphicsMode(GraphicsMode.Mode.NATIVE) // Measures real text widths. +internal class PostHogReplayComposeMaskScopeTest { + @get:Rule + val compose = createAndroidComposeRule() + + private val textModifier = Modifier.size(40.dp) + + @Test + fun `unmasking a child of a clickable row keeps its sibling masked`() { + compose.activity.setContent { + Row(Modifier.clickable {}) { + BasicText("public", textModifier.testTag("public").postHogUnmask()) + BasicText("secret", textModifier.testTag("secret")) + } + } + + assertEquals(listOf(boundsOf("secret")), maskRects()) + } + + @Test + fun `unmasking a clickable row exposes its children`() { + compose.activity.setContent { + Row(Modifier.clickable {}.postHogUnmask()) { + BasicText("first", textModifier) + BasicText("second", textModifier) + } + } + + assertEquals(emptyList(), maskRects()) + } + + @Test + fun `masking a clickable row covers the row`() { + compose.activity.setContent { + Row(Modifier.testTag("row").clickable {}.postHogMask()) { + BasicText("first", textModifier) + } + } + + assertTrue(boundsOf("row") in maskRects(maskAllTextInputs = false)) + } + + @Test + fun `password inside a clickable row is masked when text masking is off`() { + compose.activity.setContent { + Row(Modifier.clickable {}) { + BasicText("label", textModifier) + BasicTextField( + value = "hunter2", + onValueChange = {}, + modifier = textModifier.testTag("password"), + visualTransformation = PasswordVisualTransformation(), + ) + } + } + + assertEquals(listOf(boundsOf("password")), maskRects(maskAllTextInputs = false)) + } + + @Test + fun `visible overflow of text is covered by its mask`() { + compose.activity.setContent { + Row(Modifier.fillMaxWidth().clickable {}) { + BasicText( + "a secret far wider than its layout box", + textModifier.testTag("text"), + softWrap = false, + overflow = TextOverflow.Visible, + ) + } + } + + val bounds = boundsOf("text") + val mask = maskRects().single() + assertTrue(mask.contains(bounds)) + assertTrue(mask.right > bounds.right, "expected $mask to extend past $bounds") + } + + @Test + fun `postHogMask covers the visible overflow of text`() { + compose.activity.setContent { + BasicText( + "a secret far wider than its layout box", + textModifier.testTag("text").postHogMask(), + softWrap = false, + overflow = TextOverflow.Visible, + ) + } + + val mask = maskRects(maskAllTextInputs = false).single() + assertTrue(mask.right > boundsOf("text").right, "expected $mask to extend past the layout box") + } + + @Test + fun `visible overflow of scaled text is covered in window coordinates`() { + val overflowing: @Composable (Modifier) -> Unit = { modifier -> + BasicText( + "a secret far wider than its layout box", + textModifier.then(modifier), + softWrap = false, + overflow = TextOverflow.Visible, + ) + } + compose.activity.setContent { overflowing(Modifier) } + val unscaled = maskRects().single() + + compose.activity.setContent { + overflowing(Modifier.graphicsLayer(scaleX = 2f, transformOrigin = TransformOrigin(0f, 0f))) + } + + assertTrue(maskRects().single().width() >= 2 * unscaled.width() - 1) + } + + @Test + fun `text shadow outside the layout box is covered by its mask`() { + val shadow = Shadow(offset = Offset(100f, 50f), blurRadius = 10f) + compose.activity.setContent { + BasicText("secret", textModifier.testTag("text"), style = TextStyle(shadow = shadow)) + } + + val bounds = boundsOf("text") + val mask = maskRects().single() + assertTrue(mask.contains(bounds)) + assertTrue(mask.right >= bounds.right + 110 && mask.bottom >= bounds.bottom + 60, "$mask misses the shadow of $bounds") + } + + @Test + fun `span shadow outside the layout box is covered by its mask`() { + val shadow = Shadow(offset = Offset(-20f, 0f)) + compose.activity.setContent { + BasicText( + buildAnnotatedString { withStyle(SpanStyle(shadow = shadow)) { append("secret") } }, + Modifier.padding(start = 50.dp).then(textModifier).testTag("text"), + ) + } + + assertTrue(maskRects().single().left <= boundsOf("text").left - 20) + } + + @Test + fun `text stroke outside the layout box is covered by its mask`() { + compose.activity.setContent { + BasicText( + "secret", + Modifier.padding(start = 50.dp).then(textModifier).testTag("text"), + style = TextStyle(drawStyle = Stroke(width = 40f, miter = 1f)), + ) + } + + assertTrue(maskRects().single().left <= boundsOf("text").left - 20) + } + + @Test + fun `span stroke outside the layout box is covered by its mask`() { + compose.activity.setContent { + BasicText( + buildAnnotatedString { withStyle(SpanStyle(drawStyle = Stroke(width = 40f, miter = 1f))) { append("secret") } }, + Modifier.padding(start = 50.dp).then(textModifier).testTag("text"), + ) + } + + assertTrue(maskRects().single().left <= boundsOf("text").left - 20) + } + + @Test + fun `a draw drops reused text bounds so a new shadow is covered`() { + var shadow by mutableStateOf(null) + compose.activity.setContent { + BasicText( + "secret", + Modifier.padding(start = 50.dp).then(textModifier).testTag("text"), + style = TextStyle(shadow = shadow), + ) + } + val sut = PostHogReplayIntegration(compose.activity, PostHogAndroidConfig(PROJECT_TOKEN), MainHandler()) + val verify = { runWalk(sut, PostHogReplayIntegration.MaskWalk(reuseTextLayouts = true)).single() } + + val before = runWalk(sut, PostHogReplayIntegration.MaskWalk()).single() + shadow = Shadow(offset = Offset(-20f, 0f)) + assertEquals(before, verify()) + + compose.runOnIdle { + val view = findComposeView(compose.activity.window.decorView)!! + sut.onDrawCallback(view, WindowDrawState()) + } + + assertTrue(verify().left <= before.left - 20) + } + + @Test + fun `a walk over several compose roots keeps the text layouts of each root`() { + var layouts = 0 + val root = { + ComposeView(compose.activity).apply { + setContent { + Box( + textModifier.semantics { + text = AnnotatedString("secret") + getTextLayoutResult { + layouts++ + false + } + }, + ) + } + } + } + compose.activity.setContentView( + LinearLayout(compose.activity).apply { + addView(root()) + addView(root()) + }, + ) + val sut = PostHogReplayIntegration(compose.activity, PostHogAndroidConfig(PROJECT_TOKEN), MainHandler()) + val walkAll = { walk: PostHogReplayIntegration.MaskWalk -> + compose.runOnIdle { sut.findMaskableWidgets(compose.activity.window.decorView, walk) } + } + + walkAll(PostHogReplayIntegration.MaskWalk()) + assertEquals(2, layouts) + + walkAll(PostHogReplayIntegration.MaskWalk(reuseTextLayouts = true)) + assertEquals(2, layouts) + } + + @Test + fun `verification walks reuse the text layout of the first walk`() { + var layouts = 0 + var label by mutableStateOf("secret") + compose.activity.setContent { + Box( + textModifier.semantics { + text = AnnotatedString(label) + getTextLayoutResult { + layouts++ + false + } + }, + ) + } + + val sut = PostHogReplayIntegration(compose.activity, PostHogAndroidConfig(PROJECT_TOKEN), MainHandler()) + val verify = { runWalk(sut, PostHogReplayIntegration.MaskWalk(reuseTextLayouts = true)) } + + runWalk(sut, PostHogReplayIntegration.MaskWalk()) + assertEquals(1, layouts) + verify() + assertEquals(1, layouts) + + label = "changed" + verify() + assertEquals(2, layouts) + + runWalk(sut, PostHogReplayIntegration.MaskWalk()) + assertEquals(3, layouts) + } + + @Test + fun `clipped text is masked to its layout box`() { + compose.activity.setContent { + BasicText( + "a secret far wider than its layout box", + textModifier.testTag("text"), + softWrap = false, + overflow = TextOverflow.Clip, + ) + } + + assertEquals(listOf(boundsOf("text")), maskRects()) + } + + @Test + fun `text with cleared semantics is masked`() { + compose.activity.setContent { + BasicText("secret", Modifier.testTag("text").clearAndSetSemantics {}.then(textModifier)) + } + + assertEquals(listOf(boundsOf("text")), maskRects()) + } + + @Test + fun `cleared container is masked over its text`() { + compose.activity.setContent { + Box(Modifier.testTag("box").clearAndSetSemantics {}.then(textModifier)) { + BasicText("secret") + } + } + + assertTrue(boundsOf("box") in maskRects()) + } + + @Test + fun `visible overflow of text with cleared semantics is covered by its mask`() { + compose.activity.setContent { + BasicText( + "a secret far wider than its layout box", + Modifier.testTag("text").clearAndSetSemantics {}.then(textModifier), + softWrap = false, + overflow = TextOverflow.Visible, + ) + } + + val mask = maskRects().single() + assertTrue(mask.right > boundsOf("text").right, "expected $mask to extend past the layout box") + } + + @Test + fun `visible overflow of text with a replacement description is covered by its mask`() { + compose.activity.setContent { + BasicText( + "a secret far wider than its layout box", + Modifier.testTag("text").clearAndSetSemantics { contentDescription = "hidden" }.then(textModifier), + softWrap = false, + overflow = TextOverflow.Visible, + ) + } + + val mask = maskRects().single() + assertTrue(mask.right > boundsOf("text").right, "expected $mask to extend past the layout box") + } + + @Test + fun `postHogMask covers the visible overflow of text with cleared semantics`() { + compose.activity.setContent { + Box(Modifier.postHogMask()) { + BasicText( + "a secret far wider than its layout box", + Modifier.testTag("text").clearAndSetSemantics {}.then(textModifier), + softWrap = false, + overflow = TextOverflow.Visible, + ) + } + } + + val masks = maskRects(maskAllTextInputs = false, maskAllImages = false) + assertTrue(masks.any { it.right > boundsOf("text").right }, "expected one of $masks to extend past the layout box") + } + + @Test + fun `frame is discarded when cleared semantics hide text we cannot measure`() { + compose.activity.setContent { + SelectionContainer { + BasicText("secret", Modifier.clearAndSetSemantics {}.then(textModifier)) + } + } + val sut = PostHogReplayIntegration(compose.activity, PostHogAndroidConfig(PROJECT_TOKEN), MainHandler()) + val composeView = findComposeView(compose.activity.window.decorView)!! + + listOf(true, false).forEach { failClosed -> + val walk = PostHogReplayIntegration.MaskWalk(failClosed = failClosed) + compose.runOnIdle { sut.findMaskableWidgets(composeView, walk) } + assertTrue(walk.poisoned, "failClosed=$failClosed") + } + } + + @Test + fun `cleared semantics stay unmasked when masking is off or unmasked`() { + compose.activity.setContent { + BasicText("public", Modifier.clearAndSetSemantics {}.then(textModifier)) + } + assertEquals(emptyList(), maskRects(maskAllTextInputs = false, maskAllImages = false)) + + compose.activity.setContent { + Box(Modifier.postHogUnmask()) { + BasicText("public", Modifier.clearAndSetSemantics {}.then(textModifier)) + } + } + assertEquals(emptyList(), maskRects()) + } + + private fun boundsOf(tag: String): Rect { + val bounds = compose.onNodeWithTag(tag, useUnmergedTree = true).fetchSemanticsNode().boundsInWindow + return Rect(bounds.left.toInt(), bounds.top.toInt(), bounds.right.toInt(), bounds.bottom.toInt()) + } + + private fun maskRects( + maskAllTextInputs: Boolean = true, + maskAllImages: Boolean = true, + ): List { + val config = PostHogAndroidConfig(PROJECT_TOKEN) + config.sessionReplayConfig.maskAllTextInputs = maskAllTextInputs + config.sessionReplayConfig.maskAllImages = maskAllImages + return runWalk(PostHogReplayIntegration(compose.activity, config, MainHandler()), PostHogReplayIntegration.MaskWalk()) + } + + private fun runWalk( + sut: PostHogReplayIntegration, + walk: PostHogReplayIntegration.MaskWalk, + ): List { + compose.runOnIdle { + sut.findMaskableWidgets(findComposeView(compose.activity.window.decorView)!!, walk) + } + assertFalse(walk.poisoned) + return walk.rects + } + + private fun findComposeView(view: View): View? { + if (view.javaClass.name == PostHogReplayIntegration.ANDROID_COMPOSE_VIEW_CLASS_NAME) { + return view + } + if (view is ViewGroup) { + for (i in 0 until view.childCount) { + findComposeView(view.getChildAt(i))?.let { return it } + } + } + return null + } +} diff --git a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt index 8e6170e70..e09c2c0c3 100644 --- a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt @@ -14,6 +14,7 @@ import android.os.Looper import android.util.Base64 import android.view.MotionEvent import android.view.PixelCopy +import android.view.SurfaceView import android.view.View import android.view.ViewGroup import android.view.Window @@ -107,7 +108,6 @@ import kotlin.test.assertEquals import kotlin.test.assertFalse import kotlin.test.assertNotEquals import kotlin.test.assertNotNull -import kotlin.test.assertNull import kotlin.test.assertTrue @RunWith(AndroidJUnit4::class) @@ -736,78 +736,6 @@ internal class PostHogReplayIntegrationTest { } } - @Test - fun `a secure window is recorded as one black wireframe in wireframe mode`() { - val h = screenshotCaptureHarness() - try { - h.fx.config.sessionReplayConfig.screenshot = false - h.child.tag = null - h.child.text = "secret" - h.window.addFlags(WindowManager.LayoutParams.FLAG_SECURE) - - h.fx.sut.generateSnapshot(WeakReference(h.hookLayout), WeakReference(h.window)) - - @Suppress("UNCHECKED_CAST") - val events = h.fake.properties?.get("\$snapshot_data") as List - val fullSnapshot = events.first { it.type == RREventType.FullSnapshot } - val wireframe = ((fullSnapshot.data as Map<*, *>)["wireframes"] as List<*>).single() as RRWireframe - assertEquals("#000000", wireframe.style?.backgroundColor) - assertNull(wireframe.childWireframes) - assertNull(wireframe.text) - } finally { - h.fx.sut.uninstall() - } - } - - @Test - fun `a window secure when the wireframe walk starts is recorded as one black wireframe`() { - val h = screenshotCaptureHarness() - try { - h.fx.config.sessionReplayConfig.screenshot = false - h.child.tag = null - h.child.text = "secret" - h.window.attributes.flags = h.window.attributes.flags or WindowManager.LayoutParams.FLAG_SECURE - h.hookLayout.onWalkTouch = { - h.window.attributes.flags = h.window.attributes.flags and WindowManager.LayoutParams.FLAG_SECURE.inv() - } - - h.fx.sut.generateSnapshot(WeakReference(h.hookLayout), WeakReference(h.window)) - - @Suppress("UNCHECKED_CAST") - val events = h.fake.properties?.get("\$snapshot_data") as List - val fullSnapshot = events.first { it.type == RREventType.FullSnapshot } - val wireframe = ((fullSnapshot.data as Map<*, *>)["wireframes"] as List<*>).single() as RRWireframe - assertEquals("#000000", wireframe.style?.backgroundColor) - assertNull(wireframe.childWireframes) - } finally { - h.fx.sut.uninstall() - } - } - - @Test - fun `a window that turns secure during the wireframe walk is recorded as one black wireframe`() { - val h = screenshotCaptureHarness() - try { - h.fx.config.sessionReplayConfig.screenshot = false - h.child.tag = null - h.child.text = "secret" - h.hookLayout.onWalkTouch = { - h.window.attributes.flags = h.window.attributes.flags or WindowManager.LayoutParams.FLAG_SECURE - } - - h.fx.sut.generateSnapshot(WeakReference(h.hookLayout), WeakReference(h.window)) - - @Suppress("UNCHECKED_CAST") - val events = h.fake.properties?.get("\$snapshot_data") as List - val fullSnapshot = events.first { it.type == RREventType.FullSnapshot } - val wireframe = ((fullSnapshot.data as Map<*, *>)["wireframes"] as List<*>).single() as RRWireframe - assertEquals("#000000", wireframe.style?.backgroundColor) - assertNull(wireframe.childWireframes) - } finally { - h.fx.sut.uninstall() - } - } - private fun dispatchTouch( sut: PostHogReplayIntegration, action: Int = MotionEvent.ACTION_DOWN, @@ -2621,7 +2549,6 @@ internal class PostHogReplayIntegrationTest { integrationContext = ApplicationProvider.getApplicationContext(), ) fx.config.sessionReplayConfig.captureTouches = captureTouches - fx.config.sessionReplayConfig.screenshot = true fx.config.sessionReplayConfig.verifyScreenshotMaskAlignment = enableMaskAlignmentVerification val fake = PostHogFake() PostHogSessionManager.startSession() @@ -2743,7 +2670,6 @@ internal class PostHogReplayIntegrationTest { PostHogSessionManager.startSession() val sessionId = PostHogSessionManager.peekSessionId().toString() val fx = createIntegrationWithRealQueue(true, true, integrationContext = ApplicationProvider.getApplicationContext()) - fx.config.sessionReplayConfig.screenshot = true val client = object : PostHogInterface by core { override fun capture( @@ -4026,7 +3952,7 @@ internal class PostHogReplayIntegrationTest { @Test @Config(sdk = [26], shadows = [ShadowPixelCopy::class]) - fun `wireframe visibility does not race a delayed screenshot mask walk's shared scratch objects`() { + fun `a concurrent capture's visibility check does not race a delayed screenshot mask walk's shared scratch objects`() { val appContext = ApplicationProvider.getApplicationContext() val fx = createIntegrationWithRealQueue( @@ -4048,15 +3974,15 @@ internal class PostHogReplayIntegrationTest { val guardedEntered = CountDownLatch(1) val releaseGuardedCall = CountDownLatch(1) - val wireframeEntered = CountDownLatch(1) + val concurrentEntered = CountDownLatch(1) val guardedTimedOut = AtomicBoolean(false) val guardedRectWasCorrupted = AtomicBoolean(false) val guardedPointWasCorrupted = AtomicBoolean(false) val guardedRect = AtomicReference() val guardedPoint = AtomicReference() val guardedVisibilityCalls = AtomicInteger(0) - val wireframeReusedGuardedRect = AtomicBoolean(false) - val wireframeReusedGuardedPoint = AtomicBoolean(false) + val concurrentReusedGuardedRect = AtomicBoolean(false) + val concurrentReusedGuardedPoint = AtomicBoolean(false) val guardedRectValue = Rect(1, 2, 30, 40) val guardedPointValue = Point(5, 6) @@ -4076,19 +4002,19 @@ internal class PostHogReplayIntegrationTest { guardedPointWasCorrupted.set(point != guardedPointValue) } } - val wireframeView = + val concurrentView = VisibleRectHookView(activity) { rect, point -> - wireframeReusedGuardedRect.set(rect === guardedRect.get()) - wireframeReusedGuardedPoint.set(point === guardedPoint.get()) + concurrentReusedGuardedRect.set(rect === guardedRect.get()) + concurrentReusedGuardedPoint.set(point === guardedPoint.get()) rect.set(100, 200, 300, 400) point?.set(500, 600) - wireframeEntered.countDown() + concurrentEntered.countDown() } val guardedRoot = FrameLayout(activity).apply { addView(guardedView) } val outerRoot = FrameLayout(activity).apply { addView(guardedRoot) - addView(wireframeView) + addView(concurrentView) } activity.setContentView(outerRoot) shadowOf(Looper.getMainLooper()).idle() @@ -4096,18 +4022,18 @@ internal class PostHogReplayIntegrationTest { outerRoot.layout(0, 0, 100, 100) guardedRoot.layout(0, 0, 100, 50) guardedView.layout(0, 0, 50, 50) - wireframeView.layout(50, 0, 100, 50) + concurrentView.layout(50, 0, 100, 50) fx.sut.decorViews[guardedRoot] = ViewTreeSnapshotStatus(mock()) - fx.sut.decorViews[wireframeView] = ViewTreeSnapshotStatus(mock()) + fx.sut.decorViews[concurrentView] = ViewTreeSnapshotStatus(mock()) val executor = Executors.newFixedThreadPool(2) try { - val wireframeFuture = + val concurrentFuture = executor.submit { try { assertTrue(guardedEntered.await(3, TimeUnit.SECONDS)) fx.sut.generateSnapshot( - WeakReference(wireframeView), + WeakReference(concurrentView), WeakReference(activity.window), ) } finally { @@ -4119,7 +4045,6 @@ internal class PostHogReplayIntegrationTest { fx.sut.generateSnapshot( WeakReference(guardedRoot), WeakReference(activity.window), - forceScreenshot = true, ) } assertTrue( @@ -4127,21 +4052,21 @@ internal class PostHogReplayIntegrationTest { "The delayed screenshot callback did not reach its guarded post-copy mask walk", ) - val callsOverlapped = wireframeEntered.count == 0L + val callsOverlapped = concurrentEntered.count == 0L releaseGuardedCall.countDown() awaitDraining(screenshotFuture, 3000) - awaitDraining(wireframeFuture, 3000) + awaitDraining(concurrentFuture, 3000) assertFalse(guardedTimedOut.get(), "The guarded visibility hook timed out") val overlappingCallsWereSafe = - !wireframeReusedGuardedRect.get() && - !wireframeReusedGuardedPoint.get() && + !concurrentReusedGuardedRect.get() && + !concurrentReusedGuardedPoint.get() && !guardedRectWasCorrupted.get() && !guardedPointWasCorrupted.get() assertTrue( !callsOverlapped || overlappingCallsWereSafe, - "An unguarded wireframe visibility call entered during the delayed screenshot mask walk and reused " + - "its Rect=${wireframeReusedGuardedRect.get()} and Point=${wireframeReusedGuardedPoint.get()}; " + + "An unguarded visibility call entered during the delayed screenshot mask walk and reused " + + "its Rect=${concurrentReusedGuardedRect.get()} and Point=${concurrentReusedGuardedPoint.get()}; " + "guarded Rect corrupted=${guardedRectWasCorrupted.get()}, " + "Point corrupted=${guardedPointWasCorrupted.get()}", ) @@ -4647,6 +4572,48 @@ internal class PostHogReplayIntegrationTest { } } + @Test + fun `draws outside a legacy capture skip the surface scan`() { + val (fx, _) = screenshotFixture(enableMaskAlignmentVerification = false) + try { + val activity = Robolectric.buildActivity(Activity::class.java).setup().get() + shadowOf(Looper.getMainLooper()).idle() + val root = CountingChildFrameLayout(activity).apply { addView(View(activity)) } + val drawState = WindowDrawState() + drawState.recordDraw() + fx.sut.onDrawCallback(root, drawState) + val walkCountAfterFirstDraw = root.childWalkCount + + drawState.recordDraw() + fx.sut.onDrawCallback(root, drawState) + + assertEquals(walkCountAfterFirstDraw, root.childWalkCount) + } finally { + fx.sut.uninstall() + } + } + + @Test + fun `a surface redraw during a legacy capture is animation only`() { + val (fx, _) = screenshotFixture(enableMaskAlignmentVerification = false) + try { + val activity = Robolectric.buildActivity(Activity::class.java).setup().get() + shadowOf(Looper.getMainLooper()).idle() + val surface = SurfaceView(activity) + val root = FrameLayout(activity).apply { addView(surface) } + surface.layout(0, 0, 100, 100) + val drawState = WindowDrawState() + drawState.beginLegacyCapture() + drawState.recordDraw() + + fx.sut.onDrawCallback(root, drawState) + + assertTrue(drawState.isOnlyAnimationRedraw) + } finally { + fx.sut.uninstall() + } + } + // An animating view can't be placed, so the walk would otherwise ship its overflow unmasked. @Test fun `legacy mask walk is poisoned by an animating no-capture descendant only`() { @@ -5113,31 +5080,10 @@ internal class PostHogReplayIntegrationTest { } @Test - fun `debugProperties reports screenshot capture mode when the screenshot flag is on`() { - val config = PostHogAndroidConfig(PROJECT_TOKEN) - config.sessionReplayConfig.screenshot = true - val sut = getSut(config) - - assertEquals("screenshot", sut.debugProperties()["\$sdk_debug_replay_capture_mode"]) - } - - @Test - fun `debugProperties reports screenshot capture mode for the flutter host`() { - val config = PostHogAndroidConfig(PROJECT_TOKEN) - config.sdkName = "posthog-flutter" - config.sessionReplayConfig.screenshot = false - val sut = getSut(config) + fun `debugProperties reports screenshot capture mode`() { + val sut = getSut(PostHogAndroidConfig(PROJECT_TOKEN)) assertEquals("screenshot", sut.debugProperties()["\$sdk_debug_replay_capture_mode"]) - } - - @Test - fun `debugProperties reports wireframe capture mode otherwise`() { - val config = PostHogAndroidConfig(PROJECT_TOKEN) - config.sessionReplayConfig.screenshot = false - val sut = getSut(config) - - assertEquals("wireframe", sut.debugProperties()["\$sdk_debug_replay_capture_mode"]) assertFalse(sut.debugProperties().containsKey("\$sdk_debug_replay_throttle_delay_ms")) } @@ -5271,7 +5217,7 @@ internal class PostHogReplayIntegrationTest { val props = sut.debugProperties() assertEquals("disabled", props["\$recording_status"]) assertFalse(props.containsKey("\$sdk_debug_replay_flush_hold_reason")) - assertEquals("wireframe", props["\$sdk_debug_replay_capture_mode"]) + assertEquals("screenshot", props["\$sdk_debug_replay_capture_mode"]) assertEquals(0, props["\$sdk_debug_replay_internal_buffer_length"]) } finally { sut.uninstall() diff --git a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayMaskWalkBenchmark.kt b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayMaskWalkBenchmark.kt index 4fc2af9b9..308b721ac 100644 --- a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayMaskWalkBenchmark.kt +++ b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayMaskWalkBenchmark.kt @@ -44,7 +44,6 @@ internal class PostHogReplayMaskWalkBenchmark { assumeTrue(System.getenv("POSTHOG_BENCHMARK") == "1") val config = PostHogAndroidConfig(PROJECT_TOKEN).apply { - sessionReplayConfig.screenshot = true sessionReplayConfig.verifyScreenshotMaskAlignment = true } sut = PostHogReplayIntegration(ApplicationProvider.getApplicationContext(), config, MainHandler()) diff --git a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayTestUtils.kt b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayTestUtils.kt index fb1b5069a..a564cf726 100644 --- a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayTestUtils.kt +++ b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayTestUtils.kt @@ -13,14 +13,13 @@ import java.util.concurrent.TimeoutException internal fun PostHogReplayIntegration.captureSnapshot( viewRef: WeakReference, windowRef: WeakReference, - forceScreenshot: Boolean = false, ): Boolean { if (Looper.myLooper() != Looper.getMainLooper()) { - return generateSnapshot(viewRef, windowRef, forceScreenshot) + return generateSnapshot(viewRef, windowRef) } val executor = Executors.newSingleThreadExecutor() try { - val future = executor.submit(Callable { generateSnapshot(viewRef, windowRef, forceScreenshot) }) + val future = executor.submit(Callable { generateSnapshot(viewRef, windowRef) }) val deadline = System.nanoTime() + TimeUnit.SECONDS.toNanos(4) while (System.nanoTime() < deadline) { shadowOf(Looper.getMainLooper()).idle() diff --git a/posthog-android/src/test/resources/json/snapshots/batch-request.json b/posthog-android/src/test/resources/json/snapshots/batch-request.json index c9d3b3997..737b87914 100644 --- a/posthog-android/src/test/resources/json/snapshots/batch-request.json +++ b/posthog-android/src/test/resources/json/snapshots/batch-request.json @@ -104,7 +104,7 @@ "$recording_status": "disabled", "$sdk_debug_replay_event_trigger_status": "trigger_disabled", "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", - "$sdk_debug_replay_capture_mode": "wireframe", + "$sdk_debug_replay_capture_mode": "screenshot", "$sdk_debug_replay_internal_buffer_length": 0, "$sdk_debug_session_start": 1700000000123 }, diff --git a/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt b/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt index b1ebd89c4..27826ef05 100644 --- a/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt +++ b/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt @@ -48,7 +48,6 @@ class MyApp : Application() { sessionReplayConfig.maskAllTextInputs = false sessionReplayConfig.maskAllImages = false sessionReplayConfig.captureLogcat = true - sessionReplayConfig.screenshot = true // Surveys are opt-in. With :posthog-android-surveys-compose on the classpath the // core SDK auto-discovers the Compose UI delegate — no surveysConfig wiring needed. surveys = true diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index 4c6968839..ddcf0ddfd 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -1414,68 +1414,6 @@ public final class com/posthog/internal/replay/RRRemovedNode { public final fun getParentId ()Ljava/lang/Integer; } -public final class com/posthog/internal/replay/RRStyle { - public fun ()V - public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Ljava/lang/String; - public final fun component10 ()Ljava/lang/String; - public final fun component11 ()Ljava/lang/Integer; - public final fun component12 ()Ljava/lang/Integer; - public final fun component13 ()Ljava/lang/Integer; - public final fun component14 ()Ljava/lang/Integer; - public final fun component15 ()Ljava/lang/String; - public final fun component16 ()Ljava/lang/String; - public final fun component17 ()Ljava/lang/String; - public final fun component2 ()Ljava/lang/String; - public final fun component3 ()Ljava/lang/String; - public final fun component4 ()Ljava/lang/Integer; - public final fun component5 ()Ljava/lang/Integer; - public final fun component6 ()Ljava/lang/String; - public final fun component7 ()Ljava/lang/Integer; - public final fun component8 ()Ljava/lang/String; - public final fun component9 ()Ljava/lang/String; - public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Lcom/posthog/internal/replay/RRStyle; - public static synthetic fun copy$default (Lcom/posthog/internal/replay/RRStyle;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/Integer;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lcom/posthog/internal/replay/RRStyle; - public fun equals (Ljava/lang/Object;)Z - public final fun getBackgroundColor ()Ljava/lang/String; - public final fun getBackgroundImage ()Ljava/lang/String; - public final fun getBar ()Ljava/lang/String; - public final fun getBorderColor ()Ljava/lang/String; - public final fun getBorderRadius ()Ljava/lang/Integer; - public final fun getBorderWidth ()Ljava/lang/Integer; - public final fun getColor ()Ljava/lang/String; - public final fun getFontFamily ()Ljava/lang/String; - public final fun getFontSize ()Ljava/lang/Integer; - public final fun getHorizontalAlign ()Ljava/lang/String; - public final fun getIconLeft ()Ljava/lang/String; - public final fun getIconRight ()Ljava/lang/String; - public final fun getPaddingBottom ()Ljava/lang/Integer; - public final fun getPaddingLeft ()Ljava/lang/Integer; - public final fun getPaddingRight ()Ljava/lang/Integer; - public final fun getPaddingTop ()Ljava/lang/Integer; - public final fun getVerticalAlign ()Ljava/lang/String; - public fun hashCode ()I - public final fun setBackgroundColor (Ljava/lang/String;)V - public final fun setBackgroundImage (Ljava/lang/String;)V - public final fun setBar (Ljava/lang/String;)V - public final fun setBorderColor (Ljava/lang/String;)V - public final fun setBorderRadius (Ljava/lang/Integer;)V - public final fun setBorderWidth (Ljava/lang/Integer;)V - public final fun setColor (Ljava/lang/String;)V - public final fun setFontFamily (Ljava/lang/String;)V - public final fun setFontSize (Ljava/lang/Integer;)V - public final fun setHorizontalAlign (Ljava/lang/String;)V - public final fun setIconLeft (Ljava/lang/String;)V - public final fun setIconRight (Ljava/lang/String;)V - public final fun setPaddingBottom (Ljava/lang/Integer;)V - public final fun setPaddingLeft (Ljava/lang/Integer;)V - public final fun setPaddingRight (Ljava/lang/Integer;)V - public final fun setPaddingTop (Ljava/lang/Integer;)V - public final fun setVerticalAlign (Ljava/lang/String;)V - public fun toString ()Ljava/lang/String; -} - public final class com/posthog/internal/replay/RRUtilsKt { public static final fun capture (Ljava/util/List;)V public static final fun capture (Ljava/util/List;Lcom/posthog/PostHogInterface;)V @@ -1483,44 +1421,22 @@ public final class com/posthog/internal/replay/RRUtilsKt { } public final class com/posthog/internal/replay/RRWireframe { - public fun (IIIIILjava/util/List;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Lcom/posthog/internal/replay/RRStyle;Ljava/lang/Boolean;Ljava/lang/Boolean;Ljava/util/List;Ljava/lang/Integer;Ljava/lang/Integer;)V - public synthetic fun (IIIIILjava/util/List;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Lcom/posthog/internal/replay/RRStyle;Ljava/lang/Boolean;Ljava/lang/Boolean;Ljava/util/List;Ljava/lang/Integer;Ljava/lang/Integer;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (IIIIILjava/lang/String;Ljava/lang/String;)V + public synthetic fun (IIIIILjava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun component1 ()I - public final fun component10 ()Ljava/lang/String; - public final fun component11 ()Ljava/lang/Object; - public final fun component12 ()Ljava/lang/String; - public final fun component13 ()Lcom/posthog/internal/replay/RRStyle; - public final fun component14 ()Ljava/lang/Boolean; - public final fun component15 ()Ljava/lang/Boolean; - public final fun component16 ()Ljava/util/List; - public final fun component17 ()Ljava/lang/Integer; - public final fun component18 ()Ljava/lang/Integer; public final fun component2 ()I public final fun component3 ()I public final fun component4 ()I public final fun component5 ()I - public final fun component6 ()Ljava/util/List; + public final fun component6 ()Ljava/lang/String; public final fun component7 ()Ljava/lang/String; - public final fun component8 ()Ljava/lang/String; - public final fun component9 ()Ljava/lang/String; - public final fun copy (IIIIILjava/util/List;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Lcom/posthog/internal/replay/RRStyle;Ljava/lang/Boolean;Ljava/lang/Boolean;Ljava/util/List;Ljava/lang/Integer;Ljava/lang/Integer;)Lcom/posthog/internal/replay/RRWireframe; - public static synthetic fun copy$default (Lcom/posthog/internal/replay/RRWireframe;IIIIILjava/util/List;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Lcom/posthog/internal/replay/RRStyle;Ljava/lang/Boolean;Ljava/lang/Boolean;Ljava/util/List;Ljava/lang/Integer;Ljava/lang/Integer;ILjava/lang/Object;)Lcom/posthog/internal/replay/RRWireframe; + public final fun copy (IIIIILjava/lang/String;Ljava/lang/String;)Lcom/posthog/internal/replay/RRWireframe; + public static synthetic fun copy$default (Lcom/posthog/internal/replay/RRWireframe;IIIIILjava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lcom/posthog/internal/replay/RRWireframe; public fun equals (Ljava/lang/Object;)Z public final fun getBase64 ()Ljava/lang/String; - public final fun getChecked ()Ljava/lang/Boolean; - public final fun getChildWireframes ()Ljava/util/List; - public final fun getDisabled ()Ljava/lang/Boolean; public final fun getHeight ()I public final fun getId ()I - public final fun getInputType ()Ljava/lang/String; - public final fun getLabel ()Ljava/lang/String; - public final fun getMax ()Ljava/lang/Integer; - public final fun getOptions ()Ljava/util/List; - public final fun getParentId ()Ljava/lang/Integer; - public final fun getStyle ()Lcom/posthog/internal/replay/RRStyle; - public final fun getText ()Ljava/lang/String; public final fun getType ()Ljava/lang/String; - public final fun getValue ()Ljava/lang/Object; public final fun getWidth ()I public final fun getX ()I public final fun getY ()I diff --git a/posthog/src/main/java/com/posthog/internal/replay/RRStyle.kt b/posthog/src/main/java/com/posthog/internal/replay/RRStyle.kt deleted file mode 100644 index 2f1ea723a..000000000 --- a/posthog/src/main/java/com/posthog/internal/replay/RRStyle.kt +++ /dev/null @@ -1,24 +0,0 @@ -package com.posthog.internal.replay - -import com.posthog.PostHogInternal - -@PostHogInternal -public data class RRStyle( - public var color: String? = null, - public var backgroundColor: String? = null, - public var backgroundImage: String? = null, - public var borderWidth: Int? = null, - public var borderRadius: Int? = null, - public var borderColor: String? = null, - public var fontSize: Int? = null, - public var fontFamily: String? = null, - public var horizontalAlign: String? = null, - public var verticalAlign: String? = null, - public var paddingTop: Int? = null, - public var paddingBottom: Int? = null, - public var paddingLeft: Int? = null, - public var paddingRight: Int? = null, - public var bar: String? = null, - public var iconLeft: String? = null, - public var iconRight: String? = null, -) diff --git a/posthog/src/main/java/com/posthog/internal/replay/RRWireframe.kt b/posthog/src/main/java/com/posthog/internal/replay/RRWireframe.kt index c9f7309f0..a51d10f81 100644 --- a/posthog/src/main/java/com/posthog/internal/replay/RRWireframe.kt +++ b/posthog/src/main/java/com/posthog/internal/replay/RRWireframe.kt @@ -3,7 +3,6 @@ package com.posthog.internal.replay import com.posthog.PostHogInternal import org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement -// TODO: create abstractions on top of RRWireframe, eg RRTextWireframe, etc @IgnoreJRERequirement @PostHogInternal public data class RRWireframe( @@ -12,21 +11,7 @@ public data class RRWireframe( public val y: Int, public val width: Int, public val height: Int, - public val childWireframes: List? = null, - // text|image|rectangle|input|div|screenshot + // screenshot public val type: String? = null, - // checkbox|radio|text|password|email|number|search|tel|url|select|textarea|button - public val inputType: String? = null, - public val text: String? = null, - public val label: String? = null, - // string or number - public val value: Any? = null, public val base64: String? = null, - public val style: RRStyle? = null, - public val disabled: Boolean? = null, - public val checked: Boolean? = null, - public val options: List? = null, - @Transient - public val parentId: Int? = null, - public val max: Int? = null, ) From 8507dd2284e191a58e1828b1a6110ad125a3a4e8 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Wed, 4 Nov 2026 16:27:20 -0500 Subject: [PATCH 15/49] fix(replay): hit-test masked touches against the unmerged semantics tree The touch drop from #922 read the merged semantics tree, but the 4.0 mask walk reads the unmerged one. Inside a clickable parent, merging folds a postHogMask child into the parent node, so a tap on the masked child was recorded when the parent also held an unmasked sibling. Co-Authored-By: Claude Opus 5.5 --- .../replay/PostHogReplayIntegration.kt | 2 +- .../replay/PostHogReplayIntegrationTest.kt | 21 +++++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt b/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt index 5c5ac2113..66415b040 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt +++ b/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt @@ -1307,7 +1307,7 @@ public class PostHogReplayIntegration( // Only reached for a Compose view, so Compose is on the classpath. Compose bounds are // window coordinates, the touch is relative to the decor view. private fun hasComposeMaskAt(view: View): Boolean { - val root = (view as? RootForTest)?.semanticsOwner?.rootSemanticsNode ?: return false + val root = (view as? RootForTest)?.semanticsOwner?.unmergedRootSemanticsNode ?: return false return root.hasPostHogMaskAt(Offset(decorX + windowOffset[0], decorY + windowOffset[1])) } } diff --git a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt index 9cfe65479..87f52ac70 100644 --- a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt @@ -26,7 +26,9 @@ import android.widget.ImageView import android.widget.TextView import androidx.activity.ComponentActivity import androidx.activity.compose.setContent +import androidx.compose.foundation.clickable import androidx.compose.foundation.layout.Box +import androidx.compose.foundation.layout.Row import androidx.compose.foundation.layout.fillMaxSize import androidx.compose.foundation.layout.offset import androidx.compose.foundation.layout.size @@ -999,6 +1001,25 @@ internal class PostHogReplayIntegrationTest { } } + @Test + fun `a touch on a postHogMask node inside a clickable row with an unmasked sibling is not recorded`() { + withMaskedTouchHarness( + ComponentActivity::class.java, + content = { activity -> + activity.setContent { + Row(Modifier.clickable {}) { + Box(Modifier.size(20.dp).postHogMask()) + Box(Modifier.size(20.dp).postHogUnmask()) + } + } + }, + ) { h -> + h.assertDropped(5f, 5f) + val unmaskedX = 25f * h.window.context.resources.displayMetrics.density + h.assertRecorded(unmaskedX, 5f) + } + } + private fun dispatchTouch( sut: PostHogReplayIntegration, action: Int = MotionEvent.ACTION_DOWN, From a1aa0d3e3d517c0b189612a8224c487c78364aa1 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 5 Nov 2026 10:01:02 -0500 Subject: [PATCH 16/49] fix(flags): decode payloads cached by 3.x from the cached flag details (#935) * fix(flags): decode payloads cached by 3.x from the cached flag details * docs: note that 3.13 caches keep malformed payloads until /flags Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- docs/migration-3.x-to-4.0.md | 2 +- .../posthog/internal/PostHogRemoteConfig.kt | 28 +++++++++++++- .../internal/PostHogRemoteConfigTest.kt | 38 +++++++++++++++++++ 3 files changed, 66 insertions(+), 2 deletions(-) diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 8a7cf595a..f5686c9a1 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -232,7 +232,7 @@ The flag's value, enabled state, variant and any other flag's payload aren't aff If you read a payload as plain text, such as a payload saved as `hello` rather than `"hello"`, update it in PostHog to valid JSON before you upgrade, or your code gets `null`. -A malformed payload cached by 3.x can still read as the raw string after the upgrade, until the app's first `/flags` response replaces it. +Apps upgrading from 3.13 or older didn't cache flag details, so until the app's first `/flags` response, a malformed payload cached by 3.x still reads as the raw string, as it did in 3.x. ### Session replay records screenshots diff --git a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt index b63a91e32..4e17effde 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt @@ -1216,11 +1216,12 @@ public class PostHogRemoteConfig( ) as? Map ?: mapOf() @Suppress("UNCHECKED_CAST") - val payloads = + val cachedPayloads = preferences.getValue( FEATURE_FLAGS_PAYLOAD, mapOf(), ) as? Map ?: mapOf() + val payloads = withPayloadsFromCachedFlags(cachedPayloads, flags) val cachedRequestId = preferences.getValue(FEATURE_FLAG_REQUEST_ID) as? String val cachedEvaluatedAt = preferences.getValue(FEATURE_FLAG_EVALUATED_AT) as? Long @@ -1244,6 +1245,31 @@ public class PostHogRemoteConfig( } } + // 3.x cached a malformed payload as its raw string, so after an upgrade the payload cache can hold + // one. The cached flag details keep each payload as the server serialized it: decode those instead, + // the same way a /flags response is decoded. Legacy caches without flag details are kept as they are. + private fun withPayloadsFromCachedFlags( + cachedPayloads: Map, + flags: Map, + ): Map { + val serializedPayloads = + flags.mapNotNull { (key, flag) -> + when (flag) { + is FeatureFlag -> key to flag.metadata.payload + is Map<*, *> -> (flag["metadata"] as? Map<*, *>)?.let { key to (it["payload"] as? String) } + else -> null + } + }.toMap() + if (serializedPayloads.isEmpty()) { + return cachedPayloads + } + val decoded = + serializedPayloads.mapNotNull { (key, serialized) -> + serialized?.let { decodePayload(key, it) }?.let { key to it } + }.toMap() + return cachedPayloads.filterKeys { it !in serializedPayloads } + decoded + } + private fun normalizePayloads(featureFlagPayloads: Map?): Map = (featureFlagPayloads ?: mapOf()).mapValues { (key, value) -> // payloads arrive as serialized JSON strings; other values are already decoded diff --git a/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt index 34fcdcd62..57eae6915 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogRemoteConfigTest.kt @@ -10,6 +10,7 @@ import com.posthog.internal.PostHogPreferences.Companion.CAPTURE_PERFORMANCE import com.posthog.internal.PostHogPreferences.Companion.ERROR_TRACKING import com.posthog.internal.PostHogPreferences.Companion.FEATURE_FLAGS import com.posthog.internal.PostHogPreferences.Companion.FEATURE_FLAGS_PAYLOAD +import com.posthog.internal.PostHogPreferences.Companion.FLAGS import com.posthog.internal.PostHogPreferences.Companion.SESSION_REPLAY import com.posthog.internal.PostHogPreferences.Companion.SURVEYS import com.posthog.shutdownAndAwaitTermination @@ -3316,6 +3317,43 @@ internal class PostHogRemoteConfigTest { } } + @Test + fun `a malformed payload cached by 3x reads as null after the upgrade`() { + fun metadata(payload: String?) = FeatureFlagMetadata(id = 1, payload = payload, version = 1) + val asObjects = + mapOf( + "checkout" to FeatureFlag("checkout", true, "blue", metadata("hello"), null), + "beta-ui" to FeatureFlag("beta-ui", true, null, metadata("{\"color\":\"green\"}"), null), + ) + val asStoredJson = + mapOf( + "checkout" to mapOf("key" to "checkout", "metadata" to mapOf("payload" to "hello")), + "beta-ui" to mapOf("key" to "beta-ui", "metadata" to mapOf("payload" to "{\"color\":\"green\"}")), + ) + for (cachedFlags in listOf(asObjects, asStoredJson)) { + preferences.clear() + preferences.setValue(FLAGS, cachedFlags) + preferences.setValue(FEATURE_FLAGS, mapOf("checkout" to "blue", "beta-ui" to true)) + preferences.setValue(FEATURE_FLAGS_PAYLOAD, mapOf("checkout" to "hello", "beta-ui" to mapOf("color" to "green"))) + + val sut = getSut(host = "http://127.0.0.1:1/") + + assertNull(sut.getFeatureFlagResult("checkout")?.payload) + assertEquals("blue", sut.getFeatureFlagResult("checkout")?.variant) + assertEquals(mapOf("color" to "green"), sut.getFeatureFlagResult("beta-ui")?.payload) + } + } + + @Test + fun `a cache without flag details keeps its payloads`() { + preferences.setValue(FEATURE_FLAGS, mapOf("beta-ui" to true)) + preferences.setValue(FEATURE_FLAGS_PAYLOAD, mapOf("beta-ui" to mapOf("color" to "green"))) + + val sut = getSut(host = "http://127.0.0.1:1/") + + assertEquals(mapOf("color" to "green"), sut.getFeatureFlagResult("beta-ui")?.payload) + } + @Test fun `valid JSON payloads keep their decoded value`() { val sut = From df586923a0beef7906fef4dc0ddd84355a445f23 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 5 Nov 2026 10:05:16 -0500 Subject: [PATCH 17/49] feat!: send events through capture v1 and add captureAi (#881) * feat!: disable the SDK when the project token is a personal API key A `phx_` token is a personal API key; capture rejects every request made with it. Setup now logs once and stays disabled, as for an empty token. Co-Authored-By: Claude Fable 5.1 * feat!: send analytics events through capture v1 Analytics events now go to `POST /i/v1/analytics/events` with the project token in an `Authorization: Bearer` header, `PostHog-Sdk-Info`, `PostHog-Attempt`, `PostHog-Request-Id` and `PostHog-Request-Timestamp`. The body is `{created_at, batch}`; each event drops `$lib`/`$lib_version`, lifts string `$session_id`/`$window_id` to the root, and hoists the legacy `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id` properties into the new `PostHogEvent.options`. The queue reads the per-event results: `ok`, `warning` and `drop` leave the queue, only `retry` is kept and resent under the same request id and `created_at` with the next attempt number. A 2xx without readable results counts as delivered. 408 and 500/502/503/504 are retried; 429, 404 and other 4xx are terminal, as are redirects other than a same-origin 307/308 (followed at most 5 times with the same body and headers). Backoff doubles from 1 to 30 seconds with 25% jitter, and `Retry-After` is a floor capped at 30 seconds for every queue. Replay and logs keep their retry sets. Legacy cached events (`PostHogSendCachedEventsIntegration`) are sent through capture v1 too; the ones capture asks to retry are re-queued at the tail of the legacy file for the next launch. `PostHogConfig.maxRetries` is renamed `pushNotificationSubscriptionMaxRetries` since it only limits push-subscription retries. `PostHogApi.batch()` stays for posthog-server. Co-Authored-By: Claude Fable 5.1 * chore(compliance): run the capture v1 suite against the adapter The adapter advertises `capture_v1` and `encoding_gzip`, tracks `/i/v1/analytics/events` requests with `retry_attempt` derived from `PostHog-Attempt`, maps `max_retries` to the renamed config field and runs with `personProfiles = ALWAYS`, since the harness never identifies. The workflow pins harness 1.20.0 and also runs for PRs that target the `chore/v4-*` and `feat/v4-*` branches. Co-Authored-By: Claude Fable 5.1 * docs: changeset bullets and migration guide for capture v1 Co-Authored-By: Claude Fable 5.1 * fix: resend a failed capture request as is, without client retries or logged bodies The queue now resends exactly the files of a request that failed or came back with events to retry, so the API keeps its request ID and `created_at` and bumps `PostHog-Attempt`. Before, the next request took the head of the queue, and any event queued since gave it a new ID at attempt 1. A 413 still halves the batch as a new request, and a file the queue drops in the meantime starts over. The capture client turns off OkHttp's `retryOnConnectionFailure`, which resent a request on a reused connection with a stale attempt number and timestamp. Debug logs for capture requests name the event count and the response status instead of printing the request and response bodies, which hold event content. Co-Authored-By: Claude Opus 5.5 * fix: stop OkHttp resending a capture 503 with Retry-After 0 OkHttp's follow-up layer resends a 503 carrying `Retry-After: 0` even with retryOnConnectionFailure off, repeating PostHog-Attempt and PostHog-Request-Timestamp outside the queue's backoff. A network interceptor on the capture client drops that header before the retry layer sees it; the queue waits the same with or without it. Co-Authored-By: Claude Opus 5.5 * fix: cap the capture v1 response read at 1 MiB A successful capture response was read whole into memory. Read at most 1 MiB and treat a larger or endless body as unreadable, which counts the batch as delivered like any other 2xx without readable results. Co-Authored-By: Claude Opus 5.5 * fix: keep the queue's retry jitter in milliseconds Rounding the jittered backoff to whole seconds removed the jitter from the 1 s and 2 s waits, so devices refused together retried together. The delay is now kept in milliseconds. Co-Authored-By: Claude Opus 5.5 * test: send a 3.x event queued on disk through capture v1 Co-Authored-By: Claude Opus 5.5 * docs: list what a reverse proxy needs for capture v1 Co-Authored-By: Claude Opus 5.5 * fix: cap the time spent reading capture v1 results A 2xx body that trickles bytes within the read timeout held the queue thread until it ended. Reading the results now has a 10 second deadline, after which the body counts as unreadable and the events as delivered, like an oversized body. Co-Authored-By: Claude Opus 5.5 * feat!: add per-event capture options and one property precedence `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException` take an `options` map that is copied onto the new `PostHogEvent.options`, so PostHog can be told how to process one event apart from its properties and `beforeSend` can edit it. Properties are merged in one order: SDK-set values, registered super properties, the caller's properties (with `$set`, `$set_once` and `$groups` as per-call values), then `beforeSend`. `$is_identified`, `$process_person_profile` and the replay debug properties are no longer re-applied after the caller's values. The SDK sets the `process_person_profile` option to `false` only when person processing is off, and only when neither a caller option nor a caller or registered `$process_person_profile` property already says so. It no longer writes a `$process_person_profile` property. Also: a blank `distinctId` argument on `capture` uses the current distinct id; a `$set` sent with `process_person_profile: false` neither stores nor matches the person-properties hash; an event returned by `beforeSend` keeps the uuid of the client capture it came from; the minimal `$feature_flag_called` allowlist keeps `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id`; the compliance adapter forwards `options` and advertises `event_options`. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DRbQPidntd4hVufNpMT19L * test: cover capture options, property precedence and the personless option Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DRbQPidntd4hVufNpMT19L * docs: describe capture options and property precedence for 4.0 Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DRbQPidntd4hVufNpMT19L * fix: skip PostHog-reserved deep link query parameters A link opened with ?$process_person_profile=true copied that parameter into the Deep Link Opened properties, where capture v1 turns it into the process_person_profile option and enables person processing despite PersonProfiles.NEVER. Query parameters whose name starts with $ are now skipped. Co-Authored-By: Claude Opus 5.5 * docs: say the retry jitter keeps millisecond precision Co-Authored-By: Claude Opus 5.5 * fix: keep the personless option when the legacy property is null A Java caller can pass a null `$process_person_profile`. It no longer counts as an override, so the SDK still sends `process_person_profile: false` when person processing is off. Co-Authored-By: Claude Opus 5.5 * docs: escape dollar-prefixed keys in the Kotlin migration examples Co-Authored-By: Claude Opus 5.5 * feat: add captureAi on the capture v1 AI endpoint `captureAi` takes the same arguments as `capture`, goes through the same enrichment, precedence, personless default and `beforeSend`, and queues the event on its own disk queue, executor and retry identity for `POST /i/v1/ai/events`. It returns the event's uuid once it's handed to the queue, or null when the SDK is disabled or opted out or `beforeSend` dropped it. A name not starting with `$ai_` logs one debug line and is sent unchanged; `capture` never reroutes `$ai_*` events. The AI request client uses `captureAiTimeout` for its call, read and write timeouts and honors `captureAiCompression` through its own gzip interceptor instance. `PostHogQueue` becomes byte-aware through `EndpointSpec`: `maxBatchBytes` bounds a request window (check before append, an oversize record goes alone) and flushes as soon as that much is queued; `maxQueueBytes` is a FIFO disk cap on top of `maxQueueSize`, enforced on add and on load; `maxRecordBytes` drops a record over the limit when it's queued, logging only its name and size. The analytics spec gets a 5 MiB request cap; the AI spec gets 5 MiB requests, 50 MiB on disk and `captureAiMaxEventBytes` (at most 8 MiB) plus a 64 KiB envelope per event. New `PostHogConfig` knobs: `captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes`; non-positive values use the defaults. `PostHogAndroid` stores the AI queue under `posthog-disk-ai-queue`. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DRbQPidntd4hVufNpMT19L * test: cover captureAi, the AI lane and byte-aware batching SDK-level: routing by method, beforeSend and options, null returns, a terminal 404, the oversize drop (name and size only in the log), the non-`$ai_` debug line, flush and close draining the AI queue, compression per lane and the AI timeout. API-level: the AI endpoint's headers and body, separate retry identities per lane, and an AI queue keeping only the events asked to retry. Queue-level, on a synthetic record: byte-limited request windows, an oversize record sent alone, the flush at a request's worth of bytes, the per-record drop, the disk cap on add and on load, and the spec limits and config fallbacks. The Android setup test covers the AI storage prefix. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DRbQPidntd4hVufNpMT19L * chore(compliance): run the capture v1 AI suite against the adapter Adds `POST /capture_ai`, which routes through `captureAi` and returns the uuid it sent, tracks `/i/v1/ai/events` requests next to the analytics ones and advertises `capture_ai_v1`. Also restores the capture v1 adapter changes (tracking by capture path, `PostHog-Attempt` as the retry count, `personProfiles = ALWAYS`, the renamed push retries field) that the options commit reverted. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DRbQPidntd4hVufNpMT19L * docs: changeset bullets and migration guide for captureAi Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01DRbQPidntd4hVufNpMT19L * docs: list the AI endpoint in the migration guide's endpoint table Co-Authored-By: Claude Opus 5.5 * fix: check the AI event size before queuing and return null when over The queue measured an AI event after `encryption`, so an encryption that grows the data dropped events PostHog would accept, and captureAi had already returned the uuid. captureAi now measures the serialized event before encryption and returns null when it's over the limit. The queue's per-record limit had no other user and is removed. Co-Authored-By: Claude Opus 5.5 * docs: describe the AI size limit and timeout as they behave The limit covers an AI event's properties up to 8 MiB, with 64 KiB for the rest of the serialized event, measured before encryption. captureAiTimeout is a timeout without network activity, not a call timeout. Co-Authored-By: Claude Opus 5.5 * chore(compliance): report no uuid when captureAi doesn't queue the event Co-Authored-By: Claude Opus 5.5 * fix: log each event capture v1 drops with the reason it gives Debug logs named only the drop count, so a misrouted_event or ai_event_too_big drop was invisible. Each dropped event is now logged with its name, uuid and the server's details, never its properties. Adds a test that an AI event with exactly 8 MiB of properties is sent. Co-Authored-By: Claude Opus 5.5 * fix: stop measuring an AI event once it passes the size limit captureAi checks the size on the caller's thread, so a huge prompt or base64 payload no longer costs a full serialization just to be dropped. Co-Authored-By: Claude Opus 5.5 * fix: log an unserializable property by key and type, not by value Properties can hold prompts and other user content. Co-Authored-By: Claude Opus 5.5 * docs: say the AI size check builds the full JSON tree before it stops counting * test: double bytes instead of Base64 in the AI encryption test java.util.Base64 isn't on API 23, so animalsnifferTest failed. Co-Authored-By: Claude Opus 5.5 * test: make the unserializable Turn a plain class The data class hashCode calls Double.hashCode(double), which isn't on API 23. Co-Authored-By: Claude Opus 5.5 * test: write encrypted test streams in blocks Co-Authored-By: Claude Opus 5.5 * fix: retry capture v1 requests that get 404 or 429 (#897) * fix: retry capture v1 requests that get 404 or 429 A 404 usually means a misconfigured proxy and a 429 now only comes from an overloaded ingress, so keep the events queued and retry them with the usual backoff and Retry-After handling instead of dropping them. Matches PostHog/posthog-go#395. * fix: warn once when capture v1 returns 404 A 404 now keeps events queued, so nothing tells the app that the route is missing. Print one warning per client, even without debug, naming the URL and the path a reverse proxy or self-hosted instance must serve. * fix: leave host credentials and query out of the capture v1 404 warning Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * docs: escape dollar signs in captureAi examples Co-Authored-By: Claude Opus 5.5 * test: give the serializer privacy fixture a prompt-bearing toString Co-Authored-By: Claude Opus 5.5 * fix: make captureAiMaxEventBytes limit the whole serialized event Match posthog-ios, posthog-python and the Flutter desktop lane: the value is the serialized event size, defaulting to 8 MiB + 64 KiB, instead of a properties size the SDK added 64 KiB to. A value over the ceiling now logs a warning when it is clamped. Co-Authored-By: Claude Opus 5.5 * fix: subtract a queued file's counted size when it's removed A file deleted from the cache dir reads as 0 bytes, so the queue kept counting it and evicted new AI events against bytes that were gone. Co-Authored-By: Claude Opus 5.5 * fix: read lenient false person-processing values before caching person properties Capture reads "false", 0 and similar strings as false, so a $set sent with them is personless and must not store the person-properties hash. Co-Authored-By: Claude Opus 5.5 * fix: send a fatal event even while a request waits to be retried The fatal flush resent only the retry set, so the crash report stayed on disk as the process exited. Co-Authored-By: Claude Opus 5.5 * chore(compliance): count only delivered events when capture asks to retry some Co-Authored-By: Claude Opus 5.5 * chore(compliance): run the 1.26.0 test harness against the adapter (#902) * chore(compliance): run the 1.25.0 test harness against the adapter Bump the harness from 1.20.0 (CI) and 0.10.0 (local docker-compose) to 1.25.0, and declare the 1.25 capabilities the SDK supports: generated_payloads, log_capture, property_layers and fail_open. Co-Authored-By: Claude Opus 5.5 * chore(compliance): count the marker's serialized bytes when padding AI properties * chore(compliance): bump the test harness to 1.26.0 Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * feat: let wrapper SDKs run their own beforeSend on the fully built event (#904) * chore(api): keep @PostHogInternal declarations out of the API dumps * feat: let wrapper SDKs build an event, run their own beforeSend, then send it * fix: start the replay debug window when the wrapper's event is queued * fix: defer wrapper build state changes and the replay debug claim to send A built event the wrapper drops no longer caches the screen name, updates the person properties used for flags, or claims the replay debug bundle. The send does all three, as capture does, so the window starts with the event that carries the bundle. * fix: keep wrapper builds state-free and send each built event once Build defers person processing to send and records the built name for replay debug eligibility. Send adds only the throttled replay debug keys (API 23 safe, keeps keys the wrapper's hook removed), skips flag person properties when the user changed since the build, and ignores a second send of the same event. * fix: tie a wrapper send to the build's setup, instance and identity A send now drops an event this instance didn't build or built before setup()/close(), skips person processing and flag person properties after reset() (also when reuseAnonymousId keeps the distinct id), and adds the replay debug values snapshotted at build. * fix: don't restore a wrapper screen name after a reset since the build * fix: add the replay debug bundle to wrapper AI events, like captureAi * fix: read replay debug state once per wrapper build The build's required replay keys and the deferred bundle came from two debugProperties() reads, so a replay transition between them could send $recording_status=buffering without its hold reason. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * fix: record the wrapper build's identity before enriching the event A reset() or identify() during the build left the event with the old distinct ID while the build recorded the new identity, so the send applied the old user's $set to the new user's flag properties. Co-Authored-By: Claude Opus 5.5 * chore(compliance): read capture responses outside the adapter lock Co-Authored-By: Claude Opus 5.5 * fix: drop the oldest AI events while too many wait to be written to disk (#901) * fix: drop an AI event while too many wait to be written to disk One executor both writes and sends AI events, so during a slow upload new multi-MiB events waited in memory with no limit. captureAi now returns null while captureAiMaxQueueSize events or 50 MiB are waiting, the same limits the disk queue keeps. Co-Authored-By: Claude Opus 5.5 * fix: drop the oldest waiting AI events instead of the new one While a slow upload holds the AI executor, captureAi now keeps the new event and drops the oldest events still waiting to be written once captureAiMaxQueueSize events or 50 MiB wait, the same as the disk queue already does. captureAi returns null again only for disabled, opted-out, beforeSend-dropped or oversized events. Co-Authored-By: Claude Opus 5.5 * fix: queue no more AI write tasks than events waiting to be written Dropping a waiting AI event no longer leaves its executor task behind for nothing: a dropped event's task writes a newer one instead, so the executor never holds more tasks than events are waiting. Co-Authored-By: Claude Opus 5.5 * fix: queue AI write tasks in the order their events were added --------- Co-authored-by: Claude Opus 5.5 * docs: tell proxies that strip credentials to keep the project token Co-Authored-By: Claude Opus 5.5 * docs: say which capture drop logs need debug and what they print Co-Authored-By: Claude Opus 5.5 * docs: add 402, 404 warning, debug logs and AI queue details to the 4.0 guide Co-Authored-By: Claude Opus 5.5 * chore: keep PostHogInternal APIs in the api dumps apiCheck is the only check that flags a changed internal signature that posthog-server or a wrapper SDK relies on. The dumps list them again, as on main. Co-Authored-By: Claude Opus 5.5 * docs: remove leftover conflict markers from the 4.0 guide * fix: keep the capture result when an event handler throws * fix: match capture v1 rules for empty names, drop logs, retry identity and typed values (#903) * fix: match the capture v1 rules for empty names, drop logs, retry identity and typed values * fix: merge a $groups map in properties into the groups set with group() * fix: log an empty-name drop once, without the generic dropped-event line * fix: clamp each duplicates_dropped count to the batch size * fix: keep the pending retry map off Java 8 Map methods missing on API 23 * fix: keep the personless option over a legacy property and drop a 2xx without results (#905) * fix: keep the personless option when a legacy person processing property is set A passed or registered `$process_person_profile` property no longer stops the SDK from setting `process_person_profile: false` when person processing is off. The send hoists the property only into an unset option, so an option set by any layer wins, as the capture spec requires. Co-Authored-By: Claude Opus 5.5 * fix: treat a 2xx without readable per-event results as a terminal failure A 2xx whose body can't be read as `{"results": {...}}` no longer counts the batch as delivered. It throws a PostHogApiError with that status, which the queue drops without retrying, and logs only the status and event count, as the capture spec requires. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * fix: warn about empty and personal API keys without debug and log rejected batches (#909) * fix: let a caller's $process_person_profile override the personless option Reverts the person-processing half of #905. A passed or registered `$process_person_profile` property again stops the SDK from adding `process_person_profile: false` when person processing is off, so the caller wins, as the client property precedence in sdk-specs `capture` (#143) requires. The send still hoists the property into the option. Co-Authored-By: Claude Opus 5.5 * fix: log drop reasons per batch and batch migrated legacy events by bytes - The capture v1 per-batch debug line names the endpoint and counts the dropped events by their `details` tag (opaque strings, never uuids or content), e.g. `ai_event_too_big: 1, misrouted_event: 1`. - Sending events cached by 2.x/3.x closes a batch before it would pass the 5 MiB capture v1 byte target, as the queue does, so a large migrated batch isn't lost to a 413. Order is kept and an event over the target ships alone. Co-Authored-By: Claude Opus 5.5 * docs: say the token warnings print without debug Co-Authored-By: Claude Opus 5.5 * fix: name the records in the flush drop log Co-Authored-By: Claude Opus 5.5 * test: cover the capture rules on the captureStateless path Also adds the posthog-server changeset for them. Co-Authored-By: Claude Opus 5.5 * docs: fold the server capture changes into the server changeset --------- Co-authored-by: Claude Opus 5.5 * docs: keep PostHog keys when a proxy strips Authorization * fix: only move the current screen for wrapper events built as $screen (#930) * fix: keep a wrapper event sent for another distinct id out of the current user's person state (#928) * docs: review beforeSend hooks for the 4.0 event shape (#924) * docs: ask users to review beforeSend hooks for the 4.0 event shape * docs: cover replacing event.options in beforeSend Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 * feat!: report the device language as $locale and add $app_language (#927) * feat!: report the device language as $locale and add $app_language * fix: address the pre-PR review of $locale and $app_language * docs: correct the $locale migration notes * fix: read a registered $app_language without relying on merge order * fix: read locales and the locale config only on the worker thread Setup and capture no longer make Binder calls or parse the locale config, and supported locales changed at runtime with setOverrideLocaleConfig are picked up. Co-Authored-By: Claude Opus 5.5 * fix: leave out $app_language when several declared regions could match Co-Authored-By: Claude Opus 5.5 * fix: stop reading a registered $app_language on every event Registered properties are merged later and win anyway. Co-Authored-By: Claude Opus 5.5 * fix: guard LocaleList calls for the API 23 lint check Co-Authored-By: Claude Opus 5.5 * fix: read the override locale config only when the locales change Co-Authored-By: Claude Opus 5.5 * docs: say when $app_language is left out with no match --------- Co-authored-by: Claude Opus 5.5 * fix: keep events with non-string map keys and align capture v1 logs (#929) * fix: align capture v1 logs, request IDs and beforeSend handling * fix: copy arrays and cycles for beforeSend, and keep the hook failure log debug-only * fix: keep array types in the copy beforeSend hooks get * fix: keep sorted map lookups and copy primitive arrays for beforeSend * fix: read an HTTP-date Retry-After * fix: log the key type when a map key can't be serialized * docs: link the capture v1 upgrade guide and align the 4.0 guide with the backend guides (#934) * docs: link the capture v1 SDK upgrade guide Co-Authored-By: Claude Opus 5.5 * docs: add timestamps, UUID v7 and the person-only drop to the 4.0 guide * docs: align the 4.0 capture v1 guide with the backend SDK guides Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq --------- Co-authored-by: Claude Opus 5.5 * fix!: keep the 3.x PostHogEvent constructor and copy posthog-server is a minor release and its beforeSend gets PostHogEvent, so a new trailing constructor parameter broke Java callers and copy calls compiled against 3.x. options is now a property. When beforeSend returns a different event with null options, such as a copy, it keeps the options of the event the hook was given. Co-Authored-By: Claude Opus 5.5 * docs: close the 4.0 guide gaps found in the release review - Remove the two internal TODO comments. - Say surveys-compose works with core 6.x and 7.0. - List RRStyle and the trimmed RRWireframe under internal APIs. - captureAi also returns null for an empty event name. - Note per-event product quota drops, the per-batch drop reasons and the removed per-event "queued" log line. - Self-hosting needs /i/v1/ai/events for captureAi. - A whitespace-only token disables the SDK too. - Describe the 3.x $set/$set_once/$groups replacement rule and the registered $set rule. - KDoc: the AI size drop logs the limit, not the event's size. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Fable 5.1 --- .changeset/android-v4-major.md | 29 + .changeset/server-keep-on-feature-flags.md | 3 + .github/workflows/sdk-compliance-tests.yml | 4 +- docs/migration-3.x-to-4.0.md | 272 +++++- posthog-android/api/posthog-android.api | 2 + .../com/posthog/android/PostHogAndroid.kt | 1 + .../posthog/android/PostHogAndroidConfig.kt | 8 + ...HogActivityLifecycleCallbackIntegration.kt | 3 + .../android/internal/PostHogAndroidContext.kt | 23 +- .../android/internal/PostHogLocales.kt | 155 +++ .../PostHogAndroidEventSnapshotsTest.kt | 21 +- .../android/PostHogAndroidSetupLookupsTest.kt | 20 +- .../PostHogNativeCrashIntegrationTest.kt | 13 +- ...ctivityLifecycleCallbackIntegrationTest.kt | 9 + .../internal/PostHogAndroidContextTest.kt | 133 +++ .../internal/PostHogAppLanguageTest.kt | 67 ++ .../replay/PostHogReplayIntegrationTest.kt | 3 +- .../json/snapshots/batch-request.json | 129 ++- posthog/api/posthog.api | 117 ++- posthog/src/main/java/com/posthog/PostHog.kt | 922 +++++++++++++++--- .../main/java/com/posthog/PostHogConfig.kt | 65 +- .../java/com/posthog/PostHogCoreInterface.kt | 13 - .../src/main/java/com/posthog/PostHogEvent.kt | 19 +- .../main/java/com/posthog/PostHogInterface.kt | 187 +++- .../main/java/com/posthog/PostHogStateless.kt | 181 +++- .../com/posthog/PostHogStatelessInterface.kt | 13 + .../java/com/posthog/internal/EndpointSpec.kt | 161 ++- .../posthog/internal/GsonSafeMapSerializer.kt | 27 +- .../internal/GzipRequestInterceptor.kt | 115 ++- .../java/com/posthog/internal/PostHogApi.kt | 436 ++++++++- .../PostHogPushSubscriptionManager.kt | 4 +- .../java/com/posthog/internal/PostHogQueue.kt | 350 ++++++- .../PostHogSendCachedEventsIntegration.kt | 59 +- .../java/com/posthog/PostHogBeforeSendTest.kt | 103 ++ .../java/com/posthog/PostHogBootstrapTest.kt | 2 +- .../java/com/posthog/PostHogCaptureAiTest.kt | 450 +++++++++ .../com/posthog/PostHogCaptureOptionsTest.kt | 404 ++++++++ .../com/posthog/PostHogPersonProfilesTest.kt | 49 +- .../PostHogSessionReplayHandlerFake.kt | 5 +- .../java/com/posthog/PostHogStatelessTest.kt | 62 +- .../src/test/java/com/posthog/PostHogTest.kt | 225 ++++- .../com/posthog/PostHogWrapperEventTest.kt | 482 +++++++++ posthog/src/test/java/com/posthog/Utils.kt | 8 + ...ErrorTrackingAutoCaptureIntegrationTest.kt | 12 +- .../com/posthog/internal/EndpointSpecTest.kt | 36 +- .../com/posthog/internal/PostHogApiTest.kt | 6 +- .../posthog/internal/PostHogCaptureV1Test.kt | 914 +++++++++++++++++ .../PostHogPushSubscriptionManagerTest.kt | 2 +- .../internal/PostHogQueueByteLimitsTest.kt | 251 +++++ .../internal/PostHogQueueDurabilityTest.kt | 17 +- .../com/posthog/internal/PostHogQueueTest.kt | 184 +++- .../internal/PostHogReplayQueueTest.kt | 9 +- ...ogSendCachedLegacyEventsIntegrationTest.kt | 92 +- .../posthog/internal/PostHogSerializerTest.kt | 50 + .../java/com/posthog/PostHogFake.kt | 30 +- .../IMPLEMENTATION_NOTES.md | 14 +- sdk_compliance_adapter/README.md | 10 +- sdk_compliance_adapter/docker-compose.yml | 2 +- .../posthog/compliance/ComplianceAdapter.kt | 194 +++- 59 files changed, 6593 insertions(+), 584 deletions(-) create mode 100644 posthog-android/src/main/java/com/posthog/android/internal/PostHogLocales.kt create mode 100644 posthog-android/src/test/java/com/posthog/android/internal/PostHogAppLanguageTest.kt create mode 100644 posthog/src/test/java/com/posthog/PostHogCaptureAiTest.kt create mode 100644 posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt create mode 100644 posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt create mode 100644 posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt create mode 100644 posthog/src/test/java/com/posthog/internal/PostHogQueueByteLimitsTest.kt diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 36019aa41..782be62ea 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -23,5 +23,34 @@ - **Breaking:** remove `PostHogConfig.onFeatureFlags`; call `PostHog.onFeatureFlags(callback)` before `setup()` instead, which also covers the first load - **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `reloadFeatureFlags()`; it receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values, and `errorsLoading` - **Breaking:** add the abstract `onFeatureFlags()` method to `PostHogInterface`; classes that implement it must add the method +- **Breaking:** send events to capture v1 (`/i/v1/analytics/events`) with the project token in an `Authorization: Bearer` header; if you use a reverse proxy or self-host PostHog, make sure the path is served, because events stay queued and are retried on a 404, with a warning printed once even when `debug` is off, and authenticate your proxy with a header other than `Authorization`, which capture requests replace +- **Breaking:** stop retrying 3xx responses for events, retry 404 responses, and cap a `Retry-After` pause at 30 seconds for events, session replay and logs +- **Breaking:** add up to 25% random jitter to the wait after a failed send, which still doubles from 1 second to 30 seconds, and treat a `Retry-After` as a minimum wait instead of replacing the backoff, for events, session replay and logs; queued records are still kept until they're delivered +- **Breaking:** follow only a 307 or 308 redirect of a capture request to the same origin as `host`, at most 5 times; any other redirect drops the events, so point `host` at the final host +- **Breaking:** send the `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id` properties as capture options (`PostHogEvent.options`, a new property; the constructor and `copy` are unchanged, and an event `beforeSend` returns with null options keeps the incoming ones), where PostHog drops an event whose option value it can't read +- **Breaking:** rename `PostHogConfig.maxRetries` to `pushNotificationSubscriptionMaxRetries`, because it only limits push-notification subscription retries +- **Breaking:** set `$lib` and `$lib_version` from the `PostHog-Sdk-Info` request header; a value set in properties, super properties or `beforeSend` is removed before sending +- **Breaking:** send `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields; a non-string value is dropped, with a log when `debug` is on +- **Breaking:** disable the SDK at setup when `projectToken` is a personal API key (`phx_...`), as for an empty token, and print a warning for both even when `debug` is off +- **Breaking:** add an `options` argument to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException` for per-event capture options such as `cookieless_mode`, sent apart from the properties and editable in `beforeSend` through `PostHogEvent.options`; Java callers pass the trailing argument or `null`, and classes that implement `PostHogInterface` add the parameter +- **Breaking:** move `identify(distinctId, userProperties, userPropertiesSetOnce)` from `PostHogCoreInterface` to `PostHogStatelessInterface`; `PostHogInterface` declares `identify` with the trailing `options` parameter +- **Breaking:** registered super properties now override the properties the SDK sets itself, such as `$os_name`; super and event properties also override `$is_identified`, `$process_person_profile` and the session replay debug properties, which the SDK no longer re-applies after the caller's values +- **Breaking:** the SDK sets the `process_person_profile` option to `false` only when person processing is off, and no longer adds a `$process_person_profile` property to every event +- **Breaking:** keep the uuid of its own capture on the event `beforeSend` returns, so a uuid set in `beforeSend`, for example with `copy(uuid = …)`, is replaced +- **Breaking:** add `captureAi` to send AI events such as `$ai_generation` to PostHog's AI endpoint (`/i/v1/ai/events`), which accepts events whose properties are up to 8 MiB, on its own disk queue; it returns the event uuid, or `null` when the event isn't queued; past `captureAiMaxQueueSize` AI events or 50 MiB, including events still waiting to be written to disk, the oldest are dropped, and classes that implement `PostHogInterface` add the method +- use the current distinct ID when the `distinctId` argument to `capture` is empty or whitespace-only, instead of dropping the event +- **Breaking:** skip deep link query parameters whose name starts with `$` in the `Deep Link Opened` event, so a link can't set a PostHog property such as `$process_person_profile` +- stop storing or matching the person-properties deduplication hash for a `$set` sent with `process_person_profile: false` +- debug logs for capture requests name the event count and the response status instead of printing the request and response bodies, and count the events PostHog drops, the duplicate copies it drops and the events it asks to retry, in one line per batch, and log the status when PostHog rejects a whole batch +- **Breaking:** drop an event whose name is empty before sending it, including one `beforeSend` renames to `""` +- **Breaking:** let `userProperties`, `userPropertiesSetOnce` and `groups` win key by key over `$set`, `$set_once` and `$groups` maps passed in the same call's properties, instead of being replaced by them, and merge a `$groups` map in properties into the groups set with `group()` +- add `captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` to `PostHogConfig` to tune AI requests separately from other events; the defaults are gzip, 100 queued events (and at most 50 MiB), 60 seconds and 8 MiB + 64 KiB per serialized event +- cap a request at about 5 MiB of events, for analytics and AI events, and send as soon as that much is queued; an event larger than that is sent on its own +- **Breaking:** change `$locale` to the first language in the device settings, as a full language tag such as `zh-Hant-TW`, instead of the app-influenced `Locale.getDefault()` +- **Breaking:** add the abstract `setAppLanguage()` method to `PostHogInterface`; classes that implement it must add the method +- Add the `$app_language` property with the language the app displays on Android 13+, and `setAppLanguage()` to set it on every version - Add `onFeatureFlags()` to get notified after every feature flags load (on the main thread on Android), returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` +- add internal APIs so wrapper SDKs can run their own `beforeSend` on the fully built event before it's sent +- Fix losing an event whose properties hold a nested map with non-string keys +- Give `beforeSend` its own copy of nested properties and options, so an edit never changes your objects - See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md) for upgrade steps diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md index c39f151bb..57116ce82 100644 --- a/.changeset/server-keep-on-feature-flags.md +++ b/.changeset/server-keep-on-feature-flags.md @@ -4,3 +4,6 @@ - Move `PostHogOnFeatureFlags` into `posthog-server`; its API is unchanged - Bump the `posthog` core dependency to 7.0 +- Disable the client at setup when `projectToken` is a personal API key (`phx_...`), as for an empty token, and print why for both even when `debug` is off +- Drop events with an empty name before sending +- Merge `userProperties`, `userPropertiesSetOnce` and `groups` key by key over a `$set`, `$set_once` or `$groups` map in `properties` diff --git a/.github/workflows/sdk-compliance-tests.yml b/.github/workflows/sdk-compliance-tests.yml index 008b64a12..0ae320831 100644 --- a/.github/workflows/sdk-compliance-tests.yml +++ b/.github/workflows/sdk-compliance-tests.yml @@ -8,7 +8,7 @@ on: - 'sdk_compliance_adapter/**' - '.github/workflows/sdk-compliance-tests.yml' pull_request: - branches: [ main ] + branches: [ main, 'chore/v4-*', 'feat/v4-*' ] paths: - 'posthog/**' - 'sdk_compliance_adapter/**' @@ -26,5 +26,5 @@ jobs: with: adapter-dockerfile: sdk_compliance_adapter/Dockerfile adapter-context: . - test-harness-version: "0.10.0" + test-harness-version: "1.26.0" report-name: android-sdk-compliance-report diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index f5686c9a1..70880147f 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -1,9 +1,41 @@ # Migrating from PostHog Android 3.x to 4.0 -4.0 removes APIs deprecated in 3.x and changes the feature flags callback. -Most changes are compile errors with a direct replacement. Read [Behavior changes](#behavior-changes) carefully: those won't show up at build time. +4.0 sends analytics events to capture v1 (`/i/v1/analytics/events`) instead of `/batch`, removes APIs deprecated in 3.x and changes the feature flags callback. +Most removals are compile errors with a direct replacement. [Behavior changes](#behavior-changes) won't show up at build time. +Read the checklist first, then the sections that apply to you. -For the full list of changes, see the [changelog](../posthog-android/CHANGELOG.md). +For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/libraries/capture-v1). + +For the full list of 4.0 changes, see the [changelog](../posthog-android/CHANGELOG.md). + +## Checklist + +You need to change code if your app does any of these: + +- sends events to a self-hosted PostHog or a reverse proxy that doesn't serve `/i/v1/analytics/events` +- authenticates its proxy with an `Authorization` header in `requestHeaders` +- sends events through a proxy that redirects capture requests, other than with a 307 or 308 to the same origin as `host` +- captures events with an empty event name, or with an event name or distinct ID over 200 bytes +- sets an empty distinct ID in `beforeSend` +- assigns a new map to `event.options` in `beforeSend` (see [Event options](#event-options)) +- sets `projectToken` to a personal API key (`phx_...`) +- sets `$lib` or `$lib_version` and expects PostHog to store that value +- reads `$session_id` or `$window_id` from the raw request body, for example in a proxy +- sets `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` or `$product_tour_id` to a value PostHog can't read, such as `"maybe"` +- registers a super property, or passes an event property, with the same key as one the SDK sets, such as `$os_name` or `$is_identified`, and expects the SDK's value to win +- calls `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` or `captureException` from Java, implements `PostHogInterface`, or calls `identify` through a `PostHogCoreInterface` reference +- sets the event `uuid` in `beforeSend` +- relies on a `Retry-After` longer than 30 seconds +- sets `maxRetries` on `PostHogConfig` or `PostHogAndroidConfig` +- uses `apiKey`, `propertiesSanitizer`, `evaluationEnvironments`, `debouncerDelayMs`, `screenshot`, `drawableConverter` or `remoteConfig` +- passes `PostHogConfig` or `PostHogSessionReplayConfig` constructor arguments by position +- calls `getFeatureFlagPayload()`, or passes a default value to `getFeatureFlag()` +- sets `PostHogConfig.onFeatureFlags` or `PostHogOnFeatureFlags`, or passes a callback to `reloadFeatureFlags()` +- uses session replay (see [Session replay records screenshots](#session-replay-records-screenshots)) +- reads a feature flag payload that isn't valid JSON, such as plain text saved as `hello` +- breaks down by `$locale` for the language your app shows (use `$app_language`, and call `setAppLanguage()` if you need it on Android 6–12) +- reads event content or request bodies from the SDK's debug log, or matches its log text +- depends only on `posthog-android-surveys-compose`, or uses `posthog-server` ## Requirements and versions @@ -21,7 +53,7 @@ These are unchanged, so you don't need to change your build for them: - Kotlin language and API compatibility: 2.0 - `posthog-android-gradle-plugin` -Upgrade PostHog artifacts together. Core 7.0 is not binary compatible with SDK versions built against core 6.x, and a mismatch fails at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. +Upgrade PostHog artifacts together. Core 7.0 is not binary compatible with SDK versions built against core 6.x, except `posthog-android-surveys-compose`, which works with both. A mismatch fails at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. ## Removed APIs @@ -39,6 +71,7 @@ All of these are compile errors. Calling them from an already-compiled library t | `PostHogConfig.remoteConfig` | nothing; remote config always loads | | `PostHogConfig.onFeatureFlags` | `PostHog.onFeatureFlags()` before `setup()` | | `PostHogOnFeatureFlags` | `PostHogFeatureFlagsCallback` | +| `PostHogConfig.maxRetries` | `pushNotificationSubscriptionMaxRetries` (see [Retries](#retries)) | The constructor parameters of `PostHogConfig` and `PostHogSessionReplayConfig` move up where these were removed. If you pass arguments by position, check them, or switch to named arguments. @@ -186,7 +219,7 @@ The `reloadFeatureFlags()` callback still runs on a background thread, or right ## `PostHogInterface` implementations -`PostHogInterface` lost `getFeatureFlagPayload()`, gained the abstract `onFeatureFlags()` and changed the callback type of `reloadFeatureFlags()`. Classes that implement it, such as hand-written fakes for tests, no longer compile until they're updated. +`PostHogInterface` lost `getFeatureFlagPayload()`, gained the abstract `onFeatureFlags()` and `setAppLanguage()`, and changed the callback type of `reloadFeatureFlags()`. Classes that implement it, such as hand-written fakes for tests, no longer compile until they're updated. They also add the `options` parameter and `captureAi()` (see [Event options](#event-options) and [AI events](#ai-events)). ```kotlin class FakePostHog : PostHogInterface { @@ -207,7 +240,7 @@ These helpers were public only by accident and were marked `@PostHogInternal`. T - `com.posthog.internal`: `CustomHeadersInterceptor`, `PostHogPrintLogger`, `PropertyGroupDeserializer`, `PropertyValueDeserializer`, `personPropertiesContext()`, `PostHogPreferences.PUSH_SUBSCRIPTION_REJECTED` - `com.posthog.internal.errortracking`: `ThrowableCoercer.fromThrowableToPostHogProperties()` -- `com.posthog.internal.replay`: `RRDocumentNode`, `RRDomContentLoadedEvent`, `RRLoadedEvent` +- `com.posthog.internal.replay`: `RRDocumentNode`, `RRDomContentLoadedEvent`, `RRLoadedEvent`, `RRStyle`; `RRWireframe` keeps only `id`, `x`, `y`, `width`, `height`, `type` and `base64` - `com.posthog.internal.surveys`: `findBestTranslationMatch()` - `com.posthog.android.internal`: `Bitmap.isValid()`, `Bitmap.webpBase64()` - `com.posthog.android.replay.internal`: `LogLine`, `LogcatParser` @@ -234,6 +267,20 @@ If you read a payload as plain text, such as a payload saved as `hello` rather t Apps upgrading from 3.13 or older didn't cache flag details, so until the app's first `/flags` response, a malformed payload cached by 3.x still reads as the raw string, as it did in 3.x. +### `$locale` and `$app_language` + +`$locale` now means the first language in the device settings, as a full language tag such as `de-CH` or `zh-Hant-TW`. In 3.x it came from `Locale.getDefault()`, which could be a secondary language, a per-app language or a value your app set with `Locale.setDefault()`, and it dropped the script (`zh-TW`). It's left out when the device reports no language. On older Android versions, 3.x also sent the legacy codes `iw`, `in` and `ji`, so Hebrew, Indonesian and Yiddish values change, such as `in-ID` to `id-ID`. Update filters that match those. Other values mostly stay the same, so otherwise only check filters if your users change these settings. + +The new `$app_language` property is the language your app shows. Android has no API that reports it exactly, so what you get depends on the version: + +| Android | `$app_language` | +|---|---| +| 13+ with `android:localeConfig` declared (by hand or with AGP `generateLocaleConfig`) | The per-app language or, without one, the first device language, as you declare it. If you don't declare that language, your `android:defaultLocale` (Android 15+) or your language if you only declare one. Not sent if several of your declared languages could match, such as `pt` and `pt-PT` for a `pt-MZ` device, or if nothing matches and you declare several languages without a default. | +| 13+ without `localeConfig` | The per-app language, if one is set. Otherwise not sent. | +| 6–12 | Not sent. | + +Strings you don't translate fall back per string, so the value is the app's language, not a guarantee for every string. Call `PostHog.setAppLanguage("de")` at startup and whenever the language changes to send it on every version, or if you translate some other way, such as with an in-app language setting. It's kept in memory only. + ### Session replay records screenshots 4.0 removes wireframe session replay. Replay always records masked screenshots, which is what `screenshot = true` already did. @@ -266,6 +313,200 @@ The code you end up with after these two migrations compiles, so they're easy to - [`getFeatureFlagResult()` sends `$feature_flag_called` by default](#getfeatureflagpayload), unlike `getFeatureFlagPayload()`. - [Apps that set `remoteConfig = false` now load `/config`](#remoteconfig) and apply its settings. +## Endpoints + +| Data | 3.x | 4.0 | +| --- | --- | --- | +| Analytics events | `/batch` | `/i/v1/analytics/events` | +| Session replay | `/s/` | `/s/`, unchanged | +| AI events (`captureAi`) | – | `/i/v1/ai/events` (see [AI events](#ai-events)) | +| Logs | `/i/v1/logs` | `/i/v1/logs`, unchanged | +| Feature flags | `/flags` | `/flags`, unchanged | + +Capture v1 requests send the project token in an `Authorization: Bearer ` header instead of an `api_key` body field. +This header replaces any `Authorization` header you set in `PostHogConfig.requestHeaders`, so authenticate your proxy with a different header, such as `X-Proxy-Token`. +Other requests still send your `Authorization` header. + +Analytics requests are gzipped unless you set `compression` to `PostHogCompression.NONE`, as in 3.x. + +A personal API key (`phx_...`) in `projectToken` now disables the SDK at setup, as an empty or whitespace-only token does. Both print why, even when `debug` is off. To turn the SDK off in tests, use an empty token. +In 3.x, the SDK started and PostHog rejected every event with a 401. Use your project token (`phc_...`). + +### Hosts without capture v1 + +If you self-host PostHog, make sure `/i/v1/analytics/events` is served before you upgrade, and `/i/v1/ai/events` if you use `captureAi`. +PostHog Cloud (`us.i.posthog.com`, `eu.i.posthog.com`) serves it. + +If you send events through your own reverse proxy, update it before you upgrade: + +- Forward `/i/v1/analytics/events` and `/i/v1/ai/events` to PostHog. +- Pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged. PostHog answers `401` without `Authorization` and `400` without the others, and the events are dropped. If your proxy strips other credentials, keep `Authorization` values that start with `Bearer phc_`, `Bearer phs_` or `Bearer phx_`, plus the exact `Bearer ` of an older key without a prefix. +- Accept request bodies up to 20 MB. AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx. A `413` from the proxy makes the SDK halve the batch until it fits, and drops an event that doesn't fit on its own. +- Pass PostHog's response body through unchanged. A 2xx response whose body isn't PostHog's `{"results": {...}}` drops the events instead of retrying them. + +PostHog's managed reverse proxy already does this. See the [proxy guides](https://posthog.com/docs/advanced/proxy). + +The SDK doesn't fall back to `/batch`. A 404 is retried, so the events stay queued until the path is served, and the SDK prints one warning, even with `debug` off. Any other error status that isn't retried, such as 403 or 405, drops the events. + +### Redirects + +The SDK follows a 307 or 308 redirect only to the origin of `host` (same scheme, host and port), at most 5 times, and resends the same body and headers. +Any other redirect is not followed and the events are dropped. +In 3.x, OkHttp followed redirects to any host. +If a proxy redirects capture requests to another host, point `host` at the final host. + +## Event validation + +Capture v1 checks each event on its own and drops only the invalid ones, so the rest of the batch is delivered. + +The SDK drops an event whose name is empty before sending it, for example `capture("")` or one `beforeSend` renames to `""`. +With `debug` on, it logs this once. + +There's no error callback, as in 3.x. The SDK reports dropped and failed events only in its debug log. + +The SDK doesn't check the rest before sending. PostHog drops the event, and the SDK removes it from the queue. +With `debug` on, the SDK logs one line per batch with how many events PostHog dropped, how many duplicate copies it dropped and how many it asked to retry, with the reasons PostHog gave, never the event names or properties. +It no longer logs a line for each queued event. +Debug logs for capture requests name the event count and the response status, and no longer print the request and response bodies. +When a `beforeSend` hook throws, the debug log names the event and the exception type, not the exception message, which can hold the data the hook was removing. In 3.x it printed the exception. +When a property value can't be serialized, the debug log names the key and the value's type, not the value. In 3.x it printed the value. +Update any log-based checks that match the 3.x text. + +- An event with an empty or whitespace-only distinct ID is dropped, for example one `beforeSend` sets to `""`. +- An event whose name is over 200 UTF-8 bytes is dropped. Legacy capture had no limit on event name length. +- An event whose distinct ID is over 200 UTF-8 bytes is dropped. Legacy capture shortened the ID to 200 characters and kept the event. + +In 3.x, an empty event name or distinct ID made legacy capture reject the whole batch it was in. + +A `NaN` or infinite number in the properties is dropped from the event, and the event is sent without it. + +A map key in the properties that isn't a string is converted to one when it's a number, a boolean or `null`. Any other key is dropped with its value, and the rest of the event is sent. With `debug` on, the SDK logs the key's type. In 3.x, a nested map with a non-string key lost the whole event. + +The distinct ID can come from `identify()`, the `distinctId` argument of `capture` or `beforeSend`. +If you identify users with a long ID, such as a JWT or a long email address, shorten or hash it before you upgrade. Otherwise every event for that user is dropped. +`identify()` with an empty or whitespace-only distinct ID is still ignored, as in 3.x. + +## SDK identity + +PostHog sets `$lib` and `$lib_version` from the `PostHog-Sdk-Info` request header, for example `posthog-android/4.0.0`. +The SDK removes `$lib` and `$lib_version` from the properties it sends to capture v1. +A value you set in properties, in a super property or in `beforeSend` doesn't reach PostHog. +The SDK removes them when it sends the event, so `beforeSend` still sees them. + +## Property precedence + +An event's properties are merged in this order, and later values win: + +1. properties the SDK sets itself, such as `$os_name`, `$app_version`, `$screen_name`, `$is_identified`, `$session_id` and the session replay debug properties (`$recording_status`, `$sdk_debug_*`) +2. registered super properties (`register`) +3. the properties you pass to `capture` or another event-sending method; `userProperties`, `userPropertiesSetOnce` and `groups` are placed as `$set`, `$set_once` and `$groups` here, and when you also pass that key in properties they win key by key; a `$groups` map in properties adds to the groups set with `group()` instead of replacing them +4. `beforeSend` + +In 3.x, the SDK's own values won over super properties, and `$is_identified`, `$process_person_profile` and the session replay debug properties also won over the properties you pass. +In 4.0 a value you register or pass wins, for example `register("\$os_name", "custom")` sends every event with that value. +A registered `$session_id` now overrides the SDK's session ID, which can detach events from their session replay. +A caller `$screen_name` or `$session_id` still replaces the SDK's value even when it's blank, as in 3.x, so a blank `$session_id` is sent as an empty `session_id`. +In 3.x, a `$set`, `$set_once` or `$groups` map in properties replaced the per-call values and the groups set with `group()`. A `$set` or `$set_once` you pass, or `userProperties`, still replaces a registered one whole. + +## Session and window IDs + +Capture v1 sends `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, not as properties. +The SDK moves them out of `properties` for you. +A string value, including an empty string, is sent unchanged. +Any other value is removed and not sent. With `debug` on, the SDK logs the key and the value's JSON type, never the value. +A null value counts as unset and is removed without a log. +In PostHog, the events still have `$session_id` and `$window_id`, so insights, filters and session replay work as before. + +## Timestamps and IDs + +The SDK sends every timestamp in UTC with 3 fractional digits, for example `2026-01-01T00:00:00.000Z`, as 3.x did. +It doesn't check for future timestamps. PostHog replaces a timestamp more than 23 hours ahead with the time it received the event. +Event uuids and anonymous distinct IDs are UUID v7, as in 3.x. An anonymous ID you change with `getAnonymousId` is sent as you return it. +Each capture request also sends a UUID v7 request ID in the `PostHog-Request-Id` header, which 3.x didn't send. + +## Event options + +Capture v1 reads processing settings from an `options` object sent next to `properties`. +`capture` takes a new `options` argument, and `beforeSend` can read and change `PostHogEvent.options`. +`screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException` take the same argument, as their last parameter. +For `identify`, the options apply to the `$identify` or `$set` event the call sends. + +```kotlin +// 3.x +PostHog.capture("signed_up", properties = mapOf("\$cookieless_mode" to true)) + +// 4.0 +PostHog.capture("signed_up", options = mapOf("cookieless_mode" to true)) +``` + +Kotlin callers that use named or positional arguments for the existing parameters keep compiling. +Java callers pass the new trailing `options` argument, or `null`. +Classes that implement `PostHogInterface` add the parameter. +`identify(distinctId, userProperties, userPropertiesSetOnce)` moved from `PostHogCoreInterface` to `PostHogStatelessInterface`; call it through `PostHogInterface` or `PostHogStatelessInterface`. + +The legacy option properties, the `$`-prefixed properties legacy capture reads as settings, still work. +When the event is sent, the SDK removes each one from `properties` and uses it for its option: + +| Legacy option property | Option | +| --- | --- | +| `$process_person_profile` | `process_person_profile` | +| `$cookieless_mode` | `cookieless_mode` | +| `$ignore_sent_at` | `disable_skew_correction` | +| `$product_tour_id` | `product_tour_id` | + +- An option you pass to any of these methods or set in `beforeSend` wins over its legacy property. An option set to `null` counts as unset, so the legacy property fills it. +- To change person processing in `beforeSend`, edit `event.options`. A `$process_person_profile` property the hook adds only fills an option that is still unset, so it doesn't override the `false` the SDK set for an anonymous event. +- When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither, because PostHog processes person profiles by default. In 3.x, every event carried a `$process_person_profile` property. To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. A registered `$process_person_profile` changes it for every event. +- Review your `beforeSend` hooks for the new event shape. In 3.x, the SDK marked person processing with the `$process_person_profile` property. In 4.0, it's the `process_person_profile` option, and the property isn't set. A hook that assigns a new map to `event.options` without keeping that key loses the `false` the SDK set. That turns person processing on for anonymous users, overriding `personProfiles`. Editing `event.options` in place keeps it. +- `options` is a property of `PostHogEvent`, not a constructor parameter, so the constructor and `copy` are unchanged from 3.x. When `beforeSend` returns a different event whose `options` is `null`, such as one made with `event.copy(…)` or the constructor, it gets the options of the event the hook was given. To send an event with no options, set `options` to an empty map. +- A `$set` sent with `process_person_profile: false` doesn't update the person, so it no longer suppresses a later `setPersonProperties` or `identify` call with the same properties as a duplicate. +- The SDK sends option values as given. PostHog reads common forms of a value, such as `"false"` or `0` for a boolean, and drops an event whose option value it can't read. +- Other option keys are sent unchanged, and PostHog ignores keys it doesn't know. +- There are no global or context options. To set an option on every event, register its legacy property, for example `register("\$process_person_profile", false)`. +- There's no setting for GeoIP lookup or `historical_migration` on events, as in 3.x. +- With `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, `identify`, `alias`, `group` and `setPersonProperties` still turn on person processing for the user's later events, as in 3.x. +- A registered option also reaches `$identify`, `$create_alias` and `$groupidentify`. If it turns person processing off, for example `register("\$process_person_profile", false)`, PostHog accepts those events and then drops them with an ingestion warning, and the SDK doesn't report it. +- An empty or whitespace-only `distinctId` argument to `capture` now uses the current distinct ID, like `null`. In 3.x, the event was dropped. +- The event `beforeSend` returns keeps the uuid of the capture it came from. A uuid you set in `beforeSend`, for example with `copy(uuid = …)`, is replaced, so a hook that returns an event kept from an earlier call still sends one uuid per capture. +- Events still queued on disk by 3.x are sent to capture v1 after the update, with their legacy properties moved to options. + +## AI events + +4.0 adds `captureAi`, which sends AI events, such as `$ai_generation`, to PostHog's AI endpoint (`/i/v1/ai/events`) instead of the analytics endpoint. +It takes the same arguments as `capture`, and the events go through the same `beforeSend` hooks. + +```kotlin +PostHog.captureAi( + "\$ai_generation", + properties = mapOf("\$ai_model" to "gpt-5", "\$ai_trace_id" to traceId), +) +``` + +- `captureAi` returns the event's uuid, or `null` when the event isn't queued: the SDK is disabled or opted out, the event name is empty, `beforeSend` dropped it, or it's over the size limit. Once 100 AI events (`captureAiMaxQueueSize`) or 50 MiB are queued, including events still waiting to be written to disk during a slow upload, the oldest are dropped. +- An AI event's properties can be up to 8 MiB. The SDK drops a serialized event over 8 MiB + 64 KiB, measured before `encryption`. With `debug` on, it logs the event name and the limit, never the content. Set `captureAiMaxEventBytes` to lower that limit; a larger value uses 8 MiB + 64 KiB, and with `debug` on the SDK logs that it did. +- PostHog drops an event sent with `captureAi` whose name doesn't start with `$ai_`. `capture` never sends events to the AI endpoint, even ones named `$ai_*`. +- AI requests time out after 60 seconds without network activity, or `captureAiTimeout`. Other requests keep OkHttp's 10-second defaults. +- AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. +- `flush()` and `close()` also send the AI queue, and AI events left on disk are sent at the next launch. +- AI requests are gzipped unless you set `captureAiCompression` to `PostHogCompression.NONE`. `compression` doesn't apply. +- AI events use `flushAt`, `maxBatchSize` and `flushIntervalSeconds`, like other events. A request carries up to about 5 MiB, as for analytics events (see [Retries](#retries)). +- The SDK sends AI events unchanged. It doesn't redact or truncate prompts, outputs or media, so use `beforeSend` to remove anything you don't want to send. + +## Retries + +- The SDK retries network errors and 404, 408, 429, 500, 502, 503 and 504 responses. Other statuses drop the events, including 3xx, and a 402 (billing limit) drops the whole batch. A product quota, such as for exceptions or AI events, drops only those events inside a 200 response. 3.x also retried 3xx responses, and didn't retry 404. +- When the response asks to retry only some events, the SDK keeps those events queued and removes the rest. +- A failed request is resent with the same events, request ID and `created_at`, and the next attempt number, before newer events are sent. The request ID and attempt number reset after an app restart. OkHttp doesn't retry capture requests on its own. +- A `Retry-After` header sets the minimum wait before the next send, up to 30 seconds. This also applies to session replay and logs. In 3.x there was no cap. +- `Retry-After` can be a number of seconds or an HTTP date. 3.x read only a number of seconds. +- After a failed send, the wait before the next one doubles from 1 second up to 30 seconds, with up to 25% random jitter at millisecond precision. In 3.x it doubled without jitter and a `Retry-After` replaced it. This applies to events, session replay and logs. +- Event, session replay and log retries have no limit, as in 3.x: queued records stay until they're delivered or a full queue evicts them (`maxQueueSize`, or `logs.maxBufferSize` for logs). +- `maxRetries` is renamed to `pushNotificationSubscriptionMaxRetries`, with no deprecated alias. It only limits push-notification subscription retries. +- A request carries at most `maxBatchSize` events and about 5 MiB, and the SDK sends as soon as about 5 MiB of events is queued, even before `flushAt` is reached. In 3.x, batches were limited by event count only. +- There's no size limit for one analytics event in the SDK, as in 3.x. An event larger than about 5 MiB is sent in a request of its own. +- A 413 still halves the batch until it fits, as in 3.x. An event that gets a 413 on its own is dropped. +- `beforeSend` still runs when you capture the event, before it's queued, not when the batch is sent. + ## New: `onFeatureFlags()` `onFeatureFlags()` is now the way to listen for flag loads, for example from a screen or a library. You can remove the listener later: @@ -285,19 +526,12 @@ On Android, listeners run on the main thread. On the JVM, they run on a backgrou ## `posthog-server` -`posthog-server` isn't having a major release, and its API is unchanged: it keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` now ships in `posthog-server` itself. None of the changes above apply to its API. +`posthog-server` isn't having a major release, and its API is unchanged: it keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` now ships in `posthog-server` itself. None of the API changes above apply to it. `PostHogEvent`, which `beforeSend` gets, keeps its 3.x constructor and `copy`, and gains an `options` property that `posthog-server` doesn't use. -Its next release depends on core 7.0, so update it if your project also uses core 7.0 or `posthog-android` 4.0. Older `posthog-server` versions aren't compatible with core 7.0 at runtime. +It still sends events to `/batch`, not to capture v1, so the endpoint, proxy, retry and event option changes above don't apply to it either. -## Checklist +A personal API key (`phx_...`) in `projectToken` now disables the client at setup, as an empty token does, and both print why even when `debug` is off. + +Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. -- [ ] Update `posthog-android` to 4.0 and declare it in your build if you only depend on `posthog-android-surveys-compose`, and update `posthog-server` if you use it. -- [ ] Replace `apiKey` with `projectToken`. -- [ ] Replace `propertiesSanitizer` with `addBeforeSend`. -- [ ] Replace `evaluationEnvironments` with `evaluationContexts`. -- [ ] Replace `getFeatureFlagPayload()` with `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload`. -- [ ] Replace `debouncerDelayMs` with `throttleDelayMs`. -- [ ] Remove `remoteConfig`. If it was `false`, expect `/config` requests and its settings to apply. -- [ ] Replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback`, and check existing callbacks for `errorsLoading`. -- [ ] Update any class that implements `PostHogInterface`. -- [ ] Make sure every feature flag payload you read is valid JSON. +Its next release depends on core 7.0, so update it if your project also uses core 7.0 or `posthog-android` 4.0. Older `posthog-server` versions aren't compatible with core 7.0 at runtime. diff --git a/posthog-android/api/posthog-android.api b/posthog-android/api/posthog-android.api index 6e2efaee4..184deda3e 100644 --- a/posthog-android/api/posthog-android.api +++ b/posthog-android/api/posthog-android.api @@ -34,6 +34,7 @@ public class com/posthog/android/PostHogAndroidConfig : com/posthog/PostHogConfi public final fun getCapturePushNotificationSubscriptions ()Z public final fun getCaptureRageClicks ()Z public final fun getCaptureScreenViews ()Z + public final fun getDetectAppLanguage ()Z public final fun getSessionReplayConfig ()Lcom/posthog/android/replay/PostHogSessionReplayConfig; public final fun setCaptureApplicationLifecycleEvents (Z)V public final fun setCaptureDeadClicks (Z)V @@ -43,6 +44,7 @@ public class com/posthog/android/PostHogAndroidConfig : com/posthog/PostHogConfi public final fun setCapturePushNotificationSubscriptions (Z)V public final fun setCaptureRageClicks (Z)V public final fun setCaptureScreenViews (Z)V + public final fun setDetectAppLanguage (Z)V public final fun setSessionReplayConfig (Lcom/posthog/android/replay/PostHogSessionReplayConfig;)V } diff --git a/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt b/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt index 18c407822..1b988ce3c 100644 --- a/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt +++ b/posthog-android/src/main/java/com/posthog/android/PostHogAndroid.kt @@ -196,6 +196,7 @@ public class PostHogAndroid private constructor() { config.storagePrefix = config.storagePrefix ?: File(cacheDir, "posthog-disk-queue").absolutePath config.replayStoragePrefix = config.replayStoragePrefix ?: File(cacheDir, "posthog-disk-replay-queue").absolutePath config.logsStoragePrefix = config.logsStoragePrefix ?: File(cacheDir, "posthog-disk-logs-queue").absolutePath + config.aiStoragePrefix = config.aiStoragePrefix ?: File(cacheDir, "posthog-disk-ai-queue").absolutePath val preferences = config.cachePreferences ?: PostHogSharedPreferences(context, config) config.cachePreferences = preferences // Defaults to PostHogDeviceDateProvider when api < 33 diff --git a/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt b/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt index 39a571cb3..0e796481c 100644 --- a/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt +++ b/posthog-android/src/main/java/com/posthog/android/PostHogAndroidConfig.kt @@ -1,6 +1,7 @@ package com.posthog.android import com.posthog.PostHogConfig +import com.posthog.PostHogInternal import com.posthog.android.replay.PostHogReplayQueue import com.posthog.android.replay.PostHogSessionReplayConfig import com.posthog.internal.EndpointSpec @@ -97,5 +98,12 @@ public open class PostHogAndroidConfig */ public var captureDeadClicks: Boolean = false + /** + * Whether the SDK detects `$app_language` itself. Wrappers that translate outside of native + * resources, such as Flutter, turn this off and report the language they resolved. + */ + @PostHogInternal + public var detectAppLanguage: Boolean = true + internal var replayQueueHolder: PostHogReplayQueue? = null } diff --git a/posthog-android/src/main/java/com/posthog/android/internal/PostHogActivityLifecycleCallbackIntegration.kt b/posthog-android/src/main/java/com/posthog/android/internal/PostHogActivityLifecycleCallbackIntegration.kt index e08701196..32363cfbe 100644 --- a/posthog-android/src/main/java/com/posthog/android/internal/PostHogActivityLifecycleCallbackIntegration.kt +++ b/posthog-android/src/main/java/com/posthog/android/internal/PostHogActivityLifecycleCallbackIntegration.kt @@ -168,6 +168,9 @@ internal class PostHogActivityLifecycleCallbackIntegration( try { data?.let { for (item in it.queryParameterNames) { + // `$` names are PostHog's own, such as `$process_person_profile`, which would + // become a capture option; a link must not set them + if (item.startsWith("$")) continue val param = it.getQueryParameter(item) if (!param.isNullOrEmpty()) { props[item] = param diff --git a/posthog-android/src/main/java/com/posthog/android/internal/PostHogAndroidContext.kt b/posthog-android/src/main/java/com/posthog/android/internal/PostHogAndroidContext.kt index f2a8a52f5..f4347ff86 100644 --- a/posthog-android/src/main/java/com/posthog/android/internal/PostHogAndroidContext.kt +++ b/posthog-android/src/main/java/com/posthog/android/internal/PostHogAndroidContext.kt @@ -6,7 +6,6 @@ import android.os.Build import com.posthog.android.PostHogAndroidConfig import com.posthog.internal.PostHogContext import com.posthog.internal.PostHogThreadFactory -import java.util.Locale import java.util.TimeZone import java.util.concurrent.Executor import java.util.concurrent.LinkedBlockingQueue @@ -39,9 +38,10 @@ internal class PostHogAndroidContext( @Volatile private var networkCarrier: String? = null private val networkCarrierRefreshing = AtomicBoolean(false) + private val locales = PostHogLocales(context, config) init { - refreshNetworkCarrier() + refreshCachedContext() } private val cacheSdkInfo by lazy { @@ -92,7 +92,14 @@ internal class PostHogAndroidContext( override fun getDynamicContext(): Map { val dynamicContext = mutableMapOf() - dynamicContext["\$locale"] = "${Locale.getDefault().language}-${Locale.getDefault().country}" + locales.deviceLocaleTag()?.let { + dynamicContext["\$locale"] = it + } + if (config.detectAppLanguage) { + locales.appLanguage()?.let { + dynamicContext["\$app_language"] = it + } + } System.getProperty("http.agent")?.let { dynamicContext["\$user_agent"] = it // Mirrored into $raw_user_agent, the standardized property PostHog's @@ -106,15 +113,16 @@ internal class PostHogAndroidContext( networkCarrier?.let { dynamicContext["\$network_carrier"] = it } - refreshNetworkCarrier() + refreshCachedContext() return dynamicContext } + // Locale lookups share this worker because they make Binder calls too. // TelephonyManager.networkOperatorName can make a Binder call to the phone process when the // default subscription cache misses, so it's read on a worker thread and events use the last // value. TelephonyCallback isn't an option because it requires location permission. - private fun refreshNetworkCarrier() { + private fun refreshCachedContext() { if (!networkCarrierRefreshing.compareAndSet(false, true)) { return } @@ -124,6 +132,11 @@ internal class PostHogAndroidContext( networkCarrier = context.telephonyManager()?.networkOperatorName?.ifEmpty { null } } catch (ignored: Throwable) { // keep the last known value + } + try { + locales.refresh() + } catch (ignored: Throwable) { + // keep the last known value } finally { networkCarrierRefreshing.set(false) } diff --git a/posthog-android/src/main/java/com/posthog/android/internal/PostHogLocales.kt b/posthog-android/src/main/java/com/posthog/android/internal/PostHogLocales.kt new file mode 100644 index 000000000..e8462b2fb --- /dev/null +++ b/posthog-android/src/main/java/com/posthog/android/internal/PostHogLocales.kt @@ -0,0 +1,155 @@ +package com.posthog.android.internal + +import android.app.LocaleConfig +import android.app.LocaleManager +import android.content.Context +import android.content.res.Resources +import android.os.Build +import android.os.LocaleList +import androidx.annotation.RequiresApi +import com.posthog.android.PostHogAndroidConfig +import java.util.Locale + +/** + * Reads `$locale` and `$app_language`. + * + * On Android 13+, Resources.getSystem() can report the per-app language and go stale, so the only + * exact source is LocaleManager. Its Binder calls and the locale config parsing only run in [refresh], + * on a worker thread, and capture reads the last values. So the event right after a language change + * can still carry the old value, and events before the first refresh carry the Resources language + * and no app language. + */ +internal class PostHogLocales( + private val context: Context, + private val config: PostHogAndroidConfig, +) { + @Volatile + private var systemLocales: LocaleList? = null + + @Volatile + private var applicationLocales: LocaleList? = null + + @Volatile + private var supportedLocales: SupportedLocales? = null + + // parsed once, because refresh runs as often as events are captured + private val declaredLocales: SupportedLocales? by lazy { + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) readDeclaredLocales() else null + } + + fun refresh() { + if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) { + return + } + try { + val localeManager = context.getSystemService(LocaleManager::class.java) ?: return + val system = localeManager.systemLocales + val application = localeManager.applicationLocales + // Reading the override costs system_server disk I/O, so it's only read when the locales + // change. Apps add a language to the override before they select it. + if (config.detectAppLanguage && (system != systemLocales || application != applicationLocales)) { + supportedLocales = readSupportedLocales(localeManager) + } + systemLocales = system + applicationLocales = application + } catch (e: Throwable) { + config.logger.log("Error reading the locales: $e.") + } + } + + fun deviceLocaleTag(): String? { + val system = + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) systemLocales?.takeUnless { it.isEmpty }?.get(0) else null + val locale = system ?: resourcesLocale() + return locale?.withoutExtensions()?.toLanguageTag()?.takeUnless { it == "und" } + } + + /** + * The language the app displays, on Android 13+. Android has no API for the language resources + * resolved to, because the app context reports the preferred language even when the app falls + * back to another. Android 6-12 can only read the declaration by parsing the manifest, so it + * reports nothing rather than guessing. + */ + fun appLanguage(): String? { + if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) { + return null + } + val perApp = applicationLocales?.takeUnless { it.isEmpty }?.get(0) + val supported = supportedLocales ?: return perApp?.withoutExtensions()?.toLanguageTag() + val preferred = perApp ?: systemLocales?.takeUnless { it.isEmpty }?.get(0) ?: return null + return resolveAppLanguage(preferred, supported) + } + + @Suppress("DEPRECATION") + private fun resourcesLocale(): Locale? { + val configuration = Resources.getSystem().configuration + return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) configuration.locales[0] else configuration.locale + } + + // Android 14+ apps can change their supported locales at runtime with setOverrideLocaleConfig + @RequiresApi(Build.VERSION_CODES.TIRAMISU) + private fun readSupportedLocales(localeManager: LocaleManager): SupportedLocales? { + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) { + localeManager.overrideLocaleConfig?.let { return it.toSupportedLocales() } + } + return declaredLocales + } + + @RequiresApi(Build.VERSION_CODES.TIRAMISU) + private fun readDeclaredLocales(): SupportedLocales? { + return try { + val localeConfig = + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) { + LocaleConfig.fromContextIgnoringOverride(context) + } else { + LocaleConfig(context) + } + localeConfig.toSupportedLocales() + } catch (e: Throwable) { + config.logger.log("Error reading the locale config: $e.") + null + } + } +} + +internal class SupportedLocales( + val locales: List, + val default: Locale?, +) + +@RequiresApi(Build.VERSION_CODES.TIRAMISU) +private fun LocaleConfig.toSupportedLocales(): SupportedLocales? { + val locales = supportedLocales?.takeUnless { it.isEmpty } ?: return null + val default = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.VANILLA_ICE_CREAM) defaultLocale else null + return SupportedLocales(locales.toList(), default) +} + +@RequiresApi(Build.VERSION_CODES.N) +private fun LocaleList.toList(): List = (0 until size()).map { get(it) } + +// Android 14+ regional preferences add extensions such as en-US-u-fw-mon. +private fun Locale.withoutExtensions(): Locale = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) stripExtensions() else this + +/** + * The declared form of the first preferred language: the exact tag, else its only relative. With + * several relatives it reports nothing, because Android ranks them with region data it doesn't + * expose, such as pt-MZ preferring pt-PT over pt. It stops at the first preference because a + * library's translation of it makes Android use that language, showing the app's default strings + * instead of a later preference. The default's language is only known when declared or when the app + * declares just one. + */ +@RequiresApi(Build.VERSION_CODES.TIRAMISU) +internal fun resolveAppLanguage( + preferred: Locale, + supported: SupportedLocales, +): String? { + val language = preferred.withoutExtensions() + val candidates = supported.locales.filter { LocaleList.matchesLanguageAndScript(it, language) } + val match = + if (candidates.isEmpty()) { + supported.default ?: supported.locales.singleOrNull() + } else { + candidates.find { it == language } ?: candidates.singleOrNull() + } + return match?.toLanguageTag() +} diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt index e9912e7dd..619d43fd5 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt @@ -31,6 +31,7 @@ import kotlin.test.AfterTest import kotlin.test.BeforeTest import kotlin.test.Test import kotlin.test.assertEquals +import kotlin.test.assertFalse import kotlin.test.assertIs import kotlin.test.assertNotNull import kotlin.test.assertTrue @@ -97,7 +98,10 @@ internal class PostHogAndroidEventSnapshotsTest { sut.captureException(fixedThrowable(), mapOf("handled" to true, "component" to "checkout")) sut.flush() - val request = fixture.server.takeRequests(CONFIG_PATH, "/flags/?v=2", "/batch").single { it.path == "/batch" } + val request = + fixture.server.takeRequests(CONFIG_PATH, "/flags/?v=2", "/i/v1/analytics/events").single { + it.path == "/i/v1/analytics/events" + } val snapshot = requestSnapshot(request, fixture.config) normalizeBatchVolatileFields(snapshot) @@ -218,9 +222,11 @@ internal class PostHogAndroidEventSnapshotsTest { ): MutableMap { assertEquals("POST", request.method) assertEquals("gzip", request.getHeader("Content-Encoding")) - assertEquals("application/json; charset=utf-8", request.getHeader("Content-Type")) + assertTrue(assertNotNull(request.getHeader("Content-Type")).startsWith("application/json")) val userAgent = assertNotNull(request.getHeader("User-Agent")) assertEquals("posthog-android/${config.sdkVersion}", userAgent) + // capture v1 names the SDK in its own header too; other requests don't send it + request.getHeader("PostHog-Sdk-Info")?.let { assertEquals(userAgent, it) } assertTrue(config.sdkVersion.isNotEmpty()) assertEquals("android-events-v1", request.getHeader("X-PostHog-Snapshot")) @@ -233,18 +239,21 @@ internal class PostHogAndroidEventSnapshotsTest { "path" to request.path, "headers" to linkedMapOf( + "Authorization" to request.getHeader("Authorization"), "Content-Encoding" to request.getHeader("Content-Encoding"), "Content-Type" to request.getHeader("Content-Type"), + "PostHog-Attempt" to request.getHeader("PostHog-Attempt"), + "PostHog-Sdk-Info" to request.getHeader("PostHog-Sdk-Info")?.let { "posthog-android/" }, "User-Agent" to "posthog-android/", "X-PostHog-Snapshot" to request.getHeader("X-PostHog-Snapshot"), - ), + ).filterValues { it != null }, "body" to decodedBody, ) } private fun normalizeBatchVolatileFields(snapshot: MutableMap) { val body = snapshot.map("body") - assertEquals(FIXED_TIMESTAMP, body["sent_at"]) + assertEquals(FIXED_TIMESTAMP, body["created_at"]) val batch = body["batch"] assertIs>(batch) @@ -260,7 +269,9 @@ internal class PostHogAndroidEventSnapshotsTest { UUID.fromString(uuid) event["uuid"] = "" val properties = event.map("properties") - normalizeSdkVersion(properties) + // capture v1 reads the SDK name and version from the PostHog-Sdk-Info header + assertFalse(properties.containsKey("\$lib")) + assertFalse(properties.containsKey("\$lib_version")) // Depends on how many earlier captures the async queueExecutor has drained by the time // this event's properties are built on the calling thread -- not deterministic run to run. if (properties.containsKey("\$sdk_debug_pending_queue_size")) { diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidSetupLookupsTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidSetupLookupsTest.kt index adf83051d..65c9f9c12 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidSetupLookupsTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidSetupLookupsTest.kt @@ -110,6 +110,7 @@ internal class PostHogAndroidSetupLookupsTest { assertEquals(File(cacheDir, "posthog-disk-queue").absolutePath, config.storagePrefix) assertEquals(File(cacheDir, "posthog-disk-replay-queue").absolutePath, config.replayStoragePrefix) assertEquals(File(cacheDir, "posthog-disk-logs-queue").absolutePath, config.logsStoragePrefix) + assertEquals(File(cacheDir, "posthog-disk-ai-queue").absolutePath, config.aiStoragePrefix) } @Test @@ -120,15 +121,29 @@ internal class PostHogAndroidSetupLookupsTest { storagePrefix = tmpDir.newFolder().absolutePath replayStoragePrefix = tmpDir.newFolder().absolutePath logsStoragePrefix = tmpDir.newFolder().absolutePath + aiStoragePrefix = tmpDir.newFolder().absolutePath } - val expected = listOf(config.legacyStoragePrefix, config.storagePrefix, config.replayStoragePrefix, config.logsStoragePrefix) + val expected = + listOf( + config.legacyStoragePrefix, + config.storagePrefix, + config.replayStoragePrefix, + config.logsStoragePrefix, + config.aiStoragePrefix, + ) setup(config) verify(app, never()).cacheDir verify(app, never()).getDir(any(), any()) assertEquals( expected, - listOf(config.legacyStoragePrefix, config.storagePrefix, config.replayStoragePrefix, config.logsStoragePrefix), + listOf( + config.legacyStoragePrefix, + config.storagePrefix, + config.replayStoragePrefix, + config.logsStoragePrefix, + config.aiStoragePrefix, + ), ) } @@ -142,6 +157,7 @@ internal class PostHogAndroidSetupLookupsTest { assertEquals(customPath, config.storagePrefix) assertEquals(File(cacheDir, "posthog-disk-replay-queue").absolutePath, config.replayStoragePrefix) assertEquals(File(cacheDir, "posthog-disk-logs-queue").absolutePath, config.logsStoragePrefix) + assertEquals(File(cacheDir, "posthog-disk-ai-queue").absolutePath, config.aiStoragePrefix) } @Test diff --git a/posthog-android/src/test/java/com/posthog/android/errortracking/PostHogNativeCrashIntegrationTest.kt b/posthog-android/src/test/java/com/posthog/android/errortracking/PostHogNativeCrashIntegrationTest.kt index 57c896485..5c59a2131 100644 --- a/posthog-android/src/test/java/com/posthog/android/errortracking/PostHogNativeCrashIntegrationTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/errortracking/PostHogNativeCrashIntegrationTest.kt @@ -176,6 +176,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), eq(Date(200)), + anyOrNull(), ) assertEquals(200, watermark()) } @@ -195,6 +196,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), eq(Date(700_000)), + anyOrNull(), ) assertEquals(900_000, watermark()) } @@ -215,6 +217,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), eq(Date(850_000)), + anyOrNull(), ) } @@ -236,6 +239,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), eq(Date(900_000)), + anyOrNull(), ) } @@ -288,6 +292,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), anyOrNull(), + anyOrNull(), ) assertEquals(200, watermark()) } @@ -306,6 +311,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), anyOrNull(), + anyOrNull(), ) assertEquals(300, watermark()) } @@ -317,7 +323,7 @@ internal class PostHogNativeCrashIntegrationTest { doNothing() .doThrow(RuntimeException("queue rejected")) .whenever(postHog) - .capture(any(), anyOrNull(), anyOrNull(), anyOrNull(), anyOrNull(), anyOrNull(), anyOrNull()) + .capture(any(), anyOrNull(), anyOrNull(), anyOrNull(), anyOrNull(), anyOrNull(), anyOrNull(), anyOrNull()) install() @@ -332,6 +338,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), anyOrNull(), + anyOrNull(), ) assertEquals(0, watermark()) } @@ -389,6 +396,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), anyOrNull(), + anyOrNull(), ) assertEquals(500, watermark()) } @@ -442,6 +450,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), anyOrNull(), + anyOrNull(), ) // oversized is deterministic, so the record must not wedge the scanner // by holding the watermark below it forever @@ -467,6 +476,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), anyOrNull(), + anyOrNull(), ) // a deterministic parse failure must not hold the watermark below the // record forever, or every newer crash behind it would be blocked @@ -506,6 +516,7 @@ internal class PostHogNativeCrashIntegrationTest { anyOrNull(), anyOrNull(), anyOrNull(), + anyOrNull(), ) assertEquals(800, watermark()) } diff --git a/posthog-android/src/test/java/com/posthog/android/internal/PostHogActivityLifecycleCallbackIntegrationTest.kt b/posthog-android/src/test/java/com/posthog/android/internal/PostHogActivityLifecycleCallbackIntegrationTest.kt index 793241981..edb167c40 100644 --- a/posthog-android/src/test/java/com/posthog/android/internal/PostHogActivityLifecycleCallbackIntegrationTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/internal/PostHogActivityLifecycleCallbackIntegrationTest.kt @@ -29,6 +29,7 @@ import java.util.concurrent.atomic.AtomicReference import kotlin.test.BeforeTest import kotlin.test.Test import kotlin.test.assertEquals +import kotlin.test.assertFalse import kotlin.test.assertNull import kotlin.test.assertTrue @@ -209,6 +210,14 @@ internal class PostHogActivityLifecycleCallbackIntegrationTest { assertEquals("fasf", fake.properties?.get("Reference")) } + @Test + fun `onActivityCreated drops deep link query params reserved for PostHog`() { + val fake = executeDeepLinkTest("test://print?barcode=ABCDEFG&%24process_person_profile=true") + + assertEquals("ABCDEFG", fake.properties?.get("barcode")) + assertFalse(fake.properties!!.containsKey("\$process_person_profile")) + } + @Test fun `onActivityCreated captures deep link even if hierarchical url`() { val url = "mailto:nobody@google.com" diff --git a/posthog-android/src/test/java/com/posthog/android/internal/PostHogAndroidContextTest.kt b/posthog-android/src/test/java/com/posthog/android/internal/PostHogAndroidContextTest.kt index 17a51c543..ff020b48d 100644 --- a/posthog-android/src/test/java/com/posthog/android/internal/PostHogAndroidContextTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/internal/PostHogAndroidContextTest.kt @@ -1,8 +1,12 @@ package com.posthog.android.internal +import android.app.LocaleConfig +import android.app.LocaleManager import android.content.Context import android.content.pm.InstallSourceInfo +import android.content.res.Resources import android.net.ConnectivityManager +import android.os.LocaleList import android.telephony.TelephonyManager import androidx.test.ext.junit.runners.AndroidJUnit4 import com.posthog.android.PROJECT_TOKEN @@ -14,10 +18,13 @@ import com.posthog.android.mockTelephone import org.junit.runner.RunWith import org.mockito.kotlin.any import org.mockito.kotlin.mock +import org.mockito.kotlin.times +import org.mockito.kotlin.verify import org.mockito.kotlin.verifyNoInteractions import org.mockito.kotlin.whenever import org.robolectric.annotation.Config import org.robolectric.shadows.ShadowBuild +import java.util.Locale import kotlin.test.AfterTest import kotlin.test.BeforeTest import kotlin.test.Test @@ -189,6 +196,132 @@ internal class PostHogAndroidContextTest { assertEquals("name", dynamicContext["\$network_carrier"]) } + @Test + @Config(sdk = [28]) + fun `locale is the device language even after Locale setDefault`() { + context.mockTelephone() + val original = Locale.getDefault() + val deviceTag = Resources.getSystem().configuration.locales[0].toLanguageTag() + Locale.setDefault(Locale.forLanguageTag("fr-FR")) + try { + assertEquals(deviceTag, getSut().getDynamicContext()["\$locale"]) + } finally { + Locale.setDefault(original) + } + } + + @Test + @Config(sdk = [34]) + fun `reads locale off the setup and capture threads`() { + context.mockTelephone() + val localeManager = mock() + whenever(localeManager.systemLocales).thenReturn(LocaleList.forLanguageTags("de-CH,en")) + whenever(localeManager.applicationLocales).thenReturn(LocaleList.getEmptyLocaleList()) + whenever(context.getSystemService(LocaleManager::class.java)).thenReturn(localeManager) + val sut = getSut() + verifyNoInteractions(localeManager) + runPendingTasks() + assertEquals("de-CH", sut.getDynamicContext()["\$locale"]) + + whenever(localeManager.systemLocales).thenReturn(LocaleList.forLanguageTags("es-ES")) + assertEquals("de-CH", sut.getDynamicContext()["\$locale"]) + runPendingTasks() + + assertEquals("es-ES", sut.getDynamicContext()["\$locale"]) + } + + @Test + @Config(sdk = [34]) + fun `locale leaves out regional preference extensions`() { + context.mockTelephone() + val localeManager = mock() + whenever(localeManager.systemLocales).thenReturn(LocaleList.forLanguageTags("de-CH-u-fw-mon")) + whenever(localeManager.applicationLocales).thenReturn(LocaleList.getEmptyLocaleList()) + whenever(context.getSystemService(LocaleManager::class.java)).thenReturn(localeManager) + + val sut = getSut() + runPendingTasks() + + assertEquals("de-CH", sut.getDynamicContext()["\$locale"]) + } + + @Test + @Config(sdk = [34]) + fun `falls back to resources and no app language when LocaleManager throws`() { + context.mockTelephone() + val localeManager = mock() + whenever(localeManager.systemLocales).thenThrow(RuntimeException()) + whenever(context.getSystemService(LocaleManager::class.java)).thenReturn(localeManager) + val sut = getSut() + runPendingTasks() + val dynamicContext = sut.getDynamicContext() + + assertEquals(Resources.getSystem().configuration.locales[0].toLanguageTag(), dynamicContext["\$locale"]) + assertFalse(dynamicContext.containsKey("\$app_language")) + } + + @Test + @Config(sdk = [34]) + fun `a per-app language with no declaration is the app language`() { + context.mockTelephone() + val localeManager = mock() + whenever(localeManager.systemLocales).thenReturn(LocaleList.forLanguageTags("de-CH")) + whenever(localeManager.applicationLocales).thenReturn(LocaleList.forLanguageTags("fr")) + whenever(context.getSystemService(LocaleManager::class.java)).thenReturn(localeManager) + val sut = getSut() + runPendingTasks() + + assertEquals("fr", sut.getDynamicContext()["\$app_language"]) + } + + @Test + @Config(sdk = [34]) + fun `app language follows supported locales changed at runtime`() { + context.mockTelephone() + val localeManager = mock() + whenever(localeManager.systemLocales).thenReturn(LocaleList.forLanguageTags("de-CH")) + whenever(localeManager.applicationLocales).thenReturn(LocaleList.getEmptyLocaleList()) + whenever(localeManager.overrideLocaleConfig).thenReturn(LocaleConfig(LocaleList.forLanguageTags("en"))) + whenever(context.getSystemService(LocaleManager::class.java)).thenReturn(localeManager) + val sut = getSut() + runPendingTasks() + assertEquals("en", sut.getDynamicContext()["\$app_language"]) + + sut.getDynamicContext() + runPendingTasks() + verify(localeManager, times(1)).overrideLocaleConfig + + whenever(localeManager.overrideLocaleConfig).thenReturn(LocaleConfig(LocaleList.forLanguageTags("en,de"))) + whenever(localeManager.applicationLocales).thenReturn(LocaleList.forLanguageTags("de")) + sut.getDynamicContext() + runPendingTasks() + + assertEquals("de", sut.getDynamicContext()["\$app_language"]) + } + + @Test + @Config(sdk = [34]) + fun `sends no app language when turned off for wrappers`() { + context.mockTelephone() + val localeManager = mock() + whenever(localeManager.systemLocales).thenReturn(LocaleList.forLanguageTags("de-CH")) + whenever(localeManager.applicationLocales).thenReturn(LocaleList.forLanguageTags("fr")) + whenever(context.getSystemService(LocaleManager::class.java)).thenReturn(localeManager) + val sut = getSut() + config.detectAppLanguage = false + runPendingTasks() + + assertFalse(sut.getDynamicContext().containsKey("\$app_language")) + } + + @Test + @Config(sdk = [32]) + fun `does not detect the app language before Android 13`() { + context.mockTelephone() + + assertFalse(getSut().getDynamicContext().containsKey("\$app_language")) + } + @Test fun `returns network properties from snapshot`() { val sut = diff --git a/posthog-android/src/test/java/com/posthog/android/internal/PostHogAppLanguageTest.kt b/posthog-android/src/test/java/com/posthog/android/internal/PostHogAppLanguageTest.kt new file mode 100644 index 000000000..425093a51 --- /dev/null +++ b/posthog-android/src/test/java/com/posthog/android/internal/PostHogAppLanguageTest.kt @@ -0,0 +1,67 @@ +package com.posthog.android.internal + +import androidx.test.ext.junit.runners.AndroidJUnit4 +import org.junit.runner.RunWith +import org.robolectric.annotation.Config +import java.util.Locale +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertNull + +@RunWith(AndroidJUnit4::class) +@Config(sdk = [34]) +internal class PostHogAppLanguageTest { + private fun resolve( + preferred: String, + supported: String, + default: String? = null, + ) = resolveAppLanguage( + Locale.forLanguageTag(preferred), + SupportedLocales( + supported.split(",").map(Locale::forLanguageTag), + default?.let(Locale::forLanguageTag), + ), + ) + + @Test + fun `resolves a regional preference to the declared language`() { + assertEquals("de", resolve("de-CH", "en,de")) + } + + @Test + fun `prefers the exact regional match`() { + assertEquals("pt-PT", resolve("pt-PT", "pt-BR,pt-PT")) + } + + @Test + fun `reports nothing when several relatives could match`() { + assertNull(resolve("pt-MZ", "pt,pt-PT")) + assertNull(resolve("pt-MZ", "pt-BR,pt-PT", default = "pt-BR")) + } + + @Test + fun `ignores regional preference extensions when matching`() { + assertEquals("pt-PT", resolve("pt-PT-u-fw-mon", "pt-BR,pt-PT")) + } + + @Test + fun `does not cross scripts`() { + assertEquals("zh-Hant", resolve("zh-Hant-TW", "zh-Hans,zh-Hant")) + assertNull(resolve("zh-Hant-TW", "zh-Hans,en")) + } + + @Test + fun `uses the declared default when nothing matches`() { + assertEquals("en", resolve("fr-FR", "de,en", default = "en")) + } + + @Test + fun `uses the only declared language when nothing matches`() { + assertEquals("en", resolve("de-CH", "en")) + } + + @Test + fun `reports nothing when the fallback language is unknown`() { + assertNull(resolve("fr-FR", "de,en")) + } +} diff --git a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt index 6e5b5cb63..85ea95390 100644 --- a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayIntegrationTest.kt @@ -3004,10 +3004,11 @@ internal class PostHogReplayIntegrationTest { userPropertiesSetOnce: Map?, groups: Map?, timestamp: Date?, + options: Map?, ) { PostHogSessionManager.setSessionId(UUID.randomUUID()) fx.sut.onSessionIdChanged() - core.capture(event, distinctId, properties, userProperties, userPropertiesSetOnce, groups, timestamp) + core.capture(event, distinctId, properties, userProperties, userPropertiesSetOnce, groups, timestamp, options) } } fx.sut.install(client) diff --git a/posthog-android/src/test/resources/json/snapshots/batch-request.json b/posthog-android/src/test/resources/json/snapshots/batch-request.json index 737b87914..511ee3349 100644 --- a/posthog-android/src/test/resources/json/snapshots/batch-request.json +++ b/posthog-android/src/test/resources/json/snapshots/batch-request.json @@ -1,18 +1,24 @@ { "method": "POST", - "path": "/batch", + "path": "/i/v1/analytics/events", "headers": { + "Authorization": "Bearer _6SG-F7I1vCuZ-HdJL3VZQqjBlaSb1_20hDPwqMNnGI", "Content-Encoding": "gzip", - "Content-Type": "application/json; charset=utf-8", + "Content-Type": "application/json", + "PostHog-Attempt": "1", + "PostHog-Sdk-Info": "posthog-android/", "User-Agent": "posthog-android/", "X-PostHog-Snapshot": "android-events-v1" }, "body": { - "api_key": "_6SG-F7I1vCuZ-HdJL3VZQqjBlaSb1_20hDPwqMNnGI", + "created_at": "2023-11-14T22:13:20.123Z", "batch": [ { "event": "checkout completed", + "uuid": "", "distinct_id": "anonymous-user", + "timestamp": "2023-11-14T22:13:20.123Z", + "session_id": "018bcfe5-687b-7abc-8def-0123456789ab", "properties": { "$app_name": "Snapshot App", "$app_namespace": "com.example.snapshot", @@ -41,9 +47,12 @@ "$groups": { "company": "posthog" }, - "$lib": "posthog-android", - "$lib_version": "", - "$session_id": "018bcfe5-687b-7abc-8def-0123456789ab", + "$is_identified": false, + "$recording_status": "disabled", + "$sdk_debug_replay_event_trigger_status": "trigger_disabled", + "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", + "$sdk_debug_replay_internal_buffer_length": 0, + "$sdk_debug_pending_queue_size": "", "amount": 42.5, "currency": "USD", "items": [ @@ -51,21 +60,15 @@ "sku": "sku-1", "quantity": 2 } - ], - "$is_identified": false, - "$process_person_profile": true, - "$sdk_debug_pending_queue_size": "", - "$recording_status": "disabled", - "$sdk_debug_replay_event_trigger_status": "trigger_disabled", - "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", - "$sdk_debug_replay_internal_buffer_length": 0 - }, - "timestamp": "2023-11-14T22:13:20.123Z", - "uuid": "" + ] + } }, { "event": "$identify", + "uuid": "", "distinct_id": "identified-user", + "timestamp": "2023-11-14T22:13:20.123Z", + "session_id": "018bcfe5-687b-7abc-8def-0123456789ab", "properties": { "$app_name": "Snapshot App", "$app_namespace": "com.example.snapshot", @@ -94,26 +97,23 @@ "$groups": { "company": "posthog" }, - "$lib": "posthog-android", - "$lib_version": "", - "$session_id": "018bcfe5-687b-7abc-8def-0123456789ab", - "$anon_distinct_id": "anonymous-user", "$is_identified": true, - "$process_person_profile": true, - "$sdk_debug_pending_queue_size": "", "$recording_status": "disabled", "$sdk_debug_replay_event_trigger_status": "trigger_disabled", "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", "$sdk_debug_replay_capture_mode": "screenshot", "$sdk_debug_replay_internal_buffer_length": 0, - "$sdk_debug_session_start": 1700000000123 - }, - "timestamp": "2023-11-14T22:13:20.123Z", - "uuid": "" + "$sdk_debug_session_start": 1700000000123, + "$sdk_debug_pending_queue_size": "", + "$anon_distinct_id": "anonymous-user" + } }, { "event": "$groupidentify", + "uuid": "", "distinct_id": "identified-user", + "timestamp": "2023-11-14T22:13:20.123Z", + "session_id": "018bcfe5-687b-7abc-8def-0123456789ab", "properties": { "$app_name": "Snapshot App", "$app_namespace": "com.example.snapshot", @@ -133,29 +133,26 @@ "$timezone": "UTC", "$network_type": "wifi", "$network_carrier": "Snapshot Telecom", - "$lib": "posthog-android", - "$lib_version": "", - "$session_id": "018bcfe5-687b-7abc-8def-0123456789ab", + "$is_identified": true, + "$recording_status": "disabled", + "$sdk_debug_replay_event_trigger_status": "trigger_disabled", + "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", + "$sdk_debug_replay_internal_buffer_length": 0, + "$sdk_debug_pending_queue_size": "", "$group_type": "company", "$group_key": "posthog", "$group_set": { "industry": "analytics", "employees": 100 - }, - "$is_identified": true, - "$process_person_profile": true, - "$sdk_debug_pending_queue_size": "", - "$recording_status": "disabled", - "$sdk_debug_replay_event_trigger_status": "trigger_disabled", - "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", - "$sdk_debug_replay_internal_buffer_length": 0 - }, - "timestamp": "2023-11-14T22:13:20.123Z", - "uuid": "" + } + } }, { "event": "$feature_flag_called", + "uuid": "", "distinct_id": "identified-user", + "timestamp": "2023-11-14T22:13:20.123Z", + "session_id": "018bcfe5-687b-7abc-8def-0123456789ab", "properties": { "$app_name": "Snapshot App", "$app_namespace": "com.example.snapshot", @@ -178,33 +175,30 @@ "$groups": { "company": "posthog" }, - "$lib": "posthog-android", - "$lib_version": "", "$feature/snapshot-flag": "snapshot-variant", "$active_feature_flags": [ "snapshot-flag" ], - "$session_id": "018bcfe5-687b-7abc-8def-0123456789ab", + "$is_identified": true, + "$recording_status": "disabled", + "$sdk_debug_replay_event_trigger_status": "trigger_disabled", + "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", + "$sdk_debug_replay_internal_buffer_length": 0, + "$sdk_debug_pending_queue_size": "", "$feature_flag": "snapshot-flag", "$feature_flag_response": "snapshot-variant", "$feature_flag_request_id": "flag-request-123", "$feature_flag_id": 123, "$feature_flag_version": 7, - "$feature_flag_reason": "", - "$is_identified": true, - "$process_person_profile": true, - "$sdk_debug_pending_queue_size": "", - "$recording_status": "disabled", - "$sdk_debug_replay_event_trigger_status": "trigger_disabled", - "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", - "$sdk_debug_replay_internal_buffer_length": 0 - }, - "timestamp": "2023-11-14T22:13:20.123Z", - "uuid": "" + "$feature_flag_reason": "" + } }, { "event": "$exception", + "uuid": "", "distinct_id": "identified-user", + "timestamp": "2023-11-14T22:13:20.123Z", + "session_id": "018bcfe5-687b-7abc-8def-0123456789ab", "properties": { "$app_name": "Snapshot App", "$app_namespace": "com.example.snapshot", @@ -227,13 +221,16 @@ "$groups": { "company": "posthog" }, - "$lib": "posthog-android", - "$lib_version": "", "$feature/snapshot-flag": "snapshot-variant", "$active_feature_flags": [ "snapshot-flag" ], - "$session_id": "018bcfe5-687b-7abc-8def-0123456789ab", + "$is_identified": true, + "$recording_status": "disabled", + "$sdk_debug_replay_event_trigger_status": "trigger_disabled", + "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", + "$sdk_debug_replay_internal_buffer_length": 0, + "$sdk_debug_pending_queue_size": "", "$exception_level": "error", "$exception_list": [ { @@ -291,19 +288,9 @@ } ], "handled": true, - "component": "checkout", - "$is_identified": true, - "$process_person_profile": true, - "$sdk_debug_pending_queue_size": "", - "$recording_status": "disabled", - "$sdk_debug_replay_event_trigger_status": "trigger_disabled", - "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", - "$sdk_debug_replay_internal_buffer_length": 0 - }, - "timestamp": "2023-11-14T22:13:20.123Z", - "uuid": "" + "component": "checkout" + } } - ], - "sent_at": "2023-11-14T22:13:20.123Z" + ] } } diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index ddcf0ddfd..4cb3d0084 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -23,9 +23,11 @@ public final class com/posthog/PersonProfiles : java/lang/Enum { public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posthog/PostHogInterface, com/posthog/internal/PostHogPushSubscriptionReceiver { public static final field Companion Lcom/posthog/PostHog$Companion; public fun addExceptionStep (Ljava/lang/String;Ljava/util/Map;)V - public fun alias (Ljava/lang/String;)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 captureException (Ljava/lang/Throwable;Ljava/util/Map;)V + public fun alias (Ljava/lang/String;Ljava/util/Map;)V + public fun buildEventForWrapper (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;)Lcom/posthog/PostHogEvent; + public fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)V + public fun captureAi (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)Ljava/util/UUID; + public fun captureException (Ljava/lang/Throwable;Ljava/util/Map;Ljava/util/Map;)V public fun captureFeatureInteraction (Ljava/lang/String;Ljava/lang/String;)V public fun captureFeatureView (Ljava/lang/String;Ljava/lang/String;)V public fun captureLog (Ljava/lang/String;Lcom/posthog/logs/PostHogLogSeverity;Ljava/util/Map;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;)V @@ -42,8 +44,9 @@ public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posth public fun getFeatureFlagResult (Ljava/lang/String;Ljava/lang/Boolean;)Lcom/posthog/FeatureFlagResult; public fun getLogger ()Lcom/posthog/logs/PostHogLogger; public fun getSessionId ()Ljava/util/UUID; - public fun group (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;)V + public fun group (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V public fun identify (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V + public fun identify (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)V public fun isFeatureEnabled (Ljava/lang/String;ZLjava/lang/Boolean;)Z public fun isOptOut ()Z public fun isSessionActive ()Z @@ -58,9 +61,11 @@ public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posth public fun reset ()V public fun resetGroupPropertiesForFlags (Ljava/lang/String;Z)V public fun resetPersonPropertiesForFlags (Z)V - public fun screen (Ljava/lang/String;Ljava/util/Map;)V + public fun screen (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V + public fun sendBuiltEventForWrapper (Lcom/posthog/PostHogEvent;Z)Ljava/util/UUID; + public fun setAppLanguage (Ljava/lang/String;)V public fun setGroupPropertiesForFlags (Ljava/lang/String;Ljava/util/Map;Z)V - public fun setPersonProperties (Ljava/util/Map;Ljava/util/Map;)V + public fun setPersonProperties (Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)V public fun setPersonPropertiesForFlags (Ljava/util/Map;Z)V public fun setup (Lcom/posthog/PostHogConfig;)V public fun startSession ()V @@ -72,9 +77,11 @@ public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posth public final class com/posthog/PostHog$Companion : com/posthog/PostHogInterface { public fun addExceptionStep (Ljava/lang/String;Ljava/util/Map;)V - public fun alias (Ljava/lang/String;)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 captureException (Ljava/lang/Throwable;Ljava/util/Map;)V + public fun alias (Ljava/lang/String;Ljava/util/Map;)V + public fun buildEventForWrapper (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;)Lcom/posthog/PostHogEvent; + public fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)V + public fun captureAi (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)Ljava/util/UUID; + public fun captureException (Ljava/lang/Throwable;Ljava/util/Map;Ljava/util/Map;)V public fun captureFeatureInteraction (Ljava/lang/String;Ljava/lang/String;)V public fun captureFeatureView (Ljava/lang/String;Ljava/lang/String;)V public fun captureLog (Ljava/lang/String;Lcom/posthog/logs/PostHogLogSeverity;Ljava/util/Map;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;)V @@ -92,8 +99,8 @@ public final class com/posthog/PostHog$Companion : com/posthog/PostHogInterface public fun getFeatureFlagResult (Ljava/lang/String;Ljava/lang/Boolean;)Lcom/posthog/FeatureFlagResult; public fun getLogger ()Lcom/posthog/logs/PostHogLogger; public fun getSessionId ()Ljava/util/UUID; - public fun group (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;)V - public fun identify (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V + public fun group (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V + public fun identify (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)V public fun isFeatureEnabled (Ljava/lang/String;ZLjava/lang/Boolean;)Z public fun isOptOut ()Z public fun isSessionActive ()Z @@ -109,9 +116,11 @@ public final class com/posthog/PostHog$Companion : com/posthog/PostHogInterface public fun resetGroupPropertiesForFlags (Ljava/lang/String;Z)V public fun resetPersonPropertiesForFlags (Z)V public final fun resetSharedInstance ()V - public fun screen (Ljava/lang/String;Ljava/util/Map;)V + public fun screen (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V + public fun sendBuiltEventForWrapper (Lcom/posthog/PostHogEvent;Z)Ljava/util/UUID; + public fun setAppLanguage (Ljava/lang/String;)V public fun setGroupPropertiesForFlags (Ljava/lang/String;Ljava/util/Map;Z)V - public fun setPersonProperties (Ljava/util/Map;Ljava/util/Map;)V + public fun setPersonProperties (Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)V public fun setPersonPropertiesForFlags (Ljava/util/Map;Z)V public fun setup (Lcom/posthog/PostHogConfig;)V public fun startSession ()V @@ -149,6 +158,9 @@ public final class com/posthog/PostHogCompression : java/lang/Enum { public class com/posthog/PostHogConfig { public static final field Companion Lcom/posthog/PostHogConfig$Companion; + public static final field DEFAULT_CAPTURE_AI_MAX_EVENT_BYTES I + public static final field DEFAULT_CAPTURE_AI_MAX_QUEUE_SIZE I + public static final field DEFAULT_CAPTURE_AI_TIMEOUT_SECONDS I public static final field DEFAULT_EU_ASSETS_HOST Ljava/lang/String; public static final field DEFAULT_EU_HOST Ljava/lang/String; public static final field DEFAULT_FEATURE_FLAG_CALLED_CACHE_SIZE I @@ -163,9 +175,14 @@ public class com/posthog/PostHogConfig { public synthetic fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun addBeforeSend (Lcom/posthog/PostHogBeforeSend;)V public final fun addIntegration (Lcom/posthog/PostHogIntegration;)V + public final fun getAiStoragePrefix ()Ljava/lang/String; public final fun getBeforeSendList ()Ljava/util/List; public final fun getBootstrap ()Lcom/posthog/PostHogBootstrapConfig; public final fun getCachePreferences ()Lcom/posthog/internal/PostHogPreferences; + public final fun getCaptureAiCompression ()Lcom/posthog/PostHogCompression; + public final fun getCaptureAiMaxEventBytes ()I + public final fun getCaptureAiMaxQueueSize ()I + public final fun getCaptureAiTimeout ()I public final fun getCompression ()Lcom/posthog/PostHogCompression; public final fun getContext ()Lcom/posthog/internal/PostHogContext; public final fun getDateProvider ()Lcom/posthog/internal/PostHogDateProvider; @@ -188,7 +205,6 @@ public class com/posthog/PostHogConfig { public final fun getLogsStoragePrefix ()Ljava/lang/String; public final fun getMaxBatchSize ()I public final fun getMaxQueueSize ()I - public final fun getMaxRetries ()I public final fun getNetworkStatus ()Lcom/posthog/internal/PostHogNetworkStatus; public final fun getOptOut ()Z public final fun getPersistOptOut ()Z @@ -197,6 +213,7 @@ public class com/posthog/PostHogConfig { public final fun getProjectToken ()Ljava/lang/String; public final fun getProxy ()Ljava/net/Proxy; public final fun getPushIdentityProvider ()Lkotlin/jvm/functions/Function3; + public final fun getPushNotificationSubscriptionMaxRetries ()I public final fun getQueueProvider ()Lkotlin/jvm/functions/Function5; public final fun getReleaseIdentifier ()Ljava/lang/String; public final fun getRemoteConfigHolder ()Lcom/posthog/internal/PostHogRemoteConfig; @@ -218,8 +235,13 @@ public class com/posthog/PostHogConfig { public final synthetic fun getTracingHeaders ()Ljava/util/List; public final fun removeBeforeSend (Lcom/posthog/PostHogBeforeSend;)V public final fun removeIntegration (Lcom/posthog/PostHogIntegration;)V + public final fun setAiStoragePrefix (Ljava/lang/String;)V public final fun setBootstrap (Lcom/posthog/PostHogBootstrapConfig;)V public final fun setCachePreferences (Lcom/posthog/internal/PostHogPreferences;)V + public final fun setCaptureAiCompression (Lcom/posthog/PostHogCompression;)V + public final fun setCaptureAiMaxEventBytes (I)V + public final fun setCaptureAiMaxQueueSize (I)V + public final fun setCaptureAiTimeout (I)V public final fun setCompression (Lcom/posthog/PostHogCompression;)V public final fun setContext (Lcom/posthog/internal/PostHogContext;)V public final fun setDateProvider (Lcom/posthog/internal/PostHogDateProvider;)V @@ -239,7 +261,6 @@ public class com/posthog/PostHogConfig { public final fun setLogsStoragePrefix (Ljava/lang/String;)V public final fun setMaxBatchSize (I)V public final fun setMaxQueueSize (I)V - public final fun setMaxRetries (I)V public final fun setNetworkStatus (Lcom/posthog/internal/PostHogNetworkStatus;)V public final fun setOptOut (Z)V public final fun setPersistOptOut (Z)V @@ -247,6 +268,7 @@ public class com/posthog/PostHogConfig { public final fun setPreloadFeatureFlags (Z)V public final fun setProxy (Ljava/net/Proxy;)V public final fun setPushIdentityProvider (Lkotlin/jvm/functions/Function3;)V + public final fun setPushNotificationSubscriptionMaxRetries (I)V public final fun setReleaseIdentifier (Ljava/lang/String;)V public final fun setRemoteConfigHolder (Lcom/posthog/internal/PostHogRemoteConfig;)V public final fun setReplayStoragePrefix (Ljava/lang/String;)V @@ -273,8 +295,6 @@ public abstract interface class com/posthog/PostHogCoreInterface { public abstract fun debug (Z)V public static synthetic fun debug$default (Lcom/posthog/PostHogCoreInterface;ZILjava/lang/Object;)V public abstract fun flush ()V - public abstract fun identify (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V - public static synthetic fun identify$default (Lcom/posthog/PostHogCoreInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public abstract fun isOptOut ()Z public abstract fun optIn ()V public abstract fun optOut ()V @@ -283,7 +303,6 @@ public abstract interface class com/posthog/PostHogCoreInterface { public final class com/posthog/PostHogCoreInterface$DefaultImpls { public static synthetic fun debug$default (Lcom/posthog/PostHogCoreInterface;ZILjava/lang/Object;)V - public static synthetic fun identify$default (Lcom/posthog/PostHogCoreInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V } public abstract interface class com/posthog/PostHogEncryption { @@ -310,6 +329,7 @@ public final class com/posthog/PostHogEvent { public final fun getDistinctId ()Ljava/lang/String; public final fun getEvent ()Ljava/lang/String; public final fun getMessageId ()Ljava/util/UUID; + public final fun getOptions ()Ljava/util/Map; public final fun getProperties ()Ljava/util/Map; public final fun getSet ()Ljava/util/Map; public final fun getTimestamp ()Ljava/util/Date; @@ -319,6 +339,7 @@ public final class com/posthog/PostHogEvent { public final fun isExceptionEvent ()Z public final fun isFatalExceptionEvent ()Z public final fun setApiKey (Ljava/lang/String;)V + public final fun setOptions (Ljava/util/Map;)V public fun toString ()Ljava/lang/String; } @@ -382,11 +403,16 @@ public final class com/posthog/PostHogIntegration$DefaultImpls { public abstract interface class com/posthog/PostHogInterface : com/posthog/PostHogCoreInterface { public abstract fun addExceptionStep (Ljava/lang/String;Ljava/util/Map;)V public static synthetic fun addExceptionStep$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V - public abstract fun alias (Ljava/lang/String;)V - public abstract 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 static synthetic fun capture$default (Lcom/posthog/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 abstract fun captureException (Ljava/lang/Throwable;Ljava/util/Map;)V - public static synthetic fun captureException$default (Lcom/posthog/PostHogInterface;Ljava/lang/Throwable;Ljava/util/Map;ILjava/lang/Object;)V + public abstract fun alias (Ljava/lang/String;Ljava/util/Map;)V + public static synthetic fun alias$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V + public fun buildEventForWrapper (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;)Lcom/posthog/PostHogEvent; + public static synthetic fun buildEventForWrapper$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;ILjava/lang/Object;)Lcom/posthog/PostHogEvent; + public abstract fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)V + public static synthetic fun capture$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;ILjava/lang/Object;)V + public abstract fun captureAi (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)Ljava/util/UUID; + public static synthetic fun captureAi$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;ILjava/lang/Object;)Ljava/util/UUID; + public abstract fun captureException (Ljava/lang/Throwable;Ljava/util/Map;Ljava/util/Map;)V + public static synthetic fun captureException$default (Lcom/posthog/PostHogInterface;Ljava/lang/Throwable;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public abstract fun captureFeatureInteraction (Ljava/lang/String;Ljava/lang/String;)V public static synthetic fun captureFeatureInteraction$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)V public abstract fun captureFeatureView (Ljava/lang/String;Ljava/lang/String;)V @@ -407,8 +433,10 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public static synthetic fun getFeatureFlagResult$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Lcom/posthog/FeatureFlagResult; public abstract fun getLogger ()Lcom/posthog/logs/PostHogLogger; public abstract fun getSessionId ()Ljava/util/UUID; - public abstract fun group (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;)V - public static synthetic fun group$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V + public abstract fun group (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V + public static synthetic fun group$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V + public abstract fun identify (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)V + public static synthetic fun identify$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public abstract fun isFeatureEnabled (Ljava/lang/String;ZLjava/lang/Boolean;)Z public static synthetic fun isFeatureEnabled$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZLjava/lang/Boolean;ILjava/lang/Object;)Z public abstract fun isSessionActive ()Z @@ -423,12 +451,15 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public static synthetic fun resetGroupPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZILjava/lang/Object;)V public abstract fun resetPersonPropertiesForFlags (Z)V public static synthetic fun resetPersonPropertiesForFlags$default (Lcom/posthog/PostHogInterface;ZILjava/lang/Object;)V - public abstract fun screen (Ljava/lang/String;Ljava/util/Map;)V - public static synthetic fun screen$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V + public abstract fun screen (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V + public static synthetic fun screen$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V + public fun sendBuiltEventForWrapper (Lcom/posthog/PostHogEvent;Z)Ljava/util/UUID; + public static synthetic fun sendBuiltEventForWrapper$default (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogEvent;ZILjava/lang/Object;)Ljava/util/UUID; + public abstract fun setAppLanguage (Ljava/lang/String;)V public abstract fun setGroupPropertiesForFlags (Ljava/lang/String;Ljava/util/Map;Z)V public static synthetic fun setGroupPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ZILjava/lang/Object;)V - public abstract fun setPersonProperties (Ljava/util/Map;Ljava/util/Map;)V - public static synthetic fun setPersonProperties$default (Lcom/posthog/PostHogInterface;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V + public abstract fun setPersonProperties (Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)V + public static synthetic fun setPersonProperties$default (Lcom/posthog/PostHogInterface;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public abstract fun setPersonPropertiesForFlags (Ljava/util/Map;Z)V public static synthetic fun setPersonPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/util/Map;ZILjava/lang/Object;)V public abstract fun startSession ()V @@ -441,22 +472,29 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public final class com/posthog/PostHogInterface$DefaultImpls { public static synthetic fun addExceptionStep$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V - public static synthetic fun capture$default (Lcom/posthog/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 captureException$default (Lcom/posthog/PostHogInterface;Ljava/lang/Throwable;Ljava/util/Map;ILjava/lang/Object;)V + public static synthetic fun alias$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V + public static fun buildEventForWrapper (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;)Lcom/posthog/PostHogEvent; + public static synthetic fun buildEventForWrapper$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;ILjava/lang/Object;)Lcom/posthog/PostHogEvent; + public static synthetic fun capture$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;ILjava/lang/Object;)V + public static synthetic fun captureAi$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;ILjava/lang/Object;)Ljava/util/UUID; + public static synthetic fun captureException$default (Lcom/posthog/PostHogInterface;Ljava/lang/Throwable;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public static synthetic fun captureFeatureInteraction$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)V public static synthetic fun captureFeatureView$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)V public static synthetic fun captureLog$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Lcom/posthog/logs/PostHogLogSeverity;Ljava/util/Map;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;ILjava/lang/Object;)V public static synthetic fun capturePushNotificationOpened$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/lang/String;ILjava/lang/Object;)V public static synthetic fun getFeatureFlag$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Ljava/lang/Object; public static synthetic fun getFeatureFlagResult$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Lcom/posthog/FeatureFlagResult; - public static synthetic fun group$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V + public static synthetic fun group$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V + public static synthetic fun identify$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public static synthetic fun isFeatureEnabled$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZLjava/lang/Boolean;ILjava/lang/Object;)Z public static synthetic fun reloadFeatureFlags$default (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V public static synthetic fun resetGroupPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZILjava/lang/Object;)V public static synthetic fun resetPersonPropertiesForFlags$default (Lcom/posthog/PostHogInterface;ZILjava/lang/Object;)V - public static synthetic fun screen$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V + public static synthetic fun screen$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V + public static fun sendBuiltEventForWrapper (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogEvent;Z)Ljava/util/UUID; + public static synthetic fun sendBuiltEventForWrapper$default (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogEvent;ZILjava/lang/Object;)Ljava/util/UUID; public static synthetic fun setGroupPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ZILjava/lang/Object;)V - public static synthetic fun setPersonProperties$default (Lcom/posthog/PostHogInterface;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V + public static synthetic fun setPersonProperties$default (Lcom/posthog/PostHogInterface;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public static synthetic fun setPersonPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/util/Map;ZILjava/lang/Object;)V public static synthetic fun startSessionReplay$default (Lcom/posthog/PostHogInterface;ZILjava/lang/Object;)V } @@ -484,8 +522,8 @@ public class com/posthog/PostHogStateless : com/posthog/PostHogStatelessInterfac protected fun (Ljava/util/concurrent/ExecutorService;Ljava/util/concurrent/ExecutorService;)V public synthetic fun (Ljava/util/concurrent/ExecutorService;Ljava/util/concurrent/ExecutorService;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public fun aliasStateless (Ljava/lang/String;Ljava/lang/String;)V - protected final fun buildEvent (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Date;)Lcom/posthog/PostHogEvent; - public static synthetic fun buildEvent$default (Lcom/posthog/PostHogStateless;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Date;ILjava/lang/Object;)Lcom/posthog/PostHogEvent; + protected final fun buildEvent (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;Ljava/util/UUID;)Lcom/posthog/PostHogEvent; + public static synthetic fun buildEvent$default (Lcom/posthog/PostHogStateless;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;Ljava/util/UUID;ILjava/lang/Object;)Lcom/posthog/PostHogEvent; protected final fun captureExceptionEvent (Ljava/lang/Throwable;Ljava/lang/String;Ljava/util/Map;Ljava/util/Date;Lkotlin/jvm/functions/Function0;)V public fun captureExceptionStateless (Ljava/lang/Throwable;Ljava/lang/String;Ljava/util/Map;)V protected final fun captureFeatureFlagCalledEvent (Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;Ljava/util/Map;)V @@ -560,6 +598,8 @@ public abstract interface class com/posthog/PostHogStatelessInterface : com/post public static synthetic fun getFeatureFlagStateless$default (Lcom/posthog/PostHogStatelessInterface;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/lang/Object; public abstract fun groupStateless (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;)V public static synthetic fun groupStateless$default (Lcom/posthog/PostHogStatelessInterface;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V + public abstract fun identify (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V + public static synthetic fun identify$default (Lcom/posthog/PostHogStatelessInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public abstract fun isFeatureEnabledStateless (Ljava/lang/String;Ljava/lang/String;ZLjava/util/Map;Ljava/util/Map;Ljava/util/Map;)Z public static synthetic fun isFeatureEnabledStateless$default (Lcom/posthog/PostHogStatelessInterface;Ljava/lang/String;Ljava/lang/String;ZLjava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Z } @@ -571,6 +611,7 @@ public final class com/posthog/PostHogStatelessInterface$DefaultImpls { public static synthetic fun getFeatureFlagResultStateless$default (Lcom/posthog/PostHogStatelessInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/lang/Boolean;ILjava/lang/Object;)Lcom/posthog/FeatureFlagResult; public static synthetic fun getFeatureFlagStateless$default (Lcom/posthog/PostHogStatelessInterface;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/lang/Object; public static synthetic fun groupStateless$default (Lcom/posthog/PostHogStatelessInterface;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V + public static synthetic fun identify$default (Lcom/posthog/PostHogStatelessInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public static synthetic fun isFeatureEnabledStateless$default (Lcom/posthog/PostHogStatelessInterface;Ljava/lang/String;Ljava/lang/String;ZLjava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Z } @@ -622,12 +663,14 @@ public final class com/posthog/errortracking/PostHogExceptionStepsConfig { public final class com/posthog/internal/EndpointSpec { public static final field Companion Lcom/posthog/internal/EndpointSpec$Companion; + public static final fun ai (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; public static final fun batch (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; public static final fun logs (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; public static final fun snapshot (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; } public final class com/posthog/internal/EndpointSpec$Companion { + public final fun ai (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; public final fun batch (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; public final fun logs (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; public final fun snapshot (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; @@ -742,6 +785,8 @@ public final class com/posthog/internal/FlagProperty { public final class com/posthog/internal/GzipRequestInterceptor : okhttp3/Interceptor { public fun (Lcom/posthog/PostHogConfig;)V + public fun (Lcom/posthog/PostHogConfig;Lkotlin/jvm/functions/Function0;)V + public synthetic fun (Lcom/posthog/PostHogConfig;Lkotlin/jvm/functions/Function0;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public fun intercept (Lokhttp3/Interceptor$Chain;)Lokhttp3/Response; } diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index de65a0ca2..77c4506d6 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -34,11 +34,14 @@ import com.posthog.internal.PostHogSendCachedEventsIntegration import com.posthog.internal.PostHogSerializer import com.posthog.internal.PostHogSessionManager import com.posthog.internal.PostHogThreadFactory +import com.posthog.internal.captureAiMaxStoredEventBytes import com.posthog.internal.errortracking.PostHogExceptionStepsBuffer import com.posthog.internal.executeSafely +import com.posthog.internal.isFalseOptionValue import com.posthog.internal.logIntegrationFailure import com.posthog.internal.personPropertiesContext import com.posthog.internal.replay.PostHogSessionReplayHandler +import com.posthog.internal.serializedSize import com.posthog.internal.sortMapRecursively import com.posthog.internal.surveys.PostHogSurveysHandler import com.posthog.logs.PostHogLogRecord @@ -54,6 +57,7 @@ import java.util.concurrent.Executors private const val PUSH_NOTIFICATION_OPENED_EVENT = "\$push_notification_opened" private const val MAX_DEBUG_ERROR_LENGTH = 500 +private const val APP_LANGUAGE = "\$app_language" private const val REPLAY_DEBUG_PROPERTIES_INTERVAL_MILLIS = 30_000L // Kept on every event because the app reads them per event; the rest of the replay debug bundle is throttled. @@ -65,6 +69,20 @@ private val REQUIRED_REPLAY_DEBUG_PROPERTY_KEYS = "\$sdk_debug_replay_internal_buffer_length", ) +// On every event whether or not the bundle is claimed; the rest of the bundle needs the claim. +private val UNTHROTTLED_DEBUG_PROPERTY_KEYS = + REQUIRED_REPLAY_DEBUG_PROPERTY_KEYS + setOf("\$sdk_debug_pending_queue_size", "\$sdk_debug_error_capturing_properties") + +// Wrapper builds waiting for their send, and recent sends. A build the wrapper drops is evicted by +// newer ones; an evicted build can no longer be sent. +private const val MAX_TRACKED_WRAPPER_EVENTS = 1000 + +private fun requiresPersonProcessing( + userProperties: Map?, + userPropertiesSetOnce: Map?, + groups: Map?, +): Boolean = userProperties?.isEmpty() == false || userPropertiesSetOnce?.isEmpty() == false || groups?.isEmpty() == false + private fun isReplayDebugEvent(event: String): Boolean = event.startsWith("\$") && event != PostHogEventName.FEATURE_FLAG_CALLED.event && @@ -97,6 +115,10 @@ public class PostHog private constructor( Executors.newSingleThreadScheduledExecutor( PostHogThreadFactory("PostHogLogsQueueThread"), ), + private val aiExecutor: ExecutorService = + Executors.newSingleThreadScheduledExecutor( + PostHogThreadFactory("PostHogAiQueueThread"), + ), private val remoteConfigExecutor: ExecutorService = Executors.newSingleThreadScheduledExecutor( PostHogThreadFactory("PostHogRemoteConfigThread"), @@ -125,10 +147,23 @@ public class PostHog private constructor( private var lastReplayDebugPropertiesAt: Long? = null private var replayDebugClaimOutstanding = false + // Keyed by event uuid in build order. Both guarded by pendingWrapperBuilds. + private val pendingWrapperBuilds = LinkedHashMap() + private val sentWrapperEvents = LinkedHashSet() + + // Incremented by reset(), so a send can tell the user changed since the build even when + // reuseAnonymousId keeps the distinct id the same. + @Volatile + private var resetGeneration = 0L + private var replayQueue: PostHogQueueInterface? = null private var logsQueue: PostHogQueueInterface? = null + // The AI lane never shares a queue, executor or retry state with analytics events. + @Volatile + private var aiQueue: PostHogQueue? = null + private var pushSubscriptionManager: PostHogPushSubscriptionManager? = null /** @@ -286,12 +321,20 @@ public class PostHog private constructor( if (config.logger is PostHogNoOpLogger) PostHogPrintLogger(config) else config.logger if (config.projectToken.isEmpty()) { - config.logger.log( + config.logger.logWarning( "PostHog SDK is disabled because the project token is required and was empty after trimming whitespace.", ) return } + if (config.projectToken.startsWith("phx_")) { + config.logger.logWarning( + "PostHog SDK is disabled because the project token is a personal API key (phx_...), " + + "use your project token (phc_...).", + ) + return + } + if (!projectTokens.add(config.projectToken)) { config.logger.log("Project token: ${config.projectToken} already has a PostHog instance.") } @@ -326,6 +369,19 @@ public class PostHog private constructor( EndpointSpec.logs(config, api, config.logsStoragePrefix), logsExecutor, ) + val aiEventBytesCeiling = PostHogConfig.DEFAULT_CAPTURE_AI_MAX_EVENT_BYTES + if (config.captureAiMaxEventBytes > aiEventBytesCeiling) { + config.logger.log( + "captureAiMaxEventBytes ${config.captureAiMaxEventBytes} is over the " + + "$aiEventBytesCeiling byte ceiling, using $aiEventBytesCeiling.", + ) + } + val aiQueue = + PostHogQueue( + config, + EndpointSpec.ai(config, api, config.aiStoragePrefix), + aiExecutor, + ) val onRemoteConfigLoaded = PostHogOnRemoteConfigLoaded { // The callback fires whether the attempt succeeded or terminally failed; @@ -395,6 +451,7 @@ public class PostHog private constructor( this.queue = queue this.replayQueue = replayQueue this.logsQueue = logsQueue + this.aiQueue = aiQueue this.pushSubscriptionManager = PostHogPushSubscriptionManager( config, @@ -429,6 +486,7 @@ public class PostHog private constructor( applyBootstrapIfNeeded(config) + clearWrapperBuilds() super.enabled = true // Captured before any user callout below (integrations, session hooks), any of @@ -448,6 +506,7 @@ public class PostHog private constructor( queue.start() logsQueue.start() + aiQueue.start() // Force the persisted OPT_OUT to hydrate before this passive push trigger: the // manager reads config.optOut directly, and it is otherwise resolved lazily on @@ -708,12 +767,14 @@ public class PostHog private constructor( queue?.stop() replayQueue?.stop() logsQueue?.stop() + aiQueue?.stop() pushSubscriptionManager?.close() pushSubscriptionManager = null featureFlagsCalled.clear() clearFeatureFlagsLoaded() lastScreenName = null + clearWrapperBuilds() synchronized(replayDebugPropertiesLock) { lastReplayDebugPropertiesAt = null replayDebugClaimOutstanding = false @@ -808,6 +869,9 @@ public class PostHog private constructor( } } + @Volatile + private var appLanguage: String? = null + private fun buildProperties( distinctId: String, properties: Map?, @@ -818,15 +882,13 @@ public class PostHog private constructor( appendGroups: Boolean = true, timestamp: Date? = null, claimReplayDebugBundle: () -> Boolean = { false }, + readReplayDebugProperties: () -> Map = ::readReplayDebugProperties, ): MutableMap { val props = mutableMapOf() + // Values the SDK sets itself. Registered super properties and then the caller's properties + // override them below, and beforeSend has the final say. if (appendSharedProps) { - val registeredPrefs = getPreferences().getAll() - if (registeredPrefs.isNotEmpty()) { - props.putAll(registeredPrefs) - } - config?.context?.getStaticContext()?.let { props.putAll(it) } @@ -835,6 +897,10 @@ public class PostHog private constructor( props.putAll(it) } + appLanguage?.let { + props[APP_LANGUAGE] = it + } + if (config?.sendFeatureFlagEvent == true) { remoteConfig?.getFeatureFlags()?.let { if (it.isNotEmpty()) { @@ -854,22 +920,12 @@ public class PostHog private constructor( } } - userProperties?.let { - props["\$set"] = it - } - - userPropertiesSetOnce?.let { - props["\$set_once"] = it - } - - if (appendGroups) { - // merge groups - mergeGroups(groups)?.let { - props["\$groups"] = it - } - } - stampCachedScreenName(props) + + props["\$is_identified"] = isIdentified + // No `$process_person_profile`: person processing is sent as the `process_person_profile` + // option, only when it's off (see personProcessingOptions). A registered or caller + // `$process_person_profile` wins over it when the send hoists the property. } // Session replay should have the SDK info as well @@ -896,22 +952,48 @@ public class PostHog private constructor( } } - properties?.let { - props.putAll(it) - } - - // After the caller merge so the SDK's person-processing state can't be overridden per event - // (e.g. a caller `true` bypassing PersonProfiles.NEVER), matching posthog-js and posthog-ios. if (appendSharedProps) { - props["\$is_identified"] = isIdentified - props["\$process_person_profile"] = hasPersonProcessing() + // After session resolution so the debug snapshot never precedes a rotation triggered by + // getActiveSessionId() above. + props.putAll(sdkDebugProperties(sessionIdString, timestamp, claimReplayDebugBundle, readReplayDebugProperties)) + + // Registered super properties win over everything the SDK set above. + val registeredPrefs = getPreferences().getAll() + if (registeredPrefs.isNotEmpty()) { + props.putAll(registeredPrefs) + } + + // Per-call values win over registered ones. + userProperties?.let { + props["\$set"] = it + } + + userPropertiesSetOnce?.let { + props["\$set_once"] = it + } + + if (appendGroups) { + // merge groups + mergeGroups(groups)?.let { + props["\$groups"] = it + } + } } - // After the caller merge so SDK-computed debug values win, matching posthog-js's - // extend(properties, sdkDebugProperties). After session resolution so the debug snapshot - // never precedes a rotation triggered by getActiveSessionId() above. + // Caller-supplied properties win over registered super properties and SDK-set values. + val currentGroups = props["\$groups"] as? Map<*, *> + properties?.let { + props.putAll(it) + } if (appendSharedProps) { - props.putAll(sdkDebugProperties(sessionIdString, timestamp, claimReplayDebugBundle)) + putTypedValuesOverCaller( + props, + properties, + userProperties, + userPropertiesSetOnce, + groups.takeIf { appendGroups }, + currentGroups, + ) } // only Session replay needs distinct_id also in the props @@ -925,10 +1007,14 @@ public class PostHog private constructor( return props } + private fun readReplayDebugProperties(): Map = + sessionReplayHandler?.debugProperties() ?: mapOf("\$recording_status" to "disabled") + private fun sdkDebugProperties( sessionId: String?, timestamp: Date?, claimReplayDebugBundle: () -> Boolean, + readReplayDebugProperties: () -> Map = ::readReplayDebugProperties, ): Map { val props = mutableMapOf() val managerStart = PostHogSessionManager.getSessionStartedAt() @@ -941,7 +1027,7 @@ public class PostHog private constructor( // Guarded separately from the session and queue keys below: those come from the session // manager and the queue, not from replay, so a handler that throws must not suppress them. try { - val replayProps = sessionReplayHandler?.debugProperties() ?: mapOf("\$recording_status" to "disabled") + val replayProps = readReplayDebugProperties() if (claimed) { props.putAll(replayProps) } else { @@ -1017,6 +1103,45 @@ public class PostHog private constructor( return uuid.mostSignificantBits ushr 16 } + /** + * Adds `process_person_profile: false` when the SDK doesn't process person profiles for this + * event, unless the caller set that option or [properties] carry a non-null legacy + * `$process_person_profile` property (per call or registered). Nothing is added otherwise: + * PostHog processes person profiles by default. [personProcessingPending] counts a person + * processing change a wrapper build defers to its send. Returns a copy, so `beforeSend` edits + * never reach the caller's map. + */ + private fun personProcessingOptions( + options: Map?, + properties: Map, + personProcessingPending: Boolean = false, + ): MutableMap? { + val eventOptions = options?.toMutableMap() + if ((personProcessingPending && config?.personProfiles != PersonProfiles.NEVER) || + hasPersonProcessing() || + properties["\$process_person_profile"] != null + ) { + return eventOptions + } + val result = eventOptions ?: mutableMapOf() + if (result["process_person_profile"] == null) { + result["process_person_profile"] = false + } + return result + } + + /** + * Whether a `$set` sent with [options] updates the person. A personless one doesn't, so it + * neither stores nor matches the person-properties hash. + */ + private fun isPersonProcessed(options: Map?): Boolean { + val option = options?.get("process_person_profile") + if (option != null) { + return !isFalseOptionValue(option) + } + return !isFalseOptionValue(getPreferences().getValue("\$process_person_profile")) + } + /** * Stamps `$screen_name = lastScreenName` into [props]. Called inside * the `appendSharedProps` block in [buildProperties] BEFORE @@ -1039,126 +1164,516 @@ public class PostHog private constructor( userPropertiesSetOnce: Map?, groups: Map?, timestamp: Date?, + options: Map?, ) { + captureInternal( + event, + distinctId, + properties, + userProperties, + userPropertiesSetOnce, + groups, + timestamp, + options, + aiLane = false, + ) + } + + public override fun captureAi( + event: String, + distinctId: String?, + properties: Map?, + userProperties: Map?, + userPropertiesSetOnce: Map?, + groups: Map?, + timestamp: Date?, + options: Map?, + ): UUID? { + if (!event.startsWith("\$ai_")) { + config?.logger?.log("captureAi event $event doesn't start with \$ai_, so PostHog will drop it. Use capture for non-AI events.") + } + return captureInternal( + event, + distinctId, + properties, + userProperties, + userPropertiesSetOnce, + groups, + timestamp, + options, + aiLane = true, + ) + } + + /** + * Hands [event] to [aiQueue] unless, serialized and before [PostHogConfig.encryption], it's over + * the AI event limit or the queue is shut down. Runs on the caller's + * thread so captureAi can return null; writing stops at the limit, but the properties JSON tree is + * built in full first. Logs the name and size only: AI properties can hold prompts and media. + */ + private fun queueAiEvent( + aiQueue: PostHogQueue, + event: PostHogEvent, + ): Boolean { + val config = config ?: return false + val limit = config.captureAiMaxStoredEventBytes + val bytes = config.serializedSize(event, stopAfter = limit) + if (bytes > limit) { + config.logger.log("Dropping AI event ${event.event} of more than $limit bytes, over the limit.") + return false + } + if (!aiQueue.addMeasured(event, bytes)) { + config.logger.log("Dropping AI event ${event.event} of $bytes bytes, the AI queue is shut down.") + return false + } + return true + } + + /** + * Enriches and queues one event. Returns its uuid once it's handed to the queue, or null when + * it isn't. [aiLane] sends it through the AI queue instead of the analytics (or replay) queue. + */ + private fun captureInternal( + event: String, + distinctId: String?, + properties: Map?, + userProperties: Map?, + userPropertiesSetOnce: Map?, + groups: Map?, + timestamp: Date?, + options: Map?, + aiLane: Boolean, + ): UUID? { // Tracked on this call rather than derived from the event, so it survives beforeSend renaming // or replacing the event. var claimedReplayDebugBundle = false try { - if (!isEnabled()) { - return + val prepared = + prepareEvent( + event, + distinctId, + properties, + userProperties, + userPropertiesSetOnce, + groups, + timestamp, + options, + aiLane, + claimReplayDebugBundle = { claimReplayDebugPropertiesWindow().also { claimedReplayDebugBundle = it } }, + ) ?: return null + val postHogEvent = runBeforeSend(prepared.event, prepared.event.uuid) + if (postHogEvent == null) { + logDroppedEvent(event) + return null } - if (isOptedOut()) { - config?.logger?.log("PostHog is in OptOut state.") - return + return enqueueEvent(postHogEvent, event, prepared.mergedProperties, aiLane) { + if (claimedReplayDebugBundle) { + commitReplayDebugPropertiesWindow() + } + } + } catch (e: Throwable) { + config?.logger?.log("Capture failed: $e.") + return null + } finally { + if (claimedReplayDebugBundle) { + releaseReplayDebugPropertiesClaim() } + } + } - val newDistinctId = distinctId ?: this.distinctId + /** + * An event enriched for capture, before the `beforeSend` chain runs. + * + * @property mergedProperties the enriched properties before the `$feature_flag_called` + * minimization, which the surveys and replay handlers read. + */ + private class PreparedEvent( + val event: PostHogEvent, + val mergedProperties: Map, + ) - // if the user isn't identified but passed userProperties, userPropertiesSetOnce or groups, - // we should still enable person processing since this is intentional - if (userProperties?.isEmpty() == false || userPropertiesSetOnce?.isEmpty() == false || groups?.isEmpty() == false) { - requirePersonProcessing("capture", ignoreMessage = true) - } + /** + * What [buildEventForWrapper] decided from the call, read back by [sendBuiltEventForWrapper]: + * the wrapper's hook can rename the event, and a build changes no SDK state. + * [deferredReplayDebug] holds the replay debug values from the build, sent only if the send + * claims the window; null when the event can't carry them. + * [builtAsScreen] is true for a `$screen` build: a plain event the wrapper names `$screen` doesn't + * move the current screen. + */ + private class WrapperBuild( + val deferredReplayDebug: Map?, + val requiresPersonProcessing: Boolean, + val sdkDistinctId: String, + val resetGeneration: Long, + val builtAsScreen: Boolean, + ) + + /** + * Checks and enriches one event without running `beforeSend` or queueing it. Returns null when + * the SDK wouldn't capture it. [claimReplayDebugBundle] is called only for events that may carry + * the replay debug bundle. + */ + private fun prepareEvent( + event: String, + distinctId: String?, + properties: Map?, + userProperties: Map?, + userPropertiesSetOnce: Map?, + groups: Map?, + timestamp: Date?, + options: Map?, + aiLane: Boolean, + claimReplayDebugBundle: () -> Boolean, + readReplayDebugProperties: () -> Map = ::readReplayDebugProperties, + setFlagPersonProperties: Boolean = true, + deferPersonProcessing: Boolean = false, + ): PreparedEvent? { + if (!isEnabled()) { + return null + } + if (isOptedOut()) { + config?.logger?.log("PostHog is in OptOut state.") + return null + } + + // A blank distinct ID falls back to the current one, like null, instead of PostHog dropping the event. + val newDistinctId = distinctId?.takeIf { it.isNotBlank() } ?: this.distinctId + + // if the user isn't identified but passed userProperties, userPropertiesSetOnce or groups, + // we should still enable person processing since this is intentional + val requiresPersonProcessing = requiresPersonProcessing(userProperties, userPropertiesSetOnce, groups) + if (requiresPersonProcessing && !deferPersonProcessing) { + requirePersonProcessing("capture", ignoreMessage = true) + } - // Automatically set person properties for feature flags during capture event + // Automatically set person properties for feature flags during capture event + if (setFlagPersonProperties) { setPersonPropertiesForFlagsIfNeeded(userProperties, userPropertiesSetOnce) + } - if (newDistinctId.isBlank()) { - config?.logger?.log("capture call not allowed, distinctId is invalid: $newDistinctId.") - return + if (newDistinctId.isBlank()) { + config?.logger?.log("capture call not allowed, distinctId is invalid: $newDistinctId.") + return null + } + + // The AI lane always uses its own queue. + val isSnapshotEvent = !aiLane && event == PostHogEventName.SNAPSHOT.event + var groupIdentify = false + if (event == PostHogEventName.GROUP_IDENTIFY.event) { + groupIdentify = true + } + + // Externally-built $exception events (e.g. the Flutter/RN bridge) carry only + // serialized class names, so they are matched by name instead of isInstance. + val ignored = config?.errorTrackingConfig?.ignoredExceptionTypes + if (!ignored.isNullOrEmpty() && + event == PostHogEventName.EXCEPTION.event && + hasIgnoredTypeInExceptionList(properties, ignored) + ) { + config?.logger?.log( + "Skipping \$exception: an entry in \$exception_list matches ignoredExceptionTypes", + ) + return null + } + + // Attach the buffered exception steps to any $exception event (unless the caller + // already supplied them), so externally-built exceptions (e.g. from the Flutter/RN + // bridge) carry steps too, not only those captured via captureException(throwable). + val stepsBuffer = exceptionStepsBuffer + val effectiveProperties = + if (event == PostHogEventName.EXCEPTION.event && stepsBuffer != null) { + val mutableProperties = properties?.toMutableMap() ?: mutableMapOf() + stepsBuffer.attachTo(mutableProperties) + mutableProperties + } else { + properties } - var isSnapshotEvent = event == PostHogEventName.SNAPSHOT.event - var groupIdentify = false - if (event == PostHogEventName.GROUP_IDENTIFY.event) { - groupIdentify = true + val mergedProperties = + buildProperties( + newDistinctId, + properties = effectiveProperties, + userProperties = userProperties, + userPropertiesSetOnce = userPropertiesSetOnce, + groups = groups, + // only append shared props if not a snapshot event + appendSharedProps = !isSnapshotEvent, + // only append groups if not a group identify event and not a snapshot + appendGroups = !groupIdentify, + timestamp = timestamp, + claimReplayDebugBundle = { isReplayDebugEvent(event) && claimReplayDebugBundle() }, + readReplayDebugProperties = readReplayDebugProperties, + ) + + val eventProperties = minimizeIfFeatureFlagCalled(event, mergedProperties) + + // Snapshots don't carry the SDK's person-processing option. + val eventOptions = + if (isSnapshotEvent) { + options?.toMutableMap() + } else { + personProcessingOptions(options, mergedProperties, deferPersonProcessing && requiresPersonProcessing) } - // Externally-built $exception events (e.g. the Flutter/RN bridge) carry only - // serialized class names, so they are matched by name instead of isInstance. - val ignored = config?.errorTrackingConfig?.ignoredExceptionTypes - if (!ignored.isNullOrEmpty() && - event == PostHogEventName.EXCEPTION.event && - hasIgnoredTypeInExceptionList(properties, ignored) - ) { - config?.logger?.log( - "Skipping \$exception: an entry in \$exception_list matches ignoredExceptionTypes", - ) - return + // This capture's identity, kept through beforeSend. + val uuid = TimeBasedEpochGenerator.generate() + return PreparedEvent(newEvent(event, newDistinctId, eventProperties, timestamp, eventOptions, uuid), mergedProperties) + } + + private fun logDroppedEvent(event: String) { + val originalMessage = "PostHog event $event was dropped" + val message = + if (PostHogEventName.isUnsafeEditable(event)) { + "$originalMessage. This can cause unexpected behavior." + } else { + originalMessage } + config?.logger?.log(message) + } - // Attach the buffered exception steps to any $exception event (unless the caller - // already supplied them), so externally-built exceptions (e.g. from the Flutter/RN - // bridge) carry steps too, not only those captured via captureException(throwable). - val stepsBuffer = exceptionStepsBuffer - val effectiveProperties = - if (event == PostHogEventName.EXCEPTION.event && stepsBuffer != null) { - val mutableProperties = properties?.toMutableMap() ?: mutableMapOf() - stepsBuffer.attachTo(mutableProperties) - mutableProperties + /** + * Queues [postHogEvent], already through `beforeSend`, on its lane and notifies the surveys and + * replay handlers with [event] and [mergedProperties] from before the hook. Returns the event's + * uuid when it's queued. [onQueued] runs right after the event is added to the analytics or AI + * queue. + */ + private fun enqueueEvent( + postHogEvent: PostHogEvent, + event: String, + mergedProperties: Map, + aiLane: Boolean, + onQueued: () -> Unit = {}, + ): UUID? { + if (isEmptyNameDropped(postHogEvent)) { + return null + } + // Reevaluate if this is a snapshot event because the event might have been updated by the beforeSend hook + val isSnapshotEvent = !aiLane && postHogEvent.event == PostHogEventName.SNAPSHOT.event + // if this is a $snapshot event and $session_id is missing, don't process then event + if (isSnapshotEvent && postHogEvent.properties?.get("\$session_id") == null) { + config?.logger?.log("${postHogEvent.event} event dropped, because the \$session_id property is missing") + return null + } + // Replay has its own queue + if (isSnapshotEvent) { + replayQueue?.add(postHogEvent) + return postHogEvent.uuid + } + val targetQueue = if (aiLane) aiQueue ?: return null else queue + var queued = false + // beforeSend may have opted out + if (isOptedOut()) { + config?.logger?.log("PostHog is in OptOut state.") + } else if (targetQueue != null) { + // AI events are measured and admitted here rather than in the queue, so captureAi returns null + queued = + if (aiLane) { + queueAiEvent(aiQueue ?: return null, postHogEvent) } else { - properties + targetQueue.add(postHogEvent) + true } + if (queued) { + onQueued() + } + } + // The event is already queued, so a handler failure can't change the result or skip the other handler. + // Notify surveys integration about the event + try { + surveysHandler?.onEvent(event, mergedProperties) + } catch (e: Throwable) { + config?.logger?.log("Surveys onEvent failed: $e.") + } + // Notify session replay handler about the event for event triggers + try { + sessionReplayHandler?.onEvent(event, mergedProperties) + } catch (e: Throwable) { + config?.logger?.log("Session replay onEvent failed: $e.") + } + return if (queued) postHogEvent.uuid else null + } - val mergedProperties = - buildProperties( - newDistinctId, - properties = effectiveProperties, - userProperties = userProperties, - userPropertiesSetOnce = userPropertiesSetOnce, - groups = groups, - // only append shared props if not a snapshot event - appendSharedProps = !isSnapshotEvent, - // only append groups if not a group identify event and not a snapshot - appendGroups = !groupIdentify, - timestamp = timestamp, - claimReplayDebugBundle = { - isReplayDebugEvent(event) && claimReplayDebugPropertiesWindow().also { claimedReplayDebugBundle = it } - }, - ) + @PostHogInternal + override fun buildEventForWrapper( + event: String, + distinctId: String?, + properties: Map?, + userProperties: Map?, + userPropertiesSetOnce: Map?, + groups: Map?, + options: Map?, + ai: Boolean, + timestamp: Date?, + ): PostHogEvent? { + try { + if (!isEnabled()) { + return null + } + // The wrapper may drop the event after this, so state changes wait for the send. + val builtAsScreen = !ai && event == PostHogEventName.SCREEN.event + val eventProperties = + if (builtAsScreen) { + val screenTitle = properties?.get("\$screen_name") as? String ?: return null + screenProperties(screenTitle, properties, cacheScreenName = false) ?: return null + } else { + properties + } + // Read before the event takes its distinct ID, so a reset() or identify() during the build + // makes the send see a different identity instead of pairing the old event with the new one. + val sdkDistinctId = this.distinctId + val buildResetGeneration = resetGeneration + // One replay read for the build's required keys and the deferred bundle, so a replay + // transition between them can't pair keys from two different states. + val replayDebugSnapshot by lazy { runCatching { readReplayDebugProperties() } } + val readReplayDebugSnapshot = { replayDebugSnapshot.getOrThrow() } + val built = + prepareEvent( + event, + distinctId, + eventProperties, + userProperties, + userPropertiesSetOnce, + groups, + timestamp, + options, + ai, + claimReplayDebugBundle = { false }, + readReplayDebugProperties = readReplayDebugSnapshot, + setFlagPersonProperties = false, + deferPersonProcessing = true, + )?.event ?: return null + built.uuid?.let { uuid -> + // Snapshotted now, so a new session during the round trip doesn't change them. + val deferredReplayDebug = + if (isReplayDebugEvent(event)) { + sdkDebugProperties( + built.properties?.get("\$session_id") as? String, + built.timestamp, + claimReplayDebugBundle = { true }, + readReplayDebugProperties = readReplayDebugSnapshot, + ) + .filterKeys { it !in UNTHROTTLED_DEBUG_PROPERTY_KEYS } + .takeIf { it.isNotEmpty() } + } else { + null + } + val build = + WrapperBuild( + deferredReplayDebug = deferredReplayDebug, + requiresPersonProcessing = requiresPersonProcessing(userProperties, userPropertiesSetOnce, groups), + sdkDistinctId = sdkDistinctId, + resetGeneration = buildResetGeneration, + builtAsScreen = builtAsScreen, + ) + synchronized(pendingWrapperBuilds) { + pendingWrapperBuilds[uuid] = build + if (pendingWrapperBuilds.size > MAX_TRACKED_WRAPPER_EVENTS) { + pendingWrapperBuilds.remove(pendingWrapperBuilds.keys.first()) + } + } + } + return built + } catch (e: Throwable) { + config?.logger?.log("Capture failed: $e.") + return null + } + } - val eventProperties = minimizeIfFeatureFlagCalled(event, mergedProperties) + private fun clearWrapperBuilds() { + synchronized(pendingWrapperBuilds) { + pendingWrapperBuilds.clear() + } + } - val postHogEvent = buildEvent(event, newDistinctId, eventProperties, timestamp) - if (postHogEvent == null) { - val originalMessage = "PostHog event $event was dropped" - val message = - if (PostHogEventName.isUnsafeEditable(event)) { - "$originalMessage. This can cause unexpected behavior." - } else { - originalMessage + @PostHogInternal + override fun sendBuiltEventForWrapper( + event: PostHogEvent, + ai: Boolean, + ): UUID? { + var claimedReplayDebugBundle = false + try { + var alreadySent = false + val build = + event.uuid?.let { uuid -> + synchronized(pendingWrapperBuilds) { + // Checked and recorded together, so two concurrent sends can't both queue it. + alreadySent = !sentWrapperEvents.add(uuid) + if (sentWrapperEvents.size > MAX_TRACKED_WRAPPER_EVENTS) { + sentWrapperEvents.remove(sentWrapperEvents.first()) + } + pendingWrapperBuilds.remove(uuid) } - config?.logger?.log(message) - return + } + if (alreadySent) { + config?.logger?.log("Event ${event.uuid} was already sent.") + return null } - // Reevaluate if this is a snapshot event because the event might have been updated by the beforeSend hook - isSnapshotEvent = postHogEvent.event == PostHogEventName.SNAPSHOT.event - // if this is a $snapshot event and $session_id is missing, don't process then event - if (isSnapshotEvent && postHogEvent.properties?.get("\$session_id") == null) { - config?.logger?.log("${postHogEvent.event} event dropped, because the \$session_id property is missing") - return + // Builds are cleared on setup() and close() and kept per instance, so this also drops an + // event built by another instance or before a reconfigure. + if (build == null) { + config?.logger?.log("Event ${event.event} wasn't built by buildEventForWrapper on this setup, so it was dropped.") + return null } - // Replay has its own queue - if (isSnapshotEvent) { - replayQueue?.add(postHogEvent) - } else { - val queue = queue - // beforeSend may have opted out - if (isOptedOut()) { - config?.logger?.log("PostHog is in OptOut state.") - } else if (queue != null) { - queue.add(postHogEvent) - if (claimedReplayDebugBundle) { - commitReplayDebugPropertiesWindow() + if (!isEnabled()) { + return null + } + if (isOptedOut()) { + config?.logger?.log("PostHog is in OptOut state.") + return null + } + // Person processing and flag person properties apply only while the SDK still has the + // identity the event was built for: after a reset() or identify(), it belongs to the previous one. + // A wrapper that moves the event to another distinct id moves its \$set to that person too. + val sameIdentity = + build.sdkDistinctId == this.distinctId && + event.distinctId == build.sdkDistinctId && + build.resetGeneration == resetGeneration + if (sameIdentity && build.requiresPersonProcessing) { + requirePersonProcessing("capture", ignoreMessage = true) + } + val uuid = event.uuid + val properties = event.properties ?: mutableMapOf() + if (sameIdentity) { + @Suppress("UNCHECKED_CAST") + setPersonPropertiesForFlagsIfNeeded( + properties["\$set"] as? Map, + properties["\$set_once"] as? Map, + ) + } + // A reset() since the build cleared the screen name, so the old one isn't restored. + if (!ai && build.builtAsScreen && build.resetGeneration == resetGeneration && event.event == PostHogEventName.SCREEN.event) { + (properties["\$screen_name"] as? String)?.trim()?.takeIf { it.isNotEmpty() }?.let { cacheScreenName(it) } + } + // The build added only the required replay debug keys. The window is claimed here, so a + // built event the wrapper drops never holds or starts it. Eligibility and values come from + // the build, since the wrapper's hook can rename the event and the session can change. + val deferredReplayDebug = build.deferredReplayDebug + if (deferredReplayDebug != null && claimReplayDebugPropertiesWindow()) { + claimedReplayDebugBundle = true + // Only keys the event lacks, so the wrapper's values win. + deferredReplayDebug.forEach { (key, value) -> + if (!properties.containsKey(key)) { + properties[key] = value } } - // Notify surveys integration about the event - surveysHandler?.onEvent(event, mergedProperties) - // Notify session replay handler about the event for event triggers - sessionReplayHandler?.onEvent(event, mergedProperties) + } + val builtEvent = if (event.properties == null) event.copy(properties = properties) else event + // Copied before the hooks run, which can change the map in place. + val handlerProperties = + if (surveysHandler != null || sessionReplayHandler != null) properties.toMap() else emptyMap() + val postHogEvent = runBeforeSend(builtEvent, uuid) + if (postHogEvent == null) { + logDroppedEvent(builtEvent.event) + return null + } + return enqueueEvent(postHogEvent, builtEvent.event, handlerProperties, ai) { + if (claimedReplayDebugBundle) { + commitReplayDebugPropertiesWindow() + } } } catch (e: Throwable) { config?.logger?.log("Capture failed: $e.") + return null } finally { if (claimedReplayDebugBundle) { releaseReplayDebugPropertiesClaim() @@ -1169,6 +1684,7 @@ public class PostHog private constructor( override fun captureException( throwable: Throwable, properties: Map?, + options: Map?, ) { if (!isEnabled()) { return @@ -1193,7 +1709,7 @@ public class PostHog private constructor( // $exception_steps are attached in capture() for all $exception events, // so externally-built exceptions (e.g. the Flutter/RN bridge) get them too. - capture(PostHogEventName.EXCEPTION.event, properties = exceptionProperties) + capture(PostHogEventName.EXCEPTION.event, properties = exceptionProperties, options = options) } catch (e: Throwable) { // we swallow all exceptions that the SDK has thrown by trying to convert // a captured exception to a PostHog exception event @@ -1527,21 +2043,34 @@ public class PostHog private constructor( public override fun screen( screenTitle: String, properties: Map?, + options: Map?, ) { if (!isEnabled()) { return } + val props = screenProperties(screenTitle, properties) ?: return + + capture(PostHogEventName.SCREEN.event, properties = props, options = options) + } + + /** + * Caches [screenTitle], trimmed, as the current screen and returns [properties] with it as + * `$screen_name`. Returns null for a blank title. + */ + private fun screenProperties( + screenTitle: String, + properties: Map?, + cacheScreenName: Boolean = true, + ): MutableMap? { val trimmedTitle = screenTitle.trim() if (trimmedTitle.isEmpty()) { - return + return null } - if (lastScreenName != trimmedTitle) config.notifyIntegrationsChanged() - - // Cache for capture-time context snapshot on log records and for the - // $screen_name auto-attach on subsequent events (see buildProperties). - this.lastScreenName = trimmedTitle + if (cacheScreenName) { + cacheScreenName(trimmedTitle) + } val props = mutableMapOf() properties?.let { @@ -1550,11 +2079,20 @@ public class PostHog private constructor( // The title wins over a caller-supplied $screen_name, matching the cached value. props["\$screen_name"] = trimmedTitle + return props + } - capture(PostHogEventName.SCREEN.event, properties = props) + // Cache for capture-time context snapshot on log records and for the + // $screen_name auto-attach on subsequent events (see buildProperties). + private fun cacheScreenName(screenName: String) { + if (lastScreenName != screenName) config.notifyIntegrationsChanged() + this.lastScreenName = screenName } - public override fun alias(alias: String) { + public override fun alias( + alias: String, + options: Map?, + ) { if (!isEnabled()) { return } @@ -1579,7 +2117,7 @@ public class PostHog private constructor( // read the event properties can resolve both sides of the alias linkage. props["distinct_id"] = sourceDistinctId - capture(PostHogEventName.CREATE_ALIAS.event, distinctId = sourceDistinctId, properties = props) + capture(PostHogEventName.CREATE_ALIAS.event, distinctId = sourceDistinctId, properties = props, options = options) } public override fun captureFeatureView( @@ -1671,6 +2209,15 @@ public class PostHog private constructor( distinctId: String, userProperties: Map?, userPropertiesSetOnce: Map?, + ) { + identify(distinctId, userProperties, userPropertiesSetOnce, options = null) + } + + public override fun identify( + distinctId: String, + userProperties: Map?, + userPropertiesSetOnce: Map?, + options: Map?, ) { if (!isEnabled()) { return @@ -1724,6 +2271,7 @@ public class PostHog private constructor( properties = props, userProperties = userProperties, userPropertiesSetOnce = userPropertiesSetOnce, + options = options, ) if (config?.reuseAnonymousId != true) { @@ -1763,12 +2311,15 @@ public class PostHog private constructor( distinctId = distinctId, userProperties = userProperties ?: emptyMap(), userPropertiesSetOnce = userPropertiesSetOnce ?: emptyMap(), + options = options, ) // The transition event must fire even when an identical property call was cached // earlier; cache only after capture so deduplication cannot suppress it. - synchronized(cachedPersonPropertiesLock) { - cachedPersonPropertiesHash = getPersonPropertiesHash(distinctId, userProperties, userPropertiesSetOnce) + if (isPersonProcessed(options)) { + synchronized(cachedPersonPropertiesLock) { + cachedPersonPropertiesHash = getPersonPropertiesHash(distinctId, userProperties, userPropertiesSetOnce) + } } // The identified state itself is not part of the flags request; reload only when the @@ -1777,7 +2328,8 @@ public class PostHog private constructor( reloadFeatureFlags() } } else if (!hasDifferentDistinctId && (userProperties?.isNotEmpty() == true || userPropertiesSetOnce?.isNotEmpty() == true)) { - if (shouldCapturePersonPropertiesEvent( + if (!isPersonProcessed(options) || + shouldCapturePersonPropertiesEvent( distinctId, userProperties, userPropertiesSetOnce, @@ -1789,6 +2341,7 @@ public class PostHog private constructor( distinctId = distinctId, userProperties = userProperties, userPropertiesSetOnce = userPropertiesSetOnce, + options = options, ) } // Note we don't reload flags on property changes as these get processed async @@ -1800,6 +2353,7 @@ public class PostHog private constructor( public override fun setPersonProperties( userPropertiesToSet: Map?, userPropertiesToSetOnce: Map?, + options: Map?, ) { if (!isEnabled()) { return @@ -1815,7 +2369,8 @@ public class PostHog private constructor( val currentDistinctId = this.distinctId - if (!shouldCapturePersonPropertiesEvent( + if (isPersonProcessed(options) && + !shouldCapturePersonPropertiesEvent( currentDistinctId, userPropertiesToSet, userPropertiesToSetOnce, @@ -1839,6 +2394,7 @@ public class PostHog private constructor( distinctId = currentDistinctId, userProperties = userPropertiesToSet, userPropertiesSetOnce = userPropertiesToSetOnce, + options = options, ) } @@ -1950,6 +2506,7 @@ public class PostHog private constructor( type: String, key: String, groupProperties: Map?, + options: Map?, ) { if (!isEnabled()) { return @@ -1995,7 +2552,7 @@ public class PostHog private constructor( preferences.setValue(GROUPS, newGroups) } - capture(PostHogEventName.GROUP_IDENTIFY.event, distinctId = this.distinctId, properties = props) + capture(PostHogEventName.GROUP_IDENTIFY.event, distinctId = this.distinctId, properties = props, options = options) // Automatically set group properties for feature flags setGroupPropertiesForFlagsIfNeeded(type, groupProperties) @@ -2223,6 +2780,7 @@ public class PostHog private constructor( super.flush() replayQueue?.flush() logsQueue?.flush() + aiQueue?.flush() // See the setup() call site: hydrate opt-out before the manager reads the raw config field. isOptedOut() pushSubscriptionManager?.retryPending() @@ -2287,6 +2845,7 @@ public class PostHog private constructor( } config.notifyIntegrationsChanged() + resetGeneration++ // Capture the logging-out identity before preferences are cleared, so the push token can be // unregistered for it and re-registered under the new anonymous id (decision 5/6). val previousDistinctId = distinctId @@ -2382,6 +2941,10 @@ public class PostHog private constructor( getPreferences().remove(key) } + public override fun setAppLanguage(language: String?) { + appLanguage = language?.trim()?.replace('_', '-')?.ifEmpty { null } + } + override fun distinctId(): String { if (!isEnabled()) { return "" @@ -2768,12 +3331,17 @@ public class PostHog private constructor( Executors.newSingleThreadScheduledExecutor( PostHogThreadFactory("PostHogLogsQueueThread"), ), + aiExecutor: ExecutorService = + Executors.newSingleThreadScheduledExecutor( + PostHogThreadFactory("PostHogAiQueueThread"), + ), ): PostHogInterface { val instance = PostHog( queueExecutor = queueExecutor, replayExecutor = replayExecutor, logsExecutor = logsExecutor, + aiExecutor = aiExecutor, remoteConfigExecutor = featureFlagsExecutor, cachedEventsExecutor = cachedEventsExecutor, reloadFeatureFlags = reloadFeatureFlags, @@ -2798,6 +3366,7 @@ public class PostHog private constructor( userPropertiesSetOnce: Map?, groups: Map?, timestamp: Date?, + options: Map?, ) { shared.capture( event, @@ -2807,14 +3376,37 @@ public class PostHog private constructor( userPropertiesSetOnce = userPropertiesSetOnce, groups = groups, timestamp = timestamp, + options = options, ) } + public override fun captureAi( + event: String, + distinctId: String?, + properties: Map?, + userProperties: Map?, + userPropertiesSetOnce: Map?, + groups: Map?, + timestamp: Date?, + options: Map?, + ): UUID? = + shared.captureAi( + event, + distinctId = distinctId, + properties = properties, + userProperties = userProperties, + userPropertiesSetOnce = userPropertiesSetOnce, + groups = groups, + timestamp = timestamp, + options = options, + ) + public override fun captureException( throwable: Throwable, properties: Map?, + options: Map?, ) { - shared.captureException(throwable, properties) + shared.captureException(throwable, properties, options) } public override fun addExceptionStep( @@ -2828,11 +3420,13 @@ public class PostHog private constructor( distinctId: String, userProperties: Map?, userPropertiesSetOnce: Map?, + options: Map?, ) { shared.identify( distinctId, userProperties = userProperties, userPropertiesSetOnce = userPropertiesSetOnce, + options = options, ) } @@ -2875,8 +3469,9 @@ public class PostHog private constructor( public override fun setPersonProperties( userPropertiesToSet: Map?, userPropertiesToSetOnce: Map?, + options: Map?, ) { - shared.setPersonProperties(userPropertiesToSet, userPropertiesToSetOnce) + shared.setPersonProperties(userPropertiesToSet, userPropertiesToSetOnce, options) } public override fun setPersonPropertiesForFlags( @@ -2921,19 +3516,24 @@ public class PostHog private constructor( type: String, key: String, groupProperties: Map?, + options: Map?, ) { - shared.group(type, key, groupProperties = groupProperties) + shared.group(type, key, groupProperties = groupProperties, options = options) } public override fun screen( screenTitle: String, properties: Map?, + options: Map?, ) { - shared.screen(screenTitle, properties = properties) + shared.screen(screenTitle, properties = properties, options = options) } - public override fun alias(alias: String) { - shared.alias(alias) + public override fun alias( + alias: String, + options: Map?, + ) { + shared.alias(alias, options) } public override fun captureFeatureView( @@ -2963,6 +3563,10 @@ public class PostHog private constructor( shared.unregister(key) } + public override fun setAppLanguage(language: String?) { + shared.setAppLanguage(language) + } + override fun distinctId(): String = shared.distinctId() override fun getAnonymousId(): String = shared.getAnonymousId() @@ -2985,6 +3589,36 @@ public class PostHog private constructor( return shared.getConfig() } + @PostHogInternal + override fun buildEventForWrapper( + event: String, + distinctId: String?, + properties: Map?, + userProperties: Map?, + userPropertiesSetOnce: Map?, + groups: Map?, + options: Map?, + ai: Boolean, + timestamp: Date?, + ): PostHogEvent? = + shared.buildEventForWrapper( + event, + distinctId = distinctId, + properties = properties, + userProperties = userProperties, + userPropertiesSetOnce = userPropertiesSetOnce, + groups = groups, + options = options, + ai = ai, + timestamp = timestamp, + ) + + @PostHogInternal + override fun sendBuiltEventForWrapper( + event: PostHogEvent, + ai: Boolean, + ): UUID? = shared.sendBuiltEventForWrapper(event, ai) + override fun isSessionActive(): Boolean { return shared.isSessionActive() } diff --git a/posthog/src/main/java/com/posthog/PostHogConfig.kt b/posthog/src/main/java/com/posthog/PostHogConfig.kt index 929b639dd..6d70babf6 100644 --- a/posthog/src/main/java/com/posthog/PostHogConfig.kt +++ b/posthog/src/main/java/com/posthog/PostHogConfig.kt @@ -134,7 +134,7 @@ public open class PostHogConfig( * * Defaults to 3 */ - public var maxRetries: Int = 3, + public var pushNotificationSubscriptionMaxRetries: Int = 3, /** * Maximum number of retries for feature flag requests after transient network errors. * Defaults to 1. Set to 0 to disable feature flag request retries. @@ -392,7 +392,10 @@ public open class PostHogConfig( /** * Custom headers to send with every request to the PostHog API. * - * Useful for reverse-proxy setups that require authentication, e.g. an `Authorization` header. + * Useful for reverse-proxy setups that require authentication. Capture requests + * (`/i/v1/analytics/events`) send the project token in an `Authorization: Bearer` header, which + * replaces an `Authorization` header set here, so authenticate your proxy with a different + * header, such as `X-Proxy-Token`. Other requests still send your `Authorization` header. * * Read once when the SDK is set up; changes after setup are ignored. * @@ -414,6 +417,52 @@ public open class PostHogConfig( */ public var compression: PostHogCompression = PostHogCompression.GZIP + /** + * How the SDK compresses [PostHog.captureAi] request bodies, separately from [compression]. + * + * When [httpClient] is set, it applies only if that client installs a [com.posthog.internal.GzipRequestInterceptor], + * which the SDK then reads this setting through for AI requests. + * + * Default: [PostHogCompression.GZIP]. + */ + public var captureAiCompression: PostHogCompression = PostHogCompression.GZIP + + /** + * Maximum number of [PostHog.captureAi] events kept in their on-disk queue before the oldest + * are dropped. + * + * AI events can be megabytes, so this is lower than [maxQueueSize]. The queue also keeps at most + * 50 MiB of AI events, whatever this is set to. The same limits apply to AI events still waiting + * to be written to disk, for example during a slow upload: over them, the oldest waiting events + * are dropped. A value of 0 or less uses the default. + * + * Default: 100. + */ + public var captureAiMaxQueueSize: Int = DEFAULT_CAPTURE_AI_MAX_QUEUE_SIZE + + /** + * How long, in seconds, a [PostHog.captureAi] request can go without network activity before it + * times out: its HTTP client's read and write timeouts. + * + * AI requests can carry several MB, so this is longer than for other requests, which keep + * OkHttp's 10 second defaults. A value of 0 or less uses the default. + * + * Default: 60. + */ + public var captureAiTimeout: Int = DEFAULT_CAPTURE_AI_TIMEOUT_SECONDS + + /** + * Maximum size, in bytes, of a serialized [PostHog.captureAi] event, measured before [encryption]. + * The SDK drops a larger event; then `captureAi` returns null and logs only the event name and the limit. + * + * Use it to lower the limit. PostHog drops AI events whose properties are over 8 MiB, so the default + * allows 8 MiB plus 64 KiB for the rest of the event. A larger value uses the default and logs a + * warning. A value of 0 or less uses the default. + * + * Default: 8454144 (8 MiB + 64 KiB). + */ + public var captureAiMaxEventBytes: Int = DEFAULT_CAPTURE_AI_MAX_EVENT_BYTES + /** * Your PostHog project token, trimmed of leading and trailing whitespace. * @@ -468,6 +517,9 @@ public open class PostHogConfig( @PostHogInternal public var logsStoragePrefix: String? = null + @PostHogInternal + public var aiStoragePrefix: String? = null + @PostHogInternal public var cachePreferences: PostHogPreferences? = null @@ -589,6 +641,15 @@ public open class PostHogConfig( /** Shared default for [flushIntervalSeconds] and [PostHogLogsConfig.flushIntervalSeconds]. */ public const val DEFAULT_FLUSH_INTERVAL_SECONDS: Int = 30 + /** Default for [captureAiMaxQueueSize]. */ + public const val DEFAULT_CAPTURE_AI_MAX_QUEUE_SIZE: Int = 100 + + /** Default for [captureAiTimeout]. */ + public const val DEFAULT_CAPTURE_AI_TIMEOUT_SECONDS: Int = 60 + + /** Default for [captureAiMaxEventBytes]: PostHog's 8 MiB limit on an AI event's properties, plus 64 KiB for the rest of the event. */ + public const val DEFAULT_CAPTURE_AI_MAX_EVENT_BYTES: Int = 8 * 1024 * 1024 + 64 * 1024 + public const val DEFAULT_US_HOST: String = "https://us.i.posthog.com" public const val DEFAULT_US_ASSETS_HOST: String = "https://us-assets.i.posthog.com" diff --git a/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt b/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt index dc77ef3a3..ee6760ec4 100644 --- a/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt @@ -12,19 +12,6 @@ public interface PostHogCoreInterface { */ public fun close() - /** - * Identifies the user - * Docs https://posthog.com/docs/product-analytics/identify - * @param distinctId the distinctId - * @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 - */ - public fun identify( - distinctId: String, - userProperties: Map? = null, - userPropertiesSetOnce: Map? = null, - ) - /** * Flushes all the events in the Queue right away */ diff --git a/posthog/src/main/java/com/posthog/PostHogEvent.kt b/posthog/src/main/java/com/posthog/PostHogEvent.kt index 8f2ceee88..5ef2533e3 100644 --- a/posthog/src/main/java/com/posthog/PostHogEvent.kt +++ b/posthog/src/main/java/com/posthog/PostHogEvent.kt @@ -11,12 +11,12 @@ import java.util.UUID // if we'd ever allow users to inspect and mutate the event, it should be a public API /** - * The PostHog event data structure accepted by the batch API + * The PostHog event data structure sent to capture * @property event The event name * @property distinctId The distinct Id * @property properties All the event properties * @property timestamp The event timestamp. UTC is preferred; the equivalent instant is serialized in UTC - * @property uuid the UUID v4 is automatically generated and used for deduplication + * @property uuid the UUID v7 is automatically generated and used for deduplication */ public data class PostHogEvent( val event: String, @@ -38,6 +38,21 @@ public data class PostHogEvent( @SerializedName("api_key") var apiKey: String? = null, ) { + /** + * Options that tell PostHog how to process this event, separate from its properties. + * + * Known keys are `process_person_profile`, `cookieless_mode`, `disable_skew_correction` and + * `product_tour_id`; unknown keys are sent unchanged and ignored by PostHog. When the event is + * sent, the legacy `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and + * `$product_tour_id` properties are removed from [properties] and used for their option + * unless that option is already set here. + * + * Not a constructor parameter, so the constructor and [copy] keep their 3.x signatures. When + * `beforeSend` returns a different event whose options are null, such as one made with + * [copy], that event gets the options of the event the hook was given. + */ + var options: MutableMap? = null + /** * Checks if the event is an exception event ($exception) */ diff --git a/posthog/src/main/java/com/posthog/PostHogInterface.kt b/posthog/src/main/java/com/posthog/PostHogInterface.kt index 4e1be761d..372085531 100644 --- a/posthog/src/main/java/com/posthog/PostHogInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogInterface.kt @@ -68,13 +68,29 @@ public interface PostHogInterface : PostHogCoreInterface { /** * Captures events + * + * The event's properties are merged in this order, and later values win: properties the SDK + * sets itself (such as `$os`, `$app_version`, `$screen_name`, `$is_identified` and the session + * replay debug properties), registered super properties ([register]), [properties], then + * `beforeSend`. + * + * Example: + * ``` + * PostHog.capture("signed_up", options = mapOf("cookieless_mode" to true)) + * ``` * @param event the event name - * @param distinctId the distinctId, the generated [distinctId] is used if not given + * @param distinctId the distinctId, the generated [distinctId] is used if not given or blank * @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 event timestamp override. UTC is preferred; the equivalent instant is serialized in UTC. If omitted, the current time is used + * @param options settings that tell PostHog how to process this event, sent apart from its + * properties. Known keys are `process_person_profile`, `cookieless_mode`, + * `disable_skew_correction` and `product_tour_id`; unknown keys are sent unchanged and + * ignored by PostHog. An option wins over its legacy property (`$process_person_profile`, + * `$cookieless_mode`, `$ignore_sent_at`, `$product_tour_id`) when the event is sent. The map + * is copied, and `beforeSend` can change it through [PostHogEvent.options] */ public fun capture( event: String, @@ -84,16 +100,70 @@ public interface PostHogInterface : PostHogCoreInterface { userPropertiesSetOnce: Map? = null, groups: Map? = null, timestamp: Date? = null, + options: Map? = null, ) + /** + * Captures an AI observability event, such as `$ai_generation`, `$ai_span`, `$ai_trace` or + * `$ai_embedding`, and sends it to PostHog's AI endpoint (`/i/v1/ai/events`), which accepts much + * larger events than [capture]. + * + * Takes the same arguments as [capture], merges properties in the same order and goes through + * the same `beforeSend` hooks. The event is queued on disk separately from other events and sent + * unchanged: the SDK doesn't redact or truncate prompts, outputs or media. PostHog drops an event + * sent here whose name doesn't start with `$ai_`, and the SDK logs a debug message when it's + * given one. [capture] never sends events here, even ones named `$ai_*`. + * + * AI events use [PostHogConfig.flushAt], [PostHogConfig.maxBatchSize] and + * [PostHogConfig.flushIntervalSeconds], like other events, and + * [PostHogConfig.captureAiCompression], [PostHogConfig.captureAiMaxQueueSize] and + * [PostHogConfig.captureAiTimeout] instead of `compression`, `maxQueueSize` and the default + * timeouts. A serialized event over [PostHogConfig.captureAiMaxEventBytes] (8 MiB + 64 KiB by + * default) is dropped, with a log line naming the event and the limit. Requests carry up to about + * 5 MiB of events, and the SDK sends as soon as that much is queued. Up to 50 MiB of AI events + * are kept on disk; beyond that, the oldest are dropped. + * + * Example: + * ``` + * PostHog.captureAi( + * "\$ai_generation", + * properties = mapOf("\$ai_model" to "gpt-5", "\$ai_trace_id" to traceId), + * ) + * ``` + * @param event the AI event name, such as `$ai_generation` + * @param distinctId the distinctId, the generated [distinctId] is used if not given or blank + * @param properties the custom properties + * @param userProperties the user properties, set as a "$set" property + * @param userPropertiesSetOnce the user properties to set only once, set as a "$set_once" property + * @param groups the groups, set as a "$groups" property + * @param timestamp the event timestamp override. UTC is preferred; the equivalent instant is serialized in UTC. If omitted, the current time is used + * @param options settings that tell PostHog how to process this event, see `options` in [capture] + * @return the event's uuid once it's handed to the queue, or null when it isn't: the SDK is + * disabled or opted out, the event name is empty, `beforeSend` dropped it, or it's over the + * size limit + */ + public fun captureAi( + event: String, + distinctId: String? = null, + properties: Map? = null, + userProperties: Map? = null, + userPropertiesSetOnce: Map? = null, + groups: Map? = null, + timestamp: Date? = null, + options: Map? = null, + ): UUID? + /** * Captures exceptions * @param throwable the Throwable error * @param properties the custom properties + * @param options settings that tell PostHog how to process the `$exception` event, see + * `options` in [capture] */ public fun captureException( throwable: Throwable, properties: Map? = null, + options: Map? = null, ) /** @@ -238,29 +308,40 @@ public interface PostHogInterface : PostHogCoreInterface { * @param type the Group type * @param key the Group key * @param groupProperties the Group properties, set as a "$group_set" property, Docs https://posthog.com/docs/product-analytics/group-analytics + * @param options settings that tell PostHog how to process the `$groupidentify` event, see + * `options` in [capture] */ public fun group( type: String, key: String, groupProperties: Map? = null, + options: Map? = null, ) /** * Captures a screen view event * @param screenTitle the screen title. It takes precedence over a `$screen_name` key in [properties]. * @param properties the custom properties + * @param options settings that tell PostHog how to process the `$screen` event, see + * `options` in [capture] */ public fun screen( screenTitle: String, properties: Map? = null, + options: Map? = null, ) /** * Creates an alias for the user * Docs https://posthog.com/docs/product-analytics/identify#alias-assigning-multiple-distinct-ids-to-the-same-user * @param alias the alias + * @param options settings that tell PostHog how to process the `$create_alias` event, see + * `options` in [capture] */ - public fun alias(alias: String) + public fun alias( + alias: String, + options: Map? = null, + ) /** * Register a property to always be sent with all the following events until you call @@ -281,6 +362,25 @@ public interface PostHogInterface : PostHogCoreInterface { */ public fun unregister(key: String) + /** + * Sets the `$app_language` property: the language your app displays, sent with every event. + * + * Call it at startup and whenever the language changes, because the value is kept in memory + * only. It overrides the language the SDK detects, and survives [reset]. + * + * Default: on Android 13+ the SDK detects the language from your `localeConfig` declaration, and + * on Android 6-12 it sends no `$app_language` unless you call this. Compare `$locale`, which is + * the device language whichever language your app displays. + * + * ```kotlin + * PostHog.setAppLanguage("de") + * ``` + * + * @param language a BCP 47 language tag, such as `de` or `pt-BR`. Pass `null` to go back to the + * detected language + */ + public fun setAppLanguage(language: String?) + /** * Returns the registered [distinctId] property * @return The current distinct ID. @@ -362,6 +462,22 @@ public interface PostHogInterface : PostHogCoreInterface { */ public fun getSessionId(): UUID? + /** + * Identifies the user + * Docs https://posthog.com/docs/product-analytics/identify + * @param distinctId the distinctId + * @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 options settings that tell PostHog how to process the `$identify` or `$set` event + * this call sends, see `options` in [capture] + */ + public fun identify( + distinctId: String, + userProperties: Map? = null, + userPropertiesSetOnce: Map? = null, + options: Map? = null, + ) + /** * Sets properties on the person profile associated with the current distinct_id. * Learn more about [identifying users](https://posthog.com/docs/product-analytics/identify) @@ -375,10 +491,13 @@ public interface PostHogInterface : PostHogCoreInterface { * @param userPropertiesToSetOnce Optional: Properties to store about the user only if not previously set. * Note: For feature flag evaluations, if the same key is present in both parameters, * the value from userPropertiesToSet will take precedence. + * @param options settings that tell PostHog how to process the `$set` event, see `options` + * in [capture] */ public fun setPersonProperties( userPropertiesToSet: Map? = null, userPropertiesToSetOnce: Map? = null, + options: Map? = null, ) /** @@ -516,4 +635,68 @@ public interface PostHogInterface : PostHogCoreInterface { @PostHogInternal public fun getConfig(): T? + + /** + * For wrapper SDKs only (Flutter, React Native); apps use [capture] and [captureAi]. + * + * Builds the event that [capture] (or [captureAi] when [ai] is true) would send: the same + * checks, SDK and registered properties, per-call values, session, screen and options, with a + * new uuid and timestamp. It doesn't run `beforeSend` and doesn't queue the event, so a wrapper + * can run its own hook on the full event, then pass the result to [sendBuiltEventForWrapper]. + * It changes no SDK state, so a wrapper can drop the event: the current screen, the person + * properties used for flags, person processing turned on by [userProperties], + * [userPropertiesSetOnce] or [groups], and the replay debug window are updated by + * [sendBuiltEventForWrapper]. That send uses the event name passed here to decide whether the + * replay debug bundle applies, even if the wrapper's hook renamed the event. + * + * Returns null when the SDK wouldn't capture the event: disabled, opted out, an ignored + * exception type, or a `$screen` event (not on the AI lane) without a non-blank `$screen_name`. Defaults to null. + * + * ```kotlin + * val event = PostHog.buildEventForWrapper("purchase", properties = mapOf("plan" to "pro")) + * ?: return + * PostHog.sendBuiltEventForWrapper(wrapperBeforeSend(event) ?: return) + * ``` + * + * @suppress + */ + @PostHogInternal + public fun buildEventForWrapper( + event: String, + distinctId: String? = null, + properties: Map? = null, + userProperties: Map? = null, + userPropertiesSetOnce: Map? = null, + groups: Map? = null, + options: Map? = null, + ai: Boolean = false, + timestamp: Date? = null, + ): PostHogEvent? = null + + /** + * For wrapper SDKs only (Flutter, React Native); apps use [capture] and [captureAi]. + * + * Sends an event from [buildEventForWrapper] without adding properties again: runs the native + * `beforeSend` chain, then queues it on the analytics lane, or the AI lane when [ai] is true. + * The event keeps its uuid and timestamp. Legacy option properties are moved into options when + * the event is sent, as for [capture]. + * Surveys and session replay event triggers see [event] as passed in, after the wrapper's hook. + * Like [capture], it updates the person properties used for flags from `$set` and `$set_once`, + * caches the `$screen_name` of an event built and sent as `$screen` as the current screen, turns person processing on + * when the build had user properties or groups, and may add the replay debug values snapshotted + * at build that the event lacks. Keys the wrapper's hook removed aren't added back. + * + * Person processing and the person properties for flags are skipped when `reset()` or + * `identify()` changed the user since the build. The event is dropped when this instance didn't + * build it, when `setup()` or `close()` ran since the build, or when it was already sent. + * + * Returns the event's uuid once it's queued, or null when it's dropped. Defaults to null. + * + * @suppress + */ + @PostHogInternal + public fun sendBuiltEventForWrapper( + event: PostHogEvent, + ai: Boolean = false, + ): UUID? = null } diff --git a/posthog/src/main/java/com/posthog/PostHogStateless.kt b/posthog/src/main/java/com/posthog/PostHogStateless.kt index bd6505876..1d54edb9b 100644 --- a/posthog/src/main/java/com/posthog/PostHogStateless.kt +++ b/posthog/src/main/java/com/posthog/PostHogStateless.kt @@ -14,10 +14,15 @@ import com.posthog.internal.PostHogQueueInterface import com.posthog.internal.PostHogThreadFactory import com.posthog.internal.errortracking.PostHogThrowable import com.posthog.internal.errortracking.ThrowableCoercer +import com.posthog.vendor.uuid.TimeBasedEpochGenerator import java.util.Date +import java.util.IdentityHashMap +import java.util.SortedMap +import java.util.TreeMap import java.util.UUID import java.util.concurrent.ExecutorService import java.util.concurrent.Executors +import java.util.concurrent.atomic.AtomicBoolean public open class PostHogStateless protected constructor( private val queueExecutor: ExecutorService = @@ -34,6 +39,7 @@ public open class PostHogStateless protected constructor( protected val setupLock: Any = Any() protected val optOutLock: Any = Any() + private val warnedEmptyEventName = AtomicBoolean(false) private var featureFlagsCalled: PostHogFeatureFlagCalledCache? = null // Read on the capture path from any caller thread without setupLock. @@ -59,12 +65,20 @@ public open class PostHogStateless protected constructor( if (config.logger is PostHogNoOpLogger) PostHogPrintLogger(config) else config.logger if (config.projectToken.isEmpty()) { - config.logger.log( + config.logger.logWarning( "PostHog SDK is disabled because the project token is required and was empty after trimming whitespace.", ) return } + if (config.projectToken.startsWith("phx_")) { + config.logger.logWarning( + "PostHog SDK is disabled because the project token is a personal API key (phx_...), " + + "use your project token (phc_...).", + ) + return + } + if (!projectTokens.add(config.projectToken)) { config.logger.log("Project token: ${config.projectToken} already has a PostHog instance.") } @@ -207,13 +221,39 @@ public open class PostHogStateless protected constructor( props.putAll(it) } + val currentGroups = props["\$groups"] as? Map<*, *> properties?.let { props.putAll(it) } + putTypedValuesOverCaller(props, properties, userProperties, userPropertiesSetOnce, groups.takeIf { appendGroups }, currentGroups) return props } + /** + * A typed per-call value wins key by key over the same map in the caller's [properties]: + * `userProperties` over `$set`, `userPropertiesSetOnce` over `$set_once` and `groups` over `$groups`. + * A caller `$groups` adds to [currentGroups] (the stored and per-call groups) instead of replacing them. + */ + internal fun putTypedValuesOverCaller( + props: MutableMap, + properties: Map?, + userProperties: Map?, + userPropertiesSetOnce: Map?, + groups: Map?, + currentGroups: Map<*, *>? = null, + ) { + for ((key, typed) in listOf("\$set" to userProperties, "\$set_once" to userPropertiesSetOnce, "\$groups" to groups)) { + val caller = properties?.get(key) as? Map<*, *> ?: continue + val merged = LinkedHashMap() + if (key == "\$groups") currentGroups?.let { merged.putAll(it) } + if (typed == null && merged.isEmpty()) continue + merged.putAll(caller) + typed?.let { merged.putAll(it) } + props[key] = merged + } + } + protected fun mergeGroups(givenGroups: Map?): Map? { val preferences = getPreferences() @@ -285,6 +325,9 @@ public open class PostHogStateless protected constructor( config?.logger?.log(message) return } + if (isEmptyNameDropped(postHogEvent)) { + return + } queue?.add(postHogEvent) } catch (e: Throwable) { @@ -297,35 +340,145 @@ public open class PostHogStateless protected constructor( distinctId: String, properties: MutableMap, timestamp: Date? = null, - ): PostHogEvent? { - val postHogEvent = - PostHogEvent( - event, - distinctId, - properties = properties, - timestamp = timestamp ?: config?.dateProvider?.currentDate() ?: Date(), - ) - var eventChecked: PostHogEvent = postHogEvent + options: MutableMap? = null, + uuid: UUID? = null, + ): PostHogEvent? = runBeforeSend(newEvent(event, distinctId, properties, timestamp, options, uuid), uuid) + + /** + * Creates the event, without running `beforeSend`. A null [timestamp] means now, and a null + * [uuid] gets a new UUID v7. + */ + internal fun newEvent( + event: String, + distinctId: String, + properties: MutableMap, + timestamp: Date? = null, + options: MutableMap? = null, + uuid: UUID? = null, + ): PostHogEvent = + PostHogEvent( + event, + distinctId, + properties = properties, + timestamp = timestamp ?: config?.dateProvider?.currentDate() ?: Date(), + uuid = uuid ?: TimeBasedEpochGenerator.generate(), + ).also { it.options = options } + /** + * Runs the `beforeSend` chain on [postHogEvent]. Returns null when a hook drops the event or + * throws. When [uuid] is given, the result keeps it. + */ + internal fun runBeforeSend( + postHogEvent: PostHogEvent, + uuid: UUID?, + ): PostHogEvent? { val beforeSendList = config?.beforeSendList ?: emptyList() + // Hooks get their own nested values, so an edit never reaches the caller's objects. + var eventChecked: PostHogEvent = if (beforeSendList.isEmpty()) postHogEvent else copyForHooks(postHogEvent) + for (beforeSend in beforeSendList) { try { val result = beforeSend.run(eventChecked) if (result == null) { - config?.logger?.log("Event $event was rejected in beforeSend function") + config?.logger?.log("Event ${postHogEvent.event} was rejected in beforeSend function") return null } + // copy() and the constructor don't carry options, so a new event keeps the ones + // the hook was given unless it sets its own. + if (result !== eventChecked && result.options == null) { + result.options = eventChecked.options + } eventChecked = result } catch (e: Throwable) { - config?.logger?.log("Error in beforeSend function: $e") + // The type only: the message can hold the values the hook was redacting. + config?.logger?.log("Dropping event '${eventChecked.event}': beforeSend threw ${e.javaClass.name}.") return null } } + // A given uuid is this capture's identity: beforeSend can return an event kept from an + // earlier call, and a batch must never repeat a uuid. + if (uuid != null && eventChecked.uuid != uuid) { + val options = eventChecked.options + eventChecked = eventChecked.copy(uuid = uuid).also { it.options = options } + } + return eventChecked } + @Suppress("UNCHECKED_CAST") + private fun copyForHooks(event: PostHogEvent): PostHogEvent { + val copies = IdentityHashMap() + return event.copy( + properties = event.properties?.let { copyContainers(it, copies) as MutableMap }, + ).also { it.options = event.options?.let { copyContainers(it, copies) as MutableMap } } + } + + /** [copies] keeps a cycle a cycle, so a hook can still remove it. */ + private fun copyContainers( + value: Any?, + copies: IdentityHashMap, + ): Any? { + if (value == null) return null + copies[value]?.let { return it } + return when (value) { + is Map<*, *> -> { + // A sorted map keeps its comparator, so a hook's lookups still match the same keys. + @Suppress("UNCHECKED_CAST") + val copy: MutableMap = + if (value is SortedMap<*, *>) TreeMap(value.comparator() as Comparator?) else LinkedHashMap(value.size) + copies[value] = copy + value.forEach { (key, item) -> copy[key] = copyContainers(item, copies) } + copy + } + is List<*> -> { + val copy = ArrayList(value.size) + copies[value] = copy + value.forEach { copy.add(copyContainers(it, copies)) } + copy + } + is Array<*> -> copyArray(value, copies) + is BooleanArray, is ByteArray, is CharArray, is ShortArray, is IntArray, is LongArray, is FloatArray, is DoubleArray -> { + val length = java.lang.reflect.Array.getLength(value) + val copy = java.lang.reflect.Array.newInstance(value.javaClass.componentType, length) + System.arraycopy(value, 0, copy, 0, length) + copies[value] = copy + copy + } + else -> value + } + } + + /** Keeps the array's runtime type for hooks that cast it. An element whose copy doesn't fit that type stays as is. */ + private fun copyArray( + array: Array<*>, + copies: IdentityHashMap, + ): Any { + val componentType = array.javaClass.componentType + val copy = java.lang.reflect.Array.newInstance(componentType, array.size) + copies[array] = copy + array.forEachIndexed { index, item -> + val itemCopy = copyContainers(item, copies) + java.lang.reflect.Array.set(copy, index, if (componentType.isInstance(itemCopy)) itemCopy else item) + } + return copy + } + + /** + * Capture drops an event with an empty name, so the SDK drops it before queueing, after + * beforeSend too. Logs only the first drop, with no event name. + */ + internal fun isEmptyNameDropped(event: PostHogEvent): Boolean { + if (event.event.isNotEmpty()) { + return false + } + if (warnedEmptyEventName.compareAndSet(false, true)) { + config?.logger?.log("Dropping an event with an empty name.") + } + return true + } + public override fun optIn() { if (!isEnabled()) { return @@ -787,6 +940,10 @@ public open class PostHogStateless protected constructor( "locally_evaluated", "\$groups", "\$process_person_profile", + // Legacy option properties, e.g. registered as super properties, so they still become options. + "\$cookieless_mode", + "\$ignore_sent_at", + "\$product_tour_id", "\$session_id", "\$window_id", "\$lib", diff --git a/posthog/src/main/java/com/posthog/PostHogStatelessInterface.kt b/posthog/src/main/java/com/posthog/PostHogStatelessInterface.kt index 98769e366..eb409b9ce 100644 --- a/posthog/src/main/java/com/posthog/PostHogStatelessInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogStatelessInterface.kt @@ -6,6 +6,19 @@ import java.util.Date * The Stateless PostHog SDK entry point */ public interface PostHogStatelessInterface : PostHogCoreInterface { + /** + * Identifies the user + * Docs https://posthog.com/docs/product-analytics/identify + * @param distinctId the distinctId + * @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 + */ + public fun identify( + distinctId: String, + userProperties: Map? = null, + userPropertiesSetOnce: Map? = null, + ) + /** * Captures events * @param event the event name diff --git a/posthog/src/main/java/com/posthog/internal/EndpointSpec.kt b/posthog/src/main/java/com/posthog/internal/EndpointSpec.kt index 4ed7bcf48..a628c87e0 100644 --- a/posthog/src/main/java/com/posthog/internal/EndpointSpec.kt +++ b/posthog/src/main/java/com/posthog/internal/EndpointSpec.kt @@ -9,9 +9,21 @@ import java.io.OutputStream /** * Per-endpoint specification consumed by [PostHogQueue]. Carries - * everything that differs between PostHog endpoints (`/batch`, `/snapshot`, - * and any future endpoint): the codec, the send call, the retry policy, - * and the per-endpoint runtime knobs. + * everything that differs between PostHog endpoints (`/i/v1/analytics/events`, + * `/snapshot`, and any future endpoint): the codec, the send call, the retry + * policy, and the per-endpoint runtime knobs. + * + * `send` returns a [SendResult] naming the [recordId]s the server asked to + * retry; an empty set means every record is done (delivered or dropped). + * Endpoints without per-record results return an empty result and leave + * [recordId] null. + * + * The byte limits are measured on the stored record files. [maxBatchBytes] is + * a soft limit on one request: a record that doesn't fit starts the next + * request, a record larger than the limit goes alone, and the queue flushes as + * soon as that many bytes are queued. [maxQueueBytes] is a FIFO limit on the + * queued files on top of [maxQueueSize]; the newest record is always kept. + * Null means no limit. * * The queue itself stays record-type-agnostic; everything that varies * between endpoints lives here. @@ -27,10 +39,13 @@ public class EndpointSpec internal constructor( internal val encode: (Record, OutputStream) -> Unit, internal val decode: (InputStream) -> Record?, internal val describe: (Record) -> String, - internal val send: (List) -> Unit, + internal val send: (List) -> SendResult, internal val isRetriableStatusCode: (Int) -> Boolean, internal val isFatalRecord: (Record) -> Boolean = { false }, internal val canBatchTogether: ((Record, Record) -> Boolean)? = null, + internal val recordId: ((Record) -> String?)? = null, + internal val maxBatchBytes: Long? = null, + internal val maxQueueBytes: Long? = null, ) { public companion object { @JvmStatic @@ -53,9 +68,45 @@ public class EndpointSpec internal constructor( config.serializer.deserialize(stream.reader().buffered()) }, describe = { event -> "Event ${event.event}" }, - send = { events -> api.batch(events) }, - isRetriableStatusCode = ::isEventsRetriableStatusCode, + send = { events -> api.captureV1(events) }, + isRetriableStatusCode = ::isCaptureV1RetriableStatusCode, isFatalRecord = { it.isFatalExceptionEvent() }, + recordId = { event -> event.uuid?.toString() }, + maxBatchBytes = CAPTURE_V1_MAX_BATCH_BYTES, + ) + + /** + * Returns the [EndpointSpec] for the capture v1 AI endpoint (`/i/v1/ai/events`), used by + * `captureAi`. Same codec, results and retry policy as [batch], on its own queue: AI events + * can be megabytes, so the queue is capped by bytes as well as count, and an event over + * [PostHogConfig.captureAiMaxEventBytes] is dropped when queued. + */ + @JvmStatic + public fun ai( + config: PostHogConfig, + api: PostHogApi, + storagePrefix: String?, + ): EndpointSpec = + EndpointSpec( + recordsLabel = "AI events", + storagePrefix = storagePrefix, + initialCap = { it.maxBatchSize }, + initialFlushAt = { it.flushAt }, + maxQueueSize = { it.effectiveCaptureAiMaxQueueSize }, + flushIntervalSeconds = { it.flushIntervalSeconds }, + encode = { event, stream -> + config.serializer.serialize(event, stream.writer().buffered()) + }, + decode = { stream -> + config.serializer.deserialize(stream.reader().buffered()) + }, + // Name only: AI properties can hold prompts and media. + describe = { event -> "AI event ${event.event}" }, + send = { events -> api.captureAi(events) }, + isRetriableStatusCode = ::isCaptureV1RetriableStatusCode, + recordId = { event -> event.uuid?.toString() }, + maxBatchBytes = CAPTURE_V1_MAX_BATCH_BYTES, + maxQueueBytes = AI_MAX_QUEUE_BYTES, ) @JvmStatic @@ -83,8 +134,11 @@ public class EndpointSpec internal constructor( first.distinctId == next.distinctId && (first.properties?.get("\$session_id") as? String) == (next.properties?.get("\$session_id") as? String) }, - send = { events -> api.snapshot(events) }, - isRetriableStatusCode = ::isEventsRetriableStatusCode, + send = { events -> + api.snapshot(events) + SendResult() + }, + isRetriableStatusCode = ::isSnapshotRetriableStatusCode, isFatalRecord = { it.isFatalExceptionEvent() }, ) @@ -119,18 +173,101 @@ public class EndpointSpec internal constructor( map?.let { PostHogLogRecord.fromStorageMap(it) } }, describe = { _ -> "log" }, - send = { records -> api.sendLogs(records, resourceAttrs) }, + send = { records -> + api.sendLogs(records, resourceAttrs) + SendResult() + }, isRetriableStatusCode = ::isLogsRetriableStatusCode, ) } } } -internal val DEFAULT_EVENTS_RETRYABLE_STATUS_CODES: Set = setOf(408, 429, 500, 502, 503, 504) +/** + * What an endpoint's `send` reports back to the queue: the record ids the + * server asked to retry, empty when every record is done, and the + * `Retry-After` the server sent with that answer. + */ +internal class SendResult( + val retryIds: Set = emptySet(), + val retryAfterSeconds: Int? = null, +) + +/** + * Capture v1 retry policy: 404, 408, 429 and the listed 5xx. A 404 usually means a misconfigured + * proxy and a 429 an overloaded ingress, so neither drops events. Everything else, including 3xx, + * is terminal; 413 is handled by the queue's batch halving. + */ +internal fun isCaptureV1RetriableStatusCode(code: Int): Boolean = code in setOf(404, 408, 429, 500, 502, 503, 504) + +/** Soft request size for the capture v1 analytics and AI endpoints, well under their body limits. */ +internal const val CAPTURE_V1_MAX_BATCH_BYTES: Long = 5L * 1024 * 1024 + +/** Disk budget for queued AI events; the oldest are dropped first. */ +internal const val AI_MAX_QUEUE_BYTES: Long = 50L * 1024 * 1024 + +/** [PostHogConfig.captureAiMaxQueueSize], or its default when it isn't positive. */ +internal val PostHogConfig.effectiveCaptureAiMaxQueueSize: Int + get() = if (captureAiMaxQueueSize > 0) captureAiMaxQueueSize else PostHogConfig.DEFAULT_CAPTURE_AI_MAX_QUEUE_SIZE + +/** [PostHogConfig.captureAiTimeout], or its default when it isn't positive. */ +internal val PostHogConfig.effectiveCaptureAiTimeoutSeconds: Int + get() = if (captureAiTimeout > 0) captureAiTimeout else PostHogConfig.DEFAULT_CAPTURE_AI_TIMEOUT_SECONDS + +/** Thrown by [serializedSize]'s counter to stop serializing once the count passes its bound. */ +private object SerializedSizeExceeded : RuntimeException() { + override fun fillInStackTrace(): Throwable = this +} + +/** + * Bytes [event] takes serialized as the queue stores it, before any [PostHogConfig.encryption]. + * Counted as it's written, so the event isn't held in memory a second time. Stops writing at + * [stopAfter] + 1, though the serializer still builds the whole properties JSON tree first. + */ +internal fun PostHogConfig.serializedSize( + event: PostHogEvent, + stopAfter: Long = Long.MAX_VALUE, +): Long { + var count = 0L + val counter = + object : OutputStream() { + override fun write(b: Int) { + count++ + if (count > stopAfter) throw SerializedSizeExceeded + } + + override fun write( + b: ByteArray, + off: Int, + len: Int, + ) { + count += len + if (count > stopAfter) throw SerializedSizeExceeded + } + } + try { + serializer.serialize(event, counter.writer().buffered()) + } catch (e: SerializedSizeExceeded) { + return stopAfter + 1 + } + return count +} + +/** + * Size limit for a serialized AI event, before any [PostHogConfig.encryption]: [PostHogConfig.captureAiMaxEventBytes], + * capped at its default (PostHog's 8 MiB properties limit plus 64 KiB for the rest of the event). + */ +internal val PostHogConfig.captureAiMaxStoredEventBytes: Long + get() { + val limit = PostHogConfig.DEFAULT_CAPTURE_AI_MAX_EVENT_BYTES + return (if (captureAiMaxEventBytes > 0) minOf(captureAiMaxEventBytes, limit) else limit).toLong() + } -internal fun isEventsRetriableStatusCode(code: Int): Boolean = code in DEFAULT_EVENTS_RETRYABLE_STATUS_CODES +/** `/snapshot` (replay) retry policy: 408, 429, the listed 5xx, plus 3xx redirects. */ +internal fun isSnapshotRetriableStatusCode(code: Int): Boolean = code in setOf(408, 429, 500, 502, 503, 504) || code in 300..399 -internal fun isLogsRetriableStatusCode(code: Int): Boolean = code == 408 || code == 429 || code in 500..599 +/** `/i/v1/logs` retry policy: 408, 429, every 5xx, plus 3xx redirects. */ +internal fun isLogsRetriableStatusCode(code: Int): Boolean = code == 408 || code == 429 || code in 300..399 || code in 500..599 /** * Captures the resource attributes for the logs endpoint at SDK setup. diff --git a/posthog/src/main/java/com/posthog/internal/GsonSafeMapSerializer.kt b/posthog/src/main/java/com/posthog/internal/GsonSafeMapSerializer.kt index 103f6d222..7ad5b9f52 100644 --- a/posthog/src/main/java/com/posthog/internal/GsonSafeMapSerializer.kt +++ b/posthog/src/main/java/com/posthog/internal/GsonSafeMapSerializer.kt @@ -28,7 +28,17 @@ internal class GsonSafeMapSerializer(private val config: PostHogConfig) : JsonSe ): JsonElement { val jsonObject = JsonObject() - src?.forEach { (key, srcValue) -> + // A nested map can have any key type at runtime, whatever this signature says. + (src as Map<*, *>?)?.forEach { (rawKey, srcValue) -> + val key = + jsonKey(rawKey) ?: run { + // the key's type only: keys can hold user content + config.logger.log( + "Property key of type ${rawKey?.javaClass?.name} cannot be serialized to JSON. " + + "This property will be ignored.", + ) + return@forEach + } val serialized = safeSerializeValue(srcValue, key, context) if (serialized != null) { jsonObject.add(key, serialized) @@ -38,6 +48,16 @@ internal class GsonSafeMapSerializer(private val config: PostHogConfig) : JsonSe return jsonObject } + /** The JSON name for [key]: scalars are converted, and any other key has none. */ + private fun jsonKey(key: Any?): String? { + return when (key) { + null -> "null" + is String -> key + is Number, is Boolean -> key.toString() + else -> null + } + } + /** * Recursively serializes a value, handling nested maps and lists to ensure * only unserializable leaf values are dropped. @@ -59,9 +79,10 @@ internal class GsonSafeMapSerializer(private val config: PostHogConfig) : JsonSe try { config.serializer.gson.toJsonTree(targetValue) } catch (e: Throwable) { + // the value's type only: properties can hold prompts and other user content config.logger.log( - "Property '$key' with value '$targetValue' cannot be serialized to JSON: $e. " + - "This property will be ignored.", + "Property '$key' of type ${targetValue.javaClass.name} cannot be serialized to JSON " + + "(${e.javaClass.simpleName}). This property will be ignored.", ) null } diff --git a/posthog/src/main/java/com/posthog/internal/GzipRequestInterceptor.kt b/posthog/src/main/java/com/posthog/internal/GzipRequestInterceptor.kt index a84cdff8d..4c47a0022 100644 --- a/posthog/src/main/java/com/posthog/internal/GzipRequestInterceptor.kt +++ b/posthog/src/main/java/com/posthog/internal/GzipRequestInterceptor.kt @@ -37,74 +37,81 @@ import java.io.IOException /** * This interceptor compresses the HTTP request body. Many webservers can't handle this! * @property config The Config + * @property compression The setting that decides whether to compress, [PostHogConfig.compression] + * by default; the AI capture client reads [PostHogConfig.captureAiCompression] instead */ @PostHogInternal -public class GzipRequestInterceptor(private val config: PostHogConfig) : Interceptor { - @Throws(IOException::class) - override fun intercept(chain: Interceptor.Chain): Response { - val originalRequest = chain.request() - val body = originalRequest.body +public class GzipRequestInterceptor + @JvmOverloads + constructor( + private val config: PostHogConfig, + private val compression: () -> PostHogCompression = { config.compression }, + ) : Interceptor { + @Throws(IOException::class) + override fun intercept(chain: Interceptor.Chain): Response { + val originalRequest = chain.request() + val body = originalRequest.body - return if (config.compression != PostHogCompression.GZIP || - body == null || - originalRequest.header("Content-Encoding") != null || - body is MultipartBody - ) { - chain.proceed(originalRequest) - } else { - val compressedRequest = - try { - originalRequest.newBuilder() - .header("Content-Encoding", "gzip") - .method(originalRequest.method, forceContentLength(gzip(body))) - .build() - } catch (e: Throwable) { - config.logger.log("Failed to gzip the request body: $e.") + return if (compression() != PostHogCompression.GZIP || + body == null || + originalRequest.header("Content-Encoding") != null || + body is MultipartBody + ) { + chain.proceed(originalRequest) + } else { + val compressedRequest = + try { + originalRequest.newBuilder() + .header("Content-Encoding", "gzip") + .method(originalRequest.method, forceContentLength(gzip(body))) + .build() + } catch (e: Throwable) { + config.logger.log("Failed to gzip the request body: $e.") - originalRequest - } - chain.proceed(compressedRequest) + originalRequest + } + chain.proceed(compressedRequest) + } } - } - private fun gzip(body: RequestBody): RequestBody { - return object : RequestBody() { - override fun contentType(): MediaType? { - return body.contentType() - } + private fun gzip(body: RequestBody): RequestBody { + return object : RequestBody() { + override fun contentType(): MediaType? { + return body.contentType() + } - override fun contentLength(): Long { - return -1 // We don't know the compressed length in advance! - } + override fun contentLength(): Long { + return -1 // We don't know the compressed length in advance! + } - @Throws(IOException::class) - override fun writeTo(sink: BufferedSink) { - val gzipSink = GzipSink(sink).buffer() - body.writeTo(gzipSink) - gzipSink.close() + @Throws(IOException::class) + override fun writeTo(sink: BufferedSink) { + val gzipSink = GzipSink(sink).buffer() + body.writeTo(gzipSink) + gzipSink.close() + } } } - } - // https://github.com/square/okhttp/issues/350 - @Throws(IOException::class) - private fun forceContentLength(body: RequestBody): RequestBody { - val buffer = Buffer() - body.writeTo(buffer) + // https://github.com/square/okhttp/issues/350 + @Throws(IOException::class) + private fun forceContentLength(body: RequestBody): RequestBody { + val buffer = Buffer() + body.writeTo(buffer) - return object : RequestBody() { - override fun contentType(): MediaType? { - return body.contentType() - } + return object : RequestBody() { + override fun contentType(): MediaType? { + return body.contentType() + } - override fun contentLength(): Long { - return buffer.size - } + override fun contentLength(): Long { + return buffer.size + } - @Throws(IOException::class) - override fun writeTo(sink: BufferedSink) { - sink.write(buffer.snapshot()) + @Throws(IOException::class) + override fun writeTo(sink: BufferedSink) { + sink.write(buffer.snapshot()) + } } } } -} diff --git a/posthog/src/main/java/com/posthog/internal/PostHogApi.kt b/posthog/src/main/java/com/posthog/internal/PostHogApi.kt index c3cdbec6d..fed55cb26 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogApi.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogApi.kt @@ -11,6 +11,11 @@ import com.posthog.PostHogEvent import com.posthog.PostHogInternal import com.posthog.internal.logs.PostHogLogsOTLP import com.posthog.logs.PostHogLogRecord +import com.posthog.vendor.uuid.TimeBasedEpochGenerator +import okhttp3.HttpUrl +import okhttp3.HttpUrl.Companion.toHttpUrlOrNull +import okhttp3.Interceptor +import okhttp3.MediaType import okhttp3.MediaType.Companion.toMediaType import okhttp3.OkHttpClient import okhttp3.Request @@ -25,6 +30,8 @@ import java.io.OutputStream import java.net.SocketException import java.net.SocketTimeoutException import java.net.UnknownHostException +import java.util.concurrent.TimeUnit +import java.util.concurrent.atomic.AtomicBoolean import javax.net.ssl.SSLException /** @@ -37,9 +44,15 @@ public class PostHogApi( ) { private companion object { private const val APP_JSON_UTF_8 = "application/json; charset=utf-8" + private const val APP_JSON = "application/json" private const val FLAGS_INITIAL_RETRY_DELAY_MS = 300L private const val FLAGS_MAX_RETRY_DELAY_MS = 30_000L private const val ERROR_BODY_PEEK_BYTES = 2048L + private const val CAPTURE_V1_ANALYTICS_PATH = "/i/v1/analytics/events" + private const val CAPTURE_V1_AI_PATH = "/i/v1/ai/events" + private const val CAPTURE_V1_MAX_REDIRECTS = 5 + private const val CAPTURE_V1_MAX_PENDING_RETRIES = 16 + private const val CAPTURE_V1_MAX_RESULTS_BYTES = 1024L * 1024L } private val mediaType by lazy { @@ -51,6 +64,21 @@ public class PostHogApi( } } + // A 404 keeps the events queued, so the warning is printed once instead of on every retry. + private val warnedCaptureNotFound = AtomicBoolean(false) + + private val captureMediaType by lazy { + try { + APP_JSON.toMediaType() + } catch (ignored: Throwable) { + null + } + } + + // Caps the whole results read, since a body that trickles bytes never hits the read timeout + // and would hold the queue thread. Internal so tests can shorten it. + internal var captureV1ResultsReadDeadlineMs: Long = 10_000L + private val client: OkHttpClient = config.httpClient ?: OkHttpClient.Builder() .proxy(config.proxy) @@ -65,6 +93,68 @@ public class PostHogApi( .build() } + // Capture v1 decides its own redirects (see captureV1): OkHttp would follow any 3xx, drop the + // Authorization header on a cross-host hop and turn a 302 into a body-less GET. The queue owns + // retries too: an OkHttp resend would repeat PostHog-Attempt and PostHog-Request-Timestamp. + // OkHttp also resends a 503 with `Retry-After: 0` whatever retryOnConnectionFailure says, so + // that header is dropped below its retry layer; the queue waits the same with or without it. + private val captureClient: OkHttpClient by lazy { + client.newBuilder() + .followRedirects(false) + .followSslRedirects(false) + .retryOnConnectionFailure(false) + .addNetworkInterceptor( + object : Interceptor { + override fun intercept(chain: Interceptor.Chain): Response { + val response = chain.proceed(chain.request()) + return if (response.code == 503 && response.header("Retry-After")?.toIntOrNull() == 0) { + response.newBuilder().removeHeader("Retry-After").build() + } else { + response + } + } + }, + ) + .build() + } + + // AI batches can be several MB, so they get their own timeout and compression setting. + private val aiCaptureClient: OkHttpClient by lazy { + val timeoutSeconds = config.effectiveCaptureAiTimeoutSeconds.toLong() + val builder = + // Idle timeouts only: a multi-MB upload that is still making progress on a slow link + // must not be cut off by a whole-call deadline. + captureClient.newBuilder() + .readTimeout(timeoutSeconds, TimeUnit.SECONDS) + .writeTimeout(timeoutSeconds, TimeUnit.SECONDS) + val interceptors = builder.interceptors() + for (index in interceptors.indices) { + if (interceptors[index] is GzipRequestInterceptor) { + interceptors[index] = GzipRequestInterceptor(config) { config.captureAiCompression } + } + } + builder.build() + } + + private val captureV1Lock = Any() + + // The identity of each capture v1 request whose events are still to be retried, keyed by endpoint + // path and uuid set, so a send of other events in between keeps it. Holds the most recent + // CAPTURE_V1_MAX_PENDING_RETRIES: an entry stays when the queue drops its events instead of + // retrying them. In memory only: a new request id after an app restart is fine, the server only logs it. + // A plain map trimmed by hand: a LinkedHashMap subclass gets bridges to Java 8 Map methods missing on API 23. + private val captureV1PendingRetry = LinkedHashMap>, CaptureV1RequestIdentity>() + + private fun putCaptureV1PendingRetry( + key: Pair>, + identity: CaptureV1RequestIdentity, + ) { + captureV1PendingRetry[key] = identity + if (captureV1PendingRetry.size > CAPTURE_V1_MAX_PENDING_RETRIES) { + captureV1PendingRetry.remove(captureV1PendingRetry.keys.first()) + } + } + private val theHost: String get() { return if (config.host.endsWith("/")) config.host.substring(0, config.host.length - 1) else config.host @@ -87,6 +177,228 @@ public class PostHogApi( executeNoBody(request) } + /** + * Sends analytics events to capture v1 (`POST /i/v1/analytics/events`). + * + * Returns the uuids of the events the 2xx response asked to retry, with the `Retry-After` it + * sent; every other event in [events] was delivered or dropped and must not be sent again. + * + * A 2xx whose body can't be read as `{"results": {...}}`, including a transfer that failed after + * the status arrived, is a terminal failure of the whole batch: it throws a [PostHogApiError] + * with that 2xx status, which the queue doesn't retry. + * + * Only a 307 or 308 to the origin of [PostHogConfig.host] is followed, at most 5 times, with + * the same body and headers; any other redirect is a terminal [PostHogApiError]. + * + * Throws [PostHogApiError] for a non-2xx status or unreadable results, and [IOException] for a + * transport failure before the status. + */ + @Throws(PostHogApiError::class, IOException::class) + internal fun captureV1(events: List): SendResult = postCaptureV1(CAPTURE_V1_ANALYTICS_PATH, events, captureClient) + + /** + * Sends AI events to the capture v1 AI endpoint (`POST /i/v1/ai/events`). Same wire format, + * per-event results, redirect rule and retry identity (kept per path) as [captureV1], with + * [PostHogConfig.captureAiTimeout] and [PostHogConfig.captureAiCompression]. + */ + @Throws(PostHogApiError::class, IOException::class) + internal fun captureAi(events: List): SendResult = postCaptureV1(CAPTURE_V1_AI_PATH, events, aiCaptureClient) + + @Throws(PostHogApiError::class, IOException::class) + private fun postCaptureV1( + path: String, + events: List, + client: OkHttpClient, + ): SendResult { + val uuids = events.mapNotNull { it.uuid?.toString() } + val identity = nextCaptureV1Identity(path, uuids.toSet()) + val body = + mapOf( + "created_at" to identity.createdAt, + "batch" to events.map { captureV1Json(it, config.logger) }, + ) + + val url = "$theHost$path" + var request = + makeRequest(url, contentType = captureMediaType) { + // Events hold user data, and AI events prompts and media, so the debug log names only the count. + config.logger.log("Request $url: ${events.size} events") + + config.serializer.serialize(body, it.bufferedWriter()) + }.newBuilder() + .header("Authorization", "Bearer ${config.projectToken}") + .header("PostHog-Sdk-Info", config.userAgent) + .header("PostHog-Attempt", identity.attempt.toString()) + .header("PostHog-Request-Id", identity.requestId) + .header("PostHog-Request-Timestamp", formatISO8601Date(config.dateProvider.currentDate())) + .build() + + var redirects = 0 + while (true) { + logRequestHeaders(request) + + client.newCall(request).execute().use { response -> + // The status only: the results name event uuids. + config.logger.log("Response ${response.request.url}: ${response.code}") + + if (response.code == 404 && warnedCaptureNotFound.compareAndSet(false, true)) { + // Warnings log even with debug off, so drop any credentials or query the host carries. + val safeUrl = + response.request.url.newBuilder() + .username("") + .password("") + .query(null) + .fragment(null) + .build() + config.logger.logWarning( + "$safeUrl returned 404. Events stay queued and are retried. " + + "If you use a reverse proxy or self-host PostHog, make sure it serves $path.", + ) + } + if (response.code != 307 && response.code != 308) { + return captureV1Result(response, path, events, identity) + } + + val target = response.header("Location")?.let { location -> request.url.resolve(location) } + if (redirects >= CAPTURE_V1_MAX_REDIRECTS || target == null || !isConfiguredOrigin(target)) { + config.logger.log("Capture did not follow a ${response.code} redirect.") + clearCaptureV1Retry(path, identity) + throw PostHogApiError(response.code, response.message, response.body, parseRetryAfter(response)) + } + // Same origin, so the body and every header are safe to resend. + request = request.newBuilder().url(target).build() + redirects++ + } + } + } + + /** + * Reuses the request id and `created_at` with the next attempt number when [uuids] is the set + * of events the previous request to [path] left to retry; otherwise starts a new request at + * attempt 1. The identity is kept until the outcome is known, so a transport failure or a + * retriable status resends the whole batch under it. + */ + private fun nextCaptureV1Identity( + path: String, + uuids: Set, + ): CaptureV1RequestIdentity { + synchronized(captureV1Lock) { + val pending = captureV1PendingRetry[path to uuids] + val identity = + if (pending != null) { + pending.copy(attempt = pending.attempt + 1) + } else { + CaptureV1RequestIdentity( + uuids = uuids, + requestId = TimeBasedEpochGenerator.generate().toString(), + attempt = 1, + createdAt = formatISO8601Date(config.dateProvider.currentDate()), + ) + } + putCaptureV1PendingRetry(path to uuids, identity) + return identity + } + } + + private fun clearCaptureV1Retry( + path: String, + identity: CaptureV1RequestIdentity, + ) { + synchronized(captureV1Lock) { + captureV1PendingRetry.remove(path to identity.uuids) + } + } + + /** + * Reads the per-event results of a 2xx and records which events, if any, the next request + * retries under the same identity. A non-2xx is thrown; a terminal one also drops the identity, + * as does a 2xx without readable results, which is thrown as a terminal failure. + */ + @Throws(PostHogApiError::class) + private fun captureV1Result( + response: Response, + path: String, + events: List, + identity: CaptureV1RequestIdentity, + ): SendResult { + if (!response.isSuccessful) { + if (!isCaptureV1RetriableStatusCode(response.code)) { + clearCaptureV1Retry(path, identity) + } + throw PostHogApiError(response.code, response.message, response.body, parseRetryAfter(response)) + } + + // Counts only: the body may name event uuids. + val results = readCaptureV1Results(response) + if (results == null) { + clearCaptureV1Retry(path, identity) + val message = "Capture returned ${response.code} without readable per-event results, dropping ${events.size} events." + config.logger.log(message) + throw PostHogApiError(response.code, message, null) + } + + val retryUuids = mutableSetOf() + // Drop counts by the server's `details` tag, an opaque string. + val droppedByDetails = sortedMapOf() + var duplicatesDropped = 0 + // Events missing from the results count as delivered. The uuids are read once, so a repeated + // uuid's later copies (`duplicates_dropped`) are counted, not given the kept copy's verdict. + for (uuid in events.mapNotNullTo(LinkedHashSet()) { it.uuid?.toString() }) { + val entry = results[uuid] as? Map<*, *> ?: continue + when (entry["result"]) { + "retry" -> retryUuids.add(uuid) + "drop" -> { + val details = (entry["details"] as? String)?.let(::cleanDropReason) ?: "no details" + droppedByDetails[details] = (droppedByDetails[details] ?: 0) + 1 + } + } + // Clamped to the batch size, so a malformed count can't overflow the sum. + duplicatesDropped += (entry["duplicates_dropped"] as? Number)?.toLong()?.coerceIn(0L, events.size.toLong())?.toInt() ?: 0 + } + + // Counts and reasons only: one line per batch, never per event. + val dropped = droppedByDetails.values.sum() + if (dropped > 0 || duplicatesDropped > 0 || retryUuids.isNotEmpty()) { + val reasons = + if (dropped > 0) { + droppedByDetails.entries + .sortedWith(compareByDescending> { it.value }.thenBy { it.key }) + .joinToString(", ", " (", ")") { "${it.key}: ${it.value}" } + } else { + "" + } + config.logger.log( + "Capture $path: $dropped dropped$reasons, $duplicatesDropped duplicate copies dropped, ${retryUuids.size} to retry.", + ) + } + + synchronized(captureV1Lock) { + captureV1PendingRetry.remove(path to identity.uuids) + if (retryUuids.isNotEmpty()) { + putCaptureV1PendingRetry(path to retryUuids, identity.copy(uuids = retryUuids)) + } + } + return SendResult(retryUuids, parseRetryAfter(response)) + } + + private fun readCaptureV1Results(response: Response): Map<*, *>? { + return try { + // Bounded: an oversized or endless body counts as unreadable instead of filling the heap. + val source = response.body?.source() ?: return null + source.timeout().deadline(captureV1ResultsReadDeadlineMs, TimeUnit.MILLISECONDS) + if (source.request(CAPTURE_V1_MAX_RESULTS_BYTES + 1)) return null + val body = source.buffer.readUtf8() + (config.serializer.deserializeString(body) as? Map<*, *>)?.get("results") as? Map<*, *> + } catch (e: Throwable) { + null + } + } + + private fun isConfiguredOrigin(url: HttpUrl): Boolean { + val host = config.host.toHttpUrlOrNull() ?: return false + return url.scheme == host.scheme && url.host.equals(host.host, ignoreCase = true) && url.port == host.port + } + @Throws(PostHogApiError::class, IOException::class) public fun snapshot(events: List) { events.forEach { @@ -213,9 +525,19 @@ public class PostHogApi( } } + /** A drop reason is server text: no control or line-break characters, 64 characters at most. */ + private fun cleanDropReason(details: String): String { + return details.filterNot { it.isISOControl() || it == '\u2028' || it == '\u2029' }.take(64) + } + + /** `Retry-After` in seconds, from delay-seconds or an HTTP-date. */ private fun parseRetryAfter(response: Response): Int? { return try { - response.header("Retry-After")?.toIntOrNull() + val value = response.header("Retry-After")?.trim() ?: return null + value.toIntOrNull() ?: response.headers.getDate("Retry-After")?.let { date -> + val millis = date.time - config.dateProvider.currentTimeMillis() + ((millis + 999) / 1000).coerceIn(0L, Int.MAX_VALUE.toLong()).toInt() + } } catch (e: Throwable) { null } @@ -224,11 +546,12 @@ public class PostHogApi( private fun makeRequest( url: String, method: String = "POST", + contentType: MediaType? = mediaType, serializer: (outputStream: OutputStream) -> Unit, ): Request { val requestBody = object : RequestBody() { - override fun contentType() = mediaType + override fun contentType() = contentType override fun writeTo(sink: BufferedSink) { sink.outputStream().use { @@ -521,3 +844,112 @@ public class PostHogApi( } } } + +/** + * Identity of a capture v1 request, kept so a retry of the same events reuses + * `PostHog-Request-Id` and `created_at` with an incremented `PostHog-Attempt`. + */ +internal class CaptureV1RequestIdentity( + val uuids: Set, + val requestId: String, + val attempt: Int, + val createdAt: String, +) { + fun copy( + uuids: Set = this.uuids, + attempt: Int = this.attempt, + ): CaptureV1RequestIdentity = CaptureV1RequestIdentity(uuids, requestId, attempt, createdAt) +} + +/** Legacy properties and the capture v1 option each one fills. */ +internal val LEGACY_OPTION_PROPERTIES: List> = + listOf( + "\$cookieless_mode" to "cookieless_mode", + "\$ignore_sent_at" to "disable_skew_correction", + "\$product_tour_id" to "product_tour_id", + "\$process_person_profile" to "process_person_profile", + ) + +/** + * Shapes a stored event for capture v1. `$session_id` and `$window_id` move to the event root, and + * `$lib`/`$lib_version` are dropped because the server reads them from `PostHog-Sdk-Info`. + * + * Legacy option properties are hoisted here, after `beforeSend`, so events queued by older versions + * are hoisted too. Each is always removed from properties and fills its option only when the option + * is missing or null. Values aren't coerced: the server validates them. + */ +internal fun captureV1Json( + event: PostHogEvent, + logger: PostHogLogger, +): Map { + val properties = LinkedHashMap(event.properties ?: emptyMap()) + properties.remove("\$lib") + properties.remove("\$lib_version") + + val options = LinkedHashMap(event.options ?: emptyMap()) + for ((property, option) in LEGACY_OPTION_PROPERTIES) { + if (!properties.containsKey(property)) continue + val legacy = properties.remove(property) + if (options[option] == null) { + options[option] = legacy + } + } + + val json = LinkedHashMap() + json["event"] = event.event + json["uuid"] = event.uuid?.toString() + json["distinct_id"] = event.distinctId + json["timestamp"] = formatISO8601Date(event.timestamp) + liftStringProperty("\$session_id", properties, logger)?.let { json["session_id"] = it } + liftStringProperty("\$window_id", properties, logger)?.let { json["window_id"] = it } + if (options.isNotEmpty()) { + json["options"] = options + } + json["properties"] = properties + return json +} + +/** + * Removes [key] from [properties] and returns its value when it's a string, including an empty one, + * which is sent unchanged. Capture rejects the whole request when a root `session_id` or `window_id` + * isn't a string, so any other value is dropped with a warning that names its JSON type, never the + * value. A null value counts as unset and is dropped without a warning. + */ +internal fun liftStringProperty( + key: String, + properties: MutableMap, + logger: PostHogLogger, +): String? { + if (!properties.containsKey(key)) return null + val value = properties.remove(key) ?: return null + if (value is String) return value + logger.log("dropping $key: a ${jsonTypeName(value)} value is not a string") + return null +} + +/** + * Whether capture reads [value] as a false flag option: `false`, a zero number, or a string such as + * `"false"`, `"no"`, `"off"` or `"0"`, ignoring case and surrounding spaces. + */ +internal fun isFalseOptionValue(value: Any?): Boolean { + return when (value) { + is Boolean -> !value + is Number -> value.toDouble() == 0.0 + is String -> { + val text = value.trim().lowercase() + text in setOf("false", "f", "no", "n", "off") || text.toDoubleOrNull() == 0.0 + } + else -> false + } +} + +private fun jsonTypeName(value: Any): String { + return when (value) { + is Boolean -> "bool" + is Number -> "number" + is String -> "string" + is Map<*, *> -> "object" + is Iterable<*>, is Array<*> -> "array" + else -> value.javaClass.simpleName + } +} diff --git a/posthog/src/main/java/com/posthog/internal/PostHogPushSubscriptionManager.kt b/posthog/src/main/java/com/posthog/internal/PostHogPushSubscriptionManager.kt index 5df1b9821..219a40368 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogPushSubscriptionManager.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogPushSubscriptionManager.kt @@ -250,7 +250,7 @@ internal class PostHogPushSubscriptionManager( return@executeSafely } // retryCount deliberately not reset: the exponential ladder persists across triggers, so - // repeated failures still exhaust maxRetries and halt for the session. + // repeated failures still exhaust pushNotificationSubscriptionMaxRetries and halt for the session. attempt(resetStateOnFold = false) } } @@ -644,7 +644,7 @@ internal class PostHogPushSubscriptionManager( } retryCount++ - if (retryCount > config.maxRetries) { + if (retryCount > config.pushNotificationSubscriptionMaxRetries) { config.logger.log( "Push subscription retries exhausted after $retryCount attempts; " + "will retry on next SDK startup.", diff --git a/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt b/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt index 8b07352c2..2273d8b33 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt @@ -10,10 +10,13 @@ import java.util.Timer import java.util.TimerTask import java.util.UUID import java.util.concurrent.ExecutorService +import java.util.concurrent.ThreadLocalRandom import java.util.concurrent.atomic.AtomicBoolean import kotlin.concurrent.schedule +import kotlin.math.max import kotlin.math.min import kotlin.math.pow +import kotlin.math.roundToLong /** * Generic file-backed queue. One implementation, multiple instances — @@ -28,14 +31,50 @@ public class PostHogQueue( ) : PostHogQueueInterface { private val deque: ArrayDeque = ArrayDeque() private val dequeLock = Any() + + // The files of the last request that failed or came back with records to retry. The next flush + // resends exactly these, so the request keeps its id and counts the attempt. Guarded by dequeLock. + private var retryFiles: List = emptyList() + + // Total size of the files in the deque, kept only for byte-limited endpoints. Guarded by dequeLock. + private val trackBytes = spec.maxBatchBytes != null || spec.maxQueueBytes != null + private var queuedBytes = 0L + + // The size each file was counted with, so a file deleted from the cache dir is still subtracted in full. + private val fileBytes = HashMap() + + // Records added by addMeasured and not yet taken by the executor to be written to disk, oldest + // first, with their sizes. Guarded by pendingLock. + private val pendingLock = Any() + private val pending: ArrayDeque> = ArrayDeque() + private var pendingBytes = 0L + + // Executor tasks queued to write pending records, never more than pending holds. Guarded by pendingLock. + private var pendingTasks = 0 private val timerLock = Any() - private var pausedUntil: Date? = null + + @PostHogVisibleForTesting + internal var pausedUntil: Date? = null + private set private var retryCount = 0 + + // The Retry-After of the last 2xx that kept some records for retry; read by executeWithRetry. + private var partialRetryAfterSeconds: Int? = null private val batchLimits = BatchLimits(cap = spec.initialCap(config).coerceAtLeast(1), flushAt = spec.initialFlushAt(config).coerceAtLeast(1)) private val initialRetryDelaySeconds = 1 private val maxRetryDelaySeconds = 30 + // Largest fraction a retry wait moves either way, so devices refused together don't all come back + // at the same moment. + private val retryJitter = 0.25 + + /** + * Source of the backoff jitter: a uniform value in `[0, 1)`. Tests replace it for fixed delays. + */ + @Volatile + internal var jitterUnit: () -> Double = { ThreadLocalRandom.current().nextDouble() } + @Volatile private var timer: Timer? = null @@ -76,8 +115,12 @@ public class PostHogQueue( os.use { theOutputStream -> spec.encode(record, theOutputStream) } - config.logger.log("Queued ${spec.describe(record)}: ${file.name}.") - + if (trackBytes) { + val size = file.length() + synchronized(dequeLock) { + countBytes(file, size) + } + } return true } catch (e: Throwable) { config.logger.log("${spec.describe(record)}: ${file.name} failed to parse: $e.") @@ -96,18 +139,62 @@ public class PostHogQueue( return true } + /** Removes [files] from the deque and subtracts the size they were counted with. */ + private fun removeFromDeque(files: Collection) { + synchronized(dequeLock) { + deque.removeAll(files) + files.forEach { uncountBytes(it) } + } + } + + // Must hold dequeLock. + private fun countBytes( + file: File, + size: Long, + ) { + if (!trackBytes) return + fileBytes[file] = size + queuedBytes += size + } + + // Must hold dequeLock. + private fun uncountBytes(file: File) { + queuedBytes -= fileBytes.remove(file) ?: 0L + } + + // Must hold dequeLock. + private fun resetBytes() { + fileBytes.clear() + queuedBytes = 0 + } + private fun removeRecordSync() { if (deque.size > spec.maxQueueSize(config).coerceAtLeast(1)) { try { val first: File synchronized(dequeLock) { first = deque.removeFirst() + uncountBytes(first) } first.deleteSafely(config) config.logger.log("Queue is full, the oldest ${spec.recordsLabel} ${first.name} is dropped.") } catch (ignored: NoSuchElementException) { } } + val maxQueueBytes = spec.maxQueueBytes ?: return + val evicted = mutableListOf() + synchronized(dequeLock) { + // The newest record is always kept, even when it's over the limit on its own. + while (queuedBytes > maxQueueBytes && deque.size > 1) { + val first = deque.removeFirst() + uncountBytes(first) + evicted.add(first) + } + } + if (evicted.isNotEmpty()) { + evicted.forEach { it.deleteSafely(config) } + config.logger.log("Queue is over $maxQueueBytes bytes, the oldest ${evicted.size} ${spec.recordsLabel} are dropped.") + } } /** @@ -151,6 +238,65 @@ public class PostHogQueue( } } + /** + * Adds [record], [bytes] long. While a slow send holds the executor, records wait in memory before + * they're written; once more than [EndpointSpec.maxQueueSize] records or [EndpointSpec.maxQueueBytes] + * wait, the oldest waiting ones are dropped, as the disk queue drops its oldest. The newest record + * is always kept. Returns false only when the executor no longer accepts work. + */ + internal fun addMeasured( + record: Record, + bytes: Long, + ): Boolean { + val maxQueueBytes = spec.maxQueueBytes + if (maxQueueBytes == null) { + add(record) + return true + } + val maxRecords = spec.maxQueueSize(config).coerceAtLeast(1) + val entry = record to bytes + var dropped = 0 + val accepted = + synchronized(pendingLock) { + pending.addLast(entry) + pendingBytes += bytes + while (pending.size > 1 && (pending.size > maxRecords || pendingBytes > maxQueueBytes)) { + pendingBytes -= pending.removeFirst().second + dropped++ + } + // A dropped record's task writes a newer one instead, so tasks never outnumber records. + if (pendingTasks >= pending.size) return@synchronized true + pendingTasks++ + // Submitted under the lock so tasks queue in the order their records were added, and a + // flush queued after this call returns runs after this record is written. + try { + // Each task writes the oldest waiting record. + executor.execute { + val next = + synchronized(pendingLock) { + pendingTasks-- + pending.removeFirstOrNull()?.also { pendingBytes -= it.second } + } + if (next != null) { + flushRecordSync(next.first) + } + } + true + } catch (e: Throwable) { + // RejectedExecutionException once the queue is shut down + pendingTasks-- + if (pending.remove(entry)) { + pendingBytes -= bytes + } + false + } + } + if (dropped > 0) { + config.logger.log("Too many ${spec.recordsLabel} are waiting to be written, the oldest $dropped are dropped.") + } + return accepted + } + private fun flushIfOverThreshold(isFatal: Boolean) { if (isAboveThreshold(batchLimits.flushAt)) { flushBatch(isFatal) @@ -158,13 +304,7 @@ public class PostHogQueue( } private fun isAboveThreshold(flushAt: Int): Boolean { - if (deque.size >= flushAt) { - return true - } else if (deque.size > 0) { - // only log if there are records in the queue - config.logger.log("Cannot flush the Queue yet, below the threshold: $flushAt") - } - return false + return deque.size >= flushAt || isAboveByteThreshold() } private fun canFlushBatch(): Boolean { @@ -176,12 +316,38 @@ public class PostHogQueue( return true } + /** A full request's worth of queued bytes flushes like [BatchLimits.flushAt] does. */ + private fun isAboveByteThreshold(): Boolean { + val maxBatchBytes = spec.maxBatchBytes ?: return false + return synchronized(dequeLock) { queuedBytes } >= maxBatchBytes + } + + /** + * The next FIFO window: at most [BatchLimits.cap] files and, for a byte-limited endpoint, about + * [EndpointSpec.maxBatchBytes]. The check runs before each file is added, so a file that doesn't + * fit starts the next window and a file over the limit goes alone. The files of a request to + * retry go again on their own first. + */ private fun takeFiles(): List { - val events: List synchronized(dequeLock) { - events = deque.take(batchLimits.cap) + val retry = retryFiles + retryFiles = emptyList() + // A file dropped since (queue full, clear) changes the request, so it starts over. + if (retry.isNotEmpty() && deque.containsAll(retry)) { + return retry + } + val maxBatchBytes = spec.maxBatchBytes ?: return deque.take(batchLimits.cap) + val files = mutableListOf() + var bytes = 0L + for (file in deque) { + if (files.size >= batchLimits.cap) break + val size = file.length() + if (files.isNotEmpty() && bytes + size > maxBatchBytes) break + files.add(file) + bytes += size + } + return files } - return events } private fun flushBatch(isFatal: Boolean) { @@ -195,16 +361,32 @@ public class PostHogQueue( return } + if (isFatal) { + // The process may exit after this send, so it takes a FIFO window that can include the + // fatal record instead of resending only the request waiting to be retried. + keepForRetry(emptyList()) + } + executeBatch() } - private fun executeWithRetry(block: () -> Unit) { + /** + * Runs [block], which reports whether the server kept some records for retry, and applies the + * retry state: a failure or a partial retry counts as one more consecutive failure and pauses + * the queue with backoff; a full success resets both. + */ + private fun executeWithRetry(block: () -> Boolean) { var retry = false var retryAfterSeconds: Int? = null try { - block() - retryCount = 0 - pausedUntil = null + retry = block() + if (retry) { + retryCount = (retryCount + 1).coerceAtMost(maxRetryDelaySeconds) + retryAfterSeconds = partialRetryAfterSeconds + } else { + retryCount = 0 + pausedUntil = null + } } catch (e: Throwable) { config.logger.log("Flushing failed: $e.") @@ -215,6 +397,7 @@ public class PostHogQueue( retryAfterSeconds = e.retryAfterSeconds } } finally { + partialRetryAfterSeconds = null calculateDelay(retry, retryAfterSeconds) isFlushing.set(false) @@ -236,15 +419,17 @@ public class PostHogQueue( file: File, throwable: Throwable? = null, ) { - synchronized(dequeLock) { - deque.remove(file) - } + removeFromDeque(listOf(file)) file.deleteSafely(config) config.logger.log("File: ${file.name} failed to parse: $throwable.") } + /** + * Sends one FIFO window of the queue. Returns true when a group was partially retried, so the + * caller stops this flush and the kept records wait for the backoff. + */ @Throws(PostHogApiError::class, IOException::class) - private fun batchRecords() { + private fun batchRecords(): Boolean { val files = takeFiles() val records = mutableListOf>() @@ -271,47 +456,85 @@ public class PostHogQueue( while (end < records.size && spec.canBatchTogether?.invoke(records[start].second, records[end].second) != false) { end++ } - sendRecords(records.subList(start, end)) + if (sendRecords(records.subList(start, end))) { + return true + } start = end } + return false } + /** + * Sends [batch] and removes the delivered records. Returns true when the server asked to retry + * some of them: those files stay queued and the rest are deleted. + */ @Throws(PostHogApiError::class, IOException::class) - private fun sendRecords(batch: List>) { + private fun sendRecords(batch: List>): Boolean { val files = batch.map { it.first } val records = batch.map { it.second } var deleteFiles = true + var retained = emptyList() try { if (records.isNotEmpty()) { config.logger.log("Flushing ${records.size} ${spec.recordsLabel}.") - spec.send(records) - - config.logger.log("Flushed ${records.size} ${spec.recordsLabel} successfully.") + val result = spec.send(records) + + val recordId = spec.recordId + if (result.retryIds.isNotEmpty() && recordId != null) { + retained = + batch.mapNotNull { (file, record) -> + val id = recordId(record) + if (id != null && id in result.retryIds) file else null + } + if (retained.isNotEmpty()) { + partialRetryAfterSeconds = result.retryAfterSeconds + keepForRetry(retained) + } + } + if (retained.isEmpty()) { + config.logger.log("Flushed ${records.size} ${spec.recordsLabel} successfully.") + } else { + config.logger.log( + "Flushed ${records.size - retained.size} of ${records.size} ${spec.recordsLabel}, " + + "keeping ${retained.size} for retry.", + ) + } } } catch (e: PostHogApiError) { - deleteFiles = deleteFilesIfAPIError(e, batchLimits, records.size, config.logger, spec.isRetriableStatusCode) + deleteFiles = deleteFilesIfAPIError(e, batchLimits, records.size, config.logger, spec.isRetriableStatusCode, spec.recordsLabel) // only re-throw if retriable (files kept), so executeWithRetry // can track retryCount and apply backoff if (!deleteFiles) { + // A 413 halves the batch instead, so the next request carries fewer records. + if (spec.isRetriableStatusCode(e.statusCode)) { + keepForRetry(files) + } throw e } } catch (e: IOException) { deleteFiles = false + keepForRetry(files) config.logger.log("Flushing failed because of a network error, let's try again soon.") throw e } finally { if (deleteFiles) { - synchronized(dequeLock) { - deque.removeAll(files) - } + val delivered = files - retained.toSet() + removeFromDeque(delivered) - files.forEach { + delivered.forEach { it.deleteSafely(config) } } } + return retained.isNotEmpty() + } + + private fun keepForRetry(files: List) { + synchronized(dequeLock) { + retryFiles = files + } } override fun flush() { @@ -342,9 +565,11 @@ public class PostHogQueue( } executeWithRetry { - while (deque.isNotEmpty()) { - batchRecords() + var retryPending = false + while (deque.isNotEmpty() && !retryPending) { + retryPending = batchRecords() } + retryPending } } } @@ -362,24 +587,36 @@ public class PostHogQueue( synchronized(dequeLock) { tempFiles = deque.toList() deque.clear() + resetBytes() } tempFiles.forEach { it.deleteSafely(config) } } + /** + * Pauses the queue after the [retryCount]-th consecutive failure. The delay doubles from + * [initialRetryDelaySeconds] to [maxRetryDelaySeconds], scaled by a jitter factor in + * `[1 - retryJitter, 1 + retryJitter)` and capped again, in milliseconds. A server `Retry-After`, + * capped at [maxRetryDelaySeconds], is a floor applied after jitter, so jitter never retries + * earlier than the server asked. + */ private fun calculateDelay( retry: Boolean, retryAfterSeconds: Int? = null, ) { if (retry) { - val delay = - if (retryAfterSeconds != null && retryAfterSeconds > 0) { - retryAfterSeconds - } else { - min(initialRetryDelaySeconds * 2.0.pow((retryCount - 1).toDouble()).toInt(), maxRetryDelaySeconds) - } - pausedUntil = config.dateProvider.addSecondsToCurrentDate(delay) + val maxDelay = maxRetryDelaySeconds.toDouble() + val computed = min(initialRetryDelaySeconds * 2.0.pow((retryCount - 1).toDouble()), maxDelay) + val unit = jitterUnit() + val factor = if (unit >= 0.0 && unit < 1.0) 1 - retryJitter + 2 * retryJitter * unit else 1.0 + val jitteredMillis = (min(computed * factor, maxDelay) * 1000).roundToLong() + val retryAfterFloorMillis = (retryAfterSeconds ?: 0).coerceIn(0, maxRetryDelaySeconds) * 1000L + val delayMillis = max(jitteredMillis, retryAfterFloorMillis) + // Whole seconds through the date provider, the rest in milliseconds, so the short early + // waits keep their jitter instead of rounding to the same second on every device. + val wholeSeconds = config.dateProvider.addSecondsToCurrentDate((delayMillis / 1000).toInt()) + pausedUntil = Date(wholeSeconds.time + delayMillis % 1000) } } @@ -422,6 +659,7 @@ public class PostHogQueue( deque.clear() deque.addAll(files) deque.addAll(existingFiles) + files.forEach { countBytes(it, it.length()) } } config.logger.log("Loaded ${files.size} cached ${spec.recordsLabel} from disk.") } @@ -442,7 +680,16 @@ public class PostHogQueue( files.sortBy { file -> file.lastModified() } val maxQueueSize = spec.maxQueueSize(config).coerceAtLeast(1) - val overflow = (files.size - maxQueueSize).coerceAtLeast(0) + var overflow = (files.size - maxQueueSize).coerceAtLeast(0) + val maxQueueBytes = spec.maxQueueBytes + if (maxQueueBytes != null) { + // Oldest first, keeping at least the newest file, as when a record is added. + var bytes = files.drop(overflow).sumOf { it.length() } + while (bytes > maxQueueBytes && overflow < files.size - 1) { + bytes -= files[overflow].length() + overflow++ + } + } if (overflow > 0) { files.take(overflow).forEach { it.deleteSafely(config) } config.logger.log("Dropped $overflow oldest cached ${spec.recordsLabel} to enforce queue capacity.") @@ -455,6 +702,8 @@ public class PostHogQueue( synchronized(dequeLock) { deque.clear() deque.addAll(files) + resetBytes() + files.forEach { countBytes(it, it.length()) } } cachedRecordsLoaded = true } @@ -509,6 +758,14 @@ public class PostHogQueue( internal val currentRetryCountForTesting: Int @PostHogVisibleForTesting get() = retryCount + + internal val queuedBytesForTesting: Long + @PostHogVisibleForTesting + get() = synchronized(dequeLock) { queuedBytes } + + internal val pendingTasksForTesting: Int + @PostHogVisibleForTesting + get() = synchronized(pendingLock) { pendingTasks } } internal class BatchLimits( @@ -540,13 +797,9 @@ internal fun deleteFilesIfAPIError( batchLimits: BatchLimits, actualBatchSize: Int, logger: PostHogLogger, - isRetriableStatusCode: (Int) -> Boolean = ::isEventsRetriableStatusCode, + isRetriableStatusCode: (Int) -> Boolean = ::isCaptureV1RetriableStatusCode, + recordsLabel: String = "records", ): Boolean { - if (e.statusCode < 400) { - logger.log("Flushing failed with ${e.statusCode}, let's try again soon.") - - return false - } // workaround due to png images exceed our max. limit in kafka if (e.statusCode == 413 && actualBatchSize > 1 && batchLimits.cap > 1) { // try to reduce multi-event batches and flushAt until the cap is 1. @@ -557,11 +810,12 @@ internal fun deleteFilesIfAPIError( return false } - // Transient server errors and rate limiting, retry + // Transient server errors, and whatever else the endpoint's policy retries if (isRetriableStatusCode(e.statusCode)) { logger.log("Flushing failed with ${e.statusCode}, let's try again soon.") return false } + logger.log("Flushing failed with ${e.statusCode}, dropping $actualBatchSize $recordsLabel.") return true } diff --git a/posthog/src/main/java/com/posthog/internal/PostHogSendCachedEventsIntegration.kt b/posthog/src/main/java/com/posthog/internal/PostHogSendCachedEventsIntegration.kt index 4924b1f52..8f353c30e 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogSendCachedEventsIntegration.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogSendCachedEventsIntegration.kt @@ -5,13 +5,15 @@ import com.posthog.PostHogEvent import com.posthog.PostHogIntegration import com.posthog.PostHogInterface import com.posthog.PostHogVisibleForTesting +import com.posthog.vendor.uuid.TimeBasedEpochGenerator import java.io.File import java.io.IOException import java.util.concurrent.ExecutorService import java.util.concurrent.atomic.AtomicBoolean /** - * The integration that sends all the cached legacy events, triggered once the SDK is setup + * The integration that sends all the cached legacy events through capture v1, triggered once the + * SDK is setup * @property config the Config * @property api the API class * @property executor the Executor @@ -70,19 +72,30 @@ internal class PostHogSendCachedEventsIntegration( while (!legacy.isEmpty) { val events = mutableListOf() + // The stored bytes of each event in `events`, to re-queue the ones capture asks to retry. + val eventsBytes = mutableListOf() val iterator = legacy.iterator() var eventsCount = 0 + var batchBytes = 0L while (iterator.hasNext()) { val eventBytes = iterator.next() + // Checked before adding, as the queue does: a non-empty batch is sent before + // it would pass the capture v1 byte target, so order is kept and an event + // over the target ships alone. The event stays at the head for the next batch. + if (events.isNotEmpty() && batchBytes + eventBytes.size > CAPTURE_V1_MAX_BATCH_BYTES) { + break + } try { val inputStream = config.encryption?.decrypt(eventBytes.inputStream()) ?: eventBytes.inputStream() inputStream.use { theInputStream -> val event = config.serializer.deserialize(theInputStream.reader().buffered()) event?.let { - events.add(event) + events.add(normalizeLegacyEvent(event)) + eventsBytes.add(eventBytes) eventsCount++ + batchBytes += eventBytes.size } ?: run { removeFileSafely(iterator) } @@ -98,10 +111,14 @@ internal class PostHogSendCachedEventsIntegration( if (events.isNotEmpty()) { var deleteFiles = true + var retryBytes = emptyList() try { - api.batch(events) + val retryUuids = api.captureV1(events).retryIds + if (retryUuids.isNotEmpty()) { + retryBytes = eventsBytes.filterIndexed { index, _ -> events[index].uuid?.toString() in retryUuids } + } } catch (e: PostHogApiError) { - if (e.statusCode < 400) { + if (isCaptureV1RetriableStatusCode(e.statusCode)) { deleteFiles = false } throw e @@ -112,6 +129,17 @@ internal class PostHogSendCachedEventsIntegration( } throw e } finally { + if (deleteFiles && retryBytes.isNotEmpty()) { + // The legacy file is FIFO: re-queue the events capture asked to retry + // at its tail first, so they stay durable while the delivered ones are + // removed from the head below. They're sent on the next launch. + try { + retryBytes.forEach { legacy.add(it) } + } catch (e: Throwable) { + config.logger.log("Error re-queuing legacy events: $e.") + deleteFiles = false + } + } if (deleteFiles && eventsCount > 0) { for (i in 1..eventsCount) { try { @@ -127,6 +155,10 @@ internal class PostHogSendCachedEventsIntegration( } } } + if (retryBytes.isNotEmpty()) { + config.logger.log("Kept ${retryBytes.size} legacy events for retry.") + return + } } } } catch (e: Throwable) { @@ -140,6 +172,25 @@ internal class PostHogSendCachedEventsIntegration( } } + /** + * Events cached by 2.x carry their uuid as `message_id` and person properties as a root `$set`, + * which capture v1 doesn't read: a missing uuid fails the whole request, and the properties + * would be lost. Moves both where capture v1 expects them. + */ + @Suppress("DEPRECATION") + private fun normalizeLegacyEvent(event: PostHogEvent): PostHogEvent { + val uuid = event.uuid ?: event.messageId ?: TimeBasedEpochGenerator.generate() + val set = event.set + if (uuid == event.uuid && set == null) { + return event + } + val properties = event.properties ?: mutableMapOf() + if (set != null && !properties.containsKey("\$set")) { + properties["\$set"] = set + } + return event.copy(uuid = uuid, properties = properties, messageId = null, set = null) + } + private fun removeFileSafely( iterator: MutableIterator, throwable: Throwable? = null, diff --git a/posthog/src/test/java/com/posthog/PostHogBeforeSendTest.kt b/posthog/src/test/java/com/posthog/PostHogBeforeSendTest.kt index e4bbba3c1..a076f7aa0 100644 --- a/posthog/src/test/java/com/posthog/PostHogBeforeSendTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogBeforeSendTest.kt @@ -6,11 +6,13 @@ import com.posthog.internal.PostHogSerializer import okhttp3.mockwebserver.RecordedRequest import org.junit.Rule import org.junit.rules.TemporaryFolder +import java.util.TreeMap import java.util.concurrent.Executors import java.util.concurrent.TimeUnit import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertNotNull +import kotlin.test.assertTrue internal class PostHogBeforeSendTest { @get:Rule @@ -132,6 +134,107 @@ internal class PostHogBeforeSendTest { assertEquals("1", event.properties?.get("sawFirst")) } + @Test + fun `a hook's edits to nested values reach the wire but not the caller's objects`() { + val nested = mutableMapOf("kept" to mutableListOf("a")) + val requests = + captureWithHooks( + listOf( + PostHogBeforeSend { event -> + @Suppress("UNCHECKED_CAST") + val map = event.properties?.get("nested") as MutableMap + map["hook"] = true + @Suppress("UNCHECKED_CAST") + (map["kept"] as MutableList).add("b") + event + }, + ), + trigger = { it.capture("event", properties = mapOf("nested" to nested)) }, + ) + + assertEquals(mutableMapOf("kept" to mutableListOf("a")), nested) + val sent = requests.single().body.unGzip() + assertTrue(sent.contains("\"hook\":true"), sent) + assertTrue(sent.contains("\"kept\":[\"a\",\"b\"]"), sent) + } + + @Test + fun `a hook sees arrays as arrays, and its edits don't reach the caller's objects`() { + val nested = mutableMapOf("kept" to true) + val requests = + captureWithHooks( + listOf( + PostHogBeforeSend { event -> + val items = event.properties?.get("items") as Array<*> + @Suppress("UNCHECKED_CAST") + (items[0] as MutableMap)["hook"] = true + assertEquals("a", (event.properties?.get("names") as Array<*>)[0]) + event + }, + ), + trigger = { it.capture("event", properties = mapOf("items" to arrayOf(nested), "names" to arrayOf("a"))) }, + ) + + assertEquals(mutableMapOf("kept" to true), nested) + assertEquals(1, requests.size) + } + + @Test + fun `a hook's edit to a primitive array doesn't reach the caller's array`() { + val numbers = intArrayOf(1) + val requests = + captureWithHooks( + listOf( + PostHogBeforeSend { event -> + (event.properties?.get("numbers") as IntArray)[0] = 2 + event + }, + ), + trigger = { it.capture("event", properties = mapOf("numbers" to numbers)) }, + ) + + assertEquals(1, numbers[0]) + assertEquals(1, requests.size) + } + + @Test + fun `a hook's lookup in a sorted map uses the map's comparator`() { + val headers = TreeMap(String.CASE_INSENSITIVE_ORDER) + headers["Authorization"] = "secret" + val requests = + captureWithHooks( + listOf( + PostHogBeforeSend { event -> + @Suppress("UNCHECKED_CAST") + (event.properties?.get("headers") as MutableMap).remove("authorization") + event + }, + ), + trigger = { it.capture("event", properties = mapOf("headers" to headers)) }, + ) + + assertEquals("secret", headers["Authorization"]) + assertTrue(!requests.single().body.unGzip().contains("secret")) + } + + @Test + fun `a hook can remove a self-referencing property`() { + val cycle = mutableMapOf() + cycle["self"] = cycle + val requests = + captureWithHooks( + listOf( + PostHogBeforeSend { event -> + event.properties?.remove("cycle") + event + }, + ), + trigger = { it.capture("event", properties = mapOf("cycle" to cycle)) }, + ) + + assertEquals(1, requests.size) + } + @Test fun `drops the event when a hook throws`() { var callsAfterThrow = 0 diff --git a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt index 689411319..ebac2c24c 100644 --- a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt @@ -249,7 +249,7 @@ internal class PostHogBootstrapTest { // No $identify (nothing to merge); a single person-processed $set marks the transition. val event = firstEvent(http, "\$set") assertEquals("user-123", event.distinctId) - assertEquals(true, event.properties?.get("\$process_person_profile")) + assertNull(event.options?.get("process_person_profile")) assertEquals(true, prefs.getValue(IS_IDENTIFIED)) sut.close() diff --git a/posthog/src/test/java/com/posthog/PostHogCaptureAiTest.kt b/posthog/src/test/java/com/posthog/PostHogCaptureAiTest.kt new file mode 100644 index 000000000..9358c99c1 --- /dev/null +++ b/posthog/src/test/java/com/posthog/PostHogCaptureAiTest.kt @@ -0,0 +1,450 @@ +package com.posthog + +import com.posthog.internal.PostHogMemoryPreferences +import com.posthog.internal.PostHogThreadFactory +import com.posthog.internal.replay.PostHogSessionReplayHandler +import com.posthog.internal.surveys.PostHogSurveysHandler +import com.posthog.surveys.Survey +import okhttp3.mockwebserver.MockResponse +import okhttp3.mockwebserver.MockWebServer +import okhttp3.mockwebserver.RecordedRequest +import org.junit.Rule +import org.junit.rules.TemporaryFolder +import java.io.File +import java.io.FilterInputStream +import java.io.FilterOutputStream +import java.io.InputStream +import java.io.OutputStream +import java.util.concurrent.CountDownLatch +import java.util.concurrent.Executors +import java.util.concurrent.TimeUnit +import kotlin.test.AfterTest +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertNotNull +import kotlin.test.assertNull +import kotlin.test.assertTrue + +internal class PostHogCaptureAiTest { + @get:Rule + val tmpDir = TemporaryFolder() + + @get:Rule + val httpServers = TestHttpServers() + + private val queueExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestQueue")) + private val replayQueueExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestReplayQueue")) + private val logsExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestLogsQueue")) + private val aiExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestAiQueue")) + private val remoteConfigExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestRemoteConfig")) + private val cachedEventsExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestCachedEvents")) + private val logger = TestLogger() + private val clients = mutableListOf() + private lateinit var config: PostHogConfig + + private fun getSut( + http: MockWebServer, + configure: PostHogConfig.() -> Unit = {}, + ): PostHogInterface { + val storage = tmpDir.newFolder().absolutePath + config = + PostHogConfig(PROJECT_TOKEN, http.url("/").toString()).apply { + storagePrefix = File(storage, "events").absolutePath + replayStoragePrefix = File(storage, "snapshots").absolutePath + logsStoragePrefix = File(storage, "logs").absolutePath + aiStoragePrefix = File(storage, "ai").absolutePath + flushAt = 1 + preloadFeatureFlags = false + sendFeatureFlagEvent = false + cachePreferences = PostHogMemoryPreferences() + context = TestPostHogContext() + logger = this@PostHogCaptureAiTest.logger + configure() + } + return PostHog.withInternal( + config, + queueExecutor, + replayQueueExecutor, + remoteConfigExecutor, + cachedEventsExecutor, + reloadFeatureFlags = false, + logsExecutor = logsExecutor, + aiExecutor = aiExecutor, + ).also { clients.add(it) } + } + + @AfterTest + fun cleanup() { + clients.forEach { it.close() } + listOf(queueExecutor, replayQueueExecutor, logsExecutor, aiExecutor, remoteConfigExecutor, cachedEventsExecutor).forEach { + it.shutdownAndAwaitTermination() + } + tmpDir.root.deleteRecursively() + } + + private fun aiQueueFiles(): List = File(config.aiStoragePrefix!!, PROJECT_TOKEN).listFiles()?.toList() ?: emptyList() + + private fun takeRequest(http: MockWebServer): RecordedRequest = assertNotNull(http.takeRequest(5, TimeUnit.SECONDS)) + + private fun events(request: RecordedRequest): List> = captureV1Events(request.body.unGzip()) + + @Suppress("UNCHECKED_CAST") + private fun Map.properties(): Map = this["properties"] as Map + + @Test + fun `captureAi keeps the newest events while captureAiMaxQueueSize events wait to be written`() { + val http = httpServers.mockHttp(total = 3) + val sut = getSut(http) { captureAiMaxQueueSize = 2 } + val release = CountDownLatch(1) + aiExecutor.execute { release.await() } + + assertNotNull(sut.captureAi("\$ai_generation")) + assertNotNull(sut.captureAi("\$ai_generation")) + assertNotNull(sut.captureAi("\$ai_generation")) + assertTrue(logger.messages.any { it.contains("the oldest 1 are dropped") }) + + release.countDown() + aiExecutor.awaitExecution() + } + + @Test + fun `captureAi posts to the AI endpoint and returns the uuid on the wire`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + + val uuid = sut.captureAi("\$ai_generation", properties = mapOf("\$ai_model" to "gpt-5")) + + aiExecutor.awaitExecution() + val request = takeRequest(http) + assertEquals("/i/v1/ai/events", request.path) + assertEquals("Bearer $PROJECT_TOKEN", request.headers["Authorization"]) + assertEquals("1", request.headers["PostHog-Attempt"]) + val event = events(request).single() + assertEquals("\$ai_generation", event["event"]) + assertEquals(assertNotNull(uuid).toString(), event["uuid"]) + assertEquals(sut.distinctId(), event["distinct_id"]) + // same enrichment as capture: SDK context and the caller's properties + assertEquals("gpt-5", event.properties()["\$ai_model"]) + assertEquals("Android", event.properties()["\$os_name"]) + queueExecutor.awaitExecution() + assertEquals(1, http.requestCount) + } + + @Test + fun `capture keeps an ai-named event on the analytics endpoint`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + + sut.capture("\$ai_generation") + + queueExecutor.awaitExecution() + aiExecutor.awaitExecution() + assertEquals("/i/v1/analytics/events", takeRequest(http).path) + assertEquals(1, http.requestCount) + assertTrue(aiQueueFiles().isEmpty()) + } + + @Test + fun `beforeSend, options and the personless default apply to AI events`() { + val http = httpServers.mockHttp() + val sut = + getSut(http) { + addBeforeSend { event -> + event.properties?.remove("\$ai_input") + event.properties?.put("redacted", true) + event + } + } + + sut.captureAi( + "\$ai_generation", + properties = mapOf("\$ai_input" to "secret prompt"), + options = mapOf("cookieless_mode" to true), + ) + + aiExecutor.awaitExecution() + val event = events(takeRequest(http)).single() + assertEquals(true, event.properties()["redacted"]) + assertTrue("\$ai_input" !in event.properties()) + // identified-only without an identify: the SDK adds the personless option + assertEquals(mapOf("cookieless_mode" to true, "process_person_profile" to false), event["options"]) + } + + @Test + fun `captureAi returns null when disabled, opted out or rejected by beforeSend`() { + val http = httpServers.mockHttp() + val sut = getSut(http) { addBeforeSend { event -> if (event.event == "\$ai_rejected") null else event } } + + assertNull(sut.captureAi("\$ai_rejected")) + sut.optOut() + assertNull(sut.captureAi("\$ai_generation")) + sut.optIn() + sut.close() + assertNull(sut.captureAi("\$ai_generation")) + + aiExecutor.awaitExecution() + assertEquals(0, http.requestCount) + assertTrue(aiQueueFiles().isEmpty()) + } + + @Test + fun `captureAi keeps the uuid and notifies replay when event handlers throw`() { + var replayNotified = false + val surveys = + object : PostHogIntegration, PostHogSurveysHandler { + override fun onReset() {} + + override fun onEvent( + event: String, + properties: Map?, + ): Unit = throw IllegalStateException("surveys") + + override fun onSurveysLoaded(surveys: List) {} + } + val replay = + object : PostHogIntegration, PostHogSessionReplayHandler { + override fun start(resumeCurrent: Boolean) {} + + override fun stop() {} + + override fun isActive(): Boolean = false + + override fun debugProperties(): Map = emptyMap() + + override fun onEvent( + event: String, + properties: Map?, + ) { + replayNotified = true + throw IllegalStateException("replay") + } + + override fun onSessionIdChanged() {} + } + val sut = + getSut(httpServers.mockHttp()) { + addIntegration(surveys) + addIntegration(replay) + } + + assertNotNull(sut.captureAi("\$ai_generation")) + assertTrue(replayNotified) + } + + @Test + fun `a 404 from the AI endpoint keeps the event queued`() { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(404)) + val sut = getSut(http) + + sut.captureAi("\$ai_generation") + aiExecutor.awaitExecution() + + assertEquals(1, http.requestCount) + assertEquals("/i/v1/ai/events", takeRequest(http).path) + assertEquals(1, aiQueueFiles().size) + } + + @Test + fun `an AI event over captureAiMaxEventBytes returns null and logs only its name and size`() { + val http = httpServers.mockHttp() + val sut = getSut(http) { captureAiMaxEventBytes = 1 } + val prompt = "p".repeat(70_000) + + val uuid = sut.captureAi("\$ai_generation", properties = mapOf("\$ai_input" to prompt)) + + assertNull(uuid) + aiExecutor.awaitExecution() + sut.flush() + aiExecutor.awaitExecution() + assertEquals(0, http.requestCount) + assertTrue(aiQueueFiles().isEmpty()) + val dropped = logger.messages.single { it.startsWith("Dropping AI event") } + assertTrue( + dropped.matches(Regex("Dropping AI event \\\$ai_generation of more than 1 bytes, over the limit\\.")), + dropped, + ) + assertTrue(logger.messages.none { it.contains("pppp") }) + } + + @Test + fun `a captureAiMaxEventBytes over the ceiling logs a warning`() { + getSut(httpServers.mockHttp()) { captureAiMaxEventBytes = 16 * 1024 * 1024 } + + assertTrue( + logger.messages.any { + it == "captureAiMaxEventBytes 16777216 is over the 8454144 byte ceiling, using 8454144." + }, + logger.messages.toString(), + ) + } + + @Test + fun `an AI event whose properties are exactly 8 MiB is sent`() { + val ceiling = 8 * 1024 * 1024 + val http = httpServers.mockHttp() + val sut = + getSut(http) { + captureAiCompression = PostHogCompression.NONE + // pin the properties after the SDK's enrichment; {"$ai_input":"…"} is 16 bytes around the value + addBeforeSend { event -> event.copy(properties = mutableMapOf("\$ai_input" to "a".repeat(ceiling - 16))) } + } + + assertNotNull(sut.captureAi("\$ai_generation")) + + aiExecutor.awaitExecution() + val body = takeRequest(http).body.readUtf8() + // the properties object is the event's last field, closed by the event, batch and body + val properties = body.substring(body.indexOf("\"properties\":") + "\"properties\":".length, body.length - "}]}".length) + assertEquals(ceiling, properties.toByteArray(Charsets.UTF_8).size) + assertEquals("\$ai_generation", captureV1Events(body).single()["event"]) + assertTrue(logger.messages.none { it.startsWith("Dropping AI event") }) + } + + @Test + fun `the AI event limit is measured before encryption`() { + val http = httpServers.mockHttp() + val sut = + getSut(http) { + captureAiMaxEventBytes = 100_000 + // writes every byte twice, so the stored event is double its JSON size + encryption = + object : PostHogEncryption { + override fun encrypt(outputStream: OutputStream): OutputStream = + object : FilterOutputStream(outputStream) { + override fun write(b: Int) { + out.write(b) + out.write(b) + } + + override fun write( + b: ByteArray, + off: Int, + len: Int, + ) { + val doubled = ByteArray(len * 2) + for (i in 0 until len) { + doubled[2 * i] = b[off + i] + doubled[2 * i + 1] = b[off + i] + } + out.write(doubled) + } + } + + override fun decrypt(inputStream: InputStream): InputStream = + object : FilterInputStream(inputStream) { + override fun read(): Int = super.read().also { super.read() } + + override fun read( + b: ByteArray, + off: Int, + len: Int, + ): Int { + var n = 0 + while (n < len) { + val c = read() + if (c < 0) break + b[off + n++] = c.toByte() + } + return if (n == 0 && len > 0) -1 else n + } + } + } + } + // under the 100,000 byte limit as JSON, over it once encrypted + val prompt = "p".repeat(60_000) + + val uuid = sut.captureAi("\$ai_generation", properties = mapOf("\$ai_input" to prompt)) + + assertNotNull(uuid) + aiExecutor.awaitExecution() + assertEquals(uuid.toString(), events(takeRequest(http)).single()["uuid"]) + } + + @Test + fun `a name that doesn't start with ai is logged and sent unchanged`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + + sut.captureAi("not_ai") + + aiExecutor.awaitExecution() + val request = takeRequest(http) + assertEquals("/i/v1/ai/events", request.path) + assertEquals("not_ai", events(request).single()["event"]) + assertTrue(logger.messages.any { it.startsWith("captureAi event not_ai doesn't start with \$ai_") }) + } + + @Test + fun `flush and close drain the AI queue`() { + val http = httpServers.mockHttp(total = 2) + val sut = getSut(http) { flushAt = 10 } + + sut.captureAi("\$ai_generation") + aiExecutor.awaitExecution() + assertEquals(0, http.requestCount) + + sut.flush() + aiExecutor.awaitExecution() + assertEquals(1, http.requestCount) + + sut.captureAi("\$ai_span") + aiExecutor.awaitExecution() + sut.close() + aiExecutor.awaitExecution() + assertEquals(2, http.requestCount) + assertEquals(listOf("/i/v1/ai/events", "/i/v1/ai/events"), List(2) { takeRequest(http).path }) + } + + @Test + fun `compression is set per lane`() { + val http = httpServers.mockHttp(total = 2) + val sut = + getSut(http) { + compression = PostHogCompression.NONE + captureAiCompression = PostHogCompression.GZIP + } + + sut.capture("event") + sut.captureAi("\$ai_generation") + + queueExecutor.awaitExecution() + aiExecutor.awaitExecution() + val requests = List(2) { takeRequest(http) }.associateBy { it.path } + val analytics = assertNotNull(requests["/i/v1/analytics/events"]) + val ai = assertNotNull(requests["/i/v1/ai/events"]) + assertNull(analytics.headers["Content-Encoding"]) + assertTrue(analytics.body.readUtf8().contains("\"event\":\"event\"")) + assertEquals("gzip", ai.headers["Content-Encoding"]) + assertEquals("\$ai_generation", events(ai).single()["event"]) + } + + @Test + fun `captureAiCompression off sends the AI request uncompressed while analytics stay gzipped`() { + val http = httpServers.mockHttp(total = 2) + val sut = getSut(http) { captureAiCompression = PostHogCompression.NONE } + + sut.capture("event") + sut.captureAi("\$ai_generation") + + queueExecutor.awaitExecution() + aiExecutor.awaitExecution() + val requests = List(2) { takeRequest(http) }.associateBy { it.path } + assertEquals("gzip", assertNotNull(requests["/i/v1/analytics/events"]).headers["Content-Encoding"]) + val ai = assertNotNull(requests["/i/v1/ai/events"]) + assertNull(ai.headers["Content-Encoding"]) + assertEquals("\$ai_generation", captureV1Events(ai.body.readUtf8()).single()["event"]) + } + + @Test + fun `AI requests time out after captureAiTimeout and keep the event for retry`() { + val http = httpServers.mockHttp(response = MockResponse().setHeadersDelay(3, TimeUnit.SECONDS)) + val sut = getSut(http) { captureAiTimeout = 1 } + + sut.captureAi("\$ai_generation") + aiExecutor.awaitExecution() + + assertEquals(1, http.requestCount) + assertEquals(1, aiQueueFiles().size) + assertTrue(logger.messages.any { it.contains("network error") }) + } +} diff --git a/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt b/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt new file mode 100644 index 000000000..35e68f521 --- /dev/null +++ b/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt @@ -0,0 +1,404 @@ +package com.posthog + +import com.posthog.internal.PostHogBatchEvent +import com.posthog.internal.PostHogMemoryPreferences +import com.posthog.internal.PostHogSerializer +import com.posthog.internal.PostHogThreadFactory +import okhttp3.mockwebserver.MockWebServer +import org.junit.Rule +import org.junit.rules.TemporaryFolder +import java.io.File +import java.util.concurrent.Executors +import kotlin.test.AfterTest +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertFalse +import kotlin.test.assertNotEquals +import kotlin.test.assertNotSame +import kotlin.test.assertNull +import kotlin.test.assertTrue + +internal class PostHogCaptureOptionsTest { + @get:Rule + val tmpDir = TemporaryFolder() + + @get:Rule + val httpServers = TestHttpServers() + + private val queueExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestQueue")) + private val replayQueueExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestReplayQueue")) + private val remoteConfigExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestRemoteConfig")) + private val cachedEventsExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestCachedEvents")) + private val serializer = PostHogSerializer(PostHogConfig(PROJECT_TOKEN)) + private lateinit var config: PostHogConfig + + // Events as beforeSend sees them. The hook drops them, so each capture is recorded once and + // nothing is sent. + private val captured = mutableListOf() + + private fun getSut( + host: String = "http://localhost", + personProfiles: PersonProfiles = PersonProfiles.IDENTIFIED_ONLY, + beforeSend: PostHogBeforeSend = + PostHogBeforeSend { event -> + captured.add(event) + null + }, + ): PostHogInterface { + val storage = tmpDir.newFolder().absolutePath + config = + PostHogConfig(PROJECT_TOKEN, host).apply { + flushAt = 1 + storagePrefix = File(storage, "events").absolutePath + replayStoragePrefix = File(storage, "snapshots").absolutePath + preloadFeatureFlags = false + sendFeatureFlagEvent = false + cachePreferences = PostHogMemoryPreferences() + context = TestPostHogContext() + this.personProfiles = personProfiles + addBeforeSend(beforeSend) + } + return PostHog.withInternal( + config, + queueExecutor, + replayQueueExecutor, + remoteConfigExecutor, + cachedEventsExecutor, + false, + ) + } + + @AfterTest + fun `set down`() { + tmpDir.root.deleteRecursively() + } + + private fun sentEvents(http: MockWebServer): List = + List(http.requestCount) { + serializer.deserialize(http.takeRequest().body.unGzip().reader()).batch + }.flatten() + + private fun PostHogEvent.processPersonProfile(): Any? = options?.get("process_person_profile") + + @Test + fun `options reach the event of every event-sending method`() { + val options = mapOf("cookieless_mode" to true) + val cases = + listOf Unit>>( + "test_event" to { it.capture("test_event", options = options) }, + PostHogEventName.SCREEN.event to { it.screen("screen", options = options) }, + PostHogEventName.IDENTIFY.event to { it.identify("user_id", options = options) }, + PostHogEventName.SET.event to { it.setPersonProperties(userProps, options = options) }, + PostHogEventName.CREATE_ALIAS.event to { it.alias("alias", options = options) }, + PostHogEventName.GROUP_IDENTIFY.event to { it.group("type", "key", options = options) }, + PostHogEventName.EXCEPTION.event to { it.captureException(RuntimeException("boom"), options = options) }, + ) + for ((eventName, trigger) in cases) { + captured.clear() + // always processed, so the SDK adds no option of its own + val sut = getSut(personProfiles = PersonProfiles.ALWAYS) + + trigger(sut) + + val event = captured.single { it.event == eventName } + assertEquals?>(mapOf("cookieless_mode" to true), event.options, eventName) + sut.close() + } + } + + @Test + fun `identify with the same id sends its options on the set event`() { + val sut = getSut() + sut.identify("user_id") + + sut.identify("user_id", userProperties = userProps, options = mapOf("cookieless_mode" to true)) + + val event = captured.single { it.event == PostHogEventName.SET.event } + assertEquals?>(mapOf("cookieless_mode" to true), event.options) + sut.close() + } + + @Test + fun `the event gets a copy of the caller's options`() { + val callerOptions = mutableMapOf("cookieless_mode" to true) + val sut = getSut() + + sut.capture("test_event", options = callerOptions) + + val event = captured.single() + assertNotSame(callerOptions, event.options) + event.options!!["product_tour_id"] = "tour" + assertEquals?>(mapOf("cookieless_mode" to true), callerOptions) + sut.close() + } + + @Test + fun `beforeSend can edit the options`() { + val http = httpServers.mockHttp() + val sut = + getSut( + http.url("/").toString(), + beforeSend = + PostHogBeforeSend { event -> + event.options = (event.options ?: mutableMapOf()).apply { put("cookieless_mode", true) } + event + }, + ) + + sut.capture("test_event", options = mapOf("product_tour_id" to "tour")) + queueExecutor.shutdownAndAwaitTermination() + + val event = sentEvents(http).single() + assertEquals("tour", event.options?.get("product_tour_id")) + assertEquals(true, event.options?.get("cookieless_mode")) + sut.close() + } + + @Test + fun `beforeSend can remove the personless option and the send does not add it back`() { + val http = httpServers.mockHttp() + val sut = + getSut( + http.url("/").toString(), + personProfiles = PersonProfiles.NEVER, + beforeSend = + PostHogBeforeSend { event -> + event.options = null + event + }, + ) + + sut.capture("test_event") + queueExecutor.shutdownAndAwaitTermination() + + val event = sentEvents(http).single() + assertNull(event.options) + assertFalse(event.properties!!.containsKey("\$process_person_profile")) + sut.close() + } + + @Test + fun `an event beforeSend copies or builds keeps the options it was given`() { + val http = httpServers.mockHttp() + val sut = + getSut( + http.url("/").toString(), + personProfiles = PersonProfiles.NEVER, + beforeSend = + PostHogBeforeSend { event -> + if (event.event == "copied") { + event.copy(properties = mutableMapOf("edited" to true)) + } else { + PostHogEvent(event.event, event.distinctId, event.properties, event.timestamp, event.uuid) + } + }, + ) + + sut.capture("copied", options = mapOf("product_tour_id" to "tour")) + sut.capture("built") + queueExecutor.shutdownAndAwaitTermination() + + val events = sentEvents(http) + val copied: Map? = events.single { it.event == "copied" }.options + val built: Map? = events.single { it.event == "built" }.options + assertEquals(mapOf("product_tour_id" to "tour", "process_person_profile" to false), copied) + assertEquals(mapOf("process_person_profile" to false), built) + sut.close() + } + + @Test + fun `the personless option is set only when person processing is off`() { + val never = getSut(personProfiles = PersonProfiles.NEVER) + never.capture("test_event") + assertEquals(false, captured.single().processPersonProfile()) + assertFalse(captured.single().properties!!.containsKey("\$process_person_profile")) + never.close() + + captured.clear() + val identifiedOnly = getSut(personProfiles = PersonProfiles.IDENTIFIED_ONLY) + identifiedOnly.capture("anonymous_event") + identifiedOnly.identify("user_id") + identifiedOnly.capture("identified_event") + assertEquals(false, captured.single { it.event == "anonymous_event" }.processPersonProfile()) + assertNull(captured.single { it.event == PostHogEventName.IDENTIFY.event }.options) + assertNull(captured.single { it.event == "identified_event" }.options) + identifiedOnly.close() + + captured.clear() + val always = getSut(personProfiles = PersonProfiles.ALWAYS) + always.capture("test_event") + assertNull(captured.single().options) + always.close() + } + + @Test + fun `a caller option wins over the personless default`() { + val sut = getSut(personProfiles = PersonProfiles.NEVER) + + sut.capture("explicit", options = mapOf("process_person_profile" to true)) + sut.capture("unset", options = mapOf("process_person_profile" to null, "cookieless_mode" to true)) + + assertEquals?>(mapOf("process_person_profile" to true), captured.single { it.event == "explicit" }.options) + assertEquals?>( + mapOf("process_person_profile" to false, "cookieless_mode" to true), + captured.single { it.event == "unset" }.options, + ) + sut.close() + } + + @Test + fun `a registered legacy person processing property suppresses the personless option`() { + val sut = getSut(personProfiles = PersonProfiles.NEVER) + sut.register("\$process_person_profile", true) + + sut.capture("test_event") + + val event = captured.single() + assertNull(event.options) + assertEquals(true, event.properties!!["\$process_person_profile"]) + sut.close() + } + + @Test + fun `a null legacy person processing property keeps the personless option when profiles are never processed`() { + assertNullLegacyPropertyKeepsPersonlessOption(PersonProfiles.NEVER) + } + + @Test + fun `a null legacy person processing property keeps the personless option for an anonymous user`() { + assertNullLegacyPropertyKeepsPersonlessOption(PersonProfiles.IDENTIFIED_ONLY) + } + + private fun assertNullLegacyPropertyKeepsPersonlessOption(personProfiles: PersonProfiles) { + // Java callers can put a null value in the properties map. + @Suppress("UNCHECKED_CAST") + val nullLegacy = hashMapOf("\$process_person_profile" to null) as Map + val http = httpServers.mockHttp() + val sut = getSut(http.url("/").toString(), personProfiles = personProfiles, beforeSend = { it }) + + sut.capture("null_legacy", properties = nullLegacy) + queueExecutor.shutdownAndAwaitTermination() + + val event = sentEvents(http).single() + assertEquals(false, event.processPersonProfile()) + assertFalse(event.properties!!.containsKey("\$process_person_profile")) + sut.close() + } + + @Test + fun `registered properties win over SDK properties, caller properties win over registered ones`() { + val sut = getSut() + sut.register("\$os_name", "registered") + sut.register("\$is_identified", true) + sut.register("custom", "registered") + + sut.capture("test_event", properties = mapOf("custom" to "caller")) + + val props = captured.single().properties!! + assertEquals("registered", props["\$os_name"]) + assertEquals(true, props["\$is_identified"]) + assertEquals("caller", props["custom"]) + sut.close() + } + + @Test + fun `beforeSend wins over caller properties`() { + val http = httpServers.mockHttp() + val sut = + getSut( + http.url("/").toString(), + beforeSend = + PostHogBeforeSend { event -> + event.properties?.set("custom", "hook") + event + }, + ) + + sut.capture("test_event", properties = mapOf("custom" to "caller")) + queueExecutor.shutdownAndAwaitTermination() + + assertEquals("hook", sentEvents(http).single().properties!!["custom"]) + sut.close() + } + + @Test + fun `typed call values win over registered set and groups properties`() { + val sut = getSut() + sut.register("\$set", mapOf("plan" to "registered")) + sut.register("\$groups", mapOf("company" to "registered")) + + sut.capture("test_event", userProperties = mapOf("plan" to "call"), groups = mapOf("company" to "call")) + + val props = captured.single().properties!! + assertEquals(mapOf("plan" to "call"), props["\$set"] as Map<*, *>) + assertEquals(mapOf("company" to "call"), props["\$groups"] as Map<*, *>) + sut.close() + } + + @Test + fun `a blank distinct id falls back to the current one`() { + val sut = getSut() + + sut.capture("test_event", distinctId = " ") + sut.identify(" ") + + assertEquals(sut.distinctId(), captured.single().distinctId) + assertTrue(captured.none { it.event == PostHogEventName.IDENTIFY.event }) + sut.close() + } + + @Test + fun `a personless set neither stores nor matches the person properties hash`() { + val personless = mapOf("process_person_profile" to false) + val sut = getSut() + sut.identify("user_id") + captured.clear() + + sut.setPersonProperties(userProps, options = personless) + sut.setPersonProperties(userProps) + sut.setPersonProperties(userProps, options = personless) + sut.setPersonProperties(userProps) + + // only the second processed call is a duplicate + assertEquals(3, captured.count { it.event == PostHogEventName.SET.event }) + sut.close() + } + + @Test + fun `a set with a false value capture reads leniently is personless too`() { + for (value in listOf("false", " Off ", 0, "0.0")) { + val sut = getSut() + sut.identify("user_id") + captured.clear() + + sut.setPersonProperties(userProps, options = mapOf("process_person_profile" to value)) + sut.setPersonProperties(userProps) + + assertEquals(2, captured.count { it.event == PostHogEventName.SET.event }, "for $value") + sut.close() + } + } + + @Test + fun `an event returned by beforeSend keeps the uuid of its own capture`() { + val http = httpServers.mockHttp(total = 2) + var cached: PostHogEvent? = null + val sut = + getSut( + http.url("/").toString(), + beforeSend = + PostHogBeforeSend { event -> + cached ?: event.also { cached = it } + }, + ) + + sut.capture("first") + sut.capture("second") + queueExecutor.shutdownAndAwaitTermination() + + val uuids = sentEvents(http).map { it.uuid } + assertEquals(2, uuids.size) + assertNotEquals(uuids[0], uuids[1]) + sut.close() + } +} diff --git a/posthog/src/test/java/com/posthog/PostHogPersonProfilesTest.kt b/posthog/src/test/java/com/posthog/PostHogPersonProfilesTest.kt index 0f76373d9..193ee7860 100644 --- a/posthog/src/test/java/com/posthog/PostHogPersonProfilesTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogPersonProfilesTest.kt @@ -10,7 +10,9 @@ import java.util.concurrent.Executors import kotlin.test.AfterTest import kotlin.test.Test import kotlin.test.assertEquals +import kotlin.test.assertFalse import kotlin.test.assertNotNull +import kotlin.test.assertNull internal class PostHogPersonProfilesTest { @get:Rule @@ -57,6 +59,9 @@ internal class PostHogPersonProfilesTest { tmpDir.root.deleteRecursively() } + private val PostHogEvent.processPersonProfile: Any? + get() = options?.get("process_person_profile") + @Test fun `captures an identify event where personProfile is identified_only`() { val http = mockHttp() @@ -81,7 +86,7 @@ internal class PostHogPersonProfilesTest { val theEvent = batch.batch.first() assertEquals("\$identify", theEvent.event) - assertEquals(true, theEvent.properties?.get("\$process_person_profile")) + assertNull(theEvent.processPersonProfile) assertEquals(DISTINCT_ID, theEvent.distinctId) assertNotNull(theEvent.properties!!["\$anon_distinct_id"]) assertEquals(userProps, theEvent.properties!!["\$set"]) @@ -108,13 +113,13 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.first() - assertEquals(false, event.properties!!["\$process_person_profile"] as Boolean) + assertEquals(false, event.processPersonProfile) sut.close() } @Test - fun `capture ignores caller person processing properties if identified only and not identified`() { + fun `caller person processing properties win if identified only and not identified`() { val http = mockHttp() val url = http.url("/") @@ -133,8 +138,10 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.first() - assertEquals(false, event.properties!!["\$process_person_profile"] as Boolean) - assertEquals(false, event.properties!!["\$is_identified"] as Boolean) + // the caller's legacy property is hoisted into the option when the event is sent + assertEquals(true, event.processPersonProfile) + assertFalse(event.properties!!.containsKey("\$process_person_profile")) + assertEquals(true, event.properties!!["\$is_identified"] as Boolean) sut.close() http.shutdown() @@ -160,7 +167,7 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.first() - assertEquals(true, event.properties!!["\$process_person_profile"] as Boolean) + assertNull(event.processPersonProfile) sut.close() } @@ -185,7 +192,7 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.first() - assertEquals(true, event.properties!!["\$process_person_profile"] as Boolean) + assertNull(event.processPersonProfile) sut.close() } @@ -210,7 +217,7 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.first() - assertEquals(true, event.properties!!["\$process_person_profile"] as Boolean) + assertNull(event.processPersonProfile) sut.close() } @@ -234,13 +241,13 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.last() - assertEquals(true, event.properties!!["\$process_person_profile"] as Boolean) + assertNull(event.processPersonProfile) sut.close() } @Test - fun `capture ignores caller person processing properties if identified only and identified`() { + fun `caller person processing properties win if identified only and identified`() { val http = mockHttp() val url = http.url("/") @@ -261,8 +268,9 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.last() - assertEquals(true, event.properties!!["\$process_person_profile"] as Boolean) - assertEquals(true, event.properties!!["\$is_identified"] as Boolean) + assertEquals(false, event.processPersonProfile) + assertFalse(event.properties!!.containsKey("\$process_person_profile")) + assertEquals(false, event.properties!!["\$is_identified"] as Boolean) sut.close() http.shutdown() @@ -287,7 +295,7 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.last() - assertEquals(true, event.properties!!["\$process_person_profile"] as Boolean) + assertNull(event.processPersonProfile) sut.close() } @@ -311,7 +319,7 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.last() - assertEquals(true, event.properties!!["\$process_person_profile"] as Boolean) + assertNull(event.processPersonProfile) sut.reset() sut.close() @@ -334,7 +342,7 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.first() - assertEquals(true, event.properties!!["\$process_person_profile"] as Boolean) + assertNull(event.processPersonProfile) sut.reset() sut.close() @@ -359,7 +367,7 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.first() - assertEquals(false, event.properties!!["\$process_person_profile"] as Boolean) + assertEquals(false, event.processPersonProfile) sut.reset() sut.close() @@ -384,7 +392,7 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.first() - assertEquals(false, event.properties!!["\$process_person_profile"] as Boolean) + assertEquals(false, event.processPersonProfile) sut.reset() sut.close() @@ -409,14 +417,14 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.first() - assertEquals(false, event.properties!!["\$process_person_profile"] as Boolean) + assertEquals(false, event.processPersonProfile) sut.reset() sut.close() } @Test - fun `capture ignores caller process person override if never`() { + fun `caller process person override wins if never`() { val http = mockHttp() val url = http.url("/") @@ -432,7 +440,8 @@ internal class PostHogPersonProfilesTest { val event = batch.batch.first() - assertEquals(false, event.properties!!["\$process_person_profile"] as Boolean) + assertEquals(true, event.processPersonProfile) + assertFalse(event.properties!!.containsKey("\$process_person_profile")) sut.close() http.shutdown() diff --git a/posthog/src/test/java/com/posthog/PostHogSessionReplayHandlerFake.kt b/posthog/src/test/java/com/posthog/PostHogSessionReplayHandlerFake.kt index 060ab3854..117e5ac59 100644 --- a/posthog/src/test/java/com/posthog/PostHogSessionReplayHandlerFake.kt +++ b/posthog/src/test/java/com/posthog/PostHogSessionReplayHandlerFake.kt @@ -49,11 +49,14 @@ public class PostHogSessionReplayHandlerFake(private var isActive: Boolean) : Po return isActive } + // runs after each debugProperties() read, so a test can change the state between reads + public var onDebugProperties: (() -> Unit)? = null + override fun debugProperties(): Map { if (throwOnDebugProperties) { throw RuntimeException("debugProperties failed") } - return debugProperties + return debugProperties.also { onDebugProperties?.invoke() } } override fun onEvent( diff --git a/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt b/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt index 00dddfffb..ffab030c4 100644 --- a/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt @@ -277,7 +277,19 @@ internal class PostHogStatelessTest { sut.setup(config) assertFalse(sut.isEnabledPublic()) - assertTrue(mockLogger.messages.any { it.contains("PostHog SDK is disabled because the project token is required") }) + assertTrue(mockLogger.warnings.any { it.contains("PostHog SDK is disabled because the project token is required") }) + } + + @Test + fun `setup no-ops for a personal API key`() { + sut = createStatelessInstance() + val mockLogger = TestLogger() + config = PostHogConfig("phx_personal", "https://api.posthog.com").apply { logger = mockLogger } + + sut.setup(config) + + assertFalse(sut.isEnabledPublic()) + assertTrue(mockLogger.warnings.any { it.contains("PostHog SDK is disabled because the project token is a personal API key") }) } @Test @@ -464,6 +476,49 @@ internal class PostHogStatelessTest { assertEquals(mapOf("company" to "acme"), event.properties!!["\$groups"]) } + @Test + fun `captureStateless drops an event with an empty name`() { + val mockQueue = MockQueue() + sut = createStatelessInstance() + config = createConfig() + + sut.setup(config) + sut.setMockQueue(mockQueue) + + sut.captureStateless(event = "", distinctId = "user123") + + assertTrue(mockQueue.events.isEmpty()) + } + + @Test + fun `captureStateless merges typed values over the same maps in properties per key`() { + val mockQueue = MockQueue() + sut = createStatelessInstance() + config = createConfig() + + sut.setup(config) + sut.setMockQueue(mockQueue) + + sut.captureStateless( + event = "test_event", + distinctId = "user123", + properties = + mapOf( + "\$set" to mapOf("name" to "caller", "plan" to "free"), + "\$set_once" to mapOf("first" to "caller", "source" to "ad"), + "\$groups" to mapOf("company" to "caller", "team" to "core"), + ), + userProperties = mapOf("name" to "typed"), + userPropertiesSetOnce = mapOf("first" to "typed"), + groups = mapOf("company" to "typed"), + ) + + val properties = mockQueue.events.single().properties!! + assertEquals(mapOf("name" to "typed", "plan" to "free"), properties["\$set"]) + assertEquals(mapOf("first" to "typed", "source" to "ad"), properties["\$set_once"]) + assertEquals(mapOf("company" to "typed", "team" to "core"), properties["\$groups"]) + } + private class IgnoredExceptionStub(message: String) : RuntimeException(message) @Test @@ -1084,7 +1139,10 @@ internal class PostHogStatelessTest { sut.captureStateless("test", "user123") assertEquals(0, mockQueue.events.size) - assertTrue(mockLogger.messages.any { it.contains("Error in beforeSend function") }) + val line = mockLogger.messages.single { it.contains("beforeSend") } + assertTrue(line.contains("'test'")) + assertTrue(line.contains("RuntimeException")) + assertFalse(line.contains("Test error")) } @Test diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index c7348302c..d16f06f1e 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -277,7 +277,28 @@ internal class PostHogTest { ) assertTrue(sut.isOptOut()) - assertTrue(logger.messages.any { it.contains("PostHog SDK is disabled because the project token is required") }) + assertTrue(logger.warnings.any { it.contains("PostHog SDK is disabled because the project token is required") }) + + sut.close() + } + + @Test + fun `setup no-ops for a personal API key`() { + val config = PostHogConfig("phx_personal", "https://api.posthog.com") + val logger = TestLogger() + config.logger = logger + val sut = + PostHog.withInternal( + config, + queueExecutor, + replayQueueExecutor, + remoteConfigExecutor, + cachedEventsExecutor, + reloadFeatureFlags = true, + ) + + assertTrue(sut.isOptOut()) + assertTrue(logger.warnings.any { it.contains("PostHog SDK is disabled because the project token is a personal API key") }) sut.close() } @@ -682,13 +703,10 @@ internal class PostHogTest { "\$feature_flag_reason", "\$feature_flag_request_id", "\$groups", - "\$process_person_profile", - "\$session_id", - "\$lib", - "\$lib_version", ) assertEquals(expectedKeys, theEvent.properties!!.keys) assertFalse(theEvent.properties!!.containsKey("\$recording_status")) + assertEquals(false, theEvent.options?.get("process_person_profile")) assertEquals("IAmInactive", theEvent.properties!!["\$feature_flag"]) assertEquals(false, theEvent.properties!!["\$feature_flag_response"]) @@ -701,6 +719,44 @@ internal class PostHogTest { sut.close() } + @Test + fun `minimal feature flag called event keeps the registered legacy option properties`() { + val file = File("src/test/resources/json/basic-flags-minimal-flag-called-events.json") + val responseFlagsApi = file.readText() + + val http = mockHttp(response = MockResponse().setBody(responseFlagsApi)) + http.enqueue(MockResponse().setBody("")) + val url = http.url("/") + + val sut = getSut(url.toString(), preloadFeatureFlags = false, context = TestPostHogContext()) + + // registered as super properties, so the send can still hoist them into options + sut.register("\$cookieless_mode", true) + sut.register("\$ignore_sent_at", true) + sut.register("\$product_tour_id", "tour") + sut.register("myCustomProp", "value") + + sut.reloadFeatureFlags() + remoteConfigExecutor.shutdownAndAwaitTermination() + http.takeRequest() + + assertFalse(sut.getFeatureFlag("IAmInactive") as Boolean) + queueExecutor.shutdownAndAwaitTermination() + + val batch = serializer.deserialize(http.takeRequest().body.unGzip().reader()) + val event = batch.batch.first() + // the send hoists the kept legacy properties into their options + val options = event.options!! + assertEquals(true, options["cookieless_mode"]) + assertEquals(true, options["disable_skew_correction"]) + assertEquals("tour", options["product_tour_id"]) + val props = event.properties!! + assertFalse(props.containsKey("\$cookieless_mode")) + assertFalse(props.containsKey("myCustomProp")) + + sut.close() + } + @Test fun `feature flag called event keeps the full shape when gated and the flag has an experiment`() { val file = File("src/test/resources/json/basic-flags-minimal-flag-called-events.json") @@ -1808,8 +1864,7 @@ internal class PostHogTest { val content = request.body.unGzip() val batch = serializer.deserialize(content.reader()) - assertEquals(PROJECT_TOKEN, batch.projectToken) - assertNotNull(batch.sentAt) + assertEquals("Bearer $PROJECT_TOKEN", request.headers["Authorization"]) val theEvent = batch.batch.first() assertEquals(EVENT, theEvent.event) @@ -1847,10 +1902,9 @@ internal class PostHogTest { val request = http.takeRequest() val content = request.body.unGzip() - val batch = serializer.deserialize(content.reader()) - val theEvent = batch.batch.first() + val theEvent = captureV1Events(content).first() - assertEquals(callerSessionId, theEvent.properties!!["\$session_id"]) + assertEquals(callerSessionId, theEvent["session_id"]) sut.close() } @@ -2117,6 +2171,81 @@ internal class PostHogTest { sut.close() } + @Test + fun `a caller groups map adds to stored groups, and typed groups win per key`() { + val http = mockHttp() + val prefs = PostHogMemoryPreferences() + prefs.setValue(GROUPS, mapOf("org" to "stored", "company" to "stored")) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false, cachePreferences = prefs, reloadFeatureFlags = false) + + sut.capture( + EVENT, + DISTINCT_ID, + properties = mapOf("\$groups" to mapOf("company" to "caller", "team" to "t1")), + groups = mapOf("team" to "typed"), + ) + + queueExecutor.shutdownAndAwaitTermination() + + val properties = serializer.deserialize(http.takeRequest().body.unGzip().reader()).batch.first().properties!! + assertEquals(mapOf("org" to "stored", "company" to "caller", "team" to "typed"), properties["\$groups"]) + + sut.close() + } + + @Test + fun `typed per-call values win key by key over the same maps in properties`() { + val http = mockHttp() + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false) + + sut.capture( + EVENT, + DISTINCT_ID, + properties = + mapOf( + "\$set" to mapOf("plan" to "free", "seen" to true), + "\$set_once" to mapOf("first" to "a", "source" to "ad"), + "\$groups" to mapOf("company" to "caller", "team" to "t1"), + ), + userProperties = mapOf("plan" to "pro"), + userPropertiesSetOnce = mapOf("first" to "b"), + groups = mapOf("company" to "typed"), + ) + + queueExecutor.shutdownAndAwaitTermination() + + val properties = serializer.deserialize(http.takeRequest().body.unGzip().reader()).batch.first().properties!! + assertEquals(mapOf("plan" to "pro", "seen" to true), properties["\$set"]) + assertEquals(mapOf("first" to "b", "source" to "ad"), properties["\$set_once"]) + assertEquals(mapOf("company" to "typed", "team" to "t1"), properties["\$groups"]) + + sut.close() + } + + @Test + fun `drops an event whose name is empty, also after beforeSend`() { + val http = mockHttp() + val sut = + getSut(http.url("/").toString(), preloadFeatureFlags = false, beforeSend = { + if (it.event == "blanked") it.copy(event = "") else it + }) + val logger = TestLogger() + config.logger = logger + + sut.capture("") + sut.capture("blanked") + sut.capture(EVENT) + + queueExecutor.shutdownAndAwaitTermination() + + assertEquals(1, http.requestCount) + assertEquals(EVENT, serializer.deserialize(http.takeRequest().body.unGzip().reader()).batch.single().event) + assertEquals(1, logger.messages.count { it == "Dropping an event with an empty name." }) + assertTrue(logger.messages.none { it.contains("was dropped") }) + + sut.close() + } + @Test fun `captures an event with a custom timestamp`() { val http = mockHttp() @@ -2140,8 +2269,7 @@ internal class PostHogTest { val content = request.body.unGzip() val batch = serializer.deserialize(content.reader()) - assertEquals(PROJECT_TOKEN, batch.projectToken) - assertNotNull(batch.sentAt) + assertEquals("Bearer $PROJECT_TOKEN", request.headers["Authorization"]) val theEvent = batch.batch.first() assertNotNull(theEvent.timestamp) @@ -2677,7 +2805,7 @@ internal class PostHogTest { val theEvent = batch.batch.first() assertEquals("\$groupidentify", theEvent.event) - assertNotNull(theEvent.properties!!["\$session_id"]) + assertNotNull(captureV1Events(content).first()["session_id"]) assertFalse(theEvent.properties!!["\$is_identified"] as Boolean) assertFalse(theEvent.properties!!.containsKey("\$groups")) @@ -2748,6 +2876,52 @@ internal class PostHogTest { sut.close() } + @Test + fun `setAppLanguage sends the normalized language, survives reset and clears`() { + val http = mockHttp() + val url = http.url("/") + val sut = getSut(url.toString(), flushAt = 3, preloadFeatureFlags = false, reloadFeatureFlags = false) + + sut.setAppLanguage(" pt_BR ") + sut.capture(EVENT, DISTINCT_ID) + sut.reset() + sut.capture(EVENT, DISTINCT_ID) + sut.setAppLanguage(null) + sut.capture(EVENT, DISTINCT_ID) + + queueExecutor.shutdownAndAwaitTermination() + + val batch = serializer.deserialize(http.takeRequest().body.unGzip().reader()) + val languages = batch.batch.map { it.properties!!["\$app_language"] } + assertEquals(listOf("pt-BR", "pt-BR", null), languages) + + sut.close() + } + + @Test + fun `app language prefers registered, then set, then detected`() { + val http = mockHttp() + val url = http.url("/") + val context = + object : PostHogContext by TestPostHogContext() { + override fun getDynamicContext() = mapOf("\$app_language" to "en") + } + val sut = getSut(url.toString(), flushAt = 3, preloadFeatureFlags = false, reloadFeatureFlags = false, context = context) + + sut.capture(EVENT, DISTINCT_ID) + sut.setAppLanguage("de") + sut.capture(EVENT, DISTINCT_ID) + sut.register("\$app_language", "fr") + sut.capture(EVENT, DISTINCT_ID) + + queueExecutor.shutdownAndAwaitTermination() + + val batch = serializer.deserialize(http.takeRequest().body.unGzip().reader()) + assertEquals(listOf("en", "de", "fr"), batch.batch.map { it.properties!!["\$app_language"] }) + + sut.close() + } + @Test fun `registers ignore internal keys`() { val http = mockHttp() @@ -2838,8 +3012,7 @@ internal class PostHogTest { val content = request.body.unGzip() val batch = serializer.deserialize(content.reader()) - assertEquals(PROJECT_TOKEN, batch.projectToken) - assertNotNull(batch.sentAt) + assertEquals("Bearer $PROJECT_TOKEN", request.headers["Authorization"]) val theEvent = batch.batch.first() assertEquals(EVENT, theEvent.event) @@ -3151,7 +3324,7 @@ internal class PostHogTest { var batch = serializer.deserialize(content.reader()) var theEvent = batch.batch.first() - val currentSessionId = theEvent.properties!!["\$session_id"] + val currentSessionId = captureV1Events(content).first()["session_id"] assertNotNull(currentSessionId) sut.reset() @@ -3174,7 +3347,7 @@ internal class PostHogTest { batch = serializer.deserialize(content.reader()) theEvent = batch.batch.first() - val newSessionId = theEvent.properties!!["\$session_id"] + val newSessionId = captureV1Events(content).first()["session_id"] assertNotNull(newSessionId) assertTrue(currentSessionId != newSessionId) @@ -3493,7 +3666,7 @@ internal class PostHogTest { } @Test - fun `debug properties win over caller and registered properties of the same name`() { + fun `caller and registered properties win over debug properties of the same name`() { val http = mockHttp() val url = http.url("/") val integration = @@ -3502,6 +3675,7 @@ internal class PostHogTest { } val sut = getSut(url.toString(), preloadFeatureFlags = false, reloadFeatureFlags = false, integration = integration) sut.register("\$recording_status", "registered") + sut.register("\$sdk_debug_replay_event_trigger_status", "registered") sut.capture(EVENT, properties = mapOf("\$recording_status" to "caller", "\$sdk_debug_pending_queue_size" to -1)) @@ -3512,8 +3686,9 @@ internal class PostHogTest { val batch = serializer.deserialize(content.reader()) val theEvent = batch.batch.first() - assertEquals("active", theEvent.properties!!["\$recording_status"]) - assertNotEquals(-1, (theEvent.properties!!["\$sdk_debug_pending_queue_size"] as Number).toInt()) + assertEquals("caller", theEvent.properties!!["\$recording_status"]) + assertEquals("registered", theEvent.properties!!["\$sdk_debug_replay_event_trigger_status"]) + assertEquals(-1, (theEvent.properties!!["\$sdk_debug_pending_queue_size"] as Number).toInt()) sut.close() } @@ -5382,11 +5557,12 @@ internal class PostHogTest { queueExecutor.shutdownAndAwaitTermination() - http.takeRequest() + val lockedBatch = serializer.deserialize(http.takeRequest().body.unGzip().reader()) + assertEquals(false, lockedBatch.batch[0].options?.get("process_person_profile")) val request = http.takeRequest() val content = request.body.unGzip() val batch = serializer.deserialize(content.reader()) - assertEquals(true, batch.batch[0].properties?.get("\$process_person_profile")) + assertNull(batch.batch[0].options?.get("process_person_profile")) sut.close() } @@ -6482,8 +6658,9 @@ internal class PostHogTest { sut.capture(SDK_EVENT, DISTINCT_ID, properties = mapOf("\$session_id" to callerSessionId.toString())) queueExecutor.shutdownAndAwaitTermination() - val props = serializer.deserialize(http.takeRequest().body.unGzip().reader()).batch.first().properties!! - assertEquals(callerSessionId.toString(), props["\$session_id"]) + val theEvent = captureV1Events(http.takeRequest().body.unGzip()).first() + val props = theEvent["properties"] as Map<*, *> + assertEquals(callerSessionId.toString(), theEvent["session_id"]) assertEquals(managerStart - oneHourMs, (props["\$sdk_debug_session_start"] as Number).toLong()) sut.close() diff --git a/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt b/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt new file mode 100644 index 000000000..bbda6457f --- /dev/null +++ b/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt @@ -0,0 +1,482 @@ +package com.posthog + +import com.posthog.internal.PostHogMemoryPreferences +import com.posthog.internal.PostHogPreferences.Companion.PERSON_PROPERTIES_FOR_FLAGS +import com.posthog.internal.PostHogThreadFactory +import okhttp3.mockwebserver.MockWebServer +import okhttp3.mockwebserver.RecordedRequest +import org.junit.Rule +import org.junit.rules.TemporaryFolder +import java.io.File +import java.util.Date +import java.util.concurrent.Executors +import java.util.concurrent.TimeUnit +import kotlin.test.AfterTest +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertFalse +import kotlin.test.assertNotNull +import kotlin.test.assertNull + +internal class PostHogWrapperEventTest { + @get:Rule + val tmpDir = TemporaryFolder() + + @get:Rule + val httpServers = TestHttpServers() + + private val queueExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestQueue")) + private val replayQueueExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestReplayQueue")) + private val logsExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestLogsQueue")) + private val aiExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestAiQueue")) + private val remoteConfigExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestRemoteConfig")) + private val cachedEventsExecutor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("TestCachedEvents")) + private val clients = mutableListOf() + + private fun getSut( + http: MockWebServer, + configure: PostHogConfig.() -> Unit = {}, + ): PostHogInterface { + val storage = tmpDir.newFolder().absolutePath + val config = + PostHogConfig(PROJECT_TOKEN, http.url("/").toString()).apply { + storagePrefix = File(storage, "events").absolutePath + replayStoragePrefix = File(storage, "snapshots").absolutePath + logsStoragePrefix = File(storage, "logs").absolutePath + aiStoragePrefix = File(storage, "ai").absolutePath + flushAt = 1 + preloadFeatureFlags = false + sendFeatureFlagEvent = false + cachePreferences = PostHogMemoryPreferences() + context = TestPostHogContext() + configure() + } + return PostHog.withInternal( + config, + queueExecutor, + replayQueueExecutor, + remoteConfigExecutor, + cachedEventsExecutor, + reloadFeatureFlags = false, + logsExecutor = logsExecutor, + aiExecutor = aiExecutor, + ).also { clients.add(it) } + } + + @AfterTest + fun cleanup() { + clients.forEach { it.close() } + listOf(queueExecutor, replayQueueExecutor, logsExecutor, aiExecutor, remoteConfigExecutor, cachedEventsExecutor).forEach { + it.shutdownAndAwaitTermination() + } + tmpDir.root.deleteRecursively() + } + + private fun takeRequest(http: MockWebServer): RecordedRequest = assertNotNull(http.takeRequest(5, TimeUnit.SECONDS)) + + private fun events(request: RecordedRequest): List> = captureV1Events(request.body.unGzip()) + + @Suppress("UNCHECKED_CAST") + private fun Map.properties(): Map = this["properties"] as Map + + @Test + fun `build fills the event without running beforeSend or queueing it`() { + val http = httpServers.mockHttp() + var hookCalls = 0 + val sut = + getSut(http) { + addBeforeSend { event -> + hookCalls++ + event + } + } + sut.register("plan", "free") + + val event = + assertNotNull( + sut.buildEventForWrapper( + "purchase", + properties = mapOf("plan" to "pro"), + userProperties = mapOf("email" to "a@b.c"), + options = mapOf("cookieless_mode" to true), + ), + ) + + queueExecutor.awaitExecution() + assertEquals(0, http.requestCount) + assertEquals(0, hookCalls) + assertEquals("purchase", event.event) + assertEquals(sut.distinctId(), event.distinctId) + assertNotNull(event.uuid) + assertEquals("pro", event.properties?.get("plan")) + assertEquals("Android", event.properties?.get("\$os_name")) + assertEquals(mapOf("email" to "a@b.c"), event.properties?.get("\$set")) + assertEquals(true, event.options?.get("cookieless_mode")) + } + + @Test + fun `send keeps the built event's identity and properties, then runs beforeSend`() { + val http = httpServers.mockHttp() + val sut = + getSut(http) { + addBeforeSend { event -> + event.properties?.put("hooked", true) + event + } + } + val timestamp = Date(1_700_000_000_000) + val built = assertNotNull(sut.buildEventForWrapper("purchase", timestamp = timestamp)) + built.properties?.remove("\$os_name") + sut.register("late", "value") + + val uuid = sut.sendBuiltEventForWrapper(built) + + queueExecutor.awaitExecution() + val sent = events(takeRequest(http)).single() + assertEquals(built.uuid, uuid) + assertEquals(built.uuid.toString(), sent["uuid"]) + assertEquals("2023-11-14T22:13:20.000Z", sent["timestamp"]) + assertEquals(true, sent.properties()["hooked"]) + assertFalse(sent.properties().containsKey("\$os_name")) + assertFalse(sent.properties().containsKey("late")) + } + + @Test + fun `send on the AI lane posts to the AI endpoint`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + sut.startSession() + val built = assertNotNull(sut.buildEventForWrapper("\$ai_generation", ai = true)) + + assertEquals(built.uuid, sut.sendBuiltEventForWrapper(built, ai = true)) + + aiExecutor.awaitExecution() + val request = takeRequest(http) + assertEquals("/i/v1/ai/events", request.path) + assertNotNull(events(request).single().properties()["\$sdk_debug_session_start"]) + } + + @Test + fun `send returns null when beforeSend drops the event`() { + val http = httpServers.mockHttp() + val sut = getSut(http) { addBeforeSend { null } } + val built = assertNotNull(sut.buildEventForWrapper("purchase")) + + assertNull(sut.sendBuiltEventForWrapper(built)) + + queueExecutor.awaitExecution() + assertEquals(0, http.requestCount) + } + + @Test + fun `send returns null after an opt-out since the build`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + val built = assertNotNull(sut.buildEventForWrapper("purchase")) + sut.optOut() + + assertNull(sut.sendBuiltEventForWrapper(built)) + + queueExecutor.awaitExecution() + assertEquals(0, http.requestCount) + } + + @Test + fun `build returns null when opted out`() { + val sut = getSut(httpServers.mockHttp()) + sut.optOut() + + assertNull(sut.buildEventForWrapper("purchase")) + } + + @Test + fun `build of a screen event without a screen name returns null`() { + val sut = getSut(httpServers.mockHttp()) + + assertNull(sut.buildEventForWrapper("\$screen", properties = mapOf("\$screen_name" to " "))) + assertNull(sut.buildEventForWrapper("\$screen")) + } + + @Test + fun `a built event the wrapper drops leaves no state behind`() { + val prefs = PostHogMemoryPreferences() + val sut = getSut(httpServers.mockHttp()) { cachePreferences = prefs } + + assertNotNull( + sut.buildEventForWrapper( + "\$screen", + properties = mapOf("\$screen_name" to "Home"), + userProperties = mapOf("plan" to "pro"), + ), + ) + val next = assertNotNull(sut.buildEventForWrapper("tap")) + + assertFalse(next.properties!!.containsKey("\$screen_name")) + assertNull(prefs.getValue(PERSON_PROPERTIES_FOR_FLAGS)) + assertEquals(false, next.options?.get("process_person_profile")) + } + + @Test + fun `send turns on person processing for a build with user properties`() { + val sut = getSut(httpServers.mockHttp()) + val identified = assertNotNull(sut.buildEventForWrapper("signup", userProperties = mapOf("plan" to "pro"))) + + assertNotNull(sut.sendBuiltEventForWrapper(identified)) + val next = assertNotNull(sut.buildEventForWrapper("tap")) + + assertNull(identified.options?.get("process_person_profile")) + assertNull(next.options?.get("process_person_profile")) + } + + @Test + fun `send for another distinct id leaves the current user's person state alone`() { + val prefs = PostHogMemoryPreferences() + val http = httpServers.mockHttp() + val sut = getSut(http) { cachePreferences = prefs } + val built = assertNotNull(sut.buildEventForWrapper("signup", userProperties = mapOf("plan" to "pro"))) + + assertNotNull(sut.sendBuiltEventForWrapper(built.copy(distinctId = "other-user"))) + queueExecutor.awaitExecution() + val next = assertNotNull(sut.buildEventForWrapper("tap")) + + val sent = events(takeRequest(http)).single() + assertEquals("other-user", sent["distinct_id"]) + assertEquals(mapOf("plan" to "pro"), sent.properties()["\$set"]) + assertNull(prefs.getValue(PERSON_PROPERTIES_FOR_FLAGS)) + assertEquals(false, next.options?.get("process_person_profile")) + } + + @Test + fun `send caches the screen name and the person properties for flags`() { + val prefs = PostHogMemoryPreferences() + val sut = getSut(httpServers.mockHttp()) { cachePreferences = prefs } + val screen = + assertNotNull( + sut.buildEventForWrapper( + "\$screen", + properties = mapOf("\$screen_name" to " Home "), + userProperties = mapOf("plan" to "pro"), + ), + ) + + assertNotNull(sut.sendBuiltEventForWrapper(screen)) + val next = assertNotNull(sut.buildEventForWrapper("tap")) + + assertEquals("Home", screen.properties?.get("\$screen_name")) + assertEquals("Home", next.properties?.get("\$screen_name")) + assertEquals(mapOf("plan" to "pro"), prefs.getValue(PERSON_PROPERTIES_FOR_FLAGS)) + } + + @Test + fun `an event built under another name and sent as a screen doesn't cache its name`() { + val sut = getSut(httpServers.mockHttp()) + val built = assertNotNull(sut.buildEventForWrapper("\$captured_screen", properties = mapOf("\$screen_name" to "Home"))) + + assertNotNull(sut.sendBuiltEventForWrapper(built.copy(event = "\$screen"))) + val next = assertNotNull(sut.buildEventForWrapper("tap")) + + assertNull(next.properties?.get("\$screen_name")) + } + + @Test + fun `send after a reset delivers the screen without restoring its name`() { + val sut = getSut(httpServers.mockHttp()) + val screen = assertNotNull(sut.buildEventForWrapper("\$screen", properties = mapOf("\$screen_name" to "Home"))) + + sut.reset() + assertNotNull(sut.sendBuiltEventForWrapper(screen)) + val next = assertNotNull(sut.buildEventForWrapper("tap")) + + assertNull(next.properties?.get("\$screen_name")) + } + + @Test + fun `the replay debug bundle is claimed at send`() { + val http = httpServers.mockHttp() + val sut = getSut(http) { flushAt = 2 } + sut.startSession() + val first = assertNotNull(sut.buildEventForWrapper("\$first")) + val second = assertNotNull(sut.buildEventForWrapper("\$second")) + + assertNotNull(sut.sendBuiltEventForWrapper(first)) + assertNotNull(sut.sendBuiltEventForWrapper(second)) + + queueExecutor.awaitExecution() + val (sentFirst, sentSecond) = events(takeRequest(http)) + assertNotNull(sentFirst.properties()["\$sdk_debug_session_start"]) + assertFalse(sentSecond.properties().containsKey("\$sdk_debug_session_start")) + } + + @Test + fun `replay debug eligibility follows the built name across a rename`() { + val http = httpServers.mockHttp() + val sut = getSut(http) { flushAt = 2 } + sut.startSession() + val renamedAway = assertNotNull(sut.buildEventForWrapper("\$first")) + val renamedTo = assertNotNull(sut.buildEventForWrapper("tap")) + + assertNotNull(sut.sendBuiltEventForWrapper(renamedTo.copy(event = "\$second"))) + assertNotNull(sut.sendBuiltEventForWrapper(renamedAway.copy(event = "custom"))) + + queueExecutor.awaitExecution() + val (sentTo, sentAway) = events(takeRequest(http)) + assertNotNull(sentAway.properties()["\$sdk_debug_session_start"]) + assertFalse(sentTo.properties().containsKey("\$sdk_debug_session_start")) + } + + @Test + fun `send keeps a replay debug key the wrapper removed`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + sut.startSession() + val event = assertNotNull(sut.buildEventForWrapper("\$first")) + event.properties?.remove("\$recording_status") + + assertNotNull(sut.sendBuiltEventForWrapper(event)) + + queueExecutor.awaitExecution() + val sent = events(takeRequest(http)).single().properties() + assertNotNull(sent["\$sdk_debug_session_start"]) + assertFalse(sent.containsKey("\$recording_status")) + } + + @Test + fun `a second send of the same built event is a no-op`() { + val http = httpServers.mockHttp() + val sut = getSut(http) { flushAt = 2 } + val event = assertNotNull(sut.buildEventForWrapper("tap")) + + assertNotNull(sut.sendBuiltEventForWrapper(event)) + assertNull(sut.sendBuiltEventForWrapper(event)) + assertNotNull(sut.sendBuiltEventForWrapper(assertNotNull(sut.buildEventForWrapper("next")))) + + queueExecutor.awaitExecution() + assertEquals(listOf("tap", "next"), events(takeRequest(http)).map { it["event"] }) + } + + @Test + fun `send skips the person properties for flags after the user changed`() { + val prefs = PostHogMemoryPreferences() + val sut = getSut(httpServers.mockHttp()) { cachePreferences = prefs } + val event = assertNotNull(sut.buildEventForWrapper("signup", userProperties = mapOf("plan" to "pro"))) + + sut.reset() + assertNotNull(sut.sendBuiltEventForWrapper(event)) + + assertNull(prefs.getValue(PERSON_PROPERTIES_FOR_FLAGS)) + } + + @Test + fun `send skips the person properties for flags after a reset that kept the anonymous id`() { + val prefs = PostHogMemoryPreferences() + val sut = + getSut(httpServers.mockHttp()) { + cachePreferences = prefs + reuseAnonymousId = true + } + val event = assertNotNull(sut.buildEventForWrapper("signup", userProperties = mapOf("plan" to "pro"))) + + sut.reset() + assertNotNull(sut.sendBuiltEventForWrapper(event)) + + assertNull(prefs.getValue(PERSON_PROPERTIES_FOR_FLAGS)) + } + + @Test + fun `send drops an event built by another instance`() { + val built = assertNotNull(getSut(httpServers.mockHttp()).buildEventForWrapper("tap")) + val other = getSut(httpServers.mockHttp()) + + assertNull(other.sendBuiltEventForWrapper(built)) + } + + @Test + fun `send drops an event built before the SDK was set up again`() { + val http = httpServers.mockHttp() + var setupConfig: PostHogConfig? = null + val sut = getSut(http) { setupConfig = this } + val built = assertNotNull(sut.buildEventForWrapper("tap")) + + sut.close() + sut.setup(assertNotNull(setupConfig)) + + assertNull(sut.sendBuiltEventForWrapper(built)) + } + + @Test + fun `send keeps the replay debug values from the build`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + sut.startSession() + val built = assertNotNull(sut.buildEventForWrapper("\$first")) + sut.endSession() + Thread.sleep(5) + sut.startSession() + + assertNotNull(sut.sendBuiltEventForWrapper(built)) + + queueExecutor.awaitExecution() + val sent = events(takeRequest(http)).single().properties() + assertNotNull(sent["\$sdk_debug_session_start"]) + } + + @Test + fun `build reads the replay debug state once for the required and deferred keys`() { + val http = httpServers.mockHttp() + val replay = + PostHogSessionReplayHandlerFake(true).apply { + debugProperties = + mapOf( + "\$recording_status" to "buffering", + "\$sdk_debug_replay_flush_hold_reason" to "below_minimum_duration", + ) + // A replay stop between two reads would pair buffering with no hold reason. + onDebugProperties = { debugProperties = mapOf("\$recording_status" to "disabled") } + } + val sut = getSut(http) { addIntegration(replay) } + sut.startSession() + + val screen = assertNotNull(sut.buildEventForWrapper("\$screen", properties = mapOf("\$screen_name" to "Home"))) + assertNotNull(sut.sendBuiltEventForWrapper(screen)) + + queueExecutor.awaitExecution() + val sent = events(takeRequest(http)).single().properties() + assertEquals("buffering", sent["\$recording_status"]) + assertEquals("below_minimum_duration", sent["\$sdk_debug_replay_flush_hold_reason"]) + } + + @Test + fun `send skips the person properties for flags after a reset during the build`() { + val prefs = PostHogMemoryPreferences() + lateinit var sut: PostHogInterface + val replay = + PostHogSessionReplayHandlerFake(true).apply { + // Runs while the build enriches the event, after it took its distinct ID. + onDebugProperties = { + onDebugProperties = null + sut.reset() + } + } + sut = + getSut(httpServers.mockHttp()) { + cachePreferences = prefs + addIntegration(replay) + } + val event = assertNotNull(sut.buildEventForWrapper("signup", userProperties = mapOf("plan" to "pro"))) + + assertNotNull(sut.sendBuiltEventForWrapper(event)) + + assertNull(prefs.getValue(PERSON_PROPERTIES_FOR_FLAGS)) + } + + @Test + fun `send skips person processing after the user changed`() { + val sut = getSut(httpServers.mockHttp()) + val identified = assertNotNull(sut.buildEventForWrapper("signup", userProperties = mapOf("plan" to "pro"))) + + sut.reset() + assertNotNull(sut.sendBuiltEventForWrapper(identified)) + + assertEquals(false, assertNotNull(sut.buildEventForWrapper("tap")).options?.get("process_person_profile")) + } +} diff --git a/posthog/src/test/java/com/posthog/Utils.kt b/posthog/src/test/java/com/posthog/Utils.kt index 25e5e65f6..b3288259f 100644 --- a/posthog/src/test/java/com/posthog/Utils.kt +++ b/posthog/src/test/java/com/posthog/Utils.kt @@ -1,6 +1,7 @@ package com.posthog import com.posthog.internal.PostHogContext +import com.posthog.internal.PostHogSerializer import com.posthog.internal.parseISO8601Date import okhttp3.mockwebserver.MockResponse import okhttp3.mockwebserver.MockWebServer @@ -88,6 +89,13 @@ public fun Buffer.unGzip(): String { } } +/** The events of a capture v1 request [body], as sent on the wire. */ +@Suppress("UNCHECKED_CAST") +public fun captureV1Events(body: String): List> { + val parsed = PostHogSerializer(PostHogConfig(PROJECT_TOKEN)).deserialize>(body.reader()) + return parsed["batch"] as List> +} + public class TestPostHogContext : PostHogContext { override fun getStaticContext(): Map = mapOf( diff --git a/posthog/src/test/java/com/posthog/errortracking/PostHogErrorTrackingAutoCaptureIntegrationTest.kt b/posthog/src/test/java/com/posthog/errortracking/PostHogErrorTrackingAutoCaptureIntegrationTest.kt index b2c0f062d..647e62868 100644 --- a/posthog/src/test/java/com/posthog/errortracking/PostHogErrorTrackingAutoCaptureIntegrationTest.kt +++ b/posthog/src/test/java/com/posthog/errortracking/PostHogErrorTrackingAutoCaptureIntegrationTest.kt @@ -164,7 +164,7 @@ internal class PostHogErrorTrackingAutoCaptureIntegrationTest { integration.uncaughtException(thread, throwable) - verify(mockPostHog).captureException(any(), anyOrNull()) + verify(mockPostHog).captureException(any(), anyOrNull(), anyOrNull()) integration.uninstall() } @@ -193,7 +193,7 @@ internal class PostHogErrorTrackingAutoCaptureIntegrationTest { whenever(mockConfig.remoteConfigHolder).thenReturn(mockRemoteConfig) whenever(mockRemoteConfig.isAutocaptureExceptionsEnabled()).thenReturn(true) currentHandler = mockExceptionHandler - whenever(mockPostHog.captureException(any(), anyOrNull())).thenThrow(IllegalStateException("telemetry broke")) + whenever(mockPostHog.captureException(any(), anyOrNull(), anyOrNull())).thenThrow(IllegalStateException("telemetry broke")) val thread = Thread.currentThread() val throwable = RuntimeException("Test exception") @@ -494,7 +494,7 @@ internal class PostHogErrorTrackingAutoCaptureIntegrationTest { val throwable = RuntimeException("crash while dormant") integration.uncaughtException(thread, throwable) - verify(mockPostHog, never()).captureException(any(), anyOrNull()) + verify(mockPostHog, never()).captureException(any(), anyOrNull(), anyOrNull()) verify(mockExceptionHandler).uncaughtException(thread, throwable) // Clear the process-wide install flag so it doesn't leak into the next test. @@ -520,7 +520,7 @@ internal class PostHogErrorTrackingAutoCaptureIntegrationTest { val throwable = RuntimeException("crash after re-enable") integration.uncaughtException(thread, throwable) - verify(mockPostHog).captureException(any(), anyOrNull()) + verify(mockPostHog).captureException(any(), anyOrNull(), anyOrNull()) verify(mockExceptionHandler).uncaughtException(thread, throwable) // Clear the process-wide install flag so it doesn't leak into the next test. @@ -540,7 +540,7 @@ internal class PostHogErrorTrackingAutoCaptureIntegrationTest { val throwable = RuntimeException("crash while remote-disabled") integration.uncaughtException(thread, throwable) - verify(mockPostHog, never()).captureException(any(), anyOrNull()) + verify(mockPostHog, never()).captureException(any(), anyOrNull(), anyOrNull()) verify(mockExceptionHandler).uncaughtException(thread, throwable) // Clear the process-wide install flag so it doesn't leak into the next test. @@ -577,7 +577,7 @@ internal class PostHogErrorTrackingAutoCaptureIntegrationTest { val throwable = RuntimeException("crash after re-setup") second.uncaughtException(thread, throwable) - verify(mockPostHog).captureException(any(), anyOrNull()) + verify(mockPostHog).captureException(any(), anyOrNull(), anyOrNull()) verify(overlay).uncaughtException(thread, throwable) currentHandler = second diff --git a/posthog/src/test/java/com/posthog/internal/EndpointSpecTest.kt b/posthog/src/test/java/com/posthog/internal/EndpointSpecTest.kt index b3ac02c26..12946becc 100644 --- a/posthog/src/test/java/com/posthog/internal/EndpointSpecTest.kt +++ b/posthog/src/test/java/com/posthog/internal/EndpointSpecTest.kt @@ -81,7 +81,10 @@ internal class EndpointSpecTest { stream.reader().buffered().use { SyntheticRecord(it.readText()) } }, describe = { "synthetic '${it.value}'" }, - send = { records -> sender.send(records) }, + send = { records -> + sender.send(records) + SendResult() + }, isRetriableStatusCode = isRetriableStatusCode, ) @@ -257,14 +260,13 @@ internal class EndpointSpecTest { } @Test - fun `logs spec retry policy retries 408 429 and 5xx`() { + fun `logs spec retry policy retries 408 429 3xx and 5xx`() { assertTrue(isLogsRetriableStatusCode(408)) assertTrue(isLogsRetriableStatusCode(429)) assertTrue(isLogsRetriableStatusCode(500)) assertTrue(isLogsRetriableStatusCode(599)) - // 3xx redirects are not retriable — a redirect from /i/v1/logs means - // misconfigured host, retrying would loop. - assertEquals(false, isLogsRetriableStatusCode(301)) + // A 3xx that OkHttp did not follow keeps the records, as it always did for logs. + assertTrue(isLogsRetriableStatusCode(301)) assertEquals(false, isLogsRetriableStatusCode(400)) assertEquals(false, isLogsRetriableStatusCode(404)) assertEquals(false, isLogsRetriableStatusCode(600)) @@ -272,14 +274,12 @@ internal class EndpointSpecTest { @Test fun `events spec does not retry non-retriable status codes`() { - // Events keeps a curated retry set (408, 429, 500, 502, 503, 504); it - // must not retry arbitrary 4xx, nor the extra 5xx codes the broad logs - // policy (500..599) covers. Guards against widening the set by mistake. - assertEquals(false, isEventsRetriableStatusCode(400)) - assertEquals(false, isEventsRetriableStatusCode(413)) - assertEquals(false, isEventsRetriableStatusCode(501)) - assertEquals(false, isEventsRetriableStatusCode(505)) - assertEquals(false, isEventsRetriableStatusCode(599)) + assertEquals(false, isCaptureV1RetriableStatusCode(307)) + assertEquals(false, isCaptureV1RetriableStatusCode(400)) + assertEquals(false, isCaptureV1RetriableStatusCode(413)) + assertEquals(false, isCaptureV1RetriableStatusCode(501)) + assertEquals(false, isCaptureV1RetriableStatusCode(505)) + assertEquals(false, isCaptureV1RetriableStatusCode(599)) } @Test @@ -359,11 +359,11 @@ internal class EndpointSpecTest { assertEquals(1, http.requestCount) val request = assertNotNull(http.takeRequest(5, TimeUnit.SECONDS)) - assertTrue(request.path!!.startsWith("/batch")) - val batch = PostHogSerializer(config).deserialize(request.body.unGzip().reader()) - assertEquals("event-via-spec", batch.batch.single().event) - assertEquals(com.posthog.DISTINCT_ID, batch.batch.single().distinctId) - assertEquals(com.posthog.props, batch.batch.single().properties?.toMap()) + assertEquals("/i/v1/analytics/events", request.path) + val sent = com.posthog.captureV1Events(request.body.unGzip()).single() + assertEquals("event-via-spec", sent["event"]) + assertEquals(com.posthog.DISTINCT_ID, sent["distinct_id"]) + assertEquals(com.posthog.props, sent["properties"]) http.shutdown() } diff --git a/posthog/src/test/java/com/posthog/internal/PostHogApiTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogApiTest.kt index 2c0b10816..e1e2d22e1 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogApiTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogApiTest.kt @@ -60,7 +60,7 @@ internal class PostHogApiTest { debug: Boolean = false, logger: PostHogLogger? = null, httpClient: OkHttpClient? = null, - maxRetries: Int? = null, + pushNotificationSubscriptionMaxRetries: Int? = null, featureFlagRequestMaxRetries: Int? = null, requestHeaders: Map? = null, compression: PostHogCompression = PostHogCompression.GZIP, @@ -78,8 +78,8 @@ internal class PostHogApiTest { if (httpClient != null) { config.httpClient = httpClient } - if (maxRetries != null) { - config.maxRetries = maxRetries + if (pushNotificationSubscriptionMaxRetries != null) { + config.pushNotificationSubscriptionMaxRetries = pushNotificationSubscriptionMaxRetries } if (featureFlagRequestMaxRetries != null) { config.featureFlagRequestMaxRetries = featureFlagRequestMaxRetries diff --git a/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt b/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt new file mode 100644 index 000000000..230d005af --- /dev/null +++ b/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt @@ -0,0 +1,914 @@ +package com.posthog.internal + +import com.posthog.BuildConfig +import com.posthog.PROJECT_TOKEN +import com.posthog.PostHogConfig +import com.posthog.PostHogEvent +import com.posthog.TestHttpServers +import com.posthog.TestLogger +import com.posthog.awaitExecution +import com.posthog.date +import com.posthog.shutdownAndAwaitTermination +import com.posthog.unGzip +import okhttp3.OkHttpClient +import okhttp3.mockwebserver.MockResponse +import okhttp3.mockwebserver.MockWebServer +import okhttp3.mockwebserver.RecordedRequest +import okhttp3.mockwebserver.SocketPolicy +import org.junit.Assert.assertThrows +import org.junit.Rule +import org.junit.rules.TemporaryFolder +import java.io.File +import java.io.IOException +import java.text.SimpleDateFormat +import java.util.Date +import java.util.Locale +import java.util.TimeZone +import java.util.UUID +import java.util.concurrent.Executors +import java.util.concurrent.TimeUnit +import kotlin.test.AfterTest +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertFalse +import kotlin.test.assertNotEquals +import kotlin.test.assertNotNull +import kotlin.test.assertNull +import kotlin.test.assertTrue + +internal class PostHogCaptureV1Test { + @get:Rule + val httpServers = TestHttpServers() + + @get:Rule + val tmpDir = TemporaryFolder() + + private val executor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("CaptureV1Test")) + private val queues = mutableListOf>() + private val logger = TestLogger() + private val clock = FakePostHogDateProvider() + private val serializer = PostHogSerializer(PostHogConfig(PROJECT_TOKEN)) + + @AfterTest + fun cleanup() { + queues.forEach { + it.stop() + it.clear() + } + executor.shutdownAndAwaitTermination() + } + + private fun config(host: String): PostHogConfig = + PostHogConfig(PROJECT_TOKEN, host).apply { + logger = this@PostHogCaptureV1Test.logger + dateProvider = clock + } + + private fun api(host: String): PostHogApi = PostHogApi(config(host)) + + private fun queue( + http: MockWebServer, + flushAt: Int = 1, + storagePrefix: String = tmpDir.newFolder().absolutePath, + ai: Boolean = false, + ): PostHogQueue { + val config = + config(http.url("/").toString()).apply { + this.flushAt = flushAt + this.storagePrefix = storagePrefix + } + // pause time pinned to the past so a backoff never blocks the next flush + clock.setAddSecondsToCurrentDate(parseISO8601Date("1970-01-01T00:00:00.000Z")!!) + val api = PostHogApi(config) + val spec = if (ai) EndpointSpec.ai(config, api, config.storagePrefix) else EndpointSpec.batch(config, api, config.storagePrefix) + return PostHogQueue(config, spec, executor).also { queues.add(it) } + } + + private fun resultsResponse(vararg results: Pair): MockResponse { + val entries = results.joinToString(",") { (uuid, result) -> "\"$uuid\":{\"result\":\"$result\"}" } + return MockResponse().setBody("{\"results\":{$entries}}") + } + + private fun event( + name: String = "event", + properties: Map = mapOf("prop" to "value"), + options: Map? = null, + ): PostHogEvent = + PostHogEvent( + name, + distinctId = "distinctId", + properties = properties.toMutableMap(), + timestamp = date, + uuid = UUID.randomUUID(), + ).also { it.options = options?.toMutableMap() } + + @Suppress("UNCHECKED_CAST") + private fun body(request: RecordedRequest): Map = + serializer.deserialize>(request.body.unGzip().reader()) + + @Suppress("UNCHECKED_CAST") + private fun batch(request: RecordedRequest): List> = body(request)["batch"] as List> + + private fun wire(event: PostHogEvent): Map = captureV1Json(event, logger) + + @Suppress("UNCHECKED_CAST") + private fun Map.properties(): Map = this["properties"] as Map + + @Suppress("UNCHECKED_CAST") + private fun Map.options(): Map? = this["options"] as Map? + + @Test + fun `posts to the capture v1 endpoint with the required headers`() { + val http = httpServers.mockHttp(response = resultsResponse()) + clock.setCurrentDate(parseISO8601Date("2024-05-01T10:20:30.456Z")!!) + + api(http.url("/").toString()).captureV1(listOf(event())) + + val request = http.takeRequest() + assertEquals("POST", request.method) + assertEquals("/i/v1/analytics/events", request.path) + assertEquals("Bearer $PROJECT_TOKEN", request.headers["Authorization"]) + assertEquals("posthog-java/${BuildConfig.VERSION_NAME}", request.headers["PostHog-Sdk-Info"]) + assertEquals("posthog-java/${BuildConfig.VERSION_NAME}", request.headers["User-Agent"]) + assertEquals("1", request.headers["PostHog-Attempt"]) + assertEquals(7, UUID.fromString(assertNotNull(request.headers["PostHog-Request-Id"])).version()) + assertEquals("2024-05-01T10:20:30.456Z", request.headers["PostHog-Request-Timestamp"]) + assertEquals("application/json", request.headers["Content-Type"]) + assertEquals("gzip", request.headers["Content-Encoding"]) + } + + @Test + fun `captureAi posts to the AI endpoint with the same headers and body shape`() { + val http = httpServers.mockHttp(response = resultsResponse()) + clock.setCurrentDate(parseISO8601Date("2024-05-01T10:20:30.456Z")!!) + val event = event("\$ai_generation") + + api(http.url("/").toString()).captureAi(listOf(event)) + + val request = http.takeRequest() + assertEquals("POST", request.method) + assertEquals("/i/v1/ai/events", request.path) + assertEquals("Bearer $PROJECT_TOKEN", request.headers["Authorization"]) + assertEquals("posthog-java/${BuildConfig.VERSION_NAME}", request.headers["PostHog-Sdk-Info"]) + assertEquals("1", request.headers["PostHog-Attempt"]) + UUID.fromString(assertNotNull(request.headers["PostHog-Request-Id"])) + assertEquals("2024-05-01T10:20:30.456Z", request.headers["PostHog-Request-Timestamp"]) + assertEquals("application/json", request.headers["Content-Type"]) + assertEquals("gzip", request.headers["Content-Encoding"]) + val body = body(request) + assertEquals(setOf("created_at", "batch"), body.keys) + @Suppress("UNCHECKED_CAST") + assertEquals(listOf(event.uuid.toString()), (body["batch"] as List>).map { it["uuid"] }) + } + + @Test + fun `analytics and AI retries keep separate request identities`() { + val analytics = event() + val ai = event("\$ai_generation") + val http = httpServers.mockHttp(response = resultsResponse(analytics.uuid!! to "retry")) + http.enqueue(resultsResponse(ai.uuid!! to "retry")) + http.enqueue(resultsResponse(analytics.uuid!! to "ok")) + http.enqueue(resultsResponse(ai.uuid!! to "ok")) + val sut = api(http.url("/").toString()) + + sut.captureV1(listOf(analytics)) + sut.captureAi(listOf(ai)) + sut.captureV1(listOf(analytics)) + sut.captureAi(listOf(ai)) + + val requests = List(4) { http.takeRequest() } + assertEquals( + listOf("/i/v1/analytics/events", "/i/v1/ai/events", "/i/v1/analytics/events", "/i/v1/ai/events"), + requests.map { it.path }, + ) + assertEquals(listOf("1", "1", "2", "2"), requests.map { it.headers["PostHog-Attempt"] }) + val ids = requests.map { it.headers["PostHog-Request-Id"] } + assertNotEquals(ids[0], ids[1]) + assertEquals(ids[0], ids[2]) + assertEquals(ids[1], ids[3]) + } + + @Test + fun `the capture Bearer token replaces a custom Authorization header`() { + val http = httpServers.mockHttp(response = resultsResponse()) + val config = + config(http.url("/").toString()).apply { + requestHeaders = mapOf("Authorization" to "Bearer proxy", "X-Proxy" to "yes") + } + + PostHogApi(config).captureV1(listOf(event())) + + val request = http.takeRequest() + assertEquals("Bearer $PROJECT_TOKEN", request.headers["Authorization"]) + assertEquals("yes", request.headers["X-Proxy"]) + } + + @Test + fun `body carries created_at and the batch without api_key or sent_at`() { + val http = httpServers.mockHttp(response = resultsResponse()) + clock.setCurrentDate(parseISO8601Date("2024-05-01T10:20:30.456Z")!!) + val event = event() + + api(http.url("/").toString()).captureV1(listOf(event)) + + val body = body(http.takeRequest()) + assertEquals(setOf("created_at", "batch"), body.keys) + assertEquals("2024-05-01T10:20:30.456Z", body["created_at"]) + @Suppress("UNCHECKED_CAST") + assertEquals(listOf(event.uuid.toString()), (body["batch"] as List>).map { it["uuid"] }) + } + + @Test + fun `an event is sent with its root fields and an RFC 3339 UTC timestamp`() { + val event = event(properties = mapOf("prop" to "value", "\$lib" to "posthog-android", "\$lib_version" to "1.2.3")) + + val sent = wire(event) + + assertEquals(listOf("event", "uuid", "distinct_id", "timestamp", "properties"), sent.keys.toList()) + assertEquals("event", sent["event"]) + assertEquals(event.uuid.toString(), sent["uuid"]) + assertEquals("distinctId", sent["distinct_id"]) + assertEquals("2023-09-20T11:58:49.000Z", sent["timestamp"]) + // $lib and $lib_version come from the PostHog-Sdk-Info header + assertEquals(mapOf("prop" to "value"), sent.properties()) + assertNull(sent.options()) + } + + @Test + fun `lifts string session and window ids to the event root`() { + val sent = wire(event(properties = mapOf("\$session_id" to "session", "\$window_id" to ""))) + + assertEquals("session", sent["session_id"]) + assertEquals("", sent["window_id"]) + assertFalse(sent.properties().containsKey("\$session_id")) + assertFalse(sent.properties().containsKey("\$window_id")) + assertTrue(logger.messages.isEmpty()) + } + + @Test + fun `drops a non-string session id with a warning naming the key and JSON type`() { + val sent = wire(event(properties = mapOf("\$session_id" to 42, "\$window_id" to listOf("a")))) + + assertFalse(sent.containsKey("session_id")) + assertFalse(sent.containsKey("window_id")) + assertFalse(sent.properties().containsKey("\$session_id")) + assertFalse(sent.properties().containsKey("\$window_id")) + assertEquals( + listOf( + "dropping \$session_id: a number value is not a string", + "dropping \$window_id: a array value is not a string", + ), + logger.messages, + ) + } + + @Test + fun `drops a null session id silently`() { + val event = event() + @Suppress("UNCHECKED_CAST") + (event.properties as MutableMap)["\$session_id"] = null + + val sent = wire(event) + + assertFalse(sent.containsKey("session_id")) + assertFalse(sent.properties().containsKey("\$session_id")) + assertTrue(logger.messages.isEmpty()) + } + + @Test + fun `hoists legacy option properties into options and always removes them`() { + val event = + event( + properties = + mapOf( + "\$process_person_profile" to false, + "\$cookieless_mode" to "yes", + "\$ignore_sent_at" to true, + "\$product_tour_id" to 5, + ), + ) + + val sent = wire(event) + + // values are sent as given, the server reads them + assertEquals( + mapOf("cookieless_mode" to "yes", "disable_skew_correction" to true, "product_tour_id" to 5, "process_person_profile" to false), + sent.options(), + ) + assertEquals(mapOf(), sent.properties()) + } + + @Test + fun `an option set on the event wins over its legacy property`() { + val event = + event( + properties = mapOf("\$process_person_profile" to false, "\$cookieless_mode" to false), + options = mapOf("process_person_profile" to true, "cookieless_mode" to null, "custom" to "kept"), + ) + + val sent = wire(event) + + // a null option counts as unset, so the legacy property fills it; unknown keys pass through + assertEquals(mapOf("process_person_profile" to true, "cookieless_mode" to false, "custom" to "kept"), sent.options()) + assertFalse(sent.properties().containsKey("\$process_person_profile")) + assertFalse(sent.properties().containsKey("\$cookieless_mode")) + } + + @Test + fun `returns the uuids to retry and drops the rest from the batch`() { + val ok = event("ok") + val dropped = event("dropped") + val retry = event("retry") + val missing = event("missing") + val http = + httpServers.mockHttp( + response = + resultsResponse( + ok.uuid!! to "ok", + dropped.uuid!! to "drop", + retry.uuid!! to "retry", + ).setHeader("Retry-After", "7"), + ) + + val result = api(http.url("/").toString()).captureV1(listOf(ok, dropped, retry, missing)) + + assertEquals(setOf(retry.uuid.toString()), result.retryIds) + assertEquals(7, result.retryAfterSeconds) + assertTrue( + logger.messages.contains("Capture /i/v1/analytics/events: 1 dropped (no details: 1), 0 duplicate copies dropped, 1 to retry."), + ) + } + + @Test + fun `cleans and clips the server's drop reasons, most common first`() { + val events = List(3) { event("event") } + val noisy = "bad\\n\\u2028tag" + "x".repeat(100) + val http = + httpServers.mockHttp( + response = + MockResponse().setBody( + "{\"results\":{" + + "\"${events[0].uuid}\":{\"result\":\"drop\",\"details\":\"zzz\"}," + + "\"${events[1].uuid}\":{\"result\":\"drop\",\"details\":\"zzz\"}," + + "\"${events[2].uuid}\":{\"result\":\"drop\",\"details\":\"$noisy\"}}}", + ), + ) + + api(http.url("/").toString()).captureAi(events) + + val clean = "badtag" + "x".repeat(58) + assertEquals( + listOf("Capture /i/v1/ai/events: 3 dropped (zzz: 2, $clean: 1), 0 duplicate copies dropped, 0 to retry."), + logger.messages.filter { it.startsWith("Capture /") }, + ) + } + + @Test + fun `logs one line per batch with the endpoint and drop reasons, without event names, uuids or properties`() { + val misrouted = event("button_clicked", properties = mapOf("prompt" to "secret prompt")) + val tooBig = event("\$ai_generation", properties = mapOf("prompt" to "secret prompt")) + val http = + httpServers.mockHttp( + response = + MockResponse().setBody( + "{\"results\":{" + + "\"${misrouted.uuid}\":{\"result\":\"drop\",\"details\":\"misrouted_event\"}," + + "\"${tooBig.uuid}\":{\"result\":\"drop\",\"details\":\"ai_event_too_big\"}}}", + ), + ) + + api(http.url("/").toString()).captureAi(listOf(misrouted, tooBig)) + + assertEquals( + listOf("Capture /i/v1/ai/events: 2 dropped (ai_event_too_big: 1, misrouted_event: 1), 0 duplicate copies dropped, 0 to retry."), + logger.messages.filter { it.startsWith("Capture /") }, + ) + assertTrue( + logger.messages.none { + it.contains("secret prompt") || it.contains("button_clicked") || + it.contains(misrouted.uuid.toString()) || it.contains(tooBig.uuid.toString()) + }, + ) + } + + @Test + fun `counts the duplicate copies capture dropped`() { + val kept = event() + val copy = kept.copy() + val http = + httpServers.mockHttp( + response = MockResponse().setBody("{\"results\":{\"${kept.uuid}\":{\"result\":\"ok\",\"duplicates_dropped\":1}}}"), + ) + + val result = api(http.url("/").toString()).captureV1(listOf(kept, copy)) + + assertTrue(result.retryIds.isEmpty()) + assertTrue(logger.messages.contains("Capture /i/v1/analytics/events: 0 dropped, 1 duplicate copies dropped, 0 to retry.")) + } + + @Test + fun `clamps each duplicate count to the batch size`() { + val first = event() + val second = event() + val http = + httpServers.mockHttp( + response = + MockResponse().setBody( + "{\"results\":{\"${first.uuid}\":{\"result\":\"ok\",\"duplicates_dropped\":99999999999999999999}," + + "\"${second.uuid}\":{\"result\":\"ok\",\"duplicates_dropped\":-5}}}", + ), + ) + + api(http.url("/").toString()).captureV1(listOf(first, second)) + + assertTrue(logger.messages.contains("Capture /i/v1/analytics/events: 0 dropped, 2 duplicate copies dropped, 0 to retry.")) + } + + @Test + fun `a 2xx without readable results is a terminal failure`() { + for (body in listOf("not json", "{}", "{\"results\":[]}")) { + val http = httpServers.mockHttp(response = MockResponse().setBody(body)) + + val error = assertThrows(PostHogApiError::class.java) { api(http.url("/").toString()).captureV1(listOf(event())) } + + assertEquals(200, error.statusCode) + assertFalse(isCaptureV1RetriableStatusCode(error.statusCode)) + } + assertTrue(logger.messages.any { it.contains("without readable per-event results, dropping 1 events") }) + } + + @Test + fun `a 2xx whose transfer fails after the status is a terminal failure`() { + val http = + httpServers.mockHttp( + response = + MockResponse() + .setBody("{\"results\":{\"some-uuid\":{\"result\":\"retry\"}}}") + .setSocketPolicy(SocketPolicy.DISCONNECT_DURING_RESPONSE_BODY), + ) + + assertThrows(PostHogApiError::class.java) { api(http.url("/").toString()).captureV1(listOf(event())) } + } + + @Test + fun `a 2xx with results over 1 MiB is a terminal failure`() { + val event = event() + val padding = "x".repeat(1024 * 1024) + val http = + httpServers.mockHttp( + response = MockResponse().setBody("{\"results\":{\"${event.uuid}\":{\"result\":\"retry\"}},\"pad\":\"$padding\"}"), + ) + + assertThrows(PostHogApiError::class.java) { api(http.url("/").toString()).captureV1(listOf(event)) } + } + + @Test + fun `a 2xx whose results trickle past the read deadline is a terminal failure`() { + val event = event() + val padding = "x".repeat(16 * 1024) + // throttles the request read too, so allow a whole small request per period + val http = + httpServers.mockHttp( + response = + MockResponse() + .setBody("{\"results\":{\"${event.uuid}\":{\"result\":\"retry\"}},\"pad\":\"$padding\"}") + .throttleBody(1024, 200, TimeUnit.MILLISECONDS), + ) + val sut = api(http.url("/").toString()).apply { captureV1ResultsReadDeadlineMs = 300 } + + assertThrows(PostHogApiError::class.java) { sut.captureV1(listOf(event)) } + } + + @Test + fun `a 404 warns once with the capture URL`() { + val http = httpServers.mockHttp(total = 2, response = MockResponse().setResponseCode(404)) + val host = http.url("/").toString().trimEnd('/') + val sut = api(host) + + repeat(2) { assertThrows(PostHogApiError::class.java) { sut.captureV1(listOf(event())) } } + + assertEquals( + listOf( + "$host/i/v1/analytics/events returned 404. Events stay queued and are retried. " + + "If you use a reverse proxy or self-host PostHog, make sure it serves /i/v1/analytics/events.", + ), + logger.warnings, + ) + } + + @Test + fun `the 404 warning leaves out credentials and the query in the host`() { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(404)) + val origin = http.url("/").toString().trimEnd('/') + val host = origin.replace("://", "://proxy-user:proxy-password@") + "?secret=s3cr3t" + val sut = api(host) + + assertThrows(PostHogApiError::class.java) { sut.captureV1(listOf(event())) } + + val warning = logger.warnings.single() + assertTrue(warning.startsWith("$origin/"), warning) + listOf("proxy-user", "proxy-password", "s3cr3t").forEach { assertFalse(warning.contains(it), warning) } + } + + @Test + fun `a 503 with Retry-After 0 is not resent by the HTTP client`() { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(503).setHeader("Retry-After", "0")) + http.enqueue(resultsResponse()) + + assertThrows(PostHogApiError::class.java) { api(http.url("/").toString()).captureV1(listOf(event())) } + + assertEquals(1, http.requestCount) + } + + @Test + fun `a retry reuses the request id and created_at and increments the attempt`() { + val event = event() + val http = httpServers.mockHttp(response = resultsResponse(event.uuid!! to "retry")) + http.enqueue(resultsResponse(event.uuid!! to "ok")) + clock.setCurrentDate(parseISO8601Date("2024-05-01T10:20:30.000Z")!!) + val sut = api(http.url("/").toString()) + + sut.captureV1(listOf(event)) + clock.setCurrentDate(parseISO8601Date("2024-05-01T10:20:31.000Z")!!) + sut.captureV1(listOf(event)) + + val first = http.takeRequest() + val second = http.takeRequest() + assertEquals("1", first.headers["PostHog-Attempt"]) + assertEquals("2", second.headers["PostHog-Attempt"]) + assertEquals(first.headers["PostHog-Request-Id"], second.headers["PostHog-Request-Id"]) + assertEquals("2024-05-01T10:20:30.000Z", first.headers["PostHog-Request-Timestamp"]) + assertEquals("2024-05-01T10:20:31.000Z", second.headers["PostHog-Request-Timestamp"]) + assertEquals("2024-05-01T10:20:30.000Z", body(first)["created_at"]) + assertEquals("2024-05-01T10:20:30.000Z", body(second)["created_at"]) + } + + @Test + fun `a retriable status and a network error keep the request identity`() { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(503)) + http.enqueue(MockResponse().setSocketPolicy(SocketPolicy.NO_RESPONSE)) + http.enqueue(resultsResponse()) + val events = listOf(event()) + // a short read timeout turns the unanswered request into an IOException OkHttp doesn't retry itself + val config = + config(http.url("/").toString()).apply { + httpClient = OkHttpClient.Builder().readTimeout(500, TimeUnit.MILLISECONDS).build() + } + val sut = PostHogApi(config) + + assertThrows(PostHogApiError::class.java) { sut.captureV1(events) } + assertThrows(IOException::class.java) { sut.captureV1(events) } + sut.captureV1(events) + + val requestIds = List(3) { http.takeRequest() }.map { it.headers["PostHog-Request-Id"] to it.headers["PostHog-Attempt"] } + assertEquals(1, requestIds.map { it.first }.toSet().size) + assertEquals(listOf("1", "2", "3"), requestIds.map { it.second }) + } + + @Test + fun `a dropped connection is not resent by the HTTP client`() { + val http = httpServers.mockHttp(response = resultsResponse()) + // the second request reuses the pooled connection, which OkHttp would otherwise retry on a new one + http.enqueue(MockResponse().setSocketPolicy(SocketPolicy.DISCONNECT_AFTER_REQUEST)) + http.enqueue(resultsResponse()) + val sut = api(http.url("/").toString()) + + sut.captureV1(listOf(event())) + assertThrows(IOException::class.java) { sut.captureV1(listOf(event())) } + + assertEquals(2, http.requestCount) + } + + @Test + fun `debug logs leave out event content`() { + val sent = event(properties = mapOf("email" to "user@example.com")) + val http = httpServers.mockHttp(response = resultsResponse(sent.uuid!! to "ok")) + val config = config(http.url("/").toString()).apply { debug = true } + + PostHogApi(config).captureV1(listOf(sent)) + + assertTrue(logger.messages.any { it.endsWith("/i/v1/analytics/events: 1 events") }) + assertTrue(logger.messages.none { it.contains("user@example.com") || it.contains(sent.uuid.toString()) }) + } + + @Test + fun `a different set of events starts a new request identity`() { + val event = event() + val other = event("other") + val http = httpServers.mockHttp(response = resultsResponse(event.uuid!! to "retry")) + http.enqueue(resultsResponse(event.uuid!! to "ok", other.uuid!! to "ok")) + val sut = api(http.url("/").toString()) + + sut.captureV1(listOf(event)) + sut.captureV1(listOf(event, other)) + + val first = http.takeRequest() + val second = http.takeRequest() + assertEquals("1", second.headers["PostHog-Attempt"]) + assertNotEquals(first.headers["PostHog-Request-Id"], second.headers["PostHog-Request-Id"]) + } + + @Test + fun `sending other events in between keeps the pending retry identity`() { + val retried = event() + val other = event("other") + val http = httpServers.mockHttp(response = resultsResponse(retried.uuid!! to "retry")) + http.enqueue(resultsResponse(other.uuid!! to "ok")) + http.enqueue(resultsResponse(retried.uuid!! to "ok")) + val sut = api(http.url("/").toString()) + + sut.captureV1(listOf(retried)) + sut.captureV1(listOf(other)) + sut.captureV1(listOf(retried)) + + val (first, between, resent) = List(3) { http.takeRequest() } + assertEquals("1", between.headers["PostHog-Attempt"]) + assertNotEquals(first.headers["PostHog-Request-Id"], between.headers["PostHog-Request-Id"]) + assertEquals("2", resent.headers["PostHog-Attempt"]) + assertEquals(first.headers["PostHog-Request-Id"], resent.headers["PostHog-Request-Id"]) + assertEquals(body(first)["created_at"], body(resent)["created_at"]) + } + + @Test + fun `a terminal status starts a new request identity on the next send`() { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(400)) + http.enqueue(resultsResponse()) + val events = listOf(event()) + val sut = api(http.url("/").toString()) + + assertThrows(PostHogApiError::class.java) { sut.captureV1(events) } + sut.captureV1(events) + + val first = http.takeRequest() + val second = http.takeRequest() + assertEquals("1", second.headers["PostHog-Attempt"]) + assertNotEquals(first.headers["PostHog-Request-Id"], second.headers["PostHog-Request-Id"]) + } + + @Test + fun `a non-2xx throws with its status and Retry-After`() { + for (status in listOf(408, 500, 502, 503, 504, 429, 404, 400, 413)) { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(status).setHeader("Retry-After", "7")) + + val error = assertThrows(PostHogApiError::class.java) { api(http.url("/").toString()).captureV1(listOf(event())) } + + assertEquals(status, error.statusCode) + assertEquals(7, error.retryAfterSeconds) + } + } + + @Test + fun `reads an HTTP-date Retry-After as seconds from now`() { + val format = SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss 'GMT'", Locale.US).apply { timeZone = TimeZone.getTimeZone("GMT") } + val now = clock.currentTimeMillis() + for ((date, seconds) in listOf(Date(now + 20_000) to 20, Date(now - 60_000) to 0)) { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(503).setHeader("Retry-After", format.format(date))) + + val error = assertThrows(PostHogApiError::class.java) { api(http.url("/").toString()).captureV1(listOf(event())) } + + assertEquals(seconds, error.retryAfterSeconds) + } + } + + @Test + fun `follows a same-origin 307 with the same body and headers`() { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(307).setHeader("Location", "/proxied/events")) + http.enqueue(MockResponse().setResponseCode(308).setHeader("Location", "/final/events")) + http.enqueue(resultsResponse()) + + api(http.url("/").toString()).captureV1(listOf(event())) + + val requests = List(3) { http.takeRequest() } + assertEquals(listOf("/i/v1/analytics/events", "/proxied/events", "/final/events"), requests.map { it.path }) + requests.forEach { + assertEquals("POST", it.method) + assertEquals("Bearer $PROJECT_TOKEN", it.headers["Authorization"]) + assertEquals(requests[0].headers["PostHog-Request-Id"], it.headers["PostHog-Request-Id"]) + assertEquals(requests[0].headers["PostHog-Request-Timestamp"], it.headers["PostHog-Request-Timestamp"]) + } + assertEquals(1, requests.map { body(it) }.toSet().size) + } + + @Test + fun `does not follow a 302`() { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(302).setHeader("Location", "/elsewhere")) + http.enqueue(resultsResponse()) + + val error = assertThrows(PostHogApiError::class.java) { api(http.url("/").toString()).captureV1(listOf(event())) } + + assertEquals(302, error.statusCode) + assertEquals(1, http.requestCount) + } + + @Test + fun `does not follow a 307 to another origin`() { + val other = httpServers.mockHttp(response = resultsResponse()) + val http = + httpServers.mockHttp( + response = MockResponse().setResponseCode(307).setHeader("Location", other.url("/events").toString()), + ) + + val error = assertThrows(PostHogApiError::class.java) { api(http.url("/").toString()).captureV1(listOf(event())) } + + assertEquals(307, error.statusCode) + assertEquals(1, http.requestCount) + assertEquals(0, other.requestCount) + assertTrue(logger.messages.contains("Capture did not follow a 307 redirect.")) + } + + @Test + fun `stops after five redirects`() { + val http = httpServers.mockHttp(total = 6, response = MockResponse().setResponseCode(307).setHeader("Location", "/again")) + http.enqueue(resultsResponse()) + + val error = assertThrows(PostHogApiError::class.java) { api(http.url("/").toString()).captureV1(listOf(event())) } + + assertEquals(307, error.statusCode) + assertEquals(6, http.requestCount) + } + + @Test + fun `queue keeps only the events capture asked to retry and resends them under the same request id`() { + val ok = event("ok") + val dropped = event("dropped") + val retry = event("retry") + val http = httpServers.mockHttp(response = resultsResponse(ok.uuid!! to "ok", dropped.uuid!! to "drop", retry.uuid!! to "retry")) + http.enqueue(resultsResponse(retry.uuid!! to "ok")) + val sut = queue(http, flushAt = 3) + + sut.add(ok) + sut.add(dropped) + sut.add(retry) + executor.awaitExecution() + + assertEquals(1, http.requestCount) + assertEquals(1, sut.dequeList.size) + assertEquals(1, sut.currentRetryCountForTesting) + assertEquals( + listOf(retry.uuid.toString()), + sut.dequeList.map { file -> file.reader().use { serializer.deserialize(it).uuid.toString() } }, + ) + + sut.flush() + executor.awaitExecution() + + assertEquals(2, http.requestCount) + assertTrue(sut.dequeList.isEmpty()) + assertEquals(0, sut.currentRetryCountForTesting) + val first = http.takeRequest() + val second = http.takeRequest() + assertEquals(listOf(retry.uuid.toString()), batch(second).map { it["uuid"] }) + assertEquals("2", second.headers["PostHog-Attempt"]) + assertEquals(first.headers["PostHog-Request-Id"], second.headers["PostHog-Request-Id"]) + } + + @Test + fun `queue resends a failed batch alone under the same request id`() { + val failed = event("failed") + val later = event("later") + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(503)) + http.enqueue(resultsResponse(failed.uuid!! to "ok")) + http.enqueue(resultsResponse(later.uuid!! to "ok")) + val sut = queue(http) + + sut.add(failed) + executor.awaitExecution() + sut.add(later) + executor.awaitExecution() + sut.flush() + executor.awaitExecution() + + assertEquals(3, http.requestCount) + val requests = List(3) { http.takeRequest() } + assertEquals( + listOf(listOf(failed.uuid.toString()), listOf(failed.uuid.toString()), listOf(later.uuid.toString())), + requests.map { request -> batch(request).map { it["uuid"] } }, + ) + assertEquals(listOf("1", "2", "1"), requests.map { it.headers["PostHog-Attempt"] }) + assertEquals(requests[0].headers["PostHog-Request-Id"], requests[1].headers["PostHog-Request-Id"]) + assertNotEquals(requests[1].headers["PostHog-Request-Id"], requests[2].headers["PostHog-Request-Id"]) + assertTrue(sut.dequeList.isEmpty()) + } + + @Test + fun `queue resends only the retried events while newer ones wait`() { + val ok = event("ok") + val retry = event("retry") + val later = event("later") + val http = httpServers.mockHttp(response = resultsResponse(ok.uuid!! to "ok", retry.uuid!! to "retry")) + http.enqueue(resultsResponse(retry.uuid!! to "ok")) + val sut = queue(http, flushAt = 2) + + sut.add(ok) + sut.add(retry) + executor.awaitExecution() + sut.add(later) + executor.awaitExecution() + + assertEquals(2, http.requestCount) + val first = http.takeRequest() + val second = http.takeRequest() + assertEquals(listOf(retry.uuid.toString()), batch(second).map { it["uuid"] }) + assertEquals("2", second.headers["PostHog-Attempt"]) + assertEquals(first.headers["PostHog-Request-Id"], second.headers["PostHog-Request-Id"]) + assertEquals(1, sut.dequeList.size) + } + + @Test + fun `AI queue keeps only the events the AI endpoint asked to retry`() { + val ok = event("\$ai_generation") + val retry = event("\$ai_span") + val http = httpServers.mockHttp(response = resultsResponse(ok.uuid!! to "ok", retry.uuid!! to "retry")) + val sut = queue(http, flushAt = 2, ai = true) + + sut.add(ok) + sut.add(retry) + executor.awaitExecution() + + assertEquals("/i/v1/ai/events", http.takeRequest().path) + assertEquals(1, sut.currentRetryCountForTesting) + assertEquals( + listOf(retry.uuid.toString()), + sut.dequeList.map { file -> file.reader().use { serializer.deserialize(it).uuid.toString() } }, + ) + } + + @Test + fun `queue drops the batch on 400 and keeps it on 429`() { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(400)) + http.enqueue(MockResponse().setResponseCode(429)) + val sut = queue(http) + + sut.add(event()) + executor.awaitExecution() + assertTrue(sut.dequeList.isEmpty()) + + sut.add(event()) + executor.awaitExecution() + assertEquals(1, sut.dequeList.size) + } + + @Test + fun `queue drops a batch whose 2xx results can't be read without resending it`() { + val http = httpServers.mockHttp(response = MockResponse().setBody("not json")) + http.enqueue(resultsResponse()) + val sut = queue(http) + + sut.add(event()) + executor.awaitExecution() + + assertTrue(sut.dequeList.isEmpty()) + assertEquals(1, http.requestCount) + assertFalse(logger.messages.any { it.contains("successfully") }) + } + + @Test + fun `queued events round-trip their options through disk`() { + val http = httpServers.mockHttp(response = MockResponse().setResponseCode(503)) + val sut = queue(http) + + sut.add(event(options = mapOf("process_person_profile" to false, "product_tour_id" to 7))) + executor.awaitExecution() + + val stored = sut.dequeList.single().reader().use { serializer.deserialize(it) } + val options = mapOf("process_person_profile" to false, "product_tour_id" to 7) + assertEquals?>(options, stored.options) + assertEquals(options, batch(http.takeRequest()).single().options()) + } + + @Test + fun `a 3x event queued on disk is sent in the capture v1 shape`() { + val uuid = UUID.randomUUID() + val storagePrefix = tmpDir.newFolder().absolutePath + File(storagePrefix, PROJECT_TOKEN).apply { mkdirs() }.resolve("$uuid.event").writeText( + "{\"uuid\":\"$uuid\",\"event\":\"legacy\",\"distinct_id\":\"d\",\"timestamp\":\"2023-09-19T07:23:00.165Z\"," + + "\"properties\":{\"a\":\"b\",\"\$process_person_profile\":false,\"\$lib\":\"posthog-android\"," + + "\"\$lib_version\":\"3.20.0\",\"\$session_id\":\"session\"}}", + ) + val http = httpServers.mockHttp(response = resultsResponse(uuid to "ok")) + val sut = queue(http, storagePrefix = storagePrefix) + + sut.flush() + executor.awaitExecution() + + val sent = batch(http.takeRequest()).single() + assertEquals(uuid.toString(), sent["uuid"]) + assertEquals("session", sent["session_id"]) + assertEquals(mapOf("process_person_profile" to false), sent.options()) + assertEquals(mapOf("a" to "b"), sent.properties()) + assertTrue(sut.dequeList.isEmpty()) + } + + @Test + fun `queued events without options still decode`() { + val event = event() + val json = + "{\"uuid\":\"${event.uuid}\",\"event\":\"legacy\",\"distinct_id\":\"d\"," + + "\"properties\":{\"a\":1},\"timestamp\":\"2023-09-19T07:23:00.165Z\"}" + + val decoded = serializer.deserialize(json.reader()) + + assertEquals("legacy", decoded.event) + assertNull(decoded.options) + } +} diff --git a/posthog/src/test/java/com/posthog/internal/PostHogPushSubscriptionManagerTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogPushSubscriptionManagerTest.kt index dfbf5e903..6227d1764 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogPushSubscriptionManagerTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogPushSubscriptionManagerTest.kt @@ -94,7 +94,7 @@ internal class PostHogPushSubscriptionManagerTest { PostHogConfig(PROJECT_TOKEN, host = http.url("/").toString()).apply { this.storagePrefix = storagePrefix this.networkStatus = networkStatus - this.maxRetries = maxRetries + this.pushNotificationSubscriptionMaxRetries = maxRetries this.encryption = encryption this.cachePreferences = preferences this.dateProvider = clock diff --git a/posthog/src/test/java/com/posthog/internal/PostHogQueueByteLimitsTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogQueueByteLimitsTest.kt new file mode 100644 index 000000000..0630c616c --- /dev/null +++ b/posthog/src/test/java/com/posthog/internal/PostHogQueueByteLimitsTest.kt @@ -0,0 +1,251 @@ +package com.posthog.internal + +import com.posthog.PROJECT_TOKEN +import com.posthog.PostHogConfig +import com.posthog.TestLogger +import com.posthog.awaitExecution +import com.posthog.shutdownAndAwaitTermination +import org.junit.Rule +import org.junit.rules.TemporaryFolder +import java.io.File +import java.util.UUID +import java.util.concurrent.CountDownLatch +import java.util.concurrent.Executors +import kotlin.test.AfterTest +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertTrue + +/** + * The byte limits of [EndpointSpec] as [PostHogQueue] applies them, on a synthetic record whose + * stored size is its payload length. + */ +internal class PostHogQueueByteLimitsTest { + @get:Rule + val tmpDir = TemporaryFolder() + + private val executor = Executors.newSingleThreadScheduledExecutor(PostHogThreadFactory("Test")) + private val logger = TestLogger() + private val sent = mutableListOf>() + + @Volatile + private var connected = true + + private lateinit var config: PostHogConfig + private lateinit var storagePrefix: String + + @AfterTest + fun cleanup() { + executor.shutdownAndAwaitTermination() + } + + private fun record( + id: String, + bytes: Int, + ): String = id.padEnd(bytes, 'x') + + private fun queue( + maxBatchBytes: Long? = null, + maxQueueBytes: Long? = null, + flushAt: Int = 50, + maxQueueSize: Int = 1000, + ): PostHogQueue { + storagePrefix = tmpDir.newFolder().absolutePath + config = + PostHogConfig(PROJECT_TOKEN).apply { + logger = this@PostHogQueueByteLimitsTest.logger + networkStatus = + object : PostHogNetworkStatus { + override fun isConnected(): Boolean = connected + } + } + val spec = + EndpointSpec( + recordsLabel = "blobs", + storagePrefix = storagePrefix, + initialCap = { 50 }, + initialFlushAt = { flushAt }, + maxQueueSize = { maxQueueSize }, + flushIntervalSeconds = { 30 }, + encode = { record, stream -> stream.writer().use { it.write(record) } }, + decode = { stream -> stream.reader().use { it.readText() } }, + describe = { record -> "blob ${record.trimEnd('x')}" }, + send = { records -> + sent.add(records.map { it.trimEnd('x') }) + SendResult() + }, + isRetriableStatusCode = { false }, + maxBatchBytes = maxBatchBytes, + maxQueueBytes = maxQueueBytes, + ) + return PostHogQueue(config, spec, executor) + } + + private fun queuedIds(sut: PostHogQueue): List = sut.dequeList.map { it.readText().trimEnd('x') } + + @Test + fun `a flush splits the queue into requests at the byte limit`() { + val sut = queue(maxBatchBytes = 100) + connected = false + sut.add(record("a", 40)) + sut.add(record("b", 40)) + sut.add(record("c", 40)) + executor.awaitExecution() + connected = true + + sut.flush() + executor.awaitExecution() + + assertEquals(listOf(listOf("a", "b"), listOf("c")), sent) + assertTrue(sut.dequeList.isEmpty()) + assertEquals(0L, sut.queuedBytesForTesting) + } + + @Test + fun `a queued file deleted from disk is subtracted with the size it was counted with`() { + val sut = queue(maxBatchBytes = 100) + connected = false + sut.add(record("a", 40)) + sut.add(record("b", 40)) + executor.awaitExecution() + sut.dequeList.first().delete() + connected = true + + sut.flush() + executor.awaitExecution() + + assertEquals(listOf(listOf("b")), sent) + assertEquals(0L, sut.queuedBytesForTesting) + } + + @Test + fun `addMeasured drops the oldest waiting records once those waiting to be written are over the limits`() { + val sut = queue(maxQueueBytes = 100, maxQueueSize = 3) + val release = CountDownLatch(1) + executor.execute { release.await() } + + assertTrue(sut.addMeasured(record("a", 40), 40)) + assertTrue(sut.addMeasured(record("b", 40), 40)) + // 120 bytes waiting: a is dropped + assertTrue(sut.addMeasured(record("c", 40), 40)) + assertTrue(sut.addMeasured(record("d", 20), 20)) + // 4 records waiting: b is dropped + assertTrue(sut.addMeasured(record("e", 1), 1)) + // dropped while waiting, before the disk limits ever see them + assertEquals(2, logger.messages.count { it.contains("blobs are waiting to be written, the oldest 1 are dropped") }) + // one executor task per waiting record, not per add + assertEquals(3, sut.pendingTasksForTesting) + release.countDown() + executor.awaitExecution() + + assertEquals(listOf("c", "d", "e"), queuedIds(sut)) + } + + @Test + fun `a record over the byte limit is sent alone and keeps its place`() { + val sut = queue(maxBatchBytes = 100) + connected = false + sut.add(record("a", 40)) + sut.add(record("big", 150)) + sut.add(record("c", 40)) + executor.awaitExecution() + connected = true + + sut.flush() + executor.awaitExecution() + + assertEquals(listOf(listOf("a"), listOf("big"), listOf("c")), sent) + } + + @Test + fun `flushes once a request's worth of bytes is queued, before flushAt`() { + val sut = queue(maxBatchBytes = 100, flushAt = 50) + + sut.add(record("a", 60)) + executor.awaitExecution() + assertTrue(sent.isEmpty()) + + sut.add(record("b", 60)) + executor.awaitExecution() + + // one request's worth: a alone, since b doesn't fit next to it + assertEquals(listOf(listOf("a")), sent) + assertEquals(listOf("b"), queuedIds(sut)) + } + + @Test + fun `evicts the oldest records over maxQueueBytes when a record is added`() { + val sut = queue(maxQueueBytes = 100, flushAt = 50) + + sut.add(record("a", 40)) + sut.add(record("b", 40)) + sut.add(record("c", 40)) + executor.awaitExecution() + assertEquals(listOf("b", "c"), queuedIds(sut)) + + // the newest record is kept even when it's over the limit on its own + sut.add(record("big", 150)) + executor.awaitExecution() + assertEquals(listOf("big"), queuedIds(sut)) + assertEquals(sut.dequeList.single().length(), sut.queuedBytesForTesting) + assertEquals(1, File(storagePrefix, PROJECT_TOKEN).listFiles()!!.size) + assertTrue(logger.messages.any { it == "Queue is over 100 bytes, the oldest 1 blobs are dropped." }) + } + + @Test + fun `evicts the oldest cached records over maxQueueBytes on load`() { + val sut = queue(maxQueueBytes = 100, flushAt = 50) + val dir = File(storagePrefix, PROJECT_TOKEN).apply { mkdirs() } + val cached = + listOf("a", "b", "c").mapIndexed { index, id -> + File(dir, "${UUID.randomUUID()}.event").apply { + writeText(record(id, 40)) + setLastModified(System.currentTimeMillis() - (3 - index) * 1000L) + } + } + + sut.reloadFromDisk() + + assertEquals(cached.drop(1), sut.dequeList) + assertEquals(listOf("b", "c"), queuedIds(sut)) + assertEquals(2, dir.listFiles()!!.size) + } + + @Test + fun `the analytics spec caps a request at 5 MiB and the AI spec adds the disk cap`() { + val config = PostHogConfig(PROJECT_TOKEN) + val api = PostHogApi(config) + + val batch = EndpointSpec.batch(config, api, null) + assertEquals(5L * 1024 * 1024, batch.maxBatchBytes) + assertEquals(null, batch.maxQueueBytes) + + val ai = EndpointSpec.ai(config, api, null) + assertEquals(5L * 1024 * 1024, ai.maxBatchBytes) + assertEquals(50L * 1024 * 1024, ai.maxQueueBytes) + assertEquals(100, ai.maxQueueSize(config)) + } + + @Test + fun `the AI event limit can only be lowered and non-positive settings use the defaults`() { + val config = PostHogConfig(PROJECT_TOKEN) + val api = PostHogApi(config) + + config.captureAiMaxEventBytes = 1024 + assertEquals(1024L, config.captureAiMaxStoredEventBytes) + config.captureAiMaxEventBytes = 16 * 1024 * 1024 + assertEquals(8L * 1024 * 1024 + 64 * 1024, config.captureAiMaxStoredEventBytes) + config.captureAiMaxEventBytes = 0 + assertEquals(8L * 1024 * 1024 + 64 * 1024, config.captureAiMaxStoredEventBytes) + + config.captureAiMaxQueueSize = 0 + assertEquals(100, EndpointSpec.ai(config, api, null).maxQueueSize(config)) + config.captureAiMaxQueueSize = 7 + assertEquals(7, EndpointSpec.ai(config, api, null).maxQueueSize(config)) + + config.captureAiTimeout = -1 + assertEquals(60, config.effectiveCaptureAiTimeoutSeconds) + config.captureAiTimeout = 5 + assertEquals(5, config.effectiveCaptureAiTimeoutSeconds) + } +} diff --git a/posthog/src/test/java/com/posthog/internal/PostHogQueueDurabilityTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogQueueDurabilityTest.kt index 7b2822900..399c09557 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogQueueDurabilityTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogQueueDurabilityTest.kt @@ -47,7 +47,7 @@ internal class PostHogQueueDurabilityTest { maxQueueSize = capacity maxBatchSize = batchSize flushAt = 100 - maxRetries = 2 + pushNotificationSubscriptionMaxRetries = 2 dateProvider = clock this.networkStatus = networkStatus } @@ -66,10 +66,17 @@ internal class PostHogQueueDurabilityTest { } }, describe = { it }, - send = send, - isRetriableStatusCode = ::isEventsRetriableStatusCode, + send = { + send(it) + SendResult() + }, + isRetriableStatusCode = ::isCaptureV1RetriableStatusCode, ) - return PostHogQueue(config, spec, executor).also { queues.add(it) } + return PostHogQueue(config, spec, executor).also { + // the midpoint of the jitter range keeps the unjittered delays + it.jitterUnit = { 0.5 } + queues.add(it) + } } @Test @@ -111,7 +118,7 @@ internal class PostHogQueueDurabilityTest { @Test fun `retryable failures retain exact entries with capped backoff then reset after success`() { - val failures = listOf(408, 429, 500, 502, 503, 504) + val failures = listOf(408, 500, 502, 503, 504) var status = failures.first() var attempts = 0 val sut = diff --git a/posthog/src/test/java/com/posthog/internal/PostHogQueueTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogQueueTest.kt index 35b447160..9b6222428 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogQueueTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogQueueTest.kt @@ -5,6 +5,7 @@ import com.posthog.PostHogConfig import com.posthog.PostHogEvent import com.posthog.PostHogEventName import com.posthog.TestHttpServers +import com.posthog.TestLogger import com.posthog.awaitExecution import com.posthog.generateEvent import com.posthog.internal.errortracking.ThrowableCoercer @@ -69,8 +70,9 @@ internal class PostHogQueueTest { dateProvider: PostHogDateProvider = PostHogDeviceDateProvider(), maxBatchSize: Int = 50, networkStatus: PostHogNetworkStatus? = null, - maxRetries: Int = 3, + pushNotificationSubscriptionMaxRetries: Int = 3, httpClient: OkHttpClient? = null, + logger: PostHogLogger? = null, ): PostHogQueue { val config = PostHogConfig(PROJECT_TOKEN, host).apply { @@ -80,13 +82,26 @@ internal class PostHogQueueTest { this.networkStatus = networkStatus this.maxBatchSize = maxBatchSize this.dateProvider = dateProvider - this.maxRetries = maxRetries + this.pushNotificationSubscriptionMaxRetries = pushNotificationSubscriptionMaxRetries this.httpClient = httpClient + logger?.let { this.logger = it } } val api = PostHogApi(config) return PostHogQueue(config, EndpointSpec.batch(config, api, config.storagePrefix), executor).also { queues.add(it) } } + @Test + fun `queueing an event logs nothing per event`() { + val http = mockHttp() + val logger = TestLogger() + val sut = getSut(host = http.url("/").toString(), logger = logger) + + sut.add(generateEvent()) + awaitQueue() + + assertTrue(logger.messages.isEmpty(), logger.messages.toString()) + } + @Test fun `respect maxQueueSize and deletes the first if full`() { val http = mockHttp() @@ -302,7 +317,7 @@ internal class PostHogQueueTest { host = http.url("/").toString(), storagePrefix = path, flushAt = 1, - maxRetries = 0, + pushNotificationSubscriptionMaxRetries = 0, networkStatus = object : PostHogNetworkStatus { override fun isConnected() = connected @@ -358,7 +373,7 @@ internal class PostHogQueueTest { storagePrefix = path, flushAt = 100, maxQueueSize = 2, - maxRetries = 0, + pushNotificationSubscriptionMaxRetries = 0, dateProvider = fakeCurrentTime, ) @@ -398,8 +413,8 @@ internal class PostHogQueueTest { } @Test - fun `retry after remains authoritative beyond the exponential backoff cap`() { - val http = mockHttp(response = MockResponse().setResponseCode(429).setHeader("Retry-After", "120").setBody("error")) + fun `retry after is a floor capped at the exponential backoff cap`() { + val http = mockHttp(response = MockResponse().setResponseCode(503).setHeader("Retry-After", "120").setBody("error")) var scheduledDelay = 0 val dateProvider = object : PostHogDateProvider { @@ -427,7 +442,52 @@ internal class PostHogQueueTest { sut.add(generateEvent()) executor.awaitExecution() - assertEquals(120, scheduledDelay) + assertEquals(30, scheduledDelay) + assertEquals(1, sut.dequeList.size) + } finally { + sut.clear() + awaitQueue() + http.shutdown() + } + } + + @Test + fun `a partial retry honors the Retry-After of the 2xx`() { + val event = generateEvent(givenUuuid = UUID.randomUUID()) + val http = + mockHttp( + response = + MockResponse() + .setHeader("Retry-After", "10") + .setBody("{\"results\":{\"${event.uuid}\":{\"result\":\"retry\"}}}"), + ) + var scheduledDelay = 0 + val dateProvider = + object : PostHogDateProvider { + override fun currentDate() = Date() + + override fun addSecondsToCurrentDate(seconds: Int): Date { + scheduledDelay = seconds + return Date(System.currentTimeMillis() + seconds * 1000L) + } + + override fun currentTimeMillis() = System.currentTimeMillis() + + override fun nanoTime() = System.nanoTime() + } + val sut = + getSut( + host = http.url("/").toString(), + storagePrefix = tmpDir.newFolder().absolutePath, + flushAt = 1, + dateProvider = dateProvider, + ) + + try { + sut.add(event) + executor.awaitExecution() + + assertEquals(10, scheduledDelay) assertEquals(1, sut.dequeList.size) } finally { sut.clear() @@ -458,7 +518,7 @@ internal class PostHogQueueTest { host = http.url("/").toString(), storagePrefix = path, flushAt = 100, - maxRetries = 0, + pushNotificationSubscriptionMaxRetries = 0, dateProvider = fakeCurrentTime, httpClient = httpClient, ) @@ -569,8 +629,9 @@ internal class PostHogQueueTest { } else { throw IOException("retain replacements after their later send attempt") } + SendResult() }, - isRetriableStatusCode = ::isEventsRetriableStatusCode, + isRetriableStatusCode = ::isCaptureV1RetriableStatusCode, ) val sut = PostHogQueue(config, spec, queueExecutor) @@ -612,7 +673,7 @@ internal class PostHogQueueTest { } @Test - fun `does not delete file if API is 3xx`() { + fun `deletes file if API is 3xx`() { val http = mockHttp(response = MockResponse().setResponseCode(300).setBody("error")) val url = http.url("/") @@ -623,8 +684,48 @@ internal class PostHogQueueTest { awaitQueue() - assertEquals(1, sut.dequeList.size) - assertEquals(1, File(path, PROJECT_TOKEN).listFiles()!!.size) + assertEquals(0, sut.dequeList.size) + assertEquals(0, File(path, PROJECT_TOKEN).listFiles()!!.size) + } + + @Test + fun `backoff doubles from one to thirty seconds with 25 percent jitter kept in milliseconds`() { + val http = mockHttp(total = 20, response = MockResponse().setResponseCode(503).setBody("error")) + val dateProvider = + object : PostHogDateProvider { + override fun currentDate() = Date() + + // the epoch plus the delay, so the pause stays in the past and every flush sends + override fun addSecondsToCurrentDate(seconds: Int) = Date(seconds * 1000L) + + override fun currentTimeMillis() = System.currentTimeMillis() + + override fun nanoTime() = System.nanoTime() + } + val sut = getSut(host = http.url("/").toString(), flushAt = 1, dateProvider = dateProvider) + var jitter = 0.0 + sut.jitterUnit = { jitter } + val delays = mutableListOf() + sut.add(generateEvent()) + executor.awaitExecution() + delays.add(sut.pausedUntil!!.time) + + repeat(5) { + sut.flush() + executor.awaitExecution() + delays.add(sut.pausedUntil!!.time) + } + jitter = 0.999 + repeat(3) { + sut.flush() + executor.awaitExecution() + delays.add(sut.pausedUntil!!.time) + } + // -25% of 1, 2, 4, 8, 16 and 30 s; +25% of 64 s is capped at 30 s + assertEquals(listOf(750L, 1500L, 3000L, 6000L, 12000L, 22500L, 30000L, 30000L, 30000L), delays) + + sut.clear() + awaitQueue() } @Test @@ -662,7 +763,7 @@ internal class PostHogQueueTest { @Test fun `clear deletes all files and clean the queue`() { - val http = mockHttp(response = MockResponse().setResponseCode(300).setBody("error")) + val http = mockHttp(response = MockResponse().setResponseCode(503).setBody("error")) val url = http.url("/") val path = tmpDir.newFolder().absolutePath @@ -685,7 +786,7 @@ internal class PostHogQueueTest { @Test fun `flush flushes the queue`() { - val http = mockHttp(response = MockResponse().setResponseCode(300).setBody("error")) + val http = mockHttp(response = MockResponse().setResponseCode(503).setBody("error")) val url = http.url("/") val fakeCurrentTime = FakePostHogDateProvider() @@ -715,7 +816,7 @@ internal class PostHogQueueTest { @Test fun `flush flushes the queue but respect maxBatchSize`() { - val http = mockHttp(response = MockResponse().setResponseCode(300).setBody("error")) + val http = mockHttp(response = MockResponse().setResponseCode(503).setBody("error")) val url = http.url("/") val fakeCurrentTime = FakePostHogDateProvider() @@ -733,7 +834,7 @@ internal class PostHogQueueTest { assertEquals(1, sut.dequeList.size) assertEquals(1, File(path, PROJECT_TOKEN).listFiles()!!.size) - http.enqueue(MockResponse().setResponseCode(300).setBody("error")) + http.enqueue(MockResponse().setResponseCode(503).setBody("error")) sut.add(generateEvent(givenUuuid = UUID.randomUUID())) @@ -872,8 +973,21 @@ internal class PostHogQueueTest { val e = PostHogApiError(400, "", null) val config = PostHogConfig(PROJECT_TOKEN) val limits = initialBatchLimits(config) + val logger = TestLogger() - assertTrue(deleteFilesIfAPIError(e, limits, actualBatchSize = limits.cap, logger = config.logger)) + assertTrue(deleteFilesIfAPIError(e, limits, actualBatchSize = limits.cap, logger = logger)) + assertEquals(listOf("Flushing failed with 400, dropping ${limits.cap} records."), logger.messages) + } + + @Test + fun `the drop log names the records it drops`() { + val e = PostHogApiError(400, "", null) + val config = PostHogConfig(PROJECT_TOKEN) + val logger = TestLogger() + + deleteFilesIfAPIError(e, initialBatchLimits(config), actualBatchSize = 3, logger = logger, recordsLabel = "AI events") + + assertEquals(listOf("Flushing failed with 400, dropping 3 AI events."), logger.messages) } @Test @@ -904,12 +1018,23 @@ internal class PostHogQueueTest { } @Test - fun `retries on 429`() { - val e = PostHogApiError(429, "", null) + fun `retries on 404 and 429`() { val config = PostHogConfig(PROJECT_TOKEN) val limits = initialBatchLimits(config) - assertFalse(deleteFilesIfAPIError(e, limits, actualBatchSize = limits.cap, logger = config.logger)) + for (status in listOf(404, 429)) { + val e = PostHogApiError(status, "", null) + assertFalse(deleteFilesIfAPIError(e, limits, actualBatchSize = limits.cap, logger = config.logger)) + } + } + + @Test + fun `does not retry on 3xx`() { + val e = PostHogApiError(307, "", null) + val config = PostHogConfig(PROJECT_TOKEN) + val limits = initialBatchLimits(config) + + assertTrue(deleteFilesIfAPIError(e, limits, actualBatchSize = limits.cap, logger = config.logger)) } @Test @@ -958,6 +1083,25 @@ internal class PostHogQueueTest { assertEquals(0, File(path, PROJECT_TOKEN).listFiles()!!.size) } + @Test + fun `a fatal event is sent with a request waiting to be retried`() { + val http = mockHttp(response = MockResponse().setResponseCode(503).setBody("error")) + http.enqueue(MockResponse().setBody("")) + val sut = getSut(host = http.url("/").toString(), flushAt = 1) + + sut.add(PostHogEvent("before", "123")) + awaitQueue() + http.takeRequest(5, TimeUnit.SECONDS) + + val props = mutableMapOf(ThrowableCoercer.EXCEPTION_LEVEL_ATTRIBUTE to ThrowableCoercer.EXCEPTION_LEVEL_FATAL) + sut.add(PostHogEvent(PostHogEventName.EXCEPTION.event, "123", properties = props)) + + val request = assertNotNull(http.takeRequest(5, TimeUnit.SECONDS)) + val batch = PostHogSerializer(PostHogConfig(PROJECT_TOKEN)).deserialize(request.body.unGzip().reader()) + assertEquals(listOf("before", PostHogEventName.EXCEPTION.event), batch.batch.map { it.event }) + assertEquals(0, sut.dequeList.size) + } + @Test fun `loads cached events from disk on first add`() { val http = mockHttp() diff --git a/posthog/src/test/java/com/posthog/internal/PostHogReplayQueueTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogReplayQueueTest.kt index 50820f459..1fd4cfc1d 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogReplayQueueTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogReplayQueueTest.kt @@ -35,6 +35,9 @@ internal class PostHogReplayQueueTest { setAddSecondsToCurrentDate(Date(1000)) } + // past the pause: the whole seconds pinned above plus a jittered remainder under a second + private val afterPause = Date(2000) + @AfterTest fun cleanup() { queues.forEach { @@ -201,7 +204,7 @@ internal class PostHogReplayQueueTest { http.enqueue(MockResponse()) http.enqueue(MockResponse()) - clock.setCurrentDate(Date(1000)) + clock.setCurrentDate(afterPause) sut.flush() awaitQueue() assertBatches(http, listOf(List(2) { "failed" to "user" }, listOf("later" to "user"))) @@ -237,7 +240,7 @@ internal class PostHogReplayQueueTest { assertEquals(files, sut.dequeList) assertEquals(1, sut.currentBatchCapForTesting) repeat(3) { http.enqueue(MockResponse()) } - clock.setCurrentDate(Date(1000)) + clock.setCurrentDate(afterPause) sut.flush() awaitQueue() assertBatches(http, listOf(listOf("oversized" to "user"), listOf("oversized" to "user"), listOf("later" to "user"))) @@ -271,7 +274,7 @@ internal class PostHogReplayQueueTest { assertEquals(1, http.requestCount) val request = assertNotNull(http.takeRequest(5, TimeUnit.SECONDS)) - assertEquals("/batch", request.path) + assertEquals("/i/v1/analytics/events", request.path) val payload = PostHogSerializer(PostHogConfig(PROJECT_TOKEN)).deserialize>(request.body.unGzip().reader()) assertEquals(2, (payload["batch"] as List<*>).size) assertEquals(0, sut.size) diff --git a/posthog/src/test/java/com/posthog/internal/PostHogSendCachedLegacyEventsIntegrationTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogSendCachedLegacyEventsIntegrationTest.kt index ab38558b1..78b239036 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogSendCachedLegacyEventsIntegrationTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogSendCachedLegacyEventsIntegrationTest.kt @@ -6,6 +6,7 @@ import com.posthog.TestHttpServers import com.posthog.shutdownAndAwaitTermination import com.posthog.unGzip import okhttp3.mockwebserver.MockResponse +import okhttp3.mockwebserver.RecordedRequest import okhttp3.mockwebserver.SocketPolicy import org.junit.Rule import org.junit.rules.TemporaryFolder @@ -104,28 +105,91 @@ internal class PostHogSendCachedLegacyEventsIntegrationTest { assertEquals(emptyList(), retained(prefix)) assertEquals(1, http.requestCount) val request = assertNotNull(http.takeRequest(5, TimeUnit.SECONDS)) + assertEquals("/i/v1/analytics/events", request.path) + val sent = sentEvents(request).single() + assertEquals("testEvent", sent["event"]) + assertEquals("9740f814-0b10-42e2-b3d4-8f35af1b11f6", sent["distinct_id"]) + assertEquals(mapOf("testProperty" to "testValue"), sent["properties"]) + } + + @Suppress("UNCHECKED_CAST") + private fun sentEvents(request: RecordedRequest): List> { val serializer = PostHogSerializer(PostHogConfig(PROJECT_TOKEN)) - val batch = serializer.deserialize(request.body.unGzip().reader()) - val sent = batch.batch.single() - assertEquals("testEvent", sent.event) - assertEquals("9740f814-0b10-42e2-b3d4-8f35af1b11f6", sent.distinctId) - assertEquals(mapOf("testProperty" to "testValue"), sent.properties?.toMap()) + val body = serializer.deserialize>(request.body.unGzip().reader()) + return body["batch"] as List> + } + + @Test + fun `sends a 2x cached event with its message_id as the uuid and the root set as a property`() { + val legacyEvent = + """ + { + "message_id": "8837f4d8-01e3-4bb8-b3f3-16b8fa8173e5", + "event": "testEvent", + "distinct_id": "9740f814-0b10-42e2-b3d4-8f35af1b11f6", + "properties": {"testProperty": "testValue"}, + "${'$'}set": {"name": "Max"}, + "timestamp": "2023-09-19T07:23:00.165Z" + } + """.trimIndent() + val prefix = writeLegacyFile(listOf(legacyEvent)) + val http = servers.mockHttp() + getSut(prefix, http.url("/").toString()).install(mock()) + executor.shutdownAndAwaitTermination() + assertEquals(emptyList(), retained(prefix)) + val sent = sentEvents(assertNotNull(http.takeRequest(5, TimeUnit.SECONDS))).single() + assertEquals("8837f4d8-01e3-4bb8-b3f3-16b8fa8173e5", sent["uuid"]) + assertEquals(mapOf("testProperty" to "testValue", "${'$'}set" to mapOf("name" to "Max")), sent["properties"]) + } + + @Test + fun `re-queues the events capture asked to retry for the next launch`() { + val retried = event.replace("8837f4d8-01e3-4bb8-b3f3-16b8fa8173e5", "11111111-0b10-42e2-b3d4-8f35af1b11f6") + val prefix = writeLegacyFile(listOf(retried, event, event)) + val http = + servers.mockHttp( + response = + MockResponse().setBody( + "{\"results\":{\"11111111-0b10-42e2-b3d4-8f35af1b11f6\":{\"result\":\"retry\"}," + + "\"8837f4d8-01e3-4bb8-b3f3-16b8fa8173e5\":{\"result\":\"ok\"}}}", + ), + ) + getSut(prefix, http.url("/").toString()).install(mock()) + executor.shutdownAndAwaitTermination() + assertEquals(1, http.requestCount) + assertEquals(listOf(retried), retained(prefix)) } @Test fun `sends events from the legacy queue in batches`() { val prefix = writeLegacyFile(listOf(event, event)) - val http = servers.mockHttp(2) + val http = servers.mockHttp(2, MockResponse().setBody("{\"results\":{}}")) getSut(prefix, http.url("/").toString(), maxBatchSize = 1).install(mock()) executor.shutdownAndAwaitTermination() assertEquals(emptyList(), retained(prefix)) assertEquals(2, http.requestCount) } + @Test + fun `closes a batch before it would pass 5 MiB and sends an oversized event alone, in order`() { + fun sized( + name: String, + bytes: Int, + ) = event.replace("testEvent", name).replace("testValue", "a".repeat(bytes)) + val mib = 1024 * 1024 + val prefix = writeLegacyFile(listOf(sized("one", 2 * mib), sized("two", 2 * mib), sized("big", 6 * mib), sized("small", 1))) + val http = servers.mockHttp(3, MockResponse().setBody("{\"results\":{}}")) + getSut(prefix, http.url("/").toString()).install(mock()) + executor.shutdownAndAwaitTermination() + assertEquals(emptyList(), retained(prefix)) + val batches = (1..http.requestCount).map { sentEvents(assertNotNull(http.takeRequest(5, TimeUnit.SECONDS))).map { it["event"] } } + assertEquals(listOf(listOf("one", "two"), listOf("big"), listOf("small")), batches) + } + @Test fun `send a valid event and discard a broken event`() { val prefix = writeLegacyFile(listOf("invalid event", event)) - val http = servers.mockHttp(2) + val http = servers.mockHttp(2, MockResponse().setBody("{\"results\":{}}")) getSut(prefix, http.url("/").toString(), maxBatchSize = 1).install(mock()) executor.shutdownAndAwaitTermination() assertEquals(emptyList(), retained(prefix)) @@ -143,15 +207,25 @@ internal class PostHogSendCachedLegacyEventsIntegrationTest { } @Test - fun `keeps the events if returns 3xx`() { + fun `keeps the events if returns 503`() { val prefix = writeLegacyFile(listOf(event, event)) - val http = servers.mockHttp(response = MockResponse().setResponseCode(300)) + val http = servers.mockHttp(response = MockResponse().setResponseCode(503)) getSut(prefix, http.url("/").toString()).install(mock()) executor.shutdownAndAwaitTermination() assertEquals(listOf(event, event), retained(prefix)) assertEquals(1, http.requestCount) } + @Test + fun `discards the events if returns 3xx`() { + val prefix = writeLegacyFile(listOf(event, event)) + val http = servers.mockHttp(response = MockResponse().setResponseCode(300)) + getSut(prefix, http.url("/").toString()).install(mock()) + executor.shutdownAndAwaitTermination() + assertEquals(emptyList(), retained(prefix)) + assertEquals(1, http.requestCount) + } + @Test fun `keeps the events if no connection`() { val prefix = writeLegacyFile(listOf(event, event)) diff --git a/posthog/src/test/java/com/posthog/internal/PostHogSerializerTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogSerializerTest.kt index cd7a5da72..883026d76 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogSerializerTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogSerializerTest.kt @@ -1,8 +1,10 @@ package com.posthog.internal +import com.google.gson.JsonParser import com.posthog.PROJECT_TOKEN import com.posthog.PostHogConfig import com.posthog.PostHogEvent +import com.posthog.TestLogger import com.posthog.date import com.posthog.generateEvent import org.junit.Rule @@ -313,4 +315,52 @@ internal class PostHogSerializerTest { assertEquals(expectedJson, actualJson) } + + // not a data class: its generated hashCode calls Double.hashCode(double), missing on API 23. + // toString carries the prompt so logging the value would leak it + private class Turn(val prompt: String, val score: Double) { + override fun toString(): String = "Turn(prompt=$prompt)" + } + + @Test + fun `converts scalar map keys, drops and logs other keys by type and keeps the event`() { + val logger = TestLogger() + val config = PostHogConfig(PROJECT_TOKEN).apply { this.logger = logger } + val nested = + mapOf(1 to "int", 1.5 to "float", true to "bool", null to "null", listOf("SECRET-KEY") to "dropped", "text" to "string") + val event = generateEvent().copy(properties = mutableMapOf("nested" to nested)) + + val writer = StringWriter() + config.serializer.serialize(event, writer) + + val properties = JsonParser.parseString(writer.toString()).asJsonObject["properties"].asJsonObject + val sent = properties["nested"].asJsonObject + assertEquals(setOf("1", "1.5", "true", "null", "text"), sent.keySet()) + assertEquals("int", sent["1"].asString) + val message = logger.messages.single { it.contains("cannot be serialized") } + assertTrue(message.contains("Property key of type java.util.Collections\$SingletonList"), message) + assertTrue(logger.messages.none { it.contains("SECRET-KEY") }) + } + + @Test + fun `an unserializable property is logged by key and type, never by value`() { + val logger = TestLogger() + val config = PostHogConfig(PROJECT_TOKEN).apply { this.logger = logger } + val event = generateEvent().copy(properties = mutableMapOf("turn" to Turn("SECRET-PROMPT", Double.NaN))) + + config.serializer.serialize(event, StringWriter()) + + val message = logger.messages.single { it.contains("cannot be serialized") } + assertTrue(message.contains("'turn'"), message) + assertTrue(logger.messages.none { it.contains("SECRET-PROMPT") }) + } + + @Test + fun `serializedSize stops counting past its bound`() { + val config = PostHogConfig(PROJECT_TOKEN) + val event = generateEvent().copy(properties = mutableMapOf("big" to "a".repeat(1_000_000))) + + assertEquals(1_001L, config.serializedSize(event, stopAfter = 1_000)) + assertTrue(config.serializedSize(event) > 1_000_000) + } } diff --git a/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt b/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt index 00a37fcf4..3d900be7f 100644 --- a/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt +++ b/posthog/src/testFixtures/java/com/posthog/PostHogFake.kt @@ -46,12 +46,29 @@ public class PostHogFake : PostHogInterface, PostHogPushSubscriptionReceiver { userPropertiesSetOnce: Map?, groups: Map?, timestamp: Date?, + options: Map?, ) { this.event = event this.properties = properties captures++ } + override fun captureAi( + event: String, + distinctId: String?, + properties: Map?, + userProperties: Map?, + userPropertiesSetOnce: Map?, + groups: Map?, + timestamp: Date?, + options: Map?, + ): UUID? { + this.event = event + this.properties = properties + captures++ + return UUID.randomUUID() + } + override fun captureLog( message: String, severity: PostHogLogSeverity, @@ -65,6 +82,7 @@ public class PostHogFake : PostHogInterface, PostHogPushSubscriptionReceiver { override fun captureException( throwable: Throwable, properties: Map?, + options: Map?, ) { } @@ -78,6 +96,7 @@ public class PostHogFake : PostHogInterface, PostHogPushSubscriptionReceiver { distinctId: String, userProperties: Map?, userPropertiesSetOnce: Map?, + options: Map?, ) { } @@ -119,6 +138,7 @@ public class PostHogFake : PostHogInterface, PostHogPushSubscriptionReceiver { override fun setPersonProperties( userPropertiesToSet: Map?, userPropertiesToSetOnce: Map?, + options: Map?, ) { } @@ -173,17 +193,22 @@ public class PostHogFake : PostHogInterface, PostHogPushSubscriptionReceiver { type: String, key: String, groupProperties: Map?, + options: Map?, ) { } override fun screen( screenTitle: String, properties: Map?, + options: Map?, ) { this.screenTitle = screenTitle } - override fun alias(alias: String) { + override fun alias( + alias: String, + options: Map?, + ) { } override fun isOptOut(): Boolean { @@ -199,6 +224,9 @@ public class PostHogFake : PostHogInterface, PostHogPushSubscriptionReceiver { override fun unregister(key: String) { } + override fun setAppLanguage(language: String?) { + } + override fun distinctId(): String { return "" } diff --git a/sdk_compliance_adapter/IMPLEMENTATION_NOTES.md b/sdk_compliance_adapter/IMPLEMENTATION_NOTES.md index 8e45c9564..b98c39d9a 100644 --- a/sdk_compliance_adapter/IMPLEMENTATION_NOTES.md +++ b/sdk_compliance_adapter/IMPLEMENTATION_NOTES.md @@ -18,9 +18,9 @@ This directory contains the compliance test adapter for the PostHog Android SDK. #### HTTP Request Tracking The adapter uses a custom OkHttpClient with a `TrackingInterceptor` that: -- Intercepts all HTTP requests to the `/batch/` endpoint +- Intercepts all HTTP requests to the `/i/v1/analytics/events` endpoint - Parses request bodies to extract event UUIDs using regex -- Tracks request count, status codes, retry attempts, and event counts +- Tracks request count, status codes, retry attempts (`PostHog-Attempt` minus one), and event counts - Updates adapter state with request metadata #### Event UUID Tracking @@ -36,6 +36,7 @@ This dual approach ensures UUIDs are available immediately when events are captu The adapter configures the PostHog SDK for optimal testing: - `flushAt = 1` - Send events immediately (or as configured) - `flushIntervalSeconds` - Fast flush intervals for tests +- `personProfiles = ALWAYS` - The harness never identifies and expects person processing on unless an event opts out - `debug = true` - Enable logging - `httpClient` - Custom OkHttpClient with tracking interceptor @@ -75,11 +76,11 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for local build and compliance test comma ## SDK Type -The Android SDK uses **server SDK format**: -- Endpoint: `/batch/` -- Format: `{api_key: "...", batch: [{event}, {event}], sent_at: "..."}` +The Android SDK advertises `capture_v1`, `capture_ai_v1`, `encoding_gzip`, `event_options`, `generated_payloads`, `log_capture`, `property_layers` and `fail_open`: +- Endpoints: `POST /i/v1/analytics/events` (`/capture`) and `POST /i/v1/ai/events` (`/capture_ai`) +- Format: `{created_at: "...", batch: [{event}, {event}]}` with the project token in an `Authorization: Bearer` header -Tests run with `--sdk-type server` flag. +Tests run with `--sdk-type server` flag; the harness selects the `capture_v1` and `capture_ai_v1` suites from the capabilities. ## API Endpoints @@ -88,6 +89,7 @@ The adapter implements the standard compliance adapter API: - `GET /health` - Health check with SDK version info - `POST /init` - Initialize SDK with config - `POST /capture` - Capture a single event +- `POST /capture_ai` - Capture a single AI event through `captureAi` - `POST /flush` - Force flush all pending events - `GET /state` - Get adapter state for assertions - `POST /reset` - Reset SDK and adapter state diff --git a/sdk_compliance_adapter/README.md b/sdk_compliance_adapter/README.md index acfce3905..c71675ef4 100644 --- a/sdk_compliance_adapter/README.md +++ b/sdk_compliance_adapter/README.md @@ -29,7 +29,7 @@ This allows the test adapter to inject a custom OkHttpClient with tracking inter ### HTTP Request Tracking The adapter injects a custom OkHttpClient that: -- Intercepts all `/batch/` requests +- Intercepts all `/i/v1/analytics/events` requests - Extracts event UUIDs from request bodies - Tracks status codes, retry attempts, and event counts @@ -41,11 +41,11 @@ Events are tracked via: ### SDK Type -The Android SDK uses **server SDK format**: -- Endpoint: `/batch/` -- Format: `{api_key, batch, sent_at}` +The Android SDK advertises `capture_v1`, `capture_ai_v1`, `encoding_gzip`, `event_options`, `generated_payloads`, `log_capture`, `property_layers` and `fail_open`: +- Endpoints: `POST /i/v1/analytics/events` (`/capture`) and `POST /i/v1/ai/events` (`/capture_ai`) +- Format: `{created_at, batch}` with the project token in an `Authorization: Bearer` header -Tests run with `--sdk-type server`. +Tests run with `--sdk-type server`; the harness selects the `capture_v1` and `capture_ai_v1` suites from the capabilities. ## Files Created diff --git a/sdk_compliance_adapter/docker-compose.yml b/sdk_compliance_adapter/docker-compose.yml index 2a9881cbd..0bb1241ce 100644 --- a/sdk_compliance_adapter/docker-compose.yml +++ b/sdk_compliance_adapter/docker-compose.yml @@ -11,7 +11,7 @@ services: - JAVA_TOOL_OPTIONS=-Xmx512m test-harness: - image: ghcr.io/posthog/sdk-test-harness:0.10.0 + image: ghcr.io/posthog/sdk-test-harness:1.26.0 command: ["run", "--adapter-url", "http://sdk-adapter:8080", "--mock-url", "http://test-harness:8081", "--sdk-type", "server", "--debug"] networks: - test-network diff --git a/sdk_compliance_adapter/src/main/kotlin/com/posthog/compliance/ComplianceAdapter.kt b/sdk_compliance_adapter/src/main/kotlin/com/posthog/compliance/ComplianceAdapter.kt index faa5c9962..40384f7f1 100644 --- a/sdk_compliance_adapter/src/main/kotlin/com/posthog/compliance/ComplianceAdapter.kt +++ b/sdk_compliance_adapter/src/main/kotlin/com/posthog/compliance/ComplianceAdapter.kt @@ -1,11 +1,15 @@ package com.posthog.compliance +import com.google.gson.Gson +import com.google.gson.JsonParser +import com.posthog.PersonProfiles import com.posthog.PostHog import com.posthog.PostHogCompression import com.posthog.PostHogConfig import com.posthog.internal.GzipRequestInterceptor import com.posthog.internal.PostHogApi import com.posthog.internal.PostHogContext +import com.posthog.internal.PostHogLogger import io.ktor.http.HttpStatusCode import io.ktor.serialization.gson.gson import io.ktor.server.application.call @@ -21,6 +25,10 @@ import io.ktor.server.routing.routing import okhttp3.Interceptor import okhttp3.Response import java.io.File +import java.time.OffsetDateTime +import java.time.format.DateTimeParseException +import java.util.Collections +import java.util.Date import java.util.UUID import java.util.concurrent.TimeUnit import java.util.concurrent.locks.Condition @@ -33,6 +41,12 @@ private const val QUEUE_STORAGE_PREFIX = "/tmp/posthog-queue" // Upper bound on the wait for a flush()'d batch to reach the mock (generous for Docker). private const val FLUSH_SETTLE_MS = 2000L +// The capture v1 endpoints the SDK posts analytics and AI events to. +private const val CAPTURE_PATH = "/i/v1/analytics/events" +private const val CAPTURE_AI_PATH = "/i/v1/ai/events" + +private fun isCaptureUrl(url: String): Boolean = url.contains(CAPTURE_PATH) || url.contains(CAPTURE_AI_PATH) + /** * PostHog Android SDK Compliance Adapter * @@ -71,6 +85,12 @@ data class InitRequest( val flush_interval_ms: Int? = null, val max_retries: Int? = null, val enable_compression: Boolean? = null, + val super_properties: Map? = null, + val before_send: BeforeSendSpec? = null, +) + +data class BeforeSendSpec( + val set_properties: Map? = null, ) data class CaptureRequest( @@ -78,11 +98,15 @@ data class CaptureRequest( val event: String, val properties: Map? = null, val timestamp: String? = null, + val options: Map? = null, + val pad_properties_to_bytes: Int? = null, + val marker: String? = null, ) data class CaptureResponse( val success: Boolean, - val uuid: String, + // Null (omitted from the JSON) when the SDK didn't queue the event. + val uuid: String? = null, ) data class FlagRequest( @@ -114,6 +138,7 @@ data class StateResponse( val total_retries: Int, val last_error: String?, val requests_made: List, + val log_lines: List, ) data class SuccessResponse( @@ -133,16 +158,29 @@ class TestPostHogContext(private val sdkName: String, private val sdkVersion: St ) } +// Records every SDK log line for /state, and still prints it. +class RecordingLogger : PostHogLogger { + override fun log(message: String) { + println(message) + AdapterContext.logLines.add(message) + } + + override fun isEnabled(): Boolean = true +} + // Global state object AdapterContext { val state = AdapterState() val lock = ReentrantLock() - // Signalled by the tracking interceptor when a /batch response lands (see awaitBatch). + // Signalled by the tracking interceptor when a capture response lands (see awaitBatch). val batchObserved: Condition = lock.newCondition() var postHog: com.posthog.PostHogInterface? = null var api: PostHogApi? = null val capturedEvents = mutableListOf() // Store UUIDs of captured events + + // Own lock: the SDK logs from its threads, which must not wait on [lock]. + val logLines: MutableList = Collections.synchronizedList(mutableListOf()) } // OkHttp Interceptor to track requests @@ -157,14 +195,14 @@ class TrackingInterceptor : Interceptor { val uuidList = mutableListOf() // Parse request body before sending - if (url.contains("/batch") && !url.contains("/flags") && requestBody != null) { + if (isCaptureUrl(url) && requestBody != null) { try { val buffer = okio.Buffer() requestBody.writeTo(buffer) val bodyString = buffer.readUtf8() // Parse JSON to extract UUIDs - // The body format is: {"api_key": "...", "batch": [{event}, {event}], "sent_at": "..."} + // The body format is: {"created_at": "...", "batch": [{event}, {event}]} val uuidRegex = """"uuid"\s*:\s*"([^"]+)"""".toRegex() uuidRegex.findAll(bodyString).forEach { match -> uuidList.add(match.groupValues[1]) @@ -178,10 +216,12 @@ class TrackingInterceptor : Interceptor { val response = chain.proceed(request) // Track the response - if (url.contains("/batch") && !url.contains("/flags")) { + if (isCaptureUrl(url)) { try { - // Extract retry count from URL if present - val retryCount = request.url.queryParameter("retry_count")?.toIntOrNull() ?: 0 + // PostHog-Attempt starts at 1; the harness counts retries from 0. + val retryCount = (request.header("PostHog-Attempt")?.toIntOrNull() ?: 1) - 1 + // Read before taking the lock, so a slow body can't stall /state, /reset or the other lane. + val retried = if (response.isSuccessful) retriedCount(response, uuidList) else 0 AdapterContext.lock.withLock { val record = @@ -196,8 +236,10 @@ class TrackingInterceptor : Interceptor { AdapterContext.state.requestsMade.add(record) if (response.isSuccessful) { - AdapterContext.state.totalEventsSent += eventCount - AdapterContext.state.pendingEvents = maxOf(0, AdapterContext.state.pendingEvents - eventCount) + // Events the server asks to retry stay queued and count once a later request delivers them. + val delivered = eventCount - retried + AdapterContext.state.totalEventsSent += delivered + AdapterContext.state.pendingEvents = maxOf(0, AdapterContext.state.pendingEvents - delivered) } if (retryCount > 0) { @@ -214,7 +256,53 @@ class TrackingInterceptor : Interceptor { } } -// Block until [predicate] holds (signalled as each /batch response lands) or [timeoutMs] elapses. +// How many of [uuids] the capture v1 per-event results ask to retry. Peeks so the SDK still reads the +// body, within a deadline so a body that trickles in can't hold the request. +private fun retriedCount( + response: Response, + uuids: List, +): Int { + val timeout = response.body?.source()?.timeout() + timeout?.deadline(RESPONSE_PEEK_DEADLINE_SECONDS, TimeUnit.SECONDS) + return try { + val body = response.peekBody(1024 * 1024).string() + val results = JsonParser.parseString(body).asJsonObject.getAsJsonObject("results") + uuids.count { uuid -> results?.getAsJsonObject(uuid)?.get("result")?.asString == "retry" } + } catch (_: Exception) { + 0 + } finally { + timeout?.clearDeadline() + } +} + +private const val RESPONSE_PEEK_DEADLINE_SECONDS = 5L + +// The harness sends RFC 3339 timestamps, with any offset; the SDK serializes the instant in UTC. +private fun parseHarnessTimestamp(timestamp: String?): Date? = + timestamp?.let { + try { + Date.from(OffsetDateTime.parse(it).toInstant()) + } catch (_: DateTimeParseException) { + null + } + } + +// Adds a $test_padding string so [properties], as compact UTF-8 JSON, is exactly [targetBytes] long. +private fun padProperties( + properties: Map?, + targetBytes: Int, + marker: String?, +): Map { + val padded = properties.orEmpty().toMutableMap() + val prefix = marker.orEmpty() + padded["\$test_padding"] = prefix + // Measure with the marker in place so its serialized (escaped, UTF-8) size is counted. + val baseBytes = Gson().toJson(padded).toByteArray(Charsets.UTF_8).size + padded["\$test_padding"] = prefix + "x".repeat(maxOf(0, targetBytes - baseBytes)) + return padded +} + +// Block until [predicate] holds (signalled as each capture response lands) or [timeoutMs] elapses. private fun awaitBatch( timeoutMs: Long, predicate: () -> Boolean, @@ -242,8 +330,19 @@ fun main() { sdk_name = "posthog-android", sdk_version = PostHogConfig(projectToken = "").sdkVersion, adapter_version = "1.0.0", - // Opt into the capture suites (android posts /batch with gzip). - capabilities = listOf("capture_v0", "encoding_gzip"), + // Opt into the capture suites (android posts /i/v1/analytics/events and + // /i/v1/ai/events with gzip). + capabilities = + listOf( + "capture_v1", + "capture_ai_v1", + "encoding_gzip", + "event_options", + "generated_payloads", + "log_capture", + "property_layers", + "fail_open", + ), ), ) } @@ -264,9 +363,11 @@ fun main() { // Close existing instance if any AdapterContext.postHog?.close() AdapterContext.api = null + AdapterContext.logLines.clear() // close() leaves queue files on disk; wipe so they don't replay into this test. File(QUEUE_STORAGE_PREFIX).deleteRecursively() + File("$QUEUE_STORAGE_PREFIX-ai").deleteRecursively() // Create new config val flushIntervalMs = req.flush_interval_ms ?: 100 @@ -281,6 +382,10 @@ fun main() { debug = true, preloadFeatureFlags = false, ) + config.logger = RecordingLogger() + // The harness models a server SDK: it never identifies, and expects person + // processing on unless an event opts out. + config.personProfiles = PersonProfiles.ALWAYS // Create OkHttpClient with tracking and gzip interceptors val httpClient = @@ -291,13 +396,18 @@ fun main() { config.httpClient = httpClient - req.max_retries?.let { config.maxRetries = it } + req.max_retries?.let { config.pushNotificationSubscriptionMaxRetries = it } + // The harness sends one enable_compression flag and no AI-lane setting, so it sets + // both lanes. With it unset, the AI lane keeps its documented default (gzip). req.enable_compression?.let { - config.compression = if (it) PostHogCompression.GZIP else PostHogCompression.NONE + val compression = if (it) PostHogCompression.GZIP else PostHogCompression.NONE + config.compression = compression + config.captureAiCompression = compression } - // Set storage prefix for file-backed queue + // Set storage prefixes for the file-backed queues (both wiped on /init and /reset) config.storagePrefix = QUEUE_STORAGE_PREFIX + config.aiStoragePrefix = "$QUEUE_STORAGE_PREFIX-ai" // Set minimal context to provide $lib and $lib_version config.context = TestPostHogContext("posthog-android", config.sdkVersion) @@ -311,9 +421,17 @@ fun main() { } event } + req.before_send?.set_properties?.let { setProperties -> + config.addBeforeSend { event -> + event.properties?.putAll(setProperties) + event + } + } // Create PostHog instance and direct API helper for per-request flag evaluation. - AdapterContext.postHog = PostHog.with(config) + val postHog = PostHog.with(config) + req.super_properties?.forEach { (key, value) -> postHog.register(key, value) } + AdapterContext.postHog = postHog AdapterContext.api = PostHogApi(config) } @@ -342,6 +460,8 @@ fun main() { event = req.event, distinctId = req.distinct_id, properties = properties, + timestamp = parseHarnessTimestamp(req.timestamp), + options = req.options, ) // Get the UUID that was just captured (via beforeSend hook) @@ -362,6 +482,45 @@ fun main() { call.respond(CaptureResponse(success = true, uuid = uuid)) } + // Same request as /capture, sent with captureAi to /i/v1/ai/events. Ktor's Netty engine + // streams request bodies without a size limit, so an 8 MiB AI event is received whole. + post("/capture_ai") { + val req = call.receive() + + val ph = + AdapterContext.lock.withLock { + AdapterContext.postHog + } + + if (ph == null) { + call.respond(HttpStatusCode.BadRequest, mapOf("error" to "SDK not initialized")) + return@post + } + + val properties = + req.pad_properties_to_bytes?.let { padProperties(req.properties, it, req.marker) } + ?: req.properties + val uuid = + ph.captureAi( + event = req.event, + distinctId = req.distinct_id, + properties = properties, + timestamp = parseHarnessTimestamp(req.timestamp), + options = req.options, + ) + + // A null uuid means the SDK didn't queue the event (for example it's over the size + // limit), so no request will carry it and no uuid is reported. + if (uuid != null) { + AdapterContext.lock.withLock { + AdapterContext.state.totalEventsCaptured++ + AdapterContext.state.pendingEvents++ + } + } + + call.respond(CaptureResponse(success = true, uuid = uuid?.toString())) + } + post("/get_feature_flag") { val req = call.receive() @@ -450,6 +609,7 @@ fun main() { total_retries = AdapterContext.state.totalRetries, last_error = AdapterContext.state.lastError, requests_made = AdapterContext.state.requestsMade.toList(), + log_lines = synchronized(AdapterContext.logLines) { AdapterContext.logLines.toList() }, ) } @@ -465,6 +625,7 @@ fun main() { // close() leaves queue files on disk; wipe so they don't replay next test (matches iOS). File(QUEUE_STORAGE_PREFIX).deleteRecursively() + File("$QUEUE_STORAGE_PREFIX-ai").deleteRecursively() AdapterContext.state.pendingEvents = 0 AdapterContext.state.totalEventsCaptured = 0 @@ -473,6 +634,7 @@ fun main() { AdapterContext.state.lastError = null AdapterContext.state.requestsMade.clear() AdapterContext.capturedEvents.clear() + AdapterContext.logLines.clear() } call.respond(SuccessResponse(success = true)) From 34198711253743233bf6582fdc436acc9f1f7562 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 5 Nov 2026 10:53:52 -0500 Subject: [PATCH 18/49] docs: tighten the 4.0 changesets and migration guide for release - Sort the Android changeset with breaking entries first, in imperative one-line entries, and drop the composed-scene bullet that 3.76.0 already released; keep only the 4.0 change to dialog dims. - Add changelog entries for the 2xx-without-results drop, HTTP-date Retry-After, migrated 3.x queues and non-string map keys. - Add the core changes posthog-server also gets to its changeset: PostHogEvent.options, the non-string key fix, beforeSend copies and the quieter debug logs. - Guide: pin surveys-compose users to posthog-android 4.0.0 or later instead of 4.+, say PostHog no longer saves non-JSON payloads, and note that the first event after a language change can carry the previous $locale or $app_language. Co-Authored-By: Claude Opus 5.5 --- .changeset/android-v4-major.md | 89 ++++++++++------------ .changeset/server-keep-on-feature-flags.md | 10 ++- docs/migration-3.x-to-4.0.md | 6 +- 3 files changed, 51 insertions(+), 54 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 782be62ea..4d427a392 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -3,54 +3,45 @@ 'posthog-android': major --- -- **Breaking:** remove the deprecated `apiKey` property and the `PostHogConfig(apiKey = …)` and `PostHogAndroidConfig(apiKey = …)` factories; use `projectToken` instead -- **Breaking:** remove the deprecated `propertiesSanitizer` config option and the `PostHogPropertiesSanitizer` interface; use `addBeforeSend` instead -- **Breaking:** remove the deprecated `evaluationEnvironments` config option; use `evaluationContexts` instead -- **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload` instead to keep not sending `$feature_flag_called` -- **Breaking:** remove the `defaultValue` parameter from `getFeatureFlag()`, which returns `null` for a flag with no value or a disabled SDK, so use `getFeatureFlag(key) ?: default` instead; a positional `Boolean` second argument now sets `sendFeatureFlagEvent`, and `$feature_flag_called` no longer reports a fallback from `getFeatureFlag()` or `isFeatureEnabled()` as the flag's value -- **Breaking:** remove the deprecated `PostHogSessionReplayConfig.debouncerDelayMs`; use `throttleDelayMs` instead -- **Breaking:** remove wireframe session replay; replay always records masked screenshots, the mode `screenshot = true` already used. `PostHogSessionReplayConfig.screenshot` is removed, and so are `drawableConverter` and `PostHogDrawableConverter`, which only wireframe capture read - - Apps that relied on the default now upload screenshots. Masking still covers text inputs, images, `WebView`s, Compose semantics and `ph-no-capture` views and `Modifier.postHogMask()`, but custom-drawn views and other content the SDK doesn't recognize (for example maps or video) can now appear; mask them, or turn replay off with `sessionReplay = false` - - Jetpack Compose screens, which wireframe captured as empty boxes, are now recorded - - Apply `Modifier.postHogMask()` and `Modifier.postHogUnmask()` only to the element and its children, not to siblings merged into the same clickable row - - Compose text that draws past its layout box is masked in full, and nodes using `Modifier.clearAndSetSemantics` are masked while text or image masking is on; use `Modifier.postHogUnmask()` to show them - - `$sdk_debug_replay_capture_mode` is always `screenshot` - - Activity and dialog windows are composed into one scene; a dialog's dim and a dialog masked whole are sent as screenshot images - - Wrapper SDKs: the internal `RRWireframe` keeps only `id`, `x`, `y`, `width`, `height`, `type` and `base64`, and `RRStyle` is removed; screenshot frames no longer send an empty `style` -- **Breaking:** return `null` instead of the raw string for a malformed, empty, whitespace-only or lenient-only (unquoted or single-quoted) feature flag payload from `getFeatureFlagResult(key)?.payload`; payloads must be valid JSON (a JSON `null` payload now also reads as `null` instead of the string `"null"`) -- **Breaking:** make SDK-internal helpers in the `com.posthog.internal`, `com.posthog.android.internal` and `com.posthog.android.replay.internal` packages non-public -- **Breaking:** remove the deprecated `remoteConfig` config option; the SDK now always loads remote config at setup -- **Breaking:** remove `PostHogConfig.onFeatureFlags`; call `PostHog.onFeatureFlags(callback)` before `setup()` instead, which also covers the first load -- **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `reloadFeatureFlags()`; it receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values, and `errorsLoading` -- **Breaking:** add the abstract `onFeatureFlags()` method to `PostHogInterface`; classes that implement it must add the method -- **Breaking:** send events to capture v1 (`/i/v1/analytics/events`) with the project token in an `Authorization: Bearer` header; if you use a reverse proxy or self-host PostHog, make sure the path is served, because events stay queued and are retried on a 404, with a warning printed once even when `debug` is off, and authenticate your proxy with a header other than `Authorization`, which capture requests replace -- **Breaking:** stop retrying 3xx responses for events, retry 404 responses, and cap a `Retry-After` pause at 30 seconds for events, session replay and logs -- **Breaking:** add up to 25% random jitter to the wait after a failed send, which still doubles from 1 second to 30 seconds, and treat a `Retry-After` as a minimum wait instead of replacing the backoff, for events, session replay and logs; queued records are still kept until they're delivered -- **Breaking:** follow only a 307 or 308 redirect of a capture request to the same origin as `host`, at most 5 times; any other redirect drops the events, so point `host` at the final host -- **Breaking:** send the `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id` properties as capture options (`PostHogEvent.options`, a new property; the constructor and `copy` are unchanged, and an event `beforeSend` returns with null options keeps the incoming ones), where PostHog drops an event whose option value it can't read -- **Breaking:** rename `PostHogConfig.maxRetries` to `pushNotificationSubscriptionMaxRetries`, because it only limits push-notification subscription retries -- **Breaking:** set `$lib` and `$lib_version` from the `PostHog-Sdk-Info` request header; a value set in properties, super properties or `beforeSend` is removed before sending -- **Breaking:** send `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields; a non-string value is dropped, with a log when `debug` is on +- See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md) for upgrade steps +- **Breaking:** send analytics events to capture v1 (`/i/v1/analytics/events`) with the project token in an `Authorization: Bearer` header, replacing any `Authorization` header in `requestHeaders`; self-hosted instances and reverse proxies must serve the path, and a 404 keeps events queued, retries them and prints one warning even when `debug` is off +- **Breaking:** drop events when a capture request gets a non-retryable status (including 3xx), a 2xx without per-event results, or a redirect other than a 307 or 308 to the same origin as `host` (followed at most 5 times); retry 404, 408, 429, 500, 502, 503 and 504 +- **Breaking:** cap a `Retry-After` wait at 30 seconds, read it as a minimum wait and accept an HTTP date, and add up to 25% random jitter to the backoff, which still doubles from 1 to 30 seconds, for events, session replay and logs +- **Breaking:** drop events with an empty name before sending them, including one `beforeSend` renames to `""`; PostHog also drops events with an empty distinct ID or a name or distinct ID over 200 bytes +- **Breaking:** set `$lib` and `$lib_version` from the `PostHog-Sdk-Info` request header, removing any value set in properties, super properties or `beforeSend` +- **Breaking:** send `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, dropping non-string values +- **Breaking:** send `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id` as capture options instead of properties; PostHog drops an event whose option value it can't read +- **Breaking:** set the `process_person_profile` option to `false` only when person processing is off, instead of adding a `$process_person_profile` property to every event +- **Breaking:** let registered super properties override properties the SDK sets, such as `$os_name`, and let super and event properties override `$is_identified`, `$process_person_profile` and the session replay debug properties +- **Breaking:** let `userProperties`, `userPropertiesSetOnce` and `groups` win key by key over `$set`, `$set_once` and `$groups` maps in the same call's properties, and merge a `$groups` map in properties into the groups set with `group()` +- **Breaking:** keep the event's own uuid when `beforeSend` returns an event with another uuid - **Breaking:** disable the SDK at setup when `projectToken` is a personal API key (`phx_...`), as for an empty token, and print a warning for both even when `debug` is off -- **Breaking:** add an `options` argument to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException` for per-event capture options such as `cookieless_mode`, sent apart from the properties and editable in `beforeSend` through `PostHogEvent.options`; Java callers pass the trailing argument or `null`, and classes that implement `PostHogInterface` add the parameter -- **Breaking:** move `identify(distinctId, userProperties, userPropertiesSetOnce)` from `PostHogCoreInterface` to `PostHogStatelessInterface`; `PostHogInterface` declares `identify` with the trailing `options` parameter -- **Breaking:** registered super properties now override the properties the SDK sets itself, such as `$os_name`; super and event properties also override `$is_identified`, `$process_person_profile` and the session replay debug properties, which the SDK no longer re-applies after the caller's values -- **Breaking:** the SDK sets the `process_person_profile` option to `false` only when person processing is off, and no longer adds a `$process_person_profile` property to every event -- **Breaking:** keep the uuid of its own capture on the event `beforeSend` returns, so a uuid set in `beforeSend`, for example with `copy(uuid = …)`, is replaced -- **Breaking:** add `captureAi` to send AI events such as `$ai_generation` to PostHog's AI endpoint (`/i/v1/ai/events`), which accepts events whose properties are up to 8 MiB, on its own disk queue; it returns the event uuid, or `null` when the event isn't queued; past `captureAiMaxQueueSize` AI events or 50 MiB, including events still waiting to be written to disk, the oldest are dropped, and classes that implement `PostHogInterface` add the method -- use the current distinct ID when the `distinctId` argument to `capture` is empty or whitespace-only, instead of dropping the event -- **Breaking:** skip deep link query parameters whose name starts with `$` in the `Deep Link Opened` event, so a link can't set a PostHog property such as `$process_person_profile` -- stop storing or matching the person-properties deduplication hash for a `$set` sent with `process_person_profile: false` -- debug logs for capture requests name the event count and the response status instead of printing the request and response bodies, and count the events PostHog drops, the duplicate copies it drops and the events it asks to retry, in one line per batch, and log the status when PostHog rejects a whole batch -- **Breaking:** drop an event whose name is empty before sending it, including one `beforeSend` renames to `""` -- **Breaking:** let `userProperties`, `userPropertiesSetOnce` and `groups` win key by key over `$set`, `$set_once` and `$groups` maps passed in the same call's properties, instead of being replaced by them, and merge a `$groups` map in properties into the groups set with `group()` -- add `captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` to `PostHogConfig` to tune AI requests separately from other events; the defaults are gzip, 100 queued events (and at most 50 MiB), 60 seconds and 8 MiB + 64 KiB per serialized event -- cap a request at about 5 MiB of events, for analytics and AI events, and send as soon as that much is queued; an event larger than that is sent on its own -- **Breaking:** change `$locale` to the first language in the device settings, as a full language tag such as `zh-Hant-TW`, instead of the app-influenced `Locale.getDefault()` -- **Breaking:** add the abstract `setAppLanguage()` method to `PostHogInterface`; classes that implement it must add the method +- **Breaking:** add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`; Java callers pass `null` for it +- **Breaking:** add `onFeatureFlags()`, `setAppLanguage()`, `captureAi()` and the `options` parameters to `PostHogInterface`, and move `identify(distinctId, userProperties, userPropertiesSetOnce)` from `PostHogCoreInterface` to `PostHogStatelessInterface`; classes that implement these interfaces must add them +- **Breaking:** rename `PostHogConfig.maxRetries` to `pushNotificationSubscriptionMaxRetries` +- **Breaking:** remove the deprecated `apiKey` property and the `PostHogConfig(apiKey = …)` and `PostHogAndroidConfig(apiKey = …)` factories; use `projectToken` +- **Breaking:** remove the deprecated `propertiesSanitizer` option and `PostHogPropertiesSanitizer`; use `addBeforeSend` +- **Breaking:** remove the deprecated `evaluationEnvironments` option; use `evaluationContexts` +- **Breaking:** remove the deprecated `remoteConfig` option; the SDK always loads remote config at setup +- **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload` +- **Breaking:** remove the `defaultValue` parameter from `getFeatureFlag()`, which returns `null` for a missing flag or a disabled SDK; a positional `Boolean` second argument now sets `sendFeatureFlagEvent`, and `$feature_flag_called` no longer reports a fallback as the flag's value +- **Breaking:** remove `PostHogConfig.onFeatureFlags`; call `PostHog.onFeatureFlags(callback)` before `setup()` instead +- **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `reloadFeatureFlags()`, which receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and `errorsLoading` +- **Breaking:** return `null` from `getFeatureFlagResult(key)?.payload` for a payload that isn't valid JSON, such as plain text, a malformed or empty string, or a JSON `null` +- **Breaking:** remove wireframe session replay and the `screenshot`, `drawableConverter` and `debouncerDelayMs` options of `PostHogSessionReplayConfig` (use `throttleDelayMs` for the last); replay always records masked screenshots, so apps that relied on the default now upload screenshots and should mask custom-drawn views, maps and video, or turn replay off +- **Breaking:** apply `Modifier.postHogMask()` and `Modifier.postHogUnmask()` only to the element and its children, mask Compose text that draws past its layout box in full, and mask nodes using `Modifier.clearAndSetSemantics` while text or image masking is on +- **Breaking:** send a dialog's dim and a dialog masked whole as screenshot images instead of styled wireframe shapes +- **Breaking:** change `$locale` to the first language in the device settings as a full language tag, such as `zh-Hant-TW`, instead of `Locale.getDefault()` +- **Breaking:** skip deep link query parameters whose name starts with `$` in the `Deep Link Opened` event +- **Breaking:** make SDK-internal helpers in `com.posthog.internal`, `com.posthog.android.internal` and `com.posthog.android.replay.internal` non-public +- Add `captureAi()` to send AI events such as `$ai_generation` to `/i/v1/ai/events` on their own disk queue, returning the event uuid or `null` when the event isn't queued, with the `captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` options +- Add `onFeatureFlags()` to listen for every feature flags load (on the main thread on Android), returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` - Add the `$app_language` property with the language the app displays on Android 13+, and `setAppLanguage()` to set it on every version -- Add `onFeatureFlags()` to get notified after every feature flags load (on the main thread on Android), returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` -- add internal APIs so wrapper SDKs can run their own `beforeSend` on the fully built event before it's sent -- Fix losing an event whose properties hold a nested map with non-string keys -- Give `beforeSend` its own copy of nested properties and options, so an edit never changes your objects -- See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md) for upgrade steps +- Add internal APIs so wrapper SDKs can run their own `beforeSend` on the fully built event +- Send events queued on disk by 3.x through capture v1 after the update +- Cap a capture request at about 5 MiB of events and send as soon as that much is queued +- Use the current distinct ID when the `distinctId` argument to `capture` is empty or whitespace-only, instead of dropping the event +- Stop storing or matching the person-properties deduplication hash for a `$set` sent with `process_person_profile: false` +- Stop printing request and response bodies, property values and `beforeSend` exception messages in debug logs, and log per-batch drop and retry counts instead +- Fix losing an event whose properties hold a nested map with non-string keys; number, boolean and `null` keys are converted to strings +- Fix `beforeSend` edits reaching the caller's nested maps and lists, by giving each hook its own copy diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md index 57116ce82..222618acf 100644 --- a/.changeset/server-keep-on-feature-flags.md +++ b/.changeset/server-keep-on-feature-flags.md @@ -2,8 +2,12 @@ 'posthog-server': minor --- -- Move `PostHogOnFeatureFlags` into `posthog-server`; its API is unchanged -- Bump the `posthog` core dependency to 7.0 +- Bump the `posthog` core dependency to 7.0; `posthog-server` keeps its API, `/batch` endpoint and retry behavior +- Move `PostHogOnFeatureFlags` into `posthog-server` with the same name and API +- Add an `options` property to `PostHogEvent`, which `beforeSend` can read; `posthog-server` doesn't send it - Disable the client at setup when `projectToken` is a personal API key (`phx_...`), as for an empty token, and print why for both even when `debug` is off -- Drop events with an empty name before sending +- Drop events with an empty name before sending them - Merge `userProperties`, `userPropertiesSetOnce` and `groups` key by key over a `$set`, `$set_once` or `$groups` map in `properties` +- Stop printing property values and `beforeSend` exception messages in debug logs +- Fix losing an event whose properties hold a nested map with non-string keys; number, boolean and `null` keys are converted to strings +- Fix `beforeSend` edits reaching the caller's nested maps and lists, by giving each hook its own copy diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 70880147f..529c1a884 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -43,7 +43,7 @@ You need to change code if your app does any of these: | --- | --- | | `com.posthog:posthog-android` | 3.x to 4.0 | | `com.posthog:posthog` (core) | 6.x to 7.0 | -| `com.posthog:posthog-android-surveys-compose` | keep your version, and declare `com.posthog:posthog-android:4.+` in your build so Gradle resolves 4.0 instead of the 3.x version it pulls in | +| `com.posthog:posthog-android-surveys-compose` | keep your version, and declare `com.posthog:posthog-android` 4.0.0 or later in your build so Gradle resolves 4.x instead of the 3.x version it pulls in | | `com.posthog:posthog-server` | see [`posthog-server`](#posthog-server) | These are unchanged, so you don't need to change your build for them: @@ -263,7 +263,7 @@ A payload that isn't valid JSON now reads as `null` from `getFeatureFlagResult(k The flag's value, enabled state, variant and any other flag's payload aren't affected. -If you read a payload as plain text, such as a payload saved as `hello` rather than `"hello"`, update it in PostHog to valid JSON before you upgrade, or your code gets `null`. +If you read a payload as plain text, such as a payload saved as `hello` rather than `"hello"`, update it in PostHog to valid JSON before you upgrade, or your code gets `null`. PostHog no longer saves a new payload that isn't valid JSON, so only payloads saved earlier are affected. Apps upgrading from 3.13 or older didn't cache flag details, so until the app's first `/flags` response, a malformed payload cached by 3.x still reads as the raw string, as it did in 3.x. @@ -279,6 +279,8 @@ The new `$app_language` property is the language your app shows. Android has no | 13+ without `localeConfig` | The per-app language, if one is set. Otherwise not sent. | | 6–12 | Not sent. | +The SDK reads both languages in the background, so the first event after a language change can still carry the previous value. + Strings you don't translate fall back per string, so the value is the app's language, not a guarantee for every string. Call `PostHog.setAppLanguage("de")` at startup and whenever the language changes to send it on every version, or if you translate some other way, such as with an in-app language setting. It's kept in memory only. ### Session replay records screenshots From be3ed4b4008e1c0a29028bf5ce1132034583ee8e Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 5 Nov 2026 13:43:10 -0500 Subject: [PATCH 19/49] docs: scope the debug log changeset entry to analytics and AI events Replay, logs, flags and remote config requests still print their bodies with debug on; only the capture v1 lanes log counts. Co-Authored-By: Claude Opus 5.5 --- .changeset/android-v4-major.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 4d427a392..9b74992bc 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -42,6 +42,6 @@ - Cap a capture request at about 5 MiB of events and send as soon as that much is queued - Use the current distinct ID when the `distinctId` argument to `capture` is empty or whitespace-only, instead of dropping the event - Stop storing or matching the person-properties deduplication hash for a `$set` sent with `process_person_profile: false` -- Stop printing request and response bodies, property values and `beforeSend` exception messages in debug logs, and log per-batch drop and retry counts instead +- Stop printing analytics and AI event request and response bodies, property values and `beforeSend` exception messages in debug logs, and log per-batch drop and retry counts instead - Fix losing an event whose properties hold a nested map with non-string keys; number, boolean and `null` keys are converted to strings - Fix `beforeSend` edits reaching the caller's nested maps and lists, by giving each hook its own copy From cf0caa58e94246a79945c3f46377dffb641a7977 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 5 Nov 2026 15:58:49 -0500 Subject: [PATCH 20/49] docs: note that capture redirect rules also apply to a custom httpClient Co-Authored-By: Claude Opus 5.5 --- docs/migration-3.x-to-4.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 529c1a884..48b84768d 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -356,6 +356,7 @@ The SDK follows a 307 or 308 redirect only to the origin of `host` (same scheme, Any other redirect is not followed and the events are dropped. In 3.x, OkHttp followed redirects to any host. If a proxy redirects capture requests to another host, point `host` at the final host. +This also applies when you set your own `httpClient`: for capture requests, the SDK turns off its redirect following and OkHttp's connection retries, and keeps your other settings. Other requests, such as session replay and logs, behave as in 3.x. ## Event validation From a2b3c67398776a84f7d5167c5d81c2affd192d28 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 5 Nov 2026 17:58:19 -0500 Subject: [PATCH 21/49] fix: keep $lib and $lib_version on capture v1 events (#942) An event queued before an SDK upgrade keeps the version that captured it instead of getting the running version from PostHog-Sdk-Info. --- .changeset/android-v4-major.md | 1 - docs/migration-3.x-to-4.0.md | 8 --- .../PostHogAndroidEventSnapshotsTest.kt | 5 +- .../json/snapshots/batch-request.json | 50 +++++++++++-------- .../java/com/posthog/internal/PostHogApi.kt | 7 ++- .../src/test/java/com/posthog/PostHogTest.kt | 2 + .../posthog/internal/PostHogCaptureV1Test.kt | 8 +-- 7 files changed, 41 insertions(+), 40 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 9b74992bc..2887c319b 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -8,7 +8,6 @@ - **Breaking:** drop events when a capture request gets a non-retryable status (including 3xx), a 2xx without per-event results, or a redirect other than a 307 or 308 to the same origin as `host` (followed at most 5 times); retry 404, 408, 429, 500, 502, 503 and 504 - **Breaking:** cap a `Retry-After` wait at 30 seconds, read it as a minimum wait and accept an HTTP date, and add up to 25% random jitter to the backoff, which still doubles from 1 to 30 seconds, for events, session replay and logs - **Breaking:** drop events with an empty name before sending them, including one `beforeSend` renames to `""`; PostHog also drops events with an empty distinct ID or a name or distinct ID over 200 bytes -- **Breaking:** set `$lib` and `$lib_version` from the `PostHog-Sdk-Info` request header, removing any value set in properties, super properties or `beforeSend` - **Breaking:** send `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, dropping non-string values - **Breaking:** send `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id` as capture options instead of properties; PostHog drops an event whose option value it can't read - **Breaking:** set the `process_person_profile` option to `false` only when person processing is off, instead of adding a `$process_person_profile` property to every event diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 48b84768d..7608f0503 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -19,7 +19,6 @@ You need to change code if your app does any of these: - sets an empty distinct ID in `beforeSend` - assigns a new map to `event.options` in `beforeSend` (see [Event options](#event-options)) - sets `projectToken` to a personal API key (`phx_...`) -- sets `$lib` or `$lib_version` and expects PostHog to store that value - reads `$session_id` or `$window_id` from the raw request body, for example in a proxy - sets `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` or `$product_tour_id` to a value PostHog can't read, such as `"maybe"` - registers a super property, or passes an event property, with the same key as one the SDK sets, such as `$os_name` or `$is_identified`, and expects the SDK's value to win @@ -389,13 +388,6 @@ The distinct ID can come from `identify()`, the `distinctId` argument of `captur If you identify users with a long ID, such as a JWT or a long email address, shorten or hash it before you upgrade. Otherwise every event for that user is dropped. `identify()` with an empty or whitespace-only distinct ID is still ignored, as in 3.x. -## SDK identity - -PostHog sets `$lib` and `$lib_version` from the `PostHog-Sdk-Info` request header, for example `posthog-android/4.0.0`. -The SDK removes `$lib` and `$lib_version` from the properties it sends to capture v1. -A value you set in properties, in a super property or in `beforeSend` doesn't reach PostHog. -The SDK removes them when it sends the event, so `beforeSend` still sees them. - ## Property precedence An event's properties are merged in this order, and later values win: diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt index 619d43fd5..e2d5b534d 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt @@ -31,7 +31,6 @@ import kotlin.test.AfterTest import kotlin.test.BeforeTest import kotlin.test.Test import kotlin.test.assertEquals -import kotlin.test.assertFalse import kotlin.test.assertIs import kotlin.test.assertNotNull import kotlin.test.assertTrue @@ -269,9 +268,7 @@ internal class PostHogAndroidEventSnapshotsTest { UUID.fromString(uuid) event["uuid"] = "" val properties = event.map("properties") - // capture v1 reads the SDK name and version from the PostHog-Sdk-Info header - assertFalse(properties.containsKey("\$lib")) - assertFalse(properties.containsKey("\$lib_version")) + normalizeSdkVersion(properties) // Depends on how many earlier captures the async queueExecutor has drained by the time // this event's properties are built on the calling thread -- not deterministic run to run. if (properties.containsKey("\$sdk_debug_pending_queue_size")) { diff --git a/posthog-android/src/test/resources/json/snapshots/batch-request.json b/posthog-android/src/test/resources/json/snapshots/batch-request.json index 511ee3349..f7fd87b2c 100644 --- a/posthog-android/src/test/resources/json/snapshots/batch-request.json +++ b/posthog-android/src/test/resources/json/snapshots/batch-request.json @@ -38,6 +38,14 @@ "$timezone": "UTC", "$network_type": "wifi", "$network_carrier": "Snapshot Telecom", + "$is_identified": false, + "$lib": "posthog-android", + "$lib_version": "", + "$recording_status": "disabled", + "$sdk_debug_replay_event_trigger_status": "trigger_disabled", + "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", + "$sdk_debug_replay_internal_buffer_length": 0, + "$sdk_debug_pending_queue_size": "", "$set": { "plan": "pro" }, @@ -47,12 +55,6 @@ "$groups": { "company": "posthog" }, - "$is_identified": false, - "$recording_status": "disabled", - "$sdk_debug_replay_event_trigger_status": "trigger_disabled", - "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", - "$sdk_debug_replay_internal_buffer_length": 0, - "$sdk_debug_pending_queue_size": "", "amount": 42.5, "currency": "USD", "items": [ @@ -88,6 +90,16 @@ "$timezone": "UTC", "$network_type": "wifi", "$network_carrier": "Snapshot Telecom", + "$is_identified": true, + "$lib": "posthog-android", + "$lib_version": "", + "$recording_status": "disabled", + "$sdk_debug_replay_event_trigger_status": "trigger_disabled", + "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", + "$sdk_debug_replay_capture_mode": "screenshot", + "$sdk_debug_replay_internal_buffer_length": 0, + "$sdk_debug_session_start": 1700000000123, + "$sdk_debug_pending_queue_size": "", "$set": { "email": "person@example.com" }, @@ -97,14 +109,6 @@ "$groups": { "company": "posthog" }, - "$is_identified": true, - "$recording_status": "disabled", - "$sdk_debug_replay_event_trigger_status": "trigger_disabled", - "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", - "$sdk_debug_replay_capture_mode": "screenshot", - "$sdk_debug_replay_internal_buffer_length": 0, - "$sdk_debug_session_start": 1700000000123, - "$sdk_debug_pending_queue_size": "", "$anon_distinct_id": "anonymous-user" } }, @@ -134,6 +138,8 @@ "$network_type": "wifi", "$network_carrier": "Snapshot Telecom", "$is_identified": true, + "$lib": "posthog-android", + "$lib_version": "", "$recording_status": "disabled", "$sdk_debug_replay_event_trigger_status": "trigger_disabled", "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", @@ -172,19 +178,21 @@ "$timezone": "UTC", "$network_type": "wifi", "$network_carrier": "Snapshot Telecom", - "$groups": { - "company": "posthog" - }, "$feature/snapshot-flag": "snapshot-variant", "$active_feature_flags": [ "snapshot-flag" ], "$is_identified": true, + "$lib": "posthog-android", + "$lib_version": "", "$recording_status": "disabled", "$sdk_debug_replay_event_trigger_status": "trigger_disabled", "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", "$sdk_debug_replay_internal_buffer_length": 0, "$sdk_debug_pending_queue_size": "", + "$groups": { + "company": "posthog" + }, "$feature_flag": "snapshot-flag", "$feature_flag_response": "snapshot-variant", "$feature_flag_request_id": "flag-request-123", @@ -218,19 +226,21 @@ "$timezone": "UTC", "$network_type": "wifi", "$network_carrier": "Snapshot Telecom", - "$groups": { - "company": "posthog" - }, "$feature/snapshot-flag": "snapshot-variant", "$active_feature_flags": [ "snapshot-flag" ], "$is_identified": true, + "$lib": "posthog-android", + "$lib_version": "", "$recording_status": "disabled", "$sdk_debug_replay_event_trigger_status": "trigger_disabled", "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", "$sdk_debug_replay_internal_buffer_length": 0, "$sdk_debug_pending_queue_size": "", + "$groups": { + "company": "posthog" + }, "$exception_level": "error", "$exception_list": [ { diff --git a/posthog/src/main/java/com/posthog/internal/PostHogApi.kt b/posthog/src/main/java/com/posthog/internal/PostHogApi.kt index fed55cb26..236b530b9 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogApi.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogApi.kt @@ -871,8 +871,9 @@ internal val LEGACY_OPTION_PROPERTIES: List> = ) /** - * Shapes a stored event for capture v1. `$session_id` and `$window_id` move to the event root, and - * `$lib`/`$lib_version` are dropped because the server reads them from `PostHog-Sdk-Info`. + * Shapes a stored event for capture v1. `$session_id` and `$window_id` move to the event root. + * `$lib`/`$lib_version` stay in properties, so an event queued by an older SDK version keeps the + * version that captured it. * * Legacy option properties are hoisted here, after `beforeSend`, so events queued by older versions * are hoisted too. Each is always removed from properties and fills its option only when the option @@ -883,8 +884,6 @@ internal fun captureV1Json( logger: PostHogLogger, ): Map { val properties = LinkedHashMap(event.properties ?: emptyMap()) - properties.remove("\$lib") - properties.remove("\$lib_version") val options = LinkedHashMap(event.options ?: emptyMap()) for ((property, option) in LEGACY_OPTION_PROPERTIES) { diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index d16f06f1e..7fcc0d3e2 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -703,6 +703,8 @@ internal class PostHogTest { "\$feature_flag_reason", "\$feature_flag_request_id", "\$groups", + "\$lib", + "\$lib_version", ) assertEquals(expectedKeys, theEvent.properties!!.keys) assertFalse(theEvent.properties!!.containsKey("\$recording_status")) diff --git a/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt b/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt index 230d005af..d4d878a92 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt @@ -229,8 +229,7 @@ internal class PostHogCaptureV1Test { assertEquals(event.uuid.toString(), sent["uuid"]) assertEquals("distinctId", sent["distinct_id"]) assertEquals("2023-09-20T11:58:49.000Z", sent["timestamp"]) - // $lib and $lib_version come from the PostHog-Sdk-Info header - assertEquals(mapOf("prop" to "value"), sent.properties()) + assertEquals(mapOf("prop" to "value", "\$lib" to "posthog-android", "\$lib_version" to "1.2.3"), sent.properties()) assertNull(sent.options()) } @@ -895,7 +894,10 @@ internal class PostHogCaptureV1Test { assertEquals(uuid.toString(), sent["uuid"]) assertEquals("session", sent["session_id"]) assertEquals(mapOf("process_person_profile" to false), sent.options()) - assertEquals(mapOf("a" to "b"), sent.properties()) + assertEquals( + mapOf("a" to "b", "\$lib" to "posthog-android", "\$lib_version" to "3.20.0"), + sent.properties(), + ) assertTrue(sut.dequeList.isEmpty()) } From fadfbfb37b77ebf7c794ccd6bcccd107f34c9f1e Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 6 Nov 2026 14:02:08 -0500 Subject: [PATCH 22/49] docs: warn that older self-hosted proxy recipes strip Authorization Proxies set up from PostHog's proxy guides before 29 October 2026 drop the Authorization header, so capture v1 gets a 401 and the events are dropped. The managed reverse proxy needs no change. --- docs/migration-3.x-to-4.0.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 7608f0503..4cd0c95ae 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -14,6 +14,7 @@ You need to change code if your app does any of these: - sends events to a self-hosted PostHog or a reverse proxy that doesn't serve `/i/v1/analytics/events` - authenticates its proxy with an `Authorization` header in `requestHeaders` +- sends events through a reverse proxy set up from PostHog's proxy guides before 29 October 2026, which strips `Authorization` - sends events through a proxy that redirects capture requests, other than with a 307 or 308 to the same origin as `host` - captures events with an empty event name, or with an event name or distinct ID over 200 bytes - sets an empty distinct ID in `beforeSend` @@ -345,7 +346,7 @@ If you send events through your own reverse proxy, update it before you upgrade: - Accept request bodies up to 20 MB. AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx. A `413` from the proxy makes the SDK halve the batch until it fits, and drops an event that doesn't fit on its own. - Pass PostHog's response body through unchanged. A 2xx response whose body isn't PostHog's `{"results": {...}}` drops the events instead of retrying them. -PostHog's managed reverse proxy already does this. See the [proxy guides](https://posthog.com/docs/advanced/proxy). +PostHog's managed reverse proxy already does this and needs no change. A proxy set up from PostHog's [proxy guides](https://posthog.com/docs/advanced/proxy) before 29 October 2026 strips `Authorization`, so PostHog answers `401` and the events are dropped. Update it from the current guide. The SDK doesn't fall back to `/batch`. A 404 is retried, so the events stay queued until the path is served, and the SDK prints one warning, even with `debug` off. Any other error status that isn't retried, such as 403 or 405, drops the events. From a222f70af6a574089ab3f751d6cb1c81458cf1da Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 6 Nov 2026 14:02:37 -0500 Subject: [PATCH 23/49] docs: link the changelog absolutely in the 4.0 migration guide --- docs/migration-3.x-to-4.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 4cd0c95ae..e31951fa6 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -6,7 +6,7 @@ Read the checklist first, then the sections that apply to you. For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/libraries/capture-v1). -For the full list of 4.0 changes, see the [changelog](../posthog-android/CHANGELOG.md). +For the full list of 4.0 changes, see the [changelog](https://github.com/PostHog/posthog-android/blob/main/posthog-android/CHANGELOG.md). ## Checklist From 96722f0c3007367ec99f21653a252ed170e0c843 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 6 Nov 2026 14:23:12 -0500 Subject: [PATCH 24/49] docs: add dialog dim and deep link $ parameters to the 4.0 migration guide --- docs/migration-3.x-to-4.0.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index e31951fa6..95af3408f 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -306,8 +306,14 @@ Compose masking also changed, including for apps that already set `screenshot = - Text that draws past its layout box is masked in full. - Nodes using `Modifier.clearAndSetSemantics` are masked while text or image masking is on. Use `Modifier.postHogUnmask()` to show them. +A dialog's dim, and a dialog masked whole on Android 8.1 and lower, are sent as screenshot images instead of styled wireframe shapes. + The `$sdk_debug_replay_capture_mode` property is now always `screenshot`. +### Deep link query parameters + +The `Deep Link Opened` event leaves out query parameters whose name starts with `$`, such as `$process_person_profile`, so a link can't set PostHog's own properties. Other parameters and the `url` property are sent as in 3.x. + ### Other changes that don't fail the build The code you end up with after these two migrations compiles, so they're easy to miss: From 2832e8442998c3704d3e6376d559d53e2200bef9 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 6 Nov 2026 15:06:32 -0500 Subject: [PATCH 25/49] docs: say the first event after a language change carries the previous value --- docs/migration-3.x-to-4.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 95af3408f..2d707d3be 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -279,7 +279,7 @@ The new `$app_language` property is the language your app shows. Android has no | 13+ without `localeConfig` | The per-app language, if one is set. Otherwise not sent. | | 6–12 | Not sent. | -The SDK reads both languages in the background, so the first event after a language change can still carry the previous value. +The SDK reads both languages in the background when an event is captured and uses them from the next event on, so the first event after a language change carries the previous value. Changing only the runtime override (`LocaleManager.setOverrideLocaleConfig`) isn't picked up until the device or per-app language changes; call `PostHog.setAppLanguage()` if your app changes it. Strings you don't translate fall back per string, so the value is the app's language, not a guarantee for every string. Call `PostHog.setAppLanguage("de")` at startup and whenever the language changes to send it on every version, or if you translate some other way, such as with an in-app language setting. It's kept in memory only. From 56e9998ca5cddef538b16faf7c93c807860bedf1 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Sun, 8 Nov 2026 12:13:47 -0500 Subject: [PATCH 26/49] docs: correct 4.0 server, replay and isFeatureEnabled notes - Server changeset: debug logs still print the /batch body, so narrow the claim to unserializable property values and beforeSend exception messages; say /batch ignores PostHogEvent.options instead of claiming it isn't sent. - Migration guide: say when WebViews are masked, and note that screenshot frames cost more bandwidth and CPU and that newly recorded Compose screens count against the replay quota. - isFeatureEnabled KDoc: a multivariate flag counts as enabled when its variant isn't empty. --- .changeset/server-keep-on-feature-flags.md | 4 ++-- docs/migration-3.x-to-4.0.md | 7 ++++--- posthog/src/main/java/com/posthog/PostHogInterface.kt | 3 ++- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md index 222618acf..d16b8a282 100644 --- a/.changeset/server-keep-on-feature-flags.md +++ b/.changeset/server-keep-on-feature-flags.md @@ -4,10 +4,10 @@ - Bump the `posthog` core dependency to 7.0; `posthog-server` keeps its API, `/batch` endpoint and retry behavior - Move `PostHogOnFeatureFlags` into `posthog-server` with the same name and API -- Add an `options` property to `PostHogEvent`, which `beforeSend` can read; `posthog-server` doesn't send it +- Add an `options` property to `PostHogEvent`, which `beforeSend` can read; `posthog-server`'s `/batch` endpoint ignores it - Disable the client at setup when `projectToken` is a personal API key (`phx_...`), as for an empty token, and print why for both even when `debug` is off - Drop events with an empty name before sending them - Merge `userProperties`, `userPropertiesSetOnce` and `groups` key by key over a `$set`, `$set_once` or `$groups` map in `properties` -- Stop printing property values and `beforeSend` exception messages in debug logs +- Stop printing unserializable property values and `beforeSend` exception messages in debug logs - Fix losing an event whose properties hold a nested map with non-string keys; number, boolean and `null` keys are converted to strings - Fix `beforeSend` edits reaching the caller's nested maps and lists, by giving each hook its own copy diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 2d707d3be..0e73ad247 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -296,9 +296,10 @@ config.sessionReplayConfig.screenshot = true Apps that relied on the default now upload screenshots: -- Masking still covers text inputs, images, `WebView`s, Compose semantics, `ph-no-capture` views and `Modifier.postHogMask()`. +- Masking still covers text inputs, images, Compose semantics, `ph-no-capture` views and `Modifier.postHogMask()`. `WebView`s are masked whole while `maskAllTextInputs` or `maskAllImages` is on. - Custom-drawn views and other content the SDK doesn't recognize, such as maps or video, can now appear in recordings. Mask them, or turn replay off with `sessionReplay = false`. -- Jetpack Compose screens, which wireframe captured as empty boxes, are now recorded. +- Jetpack Compose screens, which wireframe captured as empty boxes, are now recorded. That can count against your replay quota and may need a consent or privacy disclosure update. +- Each frame uses more bandwidth and CPU than a wireframe. Compose masking also changed, including for apps that already set `screenshot = true`: @@ -528,7 +529,7 @@ On Android, listeners run on the main thread. On the JVM, they run on a backgrou ## `posthog-server` -`posthog-server` isn't having a major release, and its API is unchanged: it keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` now ships in `posthog-server` itself. None of the API changes above apply to it. `PostHogEvent`, which `beforeSend` gets, keeps its 3.x constructor and `copy`, and gains an `options` property that `posthog-server` doesn't use. +`posthog-server` isn't having a major release, and its API is unchanged: it keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` now ships in `posthog-server` itself. None of the API changes above apply to it. `PostHogEvent`, which `beforeSend` gets, keeps its 3.x constructor and `copy`, and gains an `options` property that `/batch` ignores. It still sends events to `/batch`, not to capture v1, so the endpoint, proxy, retry and event option changes above don't apply to it either. diff --git a/posthog/src/main/java/com/posthog/PostHogInterface.kt b/posthog/src/main/java/com/posthog/PostHogInterface.kt index 372085531..3d250da0a 100644 --- a/posthog/src/main/java/com/posthog/PostHogInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogInterface.kt @@ -242,7 +242,8 @@ public interface PostHogInterface : PostHogCoreInterface { public fun onFeatureFlags(callback: PostHogFeatureFlagsCallback): PostHogFeatureFlagsSubscription /** - * Returns if a feature flag is enabled, the feature flag must be a Boolean + * Returns whether a feature flag is enabled: a boolean flag returns its value, and a multivariate + * flag is enabled when its variant isn't empty * Docs https://posthog.com/docs/feature-flags and https://posthog.com/docs/experiments * @param key the Key * @param defaultValue the default value if not found, false if not given From 24d26d854b771ebaf7e8dd9c626a83c2a2afc210 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Sun, 8 Nov 2026 14:58:13 -0500 Subject: [PATCH 27/49] test(replay): fill the stacked-dialog dim as a rect in the golden render Stretching the 8x8 dim bitmap blends anti-aliased text edges differently on macOS and Linux Skia, so the re-recorded golden failed on CI. The dim is one solid color, so fill it as a rect (as main does) and restore main's golden. --- .../PostHogReplaySceneSchedulingTest.kt | 24 ++++++++++++------ .../replay-masking/stacked-dialogs.png | Bin 23270 -> 23270 bytes 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplaySceneSchedulingTest.kt b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplaySceneSchedulingTest.kt index f781ebd19..539e021d8 100644 --- a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplaySceneSchedulingTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplaySceneSchedulingTest.kt @@ -6,6 +6,7 @@ import android.graphics.Bitmap import android.graphics.BitmapFactory import android.graphics.Canvas import android.graphics.Color +import android.graphics.Paint import android.graphics.Rect import android.graphics.Typeface import android.graphics.drawable.ColorDrawable @@ -431,20 +432,27 @@ internal class PostHogReplaySceneSchedulingTest { assertEquals(listOf(0, 0, 320, 400), listOf(dim.x, dim.y, dim.width, dim.height)) val dimBytes = Base64.decode(assertNotNull(dim.base64).substringAfter(','), Base64.DEFAULT) val dimImage = assertNotNull(BitmapFactory.decodeByteArray(dimBytes, 0, dimBytes.size)) - try { - assertEquals(Color.argb(102, 0, 0, 0), dimImage.getPixel(0, 0)) - } finally { - dimImage.recycle() - } + val dimColor = + try { + dimImage.getPixel(0, 0) + } finally { + dimImage.recycle() + } + assertEquals(Color.argb(102, 0, 0, 0), dimColor) val bitmap = Bitmap.createBitmap(metadata["width"] as Int, metadata["height"] as Int, Bitmap.Config.ARGB_8888) try { val canvas = Canvas(bitmap) - // Rasterize the emitted screenshots, dim included, in their emitted order and - // geometry. This checks producer output, not rrweb playback. - for (frame in scene) { + // Rasterize the emitted screenshots in their emitted order and geometry. This checks + // producer output, not rrweb playback. The dim is one solid color, so it is filled as a + // rect: stretching its bitmap blends text edges differently across Skia backends. + scene.forEachIndexed { index, frame -> val x = assertNotNull(frame.x) val y = assertNotNull(frame.y) val rect = Rect(x, y, x + assertNotNull(frame.width), y + assertNotNull(frame.height)) + if (index == 2) { + canvas.drawRect(rect, Paint().apply { color = dimColor }) + return@forEachIndexed + } val bytes = Base64.decode(assertNotNull(frame.base64).substringAfter(','), Base64.DEFAULT) val image = assertNotNull(BitmapFactory.decodeByteArray(bytes, 0, bytes.size)) try { diff --git a/posthog-android/src/test/resources/snapshots/replay-masking/stacked-dialogs.png b/posthog-android/src/test/resources/snapshots/replay-masking/stacked-dialogs.png index 8d42ff28d68a15ae5987b97cfa863d1a19b12cf0..99af618542f21309ec33b781aedc6998b12db185 100644 GIT binary patch literal 23270 zcmd431yogEyDz)}0i_#h0RaW+1_33dq(fRzx{+>aDM9J(?(Py0k?scR?%J^7oBNG( z{`WiQJ@=eD?)b*H$8f9->^;|7b3XHVe(@|r6yHi=qLHFOAP`LHH{!|=2x2@0f-w9L z1^fnilvE8I5FC`HL?NYv`-PwTKu)DOY+`=v!<#El=tXR z(f_rZ$`?ZfGaAECO~sIf>8ub*Lp*NDs$Ke-A0ND-)|E-|^4e2Bp2j{crRyPT3TdJF zLLreovxTNC`IY{t*}FcK4~q?n{PE+~wB3_NzD?Ib*8>MW2X}|rXZ|>d;_w#-`=~Pn z{^o}zy1%^Xx&Svg(t*$4gB;$jSHYU-cAe-|GM5VPuq zdBLE4ttElkEH@ev>tvy`gU?eLzV`>9U;@$2CiKb7!-6jH|So zIlL~hyS=@Ab<)pT;eGG*!PvO7zaQPGH=-Mr$|HT!W_vWpT%~c=83VzyW8`KDkJ}lO6qx|^s<2l|lZtI4IhI+?cA}|GCzkO3#T|f7{<@#|&#%o<%=cux} z*e3cgS;U(X0Rchr89{hy{rKf(WH3hLTV!KZRf0e)3N!`=hUwW^nkP>nNGKRzXO~=7 zG5!7hmwzX4KIXA}-1uqxGmCEHoBcw!J(0h1z3}=X;$|dvRj*N^bH{l>QIqi4m zD`gG0db+!~x&3LmTrA>9y}EJi$Bwwa~y>6_+9E$*vT zL&9T^O`vDnF4yaEjuE@k?iYIJvN8v^9p=SXhK6 z@!A;PULD&yI(CP$wmz%bcE2|l6t3~S)2g)$0U-nrIjh;~4zQ%SR8*`r3W;2gTHMY% z!8zGIu8v5lmR?QV49(7xT1=HnB=K04JMC+EoQ+6r4QKdiRg^H_kDs4vOu@v&QDnB3 z_3xo^kGV|0KE%c*2GO8)f%F6fBlpJU`g+LEpKp|ObYA@W_3KC7k{1&SCh60fd+2Ui zrp;38pV=CV%;sjDwav}YA3wxv&U3S~A5!~I*V|>etOO8?YiT8pw}KP1JMO4P#lft)-(P7{rf-b zar%?3VvM+?q>LOK9OCNgu@5mZ)hxy?Zc41@9Ji}HuI(!fIuOm=IzA&C&QyLBU@a@L z8c5{+Q|1jT;)31X9ENgROsbNZe4L-3H*XHZnT-^&>b?I~y}vrUr?1f~`{M!LrC@fW9@8+Dxz(HF+g}${kc#(RDDX8aE-wB7 zqCvvNrT!rrT6F9L_x(7JaKi;QE(uXeVKKO)3Zq^u_D@@iBMlBF6_zs`N~)^a4IC7B z-*H5r($PIqQBg5-`}vjHaH-W(4fRoQcJ@{cN5!A>+tfKGVt;9}U^s?%|JY3RGe(9>5hy`K*2^H&muC9*G zkNvs2ob9gw|I^Kl3X2{Row2WhCOGkT0vC!8)1bVo{c1(me47(qyh=e0myefBIt{Om;;%PJDi=3q+ECpphU zeXHKQ+94{49rVo14B8V;*4fh|X(Z&x%*Hh54H4JTNq)x4N(}Lr$-%3$St0^2wFo7( zy8T$W?%*L*SeFOGEJlp%vvmQo9M%$bI{tx&B z1Z2h(?utVjS;{~xhlGauffv{Q^0E&&ky)ej;bL%Dn14_ZD&z?V2c91aX7sH0)e7p~ zLKCrU97}fsrwI-bQQ%CKNmpNAf#jT046}Bv0StPs+2+;4Rpz)m`49u+LHgWb9m`80 zp_RS8Ffi<6GP15;ztHsb^eRi1W@bn{Z!Wq)Vl=R}jz~{`Qf)pVllPH9KG9$L8$AMK zeqkXhF;Q#vxQ4=eHsZcHw_jg)?25LQs|T$NERe04at&@)q& z@%@LhEo%k`2ZzTbBpK!9isoe&cO$tKdsH;$I-eNX($;o&L%|sh$Mcm0h~vvzp^T~C zcdoavL+_xFkVklUc+30yCAEXq)m&HC*J=$B-J!%?gM(P#7!)M!?ATM?5BLiPhK8`y zyzltkF81DSSAu&n$4*__*w`Vc)9JUE^Rl{y!R!tfh0Fv51<6`lTSw3SbceFruf2Jp z-%4IvTWjm=+zWn_b3w$c^~U>2zA9s}W(6Y12Geym`r)-%9N3gE+soSSz9c7;$0sEr zxtvjHrU`o<)wRJe!4!{gUutW>FUQ4&PpjJ07Zj8J);lm^D?g)X%PT9R(GmkQ_pipB zZu>JDVNAVO(D}C62nDM&5s0#H9`>x>JGH6XEP10P5%Fv)0nZ)hy=mXGvrpf@e}BTs zi4XGds7o*+1T239lSV1TXLc+Y00h&iQVKaaIYmW9A1d!#C94Lo?5k<_w+w&&{CVR4 z%FOIJD4f}oy^D*KR&%x8rMgW=;IF9KwU$w{#)HWr;C8fR?BBh6SMPRSI4*29`V>AH z$jHdg7#TZvCW;(qEN5b;Kn-j@`NgDJYe{l)dK#6M7WuJ1_B|+O$~Vofr$-CUOYnP~ zZuJz5Wzj8ks$D%=>H0Y^5P*Xi8ykCcdrWGqZa}mn?(OZRt1@PQs4z0} zJ6`RT#eTnia)Vqb?DdKL!%rM?flm*6BdL0qJNzuFi&<8K0t5em6Y#m6Jxlexn9(Zn zzCKy6(Rw>~oVR}!C*}x%)$w_QcMV0_tgv@@O6hf8ZCYDyt9NjI>Xto)=U_5_=g^SC z^z?Lad;2SR-j4eAEo+4J2FArG-oDW_EVpFlaO%rAY z+moS2Lsc~xOkW5ttz@v%{%pv_{#>ZpSg!QG%T8-rbMs4h5wCDNH>dW;0l>g;q0y1% z=~MCgrlwGU{X#&Jl7XS4qj!HsM)%Ll%X^50MFdKF;RR(*o|(2VH@8|CIluDR!Gbmf zN4Lp|uqzPr+dYKQr0)%@nQi%g*mmCvd17g4>EG1UbaZh+ zgikMrV=|bmbOURsuYahoug`8VSu8_USuh|bY}6C>x3nAY4c``$URG^Oy@di^)%$6^ zC|Kmrpy#^`jEs!q8@r7jYO5kVpbD^?43aN6N61yfx3{;|oct2cPHH!=;$Zp{l?sEXPh@0dxO%2yy(x?KHx)_&LI{+|BQ8-{B_bg3 zR}g^_fNC4Z5~thv>CsrOycj69sac%l-gl>I@LdRCl;~2%zb@=4^_R0l+rcg`K}*nBE&3=N{T(U|q7}My;&S+0%emG$Csg z{{IO3|93gUzklx6s|>{_baWE6=Q-Kg;Qh~9VVcZYLoeFQ+2MkAIR%AY0M#)?L_|Od zpyA_toaT9vFkY(o4A2TVjNBf}TLoLvyq}2xO{dLEH*pbcxLk#_h|y8y1RlTOHzM&= zA;DY;Tcc(m;z5-4fSvW;-2BV;?*waWYx(CPk&!_yEkao2d_F5(LGVoqVrNoQLtOj; zkL9!v04(Vep+qN^$hc9dY$ABLW~18}|0zOO)Q^h7C8wZ(qpRlYjif7pcep3<$;d)M z-bNF-JwgKOHuzfDGh}01_65j|KL8xT!NdE^V>N34plNVqBq~HxTia-Vw#IZU7jv>y zH#AZh`jA54Q#+`}IqUd%cx(0&`x@qBhPnORvm7h7AVa%sX8US3`R+)5lS zwoD8vzGM~_rp%HI@4SQEAV9$O)2uK=cDpU+D}uIyn&q z8Qb<`O*-Wg6L&jK_>}gP43}F=6!jiD)%GL(wVybERL_{0#!OM404S2P4KUCOC_IyZ zqp^TXW2mgG{6wN`1ncYT8~tQ&U+Kc}3G%0#Sf2poP&l6TI33_M{2kA(JQs*bChp0yxqO2ndjf zS*802u>339BgCc>F6L_e3%(2&29O0#vq#TzWaGpmDTT7P0j0zR6D*%5=p6AVK0jpG z#Onjt7Cka~?rel;$Z(JaB8Y~EhltASiWhYgI*&Q3P>3rjwJerZoV&vUix+}uBadijNf zK&@Mx_DSjG;?sGS0EmL}Q&S^EL`009eG|b~TFpKD`#O_|-SkFKs9ns|*-(M# z$mJOt9mNBDP7fS4FUfNZn3fB%*X7mmcY{8&x5tD)~n2xn`6)t6gLvB2ZY ze4kmXx_!FB2+nMhh1>yNseYxY8LyQFK+!5Fnws^t)E9d*S(6)^n?Var&a|M$K;yoD ze_G@2>RKQ~@HHt(+p1Z7oNt>}grf~t$tYXJw*e4_?7Y0J?Cb{#2?^8HX83@Z7f$9i zHjKbZeh2@ww6yYy3S3`bUqism%rDUp za3JD99rywMC@w1cdG^F*hccU1Dk6AzSh42jdm%oEWDs6VfToGx-@&>^vZS~V-WTpr z4lv9?f}^AH!rl4)1un>|fU&T!bWTla{7&SSwQ^6T6agDDjEwhfv0jVTLuzqX*9Ofx z>y(F&9^oDw9AxUZc^Lu*qI}=kDGCQ6E8E-8Kl}N0XNUzAwgi0%CdKyLklNs-F)t<% zeK>OTks0g}ToOhvwWshmeP592|F0f@iE9V3#(6B^*x}%E3mmp^*UdU@NYR*=RHE} z{r5FGF|`1F=}fr1csAxKEiSjQo2OJy$y^_wgD@Je4V_ppTDA4MKMR7_)(o>^+Iwy^ zWMpgzBsP}$ocs~)Hqxol1SqAXA}xgRCPPvyQxt7038}ALyl&sbKPIDHwWj~|i}ccc zmsDo0LDqDAFBsxYbw+ z?bt(S7@tEbD#lqA9H~}tO>CK2aJ%W~w$^44{7}wbTbMA^oX33szC7Q}R8N%T6V{Z# z#=-H~FNN8oSqN7k-6qCve&BcKulu{tN?oEOB^EwhB7zLWy`2iQEO!Es_N6H@B(cx$ zEsU7Y6WVNXJ9Fj6uPg)w=&^QrEW3%*UVPoKnr=p_i&l=xQ+~e?SYi%K+mjLx47onW z1$U4u5AGm5scz+P?2$}P!z2*MDEy?zoWm&D9}^MDe3&2Tj99o))YFUj+ByV*oS>tX z+fTT;R6F*5mo|EDX!yDQYFD$?p84*qhsoCd69hs)MEHJURvx63_Vlm9wx7y_a1du^ z_)XtWX8w9?e@aPL6=EdWIW#4km=>4USxGfT-M&ONrl07KrsRtrmstTu|D8aH!X(>I zdYCjq8w7#eUC-dX6!9XsZEmT4@mf64|GL5)ER}o^SgK-o{-cYN@q)7O8g9LKK2o#* zM9A>3nMba!jN-Z>QFvPgKhfEEdAokt(dM+x>gsB(yfr3zn<@}=Y!oO9J3*&hW_8f_ z3s8O@zOpk~I9d@N9;T#t1ZlHejIhg+YOnHx(iH}C5-%H=1XW}ON}tZwHyF-fTj1il zQg)$YkK0AwuJk2M#%ydfhos~uy!R?5J*8C|%cz?oNJ!jKpF_F2dDC~wjw+~~Z89H| zYqW~LayTcwAB_V6Gbp9=2h&VoL+hp61LS-<1*_VFTZ$|xtdTdVk-g{VO81cfXSNU3 z;Tx{vIa2xsZ%Koj9v|Oc$H>j{6H+boNP%jpT@V+F`T|s7#sNa&2AiVyPOP^`cd8|s zTvPkqHu>gVSFf!|8^BhCF}0f;g$D0462h3j%dD+!nCZ6Rh;C{I=ertsdH7#P<(rMk z`p&fKYU_lDbmgyPuzBs2?c@o;rd&VnSz0b1ZiZ7XG^#EQO%h!rBMbCyAMS>yE+8E* zIVK%<{ur@!uqv56Ft7>g?4$`_M+^O8U}M50Peww55c9PE_P(V*Ja~(JqgM*-%|xCS z9hyVZ<)FP}on&G6*Rki<*N&YjzhCf8HV*}a$E*5eR{Xa2!UncN+nC2^|diGR7m zf7@(F#!*!{0j5UOQYUj(e^&INPN=+3*(Ft6ppLEy^ymE7b);#%nO;BtqW zd5OCnTdGT;YqE!wr6gHNQzuL|u8fAEY^PsbSdYSPjUA$ucFkxsbG3-(zC;{{pifinTvC>7ok~;&D$HTk@Bek^4;- zG`t$f+S+6w=)?~77P7sVnO_`1!_4@csnHk|(z;SW%29sYvA9S?QPcc`uYC#iveKd4 z7)JEl|M9&~sP?wePgfRo7)7}<2&(H3i(?1^I<_)b_ zZwT@6O=oCN4Q@?jF}2Nxe9~vZVEtwn&5~Q_??x4!3XJPPm|SxR~_?TSzb|0#U5Es{Wah=?SGA4ULeI zowPV+2DJkwI`|3BcHu{%KQpp4=5H`#91_=r;z!u+H0$0owO)PjZ50~{1zX4Cb_VZz zjF21R3(H^P53X*u_!+@>Go{YFP#n&Ol8#q*Fript1GfR8w%aFao$ZDqVDfe*m;(b_p3OT@HwaOgPdK$?hMa9@5l%6VYWbM}0+`Q?PC zzf^KZO}#il-1qcvCa4&s!>A=GDdyzb@)xqw(vJppn?GArJo;Im^oW+0mT!8dvv&?Z z0|`1Q>jCcWL;RV#L2k~{YjZ6W0oPho0yN9{O8f#d64TWK#`C@bmG{>QyTeu5PmJ%% z9)?DQblKcs6_xY@-ZC@Outhpe5^>?g#?Ad&t4DVax(|_|5*~lHw-)_hmp)m@D+3=Y zEJ~q}j0|cx@fodeZbnqnFl6JaZmVv+{ftbE~1Zkx=Ipz5eizcl_B_xnh0?vFv$?(VdIXL(ly^83Zhzbr*=>bL>nfimXe24_{ z8^i}dp&vhbiU{NL26cQab|)Wmn&)#3Ees$xG`Rj8P?0{Blb2^R9>=LUud{dRgxy^8 zc^}(@F>p;-+B*iZjHEEXZPeH~bXQVM($JhVbCuR!mWm^6MYxV_+ z87oQuivh>sR%ui`)hG?PY#i|AZ0@E4!`I<)8d7Jwp zpU8<>^}DyC{MgIA*s`F7Ct)0`T$x<%)U*DnH*G69z(d zoBD~Fr&o$C11CDxg;UI3(Q|NhZ8i)#!Cxem?4-}m8dGNjGzVG8vK4xF4oHCE3m z@w};JtZ((1Am1l0a*q{QUh(QrVt#FuBP;e)>U8>&Nx=(S&)x zUV)}zUaT+$8!b~%h_7SoQn27z-l=if4eow4FOfUr>zxQt8Pch=RuB&rQub!vU>QcuD0?A85r#B z$Ma&nHe@tNtFWGn(FRvdkTd1(bO#cd_d>`Su%kbY@`XEryy9Xc`S`6wYVU=vdsI@< z=aLf4m$Qu-&SlohZ3}Hw;#UP#qh}jd?&Yp?l)zqE@pInjoSe*+yvfN4K-NoR$J}HQ zUs>CBsCVGSmqeqTo}0@wa*rhKl>)hWAW8J4t7jdaKFf9MTcl~tt#jQ2@$s+%wEk-6 z!X9^%seU;m`S2b)Hq6< z<2Vg}{YDh!@e6uf?(D!{{P4;h9Q;Ndemn~^VGqft=K4^&a><8>%Z(U`e-ElZoS>4B zdfwvp10I}@`#wWj+N5PbH|?-&jN{#o?@ ze{_rqX+8`G-=zvy?1o4+o02)9V<4s(ghC#Q& zF56SC2O!~*G0M?oqV(Rr5szX2iRf_GDFJ~1bTBEeOk3pNCUtFOLC2jjQ_*k5d!g%OrYHN&OxQ^kg? zeQWgcM(5@7ynulne*-$&*UZEMi8pQ%0%0AxFkN5sFA?+#3Th%t zPN6s_r@)Q610uhYC+9TcsacELr|!Nn6T4%3u0U*(rvpPO3sNpWNOVGF#qFdY3Aj47 zrz3a{&(0L|7{TGyH`dk>H`Y;*P1*+rkO7HRO=`PrR|5RBBWzp6oO}sj!lT7G2RQh8 zn;iCIKU)W1kM!&Kv;?IAnR@>YEsEo0Qa%64lF#=j{#a7q#Rd1(r z(LV9xH#L!vRC6Vk3T&+DsuE7X3^{E8`~VtbH;9FHzI{|{no`)Wp~A? zK|b&2S~5ovMRmQ1(73Wp3*viH8&+Hrlz(0gB0i+Jq{Nn0P%2TF&=p~0!#JML`sr+~ zogW}i{#bkHhi@tDPR1Lw!ZQ?~RWF9FfeQza=Z!RM)m>I)jN@xko@ibKg*k=3y^KKa zOA(?}irJ2t8C;54_x8D>tl4@Xp4U4Hu19{1R#DQ_e315*f_qX*d;s-tOf5N4&G(%W zwSlGO3;Et2hR&rre7V$kR0u$CxN$C7i+_O2AnwzKZHSMT<9ZyzyS%xIOh#6u)k{1) zlQ+x28M9%$MLCWPfLgXIyIsgbj3d8*fJ&AmadCO_f1F@IC?1loybx6N&5tYP-!TIw zrEJ__>lLhB2?G<;7nD^nnHZGg3MC5it5udW$`)zugRPo1*7%ZG=m8ZK>?{(x-Pwyis+FI+NBkatUV~Nt?WD}t9x&4je>wMgth-cTLhO|=yzl!2;06qFlg`FmX-`QAS1OG@+{JYNK_H}zil8^*>Dk1l;M6Msdf6^Au2kgG1!oq4INfSJTqXSGSLWt{~$HJwFI3 zcAtS$duxU~8crrM={_?)hXXuAL;Uec4G=qk>O)=uJ|H72%S53u8`qe_jV+|DmW_4Rg09+S`Bfk!507TPqx%T&Ve9u0s*X*NzmeIwzhjCPCH=j$O!o)wNoj^Oy zBK2z#f2-C%*e9XWc`nl?;TN3GZ{+nfI;caBhC$w$vr182Jpw66Azk5+5=eYg&TquU z!x4cl(X45}L%YjkEoNu;sPXE?U~3rxiWL-`KLRp!G%@;bT1P5EGj<`7ol zcTWabnOJ)#ERKU)NkiAZa{-vtF;K((+1)WH&g4cboZEXPlW{JUyop^UF==Hia#2dj z?ve2AS`i9`;4zdL4usvH6o9F8O-_;yzKuA#*zuuUK;(uJ6TE~#G(l_OFrVYZ^eSyv z4=0m2rV+58G%MC+Pv((9m~m}LB?||sL~V|=9dbS<7)7PerLXrCL>4Jo z2$o(=6T3|J(F*51n?V4hD^8W4zcsU-OkYg_9B%1?s%O|lY&c8%NmzKeB2ZV&wn?5b zGZ%eI_~{S_#M+9H)c01PcNQ0S0@aU|?GW(5*#~cr}o$pE~iAFC;&USFK)!)=O zIf7fKv zSILuY3$d!WnS9Q9zpK0h$>5_|!3Z$t8HHp`jEn+0J2TxvcjvqNrW?+-W%^wJe2H#gGD^OTsS z6Nr9>hrU_1)pcE4QDWt;Hp_UFQnQua^bds$)LXITWiYM8pqx$q??Jx zCxid8WbbltvxC$IQc^`Mq@ihBp*7Ecv81<{Q;d3V0GSA=kV}s-eE4Ke65R< z=7QgLC>ZwqTQ35{Ysve8)q?Iwk(5S38t4S8ta2FPF6SiQ-#0Kf|6Co`G<`mY@Lkv= zc*PG@##14!!RL{Yejg*Xpx{wY7-?p0g!Y%11bPoYn(F_P!Tq!3f7Oy#HO)FObnK$me0|=)AQ3&aONsRp{bkXmnr-&cl;IE*lb(Oa^YIAN0^tOmS+;IyC6Ry8PDO5 z@xIlSJ=Llz8->wzYAP^x7?lvY;Kd$rYw&v_hWXW{P~ATme=HiPGA(!jiBG8UNqC12 zc@;{O`^@F&Rf&F(lNI;m=I(w7kj@0cVcDQi0-5nm_oNX3Hg+_BGXEz7fm~FJ$7@#{^8JtDptT%b}WGKB)v+Z#zf3<0jr@d4(JGqBp-ZT0ky2J zwGL>9h@`|d*fBid1)HyX3m5svVL!qZIorHS--C)^z->@*b`Jo|@ z_t<4*sm#wfd7xQ79PI3qrry6ZqiF_23w|v8cGp_<)B^J11(iSqP*tW}W_CdC6OXj^ z-5O!W>3eQAUH*{)2-Q=3NkyknEp_h;MKGCV`*buk99$^x3@C-2@F2DqqTeOw07Pa3 zS_;5TF&o`K=ndvdTOPXGAqrGqnwIm?zD*O8Mb9}q9aB&^{IA59BKA)%*`2 zGaP{*fVURFb${F4&u4#2VBEriT%yg-s~Kjt?OYC^ee*T+6QtdlX{xa4Msr@Q`w3GaZzQRMit@u$i{P`KlI z9X4qESy}1&wG>sr1g?l@j!6oxt;mPJCW?q#;L`D4d+TVk3F<}HWJ=p=ILX-XA8%ya-V4flqPSouN-G1i z5j^AoY#a*wpsOEAHDAyn)(klYOC3gAdzbm9EsqJq!vqt6r~9nN3&YSbv-2Klfhj92X*HEz8K^b&8uC#KX?cG5#czMoC$9OYI@kOWP|x zEb_@_g~MYg7KP9wC2F>G{qk`hP?LW2F#H)F`8K+K!%iEtY9f;n+5I^lL`_6FY6|@+d0AUK(Yp0m21*jx&NmWu( z@@hGyp}eLB;b=>*kJs3LMRm;;+%j=P10#4GqdlvH%(r2^3nr1Gj5pel2K}PgwI@g z-e`cjBRc&(3B4ao9c@)g|uI(>LM1}aY-((qQ_YMwV~ z!y5pC&3*r0a!cVmk+re;@rw+w$!IbYmr4Gjb|BRlcB27{Vf@8WRc^>%z8HnDnn0Kd z?H;_MXtmVcqC zxl_7L94|ovjqnN1w=1Lm>&q!|5o^Gm{5SUncP-D3RR=u_2TG@W{aaDW1g28-D=-)YHs^1>R?OMzAE z_QL>Z15tLo=z>m%VxXf`6e^4a0ZzofSuStW5SK@ggxmH7b;?%ZYsO7K(AXZv=YW9a zCzUZ=+C89@*h1a7w0JseAFIBI; zSuehw6o9WyR0i8LBBvk&_Va@6m^=64Ax@#Md5w`N?pRN_nUMggo~|$vIZ?fScrcOG zV|1}SfdoD{4ZC@ro%`_#GYkuh0#nLdE6}Ztp$EQ~LB+fwxc2SpwOc+qmYD<2Bm$)U zU%JRfYOCz~`&R5G#*ZV&Bipg>VaPm_>ToeT_bp{mS=+tz&gEJ?Jd6V+sjGGJVD^2N z=cGR2G)2}-ij6< zxf~bs7a!;c2|&}72k&>}IQbE`1j>t(J&EF_YKkZm)=W`Vpfk||#QB9djY{Rv$Q!nx z06K+&bMEgR8yg#g2VTl5%L*Q0i)99$)c*usg|(@)BdkD{MDA3BawBwcf;&V;pW-z=8>7 zh0WVvkrKm)n*zyc6fhv7yNeZ*tKH@q@NX*T8o+MTug3v6^#H4>$1;4=27qF6jWs5TqDfi;A(nE{GtX{ zduSVT+~DTa8?G(Q=T42rxzQZTGKBHE3}NVfhlsGot^>^cy4_(I_X!JmWtbV9Fr!XB|1?4x8&1kkgJ`s z`=I_PR9pTNA1x|(LGAf^Qs3#&-cPfs1KQ53dE8{jGSeS!p{Hmsu5W2y3YMp7rE!bc zbeP=Vl4TnGIhwr1K8|bPTplZ+ZN0l=Na=Z!x#0_MoFGMEjUr1=s*46qVr7$F_b^w^ zm$UV&tM`|be@kx`#NJ`vcJ%5cbN<+it|~hgzy_jA^L_xHR)Y8dZ#Fw;sRIB=cK05x zg0yd0erHwTH8Hbi-+*>&U}TjucA?YgLAa~oiLNpx6=cCshD8cgwC#XW-CJ-%R&WXc z7{6p^t9smCPYHy-79T)@>yg|TsU2L3AS|_R$OT9vIx=86YmZ*aSc;)yw`b6B!@o|54plB+08Tgv{q;8Y=`$=^vX+g_py#QT_O3E9JPs?k>j^wd6KMf0W z$;VL|1KR&M+f@PEE8uHODBCkm-d5(!dWoS1EibR&gYLGk8)~Ym%k3Gfq`VgDP2;%9}UojvFBwI(XSdVR<90H(CmZNmf2^e$F|`s_vrP4G^tu9%MBruP;V)1 zt023cEf!!tv|eXac`6>RVD9CX61#LX79qfVzo_j{WM$%2tPh&g)GYR{qfGu{g#FVH z`@ealhhq8ceDICJzjBEt&JH^)H|9%p zfH0}lvf_?Wz*5*Bi58HFKucXnK`kC*1@eC-=%>vz_6wlnri+Z6+CdxW`GTBF855_m z1w61!N$G>zpPkW(mARUxq@R3Ucbzx}lOsC^wEJ)}5dj;^koBQ*b3!k^tUyPjgh0T9 z6_Yob;^N#B$tSd-vK$29WPJn)DB1?8LR10z&bNUkZYV3)$F%PaEyF-V=rblJi?7GD zL%O1%0Tu9U)tTPu_#sVPr7jQ^nNVXu^o`YdYWHVDsWYe_Nw{_ck_c$)37}}Y%mBUc)ShWk&~Qrr z2auzoq1ff?T&-nG?JgU5+56OjzMl5^iuK(^&{*+ydz`9T@IH|elA5iP)6fIz10)+gn zb?WTPqF;J>8H(wdna3^t96%KXAiwwcTV9kcj0oh)<(UeKKuk)XcV%*FOOTJ_Kz{yi z3|d*uT}csXi!ft-n?G{V2+&0j_tGl(RA!45nMd_XkbIGJ&`bf|Aaw2X&?K4KX*L6D_Q#EVRt&V`6idwOF=W%tJ3M>bRKV zbZq7ORWañMl%NVNQe#EuwzlL=G{)3#Xl&eC&Y*Q$pO|uF zrxjxj^A?RJ02k>cMmd)5B~7tZZ0cbTcXdl|HLG6!z6_Gy(&{v`6Py3 za?6AY>u1z0YNrngCz_aD{tBC#C~`L$@H(eU7%(o;yNp43`BGAQl2t`sL_evOvO%|u zIrl9otF-xibCurxWxu*J(&oqcxZJ^5mA+`V&2SP%-Nx^CVG(^7OOn<--3ul4Q&NzC zE^4F=AxuBQhEqY$%T?hT>yf?M{m*`gpZIp-XREEPYh>>-x}*pR;_EnNdA~DlmKJHC znQpv-wdFjzYXUnWrsf_s9Gydy?Cj0wVFx}7TxHl;7QVanROWf5{hs92Y+Jhot?*$NxrS=G*&+? zcx{^=K`xjPNz6P}yv-^TE%W_ZMgeQMhG|*`^rWbSBS8-8)awj2-``XhdF;@nCvCn^ znQ&mHs=q&19o_dqx$3Js0R=@8ohmOzY2LAdkg@B0{rhq+L4q8GxYF_O#A$u|ah{EMER-qrITlKG7{-H+oN<1O(u(ujdX@V zjn4Z9kA!%+tVT7dSad8Mf6o8UgskJZSa zkcdn)R0yir+S3;?W2r8_W-TFpFqzTS`)NlmQ(0xKvU$Pr&xh)lRSijJlTDcpWBM~3 zA3vSXa`)fUJ!iT5p8cB)ZIB@^f6$xPUiez0c;mOHzQaaqTG9C@(Okp?2%1ZRI+O(+$r%YhkCeE2@UX(*aA}G9^or%bAME0xv~f&w7Ij8XMzUk|_roBvIbD?@g1FQCw1%Y-Cvr?vi zqoY~b@ZkR00`?8p#|<(WY3Z?Meiiihx#dBBwEmWKvEsWYMhPv>$K$04W(!g#j$w6{ z_~X^mMpiJVI7%x1@g1v^L+{&}jk^OI$22GJHVuUc%2KfBw_uUNV_DePqvg~vZVt=O zh`W;`^D_zWb7b>)z6iMKa9dn$xHzmfS^y? zdzIbsr`N4l%veswS_u~OgbxB}YQa=i7z5(}V^SDu2FD$oQ=3Q|@cBXB&c zXH+XrFHPYPA!HDOWzxS*EvPV}tg*!AVzKmx|8zum$~>jG;nY%lWw*qdc;3^rGh0w1 zNB>Q|WG25$Dq{EizS(l(;3S6W*Uz8L3EQG>jbMKl%8_Uky^5PVU$orw*Z9Dbbbhg0 zwrH2SPib1v-LFyf)=H$IA!Z@~eLJ=!9faw`j7`BljCoBhr!rbarN;g|ZfBThcl}`l z2{8l`v;ZzUiRb#=1p3(&{whO(?iNHol}AcgPwjmBwn2UW*8GamW80&A#m)IZF6pM|U^k0Ig??uxYPI@!*Gj;d)|)9k4>r0op!&V!*RF}=?H^51}vP#Ud7+1TD4q%^R;i%)0Ru+ zQwM2?+xiayCMggwRPt)f`-0T9Z{!lL1I>}^6m8#ZB#fD)rsewdT=ui(H%#bWHRv7= z{5Ezd9TX525teg=Sy-G+6LWo9<7>ITka8uhQ+>`bkbLUB!@rCxByzoEKK|qltGo-N z!YU%ffFo&OLy+6WYSA5800CRY@J_(?e6V3aw|H*(RyS^Q_rPcv^b22)em?MdzSY3r5RWlPhBo1pL=HFPV5e`m4AuO&};uRFJUbN9TTsCeN2Y30nr z+0OGg{$tAY3ZtdkD%q)fP_&H_SF2Sku7slENDr-}LLEUv5~DNhs7i~{QpdO>C6tJx zLYdZ8(H2!l9d)$gsw1ut`?a&Xv(G-W&+I z7A3*vya@*nW$I=b3772WY!|{}^hUoL%TXa|N^hP3dD6y)Uy5H(XmS7a2&zy+Jzo$N zR)R9$|H(5;MKxyo>AHk;>H$B{c)jbSHBVa!QT&aE@R$`waHs&G*De;kg1f%e_8VH|IvSL zZd%|p)(ppmz(M6ITBTm|%jv=~T3q=fy&v4*dbj_un`H+r%&qK-h7T;vi{GbG{-Q&! zZ6CC&rsFq=so@)Erww7yj}hyhGF*Az7dob5pC>3|*4EaA6Qj96?`f0_IbvovDd`ii z6I0Zo6&1uxWMoP?v+06RCK?0(zTr%L5L(lK|3e?kD;FfbnzXzU@4(nX-H!TkGCO3V zAgo6$DOf4NTyA_|M%NBfap^M49G1|MP4q+fA$E$D8~6_8<=S?>JxLkaM;G1=y@2r~ zR6=*Wy3)|nV&0yr^M((nTwlD=k!JI*50)xbHKi|WD9GoeStL=?Qn=vG;Ca|qzKg4? zI==Im%j<T%Y1uC>KlT1J3eQS&c2JufxJ6o>zp}Zs zC{$IcOSj|m5rM6XNx^k;22WVVtLMVlLv*0>G~Ar;0^Loct+LA1%(qDdy;?whR6y0* zCscM&kGLV;T{p>E9ta@#ziIh=kT-d#Fa;4l&gEv^j*k2Mz!BH;B6e@BmSC6p+qE%C zn5>>PWowg_e#FoPv02#Wqci0m6x*8U&s+*ontviHCYyav>FyFo=ET^v3%0*v&NkzW zJo9q*(Y2mpug(qd_I}q~Ms`<`MVLnD9KjVNzEJD&=>o34oY-qtXj>I;&zBmJ30h!W zgu#LGQ^h-ba{{Y_)}D^9J$xU^lUaBu%A2Ao?ior_*p_cckGgB!)S{_oFBfR}Ea}xb z(hr!O55;D|eRX7NklVJi;qq{k3F3q0RpO40(pHo;J^Iz}g$P01psb{5221j_=^aOv zd7pT;Tg}DvaYJ>y%z$mVw1%5%NXV)7N809`Tnp#EBYMFma7}EUQzx$6i=3hE_H7-P zP2`R50^T@2C+u*y1-8Tuew?9B$JMFjH12x=*`hQdXP+XfAh1cN z?{Mh}3qAn5i!m32muL0w{gd5kw$=+Oj@I_{ z3$3=_1c1p^I~u?`dNgF}^~hBuK?y^nc~ysMHx_=#c%!{gh}CNnSPP`+dVxbdkE`ZB zc^R={?pifhcqXr?4E;Yr>Rk z{MvlqGjU0_ZvvnyMhT{I%xUl}hm*_n3jE~AvaoFPr#D9AH>I}jEADUQ@XEa_Xz#g%$Vn743p^nN`CiD7l*ql zz)@Jl0j8aE5w->+9|dEN4*I(ynV7COqlHe5r#d`fzVE6=zv_F6kA4|@q;Q|&amG5x zmRQa1JxmkBJNFOZI+gA+dHt@$@G&%fjkGn|;V={H_H{&7^!me}*8k!xp>?OK&9PWT zel%X;U+qQY>jm~V_}+@M?IyDrAl@ish?~qQzfP7uyNr9|my$Dm)uj9=gZ0FQ^M+4S z$lceDn*;b+YWsc&G5eFmqZv85oM-_8t7-ixmtAWzJ~{GpV%JGiS;JzKlv=?J<$fc? z)zy1K*xFe&t8_t%=*9|be0)SkGUFz;F=~mmHs`*2PvAX-&&=b5+mXV4Y;`~G1=b7l zOaHf1yu;7Lpb%;9)!V z0W)GTLBAqmQ+x7S64BtK%YNmKF5pP%DO4WYr)mTsD{wbGLzJx|vnB(&#O01jkk)87 z4v8}ww8zhOFrpX@$s9)?mq=0Ap3cf$c4OR+Ss|Y|<=!4kNNB*YfZCgFbd+Uzy{tDp zUzE`v#weMvRfoyF(Z?}X2rJs2O7$OQ%gV|-QhEhKpY$goI@Zd zo+}zamMk*dGQO*XoQW*Q7ahOmGK0u9@gFg%R%mH2dXnZLJnU;q$}ti)O>-5V0I8D7 zJ?D4pJy55SYtJe^DhHTH5|~z=-z%e@AFnv0U1T!9X~VZ?q7)HNa2@vq3;fF~(Co1; zGp_vb&gq2%YkqZbOn8GAj5}lj&OpF3&bQ^bG-I2WpKo?)hgs5IpOZE81)ikx4hAly zD_ryVxdCzdhe+W~`{!lP#xLHY2J9}D&XhN^xwyHE^k1;F3cVf+%(Hh>@f_he(jgb6 zr&{0^L0tKK#YGJ}+c}SK%mMBSLs}BS`>mQcWSrMuC$AB{7|e##Nqa5NXF%o+Bf|5tS58kQGOj+w5O!ymi8GZS^Ktp>Oj1@$;8h*6}%$WfPM> z8-0*Ea`0Y08Pe6+J}z(W2;TLOrs@?yAhZMwbiZ%{nfaXJwxsqmBpOBO?k%rEmgoiX z-HT!5_sVchP2TiiZ@?>73X79r^KNY{af`_(XMn7P-Heb^Z3IiOs0jeEgJ;&vNyK2L zmy7d2_?v3_ojuZ}Uo{`#-Cy6SE6m5+x$Afs2Bqe~WV*^EOQ+A7HK`P&Q<6pr-aX~S z@YQDRZt=p@@uRou4zpvB!3`7sLYb%0fF=Ed^=>^c1QR#y7yWk4;e5mE^D|P&EAR2$0F!zDzBG?`<^=4f$-Oj#ykxmtZ0`FRs09G zU8(;rhZ*dtI>(t>f}^0My3Wwu{L)F@B|)^vfOS zplxyb+d@-!tuBv(O=|iv3bD)y3lKk0z`^}shhCd0E`Cv!lKL*O=i&Xc1S36DIO*wy zHpe1Inr-e|a%10G~RGru|fm-e2bLHJQmU-#?uJ3T{$C$R7>|<$t1>O%( z>l=5vv8%lcCWrQ)esgAfr^nTUnGUS^Xyul=;>H&JqH>i*)z{qj{?7+hbpH){?yT>W zd>mO!oz@08@cUFy*)YJ-(cr%ww1XmQ_5l-Ht^3E`{9n04ge`u(^~DVl!yS;M`S$e2 zY{Sj}g--sEF@6tel*)R2DpnLg7lw8J$DwSAkF|e1x4MtE4JVMfsr9*HlS`3*1$l{V AJOBUy literal 23270 zcmce;1z42dx;H$Egmfq!(x9Z2w2~qM0@4i%GL&==Al;%8f`D{4Lw8Eo0MaGh-SDpY z?|shM=X~!z-#*uOu5T{99%N>oSLHE_6NuOce}DeR|Q2miTeFCq6913Wx1-UUG*k05eVFW$QR*qU+Hd}}r- zzPCI0ZjI^%J{A>0i8Pz0@pv}(2Dyn`s+RFVVZu8B)6>y8rc2Wq1xFLzv=7Fq9lr_P z2`Tt3HA@Dq9=tG@$mHcyI+IA<6Zl|cpPQIeC;pcgFw8U7>kXM$Mlz=y*!AHj>f>jkv26o^&PMF zIJd*57STMh8f8|PXtZOS)8<_{8(ldYj=dhyP8769OG!!D+uLiB=d6F5RuA939iyfp zfOBA4>6a%ZB}FKSUq3*{qn0u?WvZ*I<8nQCceTvvrMy{bxBTjL0zVE12gdLnp);2n z7(SsSoOE1V_?Z5wqYqwdb^?suPP z5N@I2;^wwE<2+ZuljP@j?{ys49WZY#o0j1<%VE?6+l8V6Pga#(Q!Hq=+w*9#jPA$L&F=F=j@ za=H8KTo1XNcXSJu+=g$iFZZYI2aLMEvHouKYSd21oGZ#)LeKWPji44KCmEyf!Oq~trbr4x^ZP-V0gJblBFbj zdvmRrWkx|OaSFcobY@pCwe2Jg}oyw58>mBFC*?M=C%Z_l0_I#}} zDSiDUmM2e$cIyr!&bG=1(odFqVnZj&%tBjQB$PEZSzx!9b6D&G_02uw6?nW>jhV~i z1v<>($;ru_rhV~@{MOSf@WzXcJmc$&Oc-g(Smyev&Rm7Xh*@7epK;e0#^Iwc zjPh+8qj_+BebuP|9E!H&nYTLoy zl8&SnMGjEf+}yk`+C1u~A3mL+pcW|wh5SgGOgJGrE@igx%jXQt%%Reu#KFj!4GF=7 zpDeTnhJwhDAJHh(CGfmFiO!UikdS)!E}hqNp~WBVVH}Q@euC%T(TRmN?AK@7MMRG3 zumgCSl;1LrcYAS>ZfCasiNajHyGB)2)yon4)&7TABpeS`2a=0QcK_g0QL*d0tuvat z-CUj12?=S(j~!il=9kM`zs6QC)Xf>y8a_I50FjF}G&BV9 z1`Cy%nkoTpv|S452*lNQU4EFJkzq8NtH$+I1y7itpI9|ZQ7ysd!v~h@A8~OQ=;-L? z7hTElA;dDDRU^~>{(f;~Wo+j5_BH_t39|woDHjCnE#JUEbjbX4wLNnGAsVb_gsv_& zi!`h47{P~ene|ip`TI8y4VAo@QjVn(b}~F%>HA&hTE<&s(iwq)iFxM(A8ei;}H=DReQUg(+n_OX%S z-kLSDs;Vj}De2GjbSbC}^kyg>zC}X^)hmC@mHcOQH4uEFaf{!5ZIZa6x&zEig@k~{ z>unpZr%xq}jp;l*JP>29yR)KamzU$!5g=4s$Hs_xOnaYeX^}B0{$PQhUtTUPMT*Nb z!mgouV?90c+s#DLuQJr8?bwUVFZu3cU_5tns^Crh`V~c7T-@C4{9qX*Q<1TJEfj!1 zRn^r-;4dn*!NI{t=n^oPSW9awH<(GvXCHrpX-rsLG`>1piu~2r=bw|q>MeWggG2cY z-|KqQz{uLVaCEma$Fw)j=hv^7adB~m9bsgpMP3(2>(AVdSlHOvGd^Wzd=R?frMk7t zwz=)*Zs7R$P5*X&{ZpofIv?NdhvCUnJc9KA_2i40T4#DuQL5$TiL?qjMe%1Y|~Y?lF(!^Pa!ZDzNx8n-(q4G zYj+z)Ov~Qu=#QLO931p;njCM8vaqp%oK34bVl;agp>Qz%SOxt!a*u%_s%zF)bt8u;dzkCo;huiCV8Gr$P{>i^c$|NID*{X zv67yb8WH=B)qfAYg2amRtdiu$iUzNs?C&4!sgU`qWp2(uQ%5Hhr2LY1U4&5y2|8&8 z$ZW;?;q%%gJP%-E^h&abs|q&RQ>ml1A;~Z*Vf7!P?&@HIrJ+TIg~YGkogS8%4a7|DBRs`jU0saHvhuF;*3S?}=k9J(NSv>itu6HY z*>_W9F~Piwf)8SquVeh17q!LKs!}1K2p7_MBn7IQ#FUg_UN?uyq{2@54%J)T(NE$; z-T6UUcc4tXIcuf4@!ntRGyx%4gDcHxdrL^LjyFr1h7S0_&$o{=7E9C9?*Vqw=Qd#C zPUqJI!vEu9+x;+7Zi(@QHL4v0I=btT`9P2C-*~*&r zZtz0M5vcn6iIZwz%=J7ui&5~JkBU05U)}BF2O(kN7Vmcl?eawI#o2l z5p!~KN(+!I9cYD$V*&y`;zJ4oz5sPpQ#UuES=gl&NN%mo&39;NY0uWuBGaAxCGLP9 zB$-PPz!R{ZexswG@@9UeFJbtoP_LHDW>!SRV=4{rvop zn}`c!;lJ_n(F;KLn)>^3197QZewUaacPR}`GWn*E=LK(t<-{i(3jU_HHmRfna4Leo zP6Y%285LFdP?~J(&=3JXKR*UGcH3Zzk=g;2viJ0c+n|&ePxw()10s~FJQ^=tP(!hdBOP}U=nVYl5aOh!ja&iJ*kDsNO zIP5luA7#D%RQzcpfpQ*W`CgINwLCVBn68wJOh|WkH~BV1N=4-hFUYs%3rkCBW7K41 zteLOB)0LK%mXnosT&Sw3q_2Pb_F(_r8lD(nYV7;zla!Q{Up7cKfc?=iGD^3#wPlAV$HzbR!#4(EYSFpz zGO@~eHwn=II61e)7+X|qEHfBvoA7QOy%-QJIi3K&j8C>EQj3e@k^cIJZ2b&#N|D-YY#9X%scQ}tDsuCA_@-@i5ElK_84rjchL=VXHi zU&Eh2?@B%l(Uo|dACP+n;L&g>CX2Bv7*yLyA8k)*#N*z-PXNg5@R2_jNt}1^B!=FK z?1}&#w4l5OT{Y#6;lZD-I1$&Ui;IhUHeMy8~V~Jf&r2 z`>~Bzs1{@S=EJIfAg%GOR0H-Y4#1sWT-+dD{c$uGmy3gdH-K+!Z0t8GDs=FytSl1% zCqWSrXb`ZI@E<;WsB#I;xd&9J@p5-`P)JD24?%l;Vq!E|S=pR{Cq;Fi%FB84wc(gD zG8?sg|BSu`XFHBK!rsB?Q^&HKi&zg14_k*b zafiHA!B>uhzk)(W`(a$I^R5g?LESw)QQyA@TTN9M0UU&Sf+YMI_z*=67nlkBRxK_5 zSQdKYb2ldf9$+IwiI< z($mrXRLObd=k4#0>f!0B{Pu17SSLtEz^v#%Ue>PHErqbt*5^rLHcjt`Pt+d?3sXQo zM@MIz(fH+dan&sH+;Wlo=fM0&wAfln+WKv3E6LQ>O2*4(z zivX~{M4ef)GvrZ<|#L_`z@glgQ=_aSFHwYz@!62No_R!HCv237_VsL}AK*}&GMKjvg*C6JF{BLH>* z9Rq_DrJ!BijGm98Obs*P3R3C!59tZurb3>w9ox06&%72et>+Yc z@bC8b0~K^6+c^8820KrUh3zpKL{mF%^BE!CFzQNY4YxQU947RHD~&_HS*g~mndkZw zw^jE&ppq70rc95YXrH=oYQIAG_k47+lQQ%!DwL#6CGNP=6km}|9aCaP1?C^W)3&I$ zGQ9*hv<=@Jc4|#sgON2#An{0SpZG^2r6Uz40i0{4^8)!vI6|ykoCdXbGKL@cN?e$4 z>FDW&{~A%Qvg1Rmc6I$|=kWZ^Pw}MnDJ&V8TO4uDMo3gv8a_p`U+ICJi@Q_n-XOk% zgOiGmftITvhkipqT$R+c*XR2vC@8ynwi=Q1aorr#JG*pier=vxvg$!8+bIrp(rh6Bc zhCBJ@K=!B{IU>)FMbhh&ks8A0P!K>JG$aj}JUkh^0ePYJ1tt_g65WN&RNz%PAj_$d7My`%Mq*)bw~6VX;&j`)7Zo+ zoccy=jcB@T7FNN}59V%Is2?IubF?`_GzV)$;n9!75YQljJGl$%eESwNrde2Cj_p*z zKV0tP^P-^ZV83=cD2UqR-y*Mz@!;okuRmbCCs&MGVnwqO;UCE}&8LQDTE#WUs*x!ze^4FJXdV`T3M!Vq437 z?}y00iUO;%J!3OT%KMY1W!x)L?-KW?^BcT4)@T;?C#~1$TE)d&u}PMcl*4$o_vOw^ zTh*~CL?9<8PTq?{sxdj{WG+sc+eHf>H~)OvH<6jI?GxUc?BQ%VscdXOKiTztG9*xJ zc1wG7zCB7wQlu-X54$6gv`)`HmzO0TA)VwO9{x~BNH_&Jgc^nIj|4ay$Mzvjop}_g z9QpxizEnbSPS0Jn1gB?oDas9kvbT)@<}eJS3tciLFQlL>fC~pFZ3Q_`M*2PDmZjxj zfyF9XQO|G-Wzj%#IL|7F(Rc&Oo16n96BC@s{zR^y1~xg#)zxGzD+3+=@*1`q)9tdm zuBxO!X`s#2j@=S2H9-vCt^P4?#S>o~t>!U$Z+-{NW}TQ9e?+24D316Q1}a#4&bkJ} zh)MTZG~6{TNqYJpV(xeFo|b_{44u~(9c)zM%s<;m(C(xVwj;%*32!@{a%z5_;{7!Z zMgKcbTJvQ<&?GfrjIyZ}inP4ba@Xr527Kla3!X&Sj35Er z`&HS*`b?zY3pyggdi_@!=;8nJFY5<3WAPK&hcm&z_78fESg^iy`=FE3>=>rn?8>kr6Ev$($exJ=+D8kWQ4{CeiGt1 zDX9VomOLGlqlSgo6_1G^Dx#!{AvI?3OLYJ$6JQqvT_NBYg}cASNB~cd=@zs)pzht| z-v3>`%Oq>_~eP<#~BKVS&Eyms=qo*~u? zOflUbeqUvG98lPr{dE}epl8+~tdaBjD-s%+<|pLohW%rHi3*AO=BO+$oFu-3Jal6Gvx$ ztP2&SW>uY&ammh)oJ(TFz3$5Kv9Si;0G>h8kN}8VCt7Rd@&NNlD;1X^-J3E4D9tgNFE^h9Q`Y`n0mxr_> z`PtdZzq_QPV5(LHv1agFV)VW}i#pNc&f{jg` z$Xl43D{}-V4Ws0i(l#(MA{Z;2!;b8?juZ5J8WtXgAN!FgZ``USp{Nm?8T}HiJ!>1r z%F5b)p)dvDAsnQNjJsmO%p^=qOnt;O;HuV{6CcJ27!%=>&SS}A*+ZTidUIO0F=aoD zGwV0_WFc$zI-cv5P}%y$?26YxiEtLuKn2o@HWw)P&4gn}j!B1eLg z3jR1=qjGHzFod@C?9kz=S^b$3&sA7@W=3mT83p9gw!RQJ$KJ;5aqzL;ryO&1P#mQU z3!}b<>gxU2f5d~8)&HXtFa+`k$rYE&uMyG@h#xLRVj1{<|E{vJxv_YKIO(SN`?#ll zwUo7jt3uzK`+%L%#yI|2O()g)utCbKF5(!e!B!A+M<~n<3)N@q--=&@c6_#@aV@{Wfm>zYtD3DS+ zJEP2ets|D`4J9QkT5uYy{ou;aQTq^7e`zG7v<5!pi;4dFD%!xzqdHdv?kehjwh$}X ziCk)kNR5b?WwCbh58a2j)Pg>~vWmY5!IUsEYoJ;@kq_VeDl7)F->?#3K}GFtv{hyh zG`y`M{@bGotSVw6=7({(P8BTd?0F?uBZs)sKiZb_1oo!SqDc9l-7__P1yFra#`12% zTus?TMeA%oF=Ivsyu-}QB8`6_&t2mI@s1=^TL?QGJ1X%j7Uw`A)YCG*V5oHt-Sd-s zH*y^9V;yMz($eJP%+4NQi>D`RU!mxx{d+F}p{tx6D~Igd^W^!YkIwdLm*ce>j|z3e zU)ajs_m+*-Um~=Tz(}cxm~vJ{WDXdF$gKUmSzA~IcK(yNIMUXpCJ3wfdS4Cu-!VQ^ z3B%`imDHJ=d+sqGk18F@AWg8q?tFjZH`&wVn-ly&lRG!F$ZdP##Q(9lvS7a`rF@3- z&c6`|zR>fPFyw+AsfLoo-IuF0oJ>Kfak4EM8iR)l3psGTShP7k^cNXH&oN*BeY;7J zKGXAD+YK#(GE{1^9vi+~<9z(wQkQTiV@?*pHaK(wo}6*aE2CJ53El#~akn(Q75g>7 z*_3o0m|ih+iAM+6KJCC!PDwwYOhKVa5-ojGa2R~)=bh`%(O*LWx0tuKd;FBAEb7OX zfNU%ce4^OwvC7g?LdM3#E_O~%S=aMca{sD|%l98&iaT&|Hw#cyEXuqVdAegpxAcOE z&}LSqZGR;EZ(&$O+$aTG-oQCpr_$W4WepDx_Yw|uMQMH!IqQ6WaW(PGX%TzO^AZIV z42A@%nDu{flNrF^`r13y`)MCV4%jNTeusbhLni)b*Bbc-vUj-OvWc~lEn0UNXC{DWd1=c@JzLZiI>I#mp|YH- zbMw$_skd7GH+&cJHrE4qORZ`4%-Cz=IvbU{v8_QO_WJR&4ff&{yVH0;@6?_4QxwBX ztOsG-0s@l1uO_NKu0K{xtUX&3jl)FwJu&gqT_X~$Qx-(pc7lY6=j0}9GHhS%D_SxC z$apxZ6}hJPk?XwdvOwW;$rT(#=d2(Z@*h?nt5Q+?PngFf9JB z$YTcv5fR;ST6|?;1YvdHe}-K)roX}NKc2@S%#1rYo3Z>|;lk-NLIU{RNFpyy&A149 zS~}0PP;p}|U<1JE*m#3qa@5ob4R4{E!sOoD1I3JB8jYn9KR?YS4)Y5-isG=~n*A3g z^Z%Qq{@;H7>98YYEQC!j@VOK_gTb>6AwPb9pmeSWE3ba>0Ma5Q#qb14Uj8?aiC!eG zUs?4WsO~6VD#xd6Vr0|C(FAMb9;T5eH8UWWQ>&!uzdypSvwrD3H`gK)yZV6o_{ozy z5PN-(J3emYxYDaM`ut13_+)18fs*N?<&U%5Y-!0zG{P0_;XZ3ybg_J<-7; zB~F(rXDH(0TV|%_$&K;1=-8!eFOR}wy8yI+aPr8Y>}oD?LS^~Ep1VYljtFuznxY*R z4%QdC9)#-tUV-bX%&7*uKV=F4`aCy>=BgP;N}|;5U%G~q2ZFZ(KS9}kWa{q7SOyV!s(qFhAj&4Lv#zU`HyH68gZLzT4wL?&+SY zNYq1p%a0zRu^g?nHuVvUi-bQ!9{Sg^nu8+5r{p4%%-57CkTa(dCy*fCPQf5&%ZB%M z#DBHq*_-jZBm`$~n;^Bw7oA$ykZF*)#q?)vHx)~Hi;9aeEXHkQAldo(0N%LQM$2SQ2x?-(~}B5_aVR& z|JC0WojD-&?`%V4TDW<%oooP?;vUWJ4ln~e(mDoL^cif5c7Q(m93R8cCtn+jtEMkj zSL1Bu-~kf6i|xe&7suVZX3XdgyDN7Lc6U^2Bb}YU#l|l6&pa^Kx9b-D_U&6sXQ+}r zA>6Dt637NSs0L~#{wNpk)$Z3&pcgUr4g;d1E)wtljZxH2EEboRBgxhxq0Os9!Y|gX zbK_XR#|e+%;S+BJ@Q9WGd;7mNKBIG)m~4E38^UE0|+3}X!LYF2jXKZY}aPreB zg()srF9z_%=3gD*yiOKMS)h0>5q}Ffun! z8Ost}Y$9+ISwZ;^rtndz(yui-slC{}we!IL(zpamEyhym; zdNLFA42H>*rSPe~z5ro1=nebT-PK;`iT+VQ@F8#yUMk8-BK)5O1gh~rfJz2>`3k)xD8;0q+@ZWw6M|+3XM{Ysc zR>rV=3ScaV9GzgV__THs*k18cZdol%6ky$)t$0+499#1OR*h86{Xc5`0PH`{=nf1I z=MxcfZt;fIXTXp)#4qNgSJVGbGzXwCr|G{6~!T*86KvGcfcUoE* zJ-}55>p$bI1j@brv( zf2Gvmg3LB*2yz1nR}Ld}F{d->`JI+Zuaq4h?y~%P9kd?d)ymDm#B6{$07so%w_4&8k?S zI8gnIOG-Wg-^HV@CdFp=CwUJLRwxiQ_Ff&f{(ukL`%$o^?+;UB2#ART_Bh1`9Z3sb z)v|C6=vCc|e%#n`HDboO2-Fxh*%5X?Ag*6j6zvXEmeF;GRou%8rt7$5)Ec35T zu=u)Y9Z5IvqcfX8lFQ*21b*)L& z0M}odJ(dLr8yhMrZ)WvA_{*1J)6mV9<-D`wdG4$IzVqUW(t8k4i8X59I40%uz(`sr z!G<8g{0OeeFk2Vi+iUrNB(`a2h#H6t(x=7ZVd3F-L~7V>C!dtL&aZa+C0V1+ z!fT)k+OSkRT3hSCB5ay_I3+T=WkKrs)z>2#+i&gS^m|^0qz&m;i%|Ik&jhfF)~Paz zfWUyCX=SRu3vrUsW0!sw~#7(oa6`(mwQ_~Na9Y}8ga0F}9!5WguRtb&epExh8LTg zJ2|=p337gMbMx^&i2wcxj=E}?0oF{vc~0{+|Eu7gKUt*L=mI;fiK7rR@?(eDECtEySQ$ws;@j`m!W*+pt;Dxprrt`9t#@#5a8 z6oBDp!h(pk%RiDluQJT*@rHo2VscYQlJV(y{n)&g3TI+ApbhAxbep5nCXch?yTYee zAzehWtsNb&HkZMkHSRePjpH-H`~hW!mS^-yijAqqxWE=kw{Fhy{qW<2%-JmS;i03= z{lwq31fhq$z26|-xKu(vCDDl>-oe55LqbAFFB~_AwXC#(i!#ue_rlDDCKS{(KsD{H zrRd7g1P*e4x_HXS1dwuD;$IwZ`}?&eR8e}Ophr?73wLo`)(pMh!rj+cxSA?w%Tgw- z1E;6t!H|o(cIzd$|0G%#9Iho1t zxx_F#*yj>59VibT5T}&q=Z`Vx;^5#|T%VhFYlrZHsvNMQ`8qDk|HDJ!b(y#T^};lp z-A6~;RDORD?!RkH@FFNhwU#UkE1wV3C`KfOk{KSbaz|yK4E9~9ks!u;PVTI^SPZ}@?My`TLFpD^7+NJ z?N-}&8Irj854BY6CH2VgeU6kQHjTr_F8b53Z38z8(5RqB&{4&YH za1e7c#S?Z>(6L9;n$Vbx4$*`=q0~5^dMD(CB37?5K7^49;fr2*AYv5c?e`cL3&}?3|rAjuoGzEF?4(T?+*_S z0)JOuYJfq!j6dBfZbtscuP>SXVbe^l+arFC`+7pPt<%%k!0)Z1rig4yp9&Aba&bsr zM{=wARUELjcjpLq z;|@;-At)gMa|nx=cm=R<>o=BQ4el3#-WM}7l#Co!Wb1^(B?qW#_*R!?j@E=lY6wW_ z)nUt`3p;Radmoe@pf%dbO>KYZJ?SPuqLfZrENW&2Ozdp!rqglGx)5Gpvin5jfh{3e z^s(xOprx!g?77^QFM|;L4ttO`Mh4o&GuAK~p1Tm>z$rhYb|uzv+LC$kf&k!Is&mov zx~J|!H^=9>GVT0;lmE#*D7IP^dqDgk#a#doOisZ`NTO#WrOco2hr>rFiI+$}6%c{> zdgod1f^a@>+0$1I|BPQ!P$tOBGV9h;V*xo65-LA$XoFs<$e~%jr&i@?m*e;y=)i@& zp_d+wRwURDFrNtuW!J~ZQGh*QQlSxXhV(ee{qa+01ASp9 zK2#41bCro86+9zzukqiZvj&{^xl^sywG*4ag8dLsC@Oc+UZ!*XZM+{|C) z00hQA`X9*|{6ojYdd}Y7N8mUhIQGia|5L?Bw1ek~R9|Rv z$>cv0x?y{fRtbd2*+eddfhq`3T#=hdE;hE;ol*F3Pc}9_6VQf$h$tRpfQk^uOj=x` znwkd`(m$euCT?^^E*N+We)7RzzduH)y(Id->}34i8Of`-)%){`L{IiP0=DPwG8N-? zV4|t1iG?PSP6PUuH?7~n-j19gOIpL^Sn{bI?pNnIm4gfr76bC{@JekJnF*4aqRP;6M&dgFLRR%EM<_kpFVLMa@nHu z1RSW)2%;4Cdoh)J=FJM2>i@nb&i~e~GI{OJ_1|?G3{eyWdoMm`!ahAvDrV{mkT{6hFE3JN_S;Oo#r2yfI>8p3s18qCk=%91WfAGbCh<5U0 zyoEWB$cE+@apKNQka=Kb!^H51^8fY$Oxrd8P>tXPKn`h|>3jJ1ngpq^T^wQ@2icRE1o;i&Q<5xW{T@z2CaY4?!;hNCSu!E$z7RwXDBa z_RW_6j8%(Sbuc15OmuLKfB{R(nVW~7XJouDE`uv4Wc5wRfKmr&0w1mU#}^)*9wJ>K zKm1`4+Iz-JgbSP76Z6Ne4o;G~iwf}LJ57KLl6U@fUJ^GQ!<9d|zy;CYZ0tk>b?d9E zyIT`pFQHTQw~qk(#6NhQj220D@R|n6JZ_6*KRa=vn6HyPvtuJPKYfb05EbMAs|?U{ zD(e>>C_JPDeT7$ef~q70@=xo>mn`u2HfEO}JV9M>rc%5K+)3l<>%Q1d_H}<*V>1J$ z6an}F;4}{;S{)~q8qadIP>R*x@mZn1B5}Pt6jh@S>Y57Ui1Ckr4pSUgRGwUso{XVC zl}@GbP#{n~G~c<(u8jTlS8tTSzXkYzJszE~9-OrF4XXjumoK5b#i1`TXrt-s>tNm%bDq9O5AxqCsoU=*0N%pg>w>c~{+c;6}jpXM{7xppQe} z>h>3V-=O2Yg5edb+P$4GUWO;VIcG=7@ z>}nUC2B-;7xL9G5=f`as%7)ou)TN|kU+)Hbu4U)L64(;|H*t^bvD0%BlBULikB}yd z+cHw{;`xmU*#aeyb@Z+!(<_qkq!47ud1f@Af*f`jo67CAkUVtwU3pF1fetzIa52C~ zjkdl`Xr6U8F1|43*N?wN4`IK%z~kyp5*5E@!9c*S^L*Ov<&(nBwxxph-K9vI-oPSfXV6MPQP2Sf?DMw)b4G2Z zOgXD?8LvGGzizmO35!h6>@D27lYoA8$Y7osBq_NXvMFHIYB1}nx?y2v=F2H|0|^KS z08LdzJ5{kTn%YwuDd4KAh|8k8ubY9oB7B{hjFhx#vRfr@yV~v;jlbv?FD#sfsu0w1 zp+{sQ#o}(q*iAtxzCYivAiFyln6nmIBQ-wop%K9GkiIA4sSBE_lH=Oo3zKB}PC9Pj zth2h_jU=2}i;}ec^C4Y(?!HM<^p{l=>YYST^I}nII*#Ky(PDKSYabgUhZq_e;W9I$ zL%hF#C!7$h?nB;G%l_ASuQUxeQVR8iklZgEGz~m8v@p>#X$Xfu{Gz&>(`WBcoHqoV z^`D^8d*25Nl;g^8CHDh0YOs2JWVi%yqrZ&~c^0z^)TO}c|0yT z)&PQcst7&A#&*fZSDxy;dWm>?mNO{%l{rkt?iD%zRdL!ZEKN3G@nf6Z-)!onJuETJfgVS12B=|YbI!Nkr?>lp*0VLC-1LDhEiIJQ)vmy8{5E@iav;xB zY(G$>dEu38+<^#&cw32YOS*NS^tzk7m33&|?9slG2X3Tvdpi*JKA`Ts4P&OGLly|& z*h$R@)mx&Ir~F=JgrMl`;@l;^_v*Lsnepg2%VUn13*gYVDJ6`j=H_A+aa<9tH13;$ zu`XrNjJ1rmS5FwbdrhpaZP3uwI2)lPYE=!9{<&0 z8qWu@kXA1%Y=l$XZdfR2&w|{T`7%g5xxD3wiM??-VMamw=I{NdC9Yt2qXmD@l>bUq z<{wGh|K#;#>p~D{d?su{6krU1{2Lu6X6|{?Fe2-N3}rqe{UF4n`%Ta zOSCU@7I>NAPS4Ed6o3361XSd*ZT;{aE8r(rzmS&RBo1*5B1S|^fAa~i4ybhr zf%IFji4T|+WA!0DmOQj)(l{k&9ChWN^sM%YITLxnr=%Cpr-)OXSzcheG z7^}=*h^f0g8;cLG$}dSoMmR}FGGBYAq|ok|nF14_^nFL;M>5cGfq}hOP!^d&n_NPd z8UunuPlEfU#)%2A1Q2R+@ex_eKgh`ZcH zX2FkkM9B$`p6M~O_JaZ)8zb|kHat9_xN=$y2!s1EJ0Pq)!*TOYy z1q5+GnTa0oAyC4(2WmCn8|n?;9nH;Dy}z`cmQ$1lWpU7PDrW`ittIy$ZzPw4KSChn zF39f%&{g^LJ~>|sm~S18&y*t+Vnzqh>GmdX*<>#IApODTBy|7|wW! zHT#teY&?6MitMrdtDJT?R#3Zldi?48aQQ4Ox6UK~+?43<`wn-z8GKrCmg)d;1 zt$>Xt&IluIx?(PYR?sK|_3Z2G1Ko}GYhxKaz!Dt-**gH|KCl}};jkFumErKsR~b3H z*GGL@Ai2L9xghe;Ap%t$9s?K(s8j4Mt$frKx_)wVIwNj4rF6O1o?GNdrC$c(3OJdF zi8G*hgAYm4ruwQ74q%rf2!Yjd4?<6G67C5)Vp;~q<+qD;|1(ifj-Ci11^vdx*eOR3XfATv6%HcG>ZjXZq58A3(p=_F5=JKY zpr~F1tDBi4T(6cOFxsM_{kuKM!k;y7lFYEcK=&-PqTRu$ucSgBAV^@k2%p+J4xo9X zt{$N;in2FRdK)O9pAaZ2P9ss2bO++?PIg*ylF;|e;fMiT4wvOejGNWtSU`ta!)rk= z*V$^;6Wfmird19OcOmag-*tzvxm7=^JP>*8ARt@BYFvBX z*q{CuH&~E?fk!Zl^H_mApp>7&)ahy3pNs1fU4z&zC#&S`$wJYcN}WpG(N{@ZvkWi(;F9RA+IK*B!2k?$m?Jd-#X?^wZR5&Qr*9r49{n9XZ zYmoR#q##P^b-CNlg@xInko9o&yZW+uB5A9+0tCWgG>_sZ^^6d-ZSci8IZ3;Qc~K-J zBtR0aR|sygF~})9T5lmMC>VX+=@k9Mb<-Hk>XMdL?Axx|)X|bJ4(yQ$d3lN*9qT^& zDY<$*2H;*=p$DFCi+WuYNXkl&TFy$oq*tBY6Fu8o!gMc=je#A-Fqki`u=K?pX7*is z)>;%@9IvPJMNPqh%~zm*lF}_GoY$pC#piwz3Y|=kiYe5jXBB3^r4*5&?Mv9$9yjZ5 z&-hVcJ(YppBJ<%ow;eNIN9POgPa7qxsS;V9)w-O@xj0t2c)`nA1Q5&n`Nj)dY##;f(Z!!-9u=t%hks=B#MVhyJkGcl-%(w;3iJ z(x);y4Z4MscW(GSMGtE9bzUd(>VHAxzbC0bDT*!FLF*r=;#5ea&nkU?e6q=-R`{a~ z78*X%9xCX?fAEweq;goF=FS70K91_II?qjh(91R_2c{ySL z>o2{TO5j)5_4u@?#5jqVQxcc8SR66oHJ{WKq$yan*^^_g3+9e5d6N@|6Ns`M6e7zurAvFZ?|9kb)wa{_Py`^qZw*kLiP|39IG{ z!HXa!TPt#V!T z$pyyG56|8;9i8SC4svY6VN1l|y9Az8DWg=^d{bR%XJceYD*54P?x_(3yV|8KxZI%V znM%9#63IrCJHTs%)1TX8s$P}Y5xymyF2Ak0gHoIF1 z6p!Ds6df$jFv{)hSPR8^%!18P8?PhE|NZp_;zr+-s9IFX#9$!in7k{-7X5fPEvIaD zu=>w~q}vGPgEt^{P(kc`LEJQq9ULAH-O%7YHr__Nc3lp6td^f$;|SH71a~BV zINFmfx9ZgQEVYb&{e>KLbbO7#x8TIJC(=4`(p(;)$gWi)^ZqpxG7KVdsUOK{H`<0e z?VN*1-YtQllCPTfnwF(j?5ZP9W*d<~KI-Tt!rdcj!KkK3aM)=b# ziBxMo8RdaeMzz>o7IIt)E=Jbu7ow{ZF}P$ z;;puJf9UndFpuR<(F;Q=#w4*c-0jH^AUolBfK*kenfCMI*x~5+eQA(xIH;yxUCfbv zyYW1%2tG(v605wo5Gi)9Ya)Z&HST5=m1IlXSpuRFY`wB-PMvX!2Ra?>s+nOm&f7nc zA?-YON8$T%4bUvSUONc7IM%I{@-bP6bZZKVsX2Tr6z*o%n})ePJ-cxhDPT#2NOk3r zhSkca$zoTyC0y0+dKFhUx=&3P%*<_%6Qu>150_WF*(_waS-y-55SuojZ((Kulhl{+ zl}f$F$vTgoyHl+;#;Z^Ool?X>v&_Itc2k}03&Sz>GhHj~8S`rO!I9&EuD&;;z?eiB1^5J0uRsJjp2+0o0o~nwhByNwJR-C_BsQhD>&mBD~`Gl2u2)k z_VEnuWT|7|4ra9;0EQ>$9wGdev$;0TTX3kr*22xkpy$ubem6-^_rUIVPg(7z6t9o$ z%lod6*C*6GTLSXj$8ojy#whc~cSCedj$O_^a~-?C`=+u$-LsDhKSbmSU=P(s~Gfw_pJ^gX_`Yfh8y0VGO&!*0RyEIWFXdqvKJj<22sR=svwo#B)5}Q1dr9jX8^J9H`L0?RxI2SH#Yw=lb`Tlg%arC}*#{B0ko~!{8afRcAnLKY9_JW<3flap} zGya4_hq3+h{RJq#rbb$l+Y4XWun`Iy_TKTT{(i-HzSCQTMN^s^?4S`*E=OO_yU^tk zjs@}VvgA*&8J!Db+f6UhMTD5>y9s`lU`C|putXf$eW`m6YZ0B^6lUC zN^){tnAyuk>dt{{CCw-WJA~~0S9c}L_qMAyh6>W^vs53ZV{lB_-q^DG zYm$egbe(1tAqbOwW%DlZZOlO@7$jv5PtS$qap>i~!=U)JM&ui%ZEgezY+jm~AQ6*H zaTlk(Ao8(nB<$I)cY;c`Xzig5!w(OIA5B@&07s+^4|eM|9ZqU^ry=BNMY=ws37SPc zI{jWBZN4)Kl$v(Jk#ev5ETG7X6F9CKeAQC)-NyPX(u&V1)^Du}?2Oz74AT=;6@nlq z1=wLw_{IPLIu!X}D`*B%6%+c+^4~l6wNlq=aXqsM%Ry{{6z&!zKFOh33KU{$0%DJcoR%quilcsRL^GX20B^=|Zc$duu8 zQxNAEFUe<`d%BzpAxv&T0;*-dlTLwnrgRa2l5uc2g-&|%<90`H^Un9aDq*2d2?1>P z%Wmqa!y^+v&{JWk7BG!B5+WzaD;}0sNgww&4(;%=Q%1v8UPe1aq)WbNvBpVTCYuJC0@IrRmqH2WX92()`l*wDQ3Y zkA=G&9Vvff6PFAzOmU1(DebIjTu4*vwB_Js73&hqetiz+?G0gku&FXajc`xm_|_&C zUx1CF!n*ApKEY^GMG!v!c}`5>nLx*)ATU7Pg(t}YWd=A7lxijOW!oVs{_jn6)cP{ZHD zZ)r>J^6Y5n)GDv6wBesj4=@4m@y!eu9uhutQw3r5Nl(zkwP&KXH2iZIyQB1S#9aPP z?nga2ARe};5SBFUs|i?TmgoDL*Ulvb-uD1T>IzrIMcIM#OINo`ohhxJ!(vq}I=__qqTX+~ymG>ks?@Ryg;U*i$c=9W39`~ zWNGU$VBS4C_Xfi7lgqb~?$Xm=bv;}Y`Bb8md7@Yze^YQ(QHNFH-e=qsH1#}0Cb1`| z(BfvON}UM_oM4j!&*)ZC$GgQZA}Rt)#Ga>j5kKZjt)k7-alw1srOV@l$?h20M+pjH zVVcry)XGB{85zJQ6tnPHKe6a4_4MZ0?pJnZJ;BQSS+xvgdhVxB-`H2(b7`M0>(l~B z(@do$(dZu2RZGW$`$BnXjJUy}T|TxY%7hT56swNh>I6iJq za+blmk1gWp#8b<++lRa}dM>wjZSK`9n@nN@LrIOV=Zk{LR)meoFg36&Aa=&avJ?CQZojv*2J5}6P(2*{mdxuRj^P+CQOA zYpu@CneDT)V*!9<48F75Pn$#@UlPYOI*K;#QCPFgu8oQD=#5tN^ABu4x!`K^We#FR zCWo5MWD~6p7k7ES!bSn!x3lzDyt8@xj0KtXIdpm7v0dclTMR>m_w1CTwsvHe=~bPT zy9^6iVR5eLvRhp>((iW^_;aY-%|CA7Fg+E$5jvq4zVTy$)?Wp>WW6m-Sw!vZTS;ys zecwXo_D#w~)?O+@sJAjT#Hh{**&=j9lD9`MM!LJyj5j~Mm}Z_>|MF)=^n3xP51<3) zf*J5n6xuB%GK4oTYg=_G@BaN?3w>s$)zRIh{uBY24(Qbm4-dZ#eZ%?85Sf33!vgW+ zZb;m;`YaTx6XquJw`##Es|+F(_&@G6$uhHE@56VJGp|duSy{2RN#q@$^w0aPhnkI!1KgCxOSfR&6%y-uKBHvbJJ0T?p|?-ZUCGa7GDDw zT4yKbN8}t@~mc#w^+jU4#QUy(Z%DOOp&`tM3^3xw(^321adz z@vaicL&l^45YYsnQJD49Pr|mdE#?9W2jk%vz&2|HZS3;~;2CBVnG6^8)I(^^)ztu`JQl>!b&s-{$P4!NpPXheje*7y?co8V zo}?fS&mlbYM)$F&Do<(dADWx*-0l?W75h4cpS>(D9UmL{Id|%$0%iB}^jmRpRyi?T zmAZwrnhNR@8CfL3I8IWt{z_sPN`)wmSS)HDf}tLefm$Az^4rX0HtN}=z(=$qCg$Zs zLPJNi91f)PyC#tsjUSp-=yQ?`*r6=bmeG1nw-m@iEHr`eq$=@c85q?(Hv3?8E1xl{ z6)`%c&0`gK`xCKBA#^7K z^KY)LXb{C~H~5DAHsCJ~-%2adGJ?aF+!B$c$-|g6C;28{fYs zD<+;rE*>M@zGMu^Z~2eoY%~^6@sr>i5`lDc2LVG6m^D`l*$=LT4-Z>*jIMzPdB^xb zf`YvKd0}0Lhr5e98oL^7z(37O@ndEWs=)RL{oTK&u+q4WY>vnt<%=H<1J@|bPRTcG ztjq)1n1*~jR*;R6C01k`zTJrN6GY@lIn`93u>RrAly}53)P}3&C#UIY`>w@BU#l$+ zYw3nnN7OP0%EB`F)-M6>4k%9X>tzHo;J>Q@Gv+$9=R OhR_Bk`cJ=iy8drrk_*KE From d6ce5b30ac45c8bdfddb6ceda6a83e1118d1f125 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:29:00 -0500 Subject: [PATCH 28/49] fix: replay onFeatureFlags to a late listener without waiting for the flags request (#948) The catch-up replay for a listener registered after setup() hopped onto the remote config thread first, so it queued behind an in-flight /config or /flags request. With bootstrap flags and a slow network, the listener never saw the bootstrapped values. Post the replay straight to the listener executor (the main thread on Android) instead; delivery still reads the latest value at run time and skips one already delivered, so a load landing right after is delivered once, after the replay. --- posthog/src/main/java/com/posthog/PostHog.kt | 15 ++-- .../java/com/posthog/PostHogBootstrapTest.kt | 72 +++++++++++++++++-- 2 files changed, 75 insertions(+), 12 deletions(-) diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 77c4506d6..799c111e9 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -2592,11 +2592,16 @@ public class PostHog private constructor( val listener = FeatureFlagsListener(callback) featureFlagsListeners.add(listener) - remoteConfigExecutor.executeSafely { - runFeatureFlagsListener { - // Read at delivery time so a delivery already queued can't be followed by an older value. - lastFeatureFlagsLoaded?.let { deliverFeatureFlags(listener, it) } - } + // Read at delivery time so a delivery already queued can't be followed by an older value. + val replay = { lastFeatureFlagsLoaded?.let { deliverFeatureFlags(listener, it) } } + // Post straight to the listener executor (the main thread on Android), so the replay doesn't + // wait behind a flags request in flight on the remote config thread. Without one, listeners + // run on the remote config thread, so the replay queues there. + val executor = config?.featureFlagsListenerExecutor + if (executor != null) { + executor.executeSafely { replay() } + } else { + remoteConfigExecutor.executeSafely { runFeatureFlagsListener { replay() } } } return PostHogFeatureFlagsSubscription { diff --git a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt index ebac2c24c..380e7e5c6 100644 --- a/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogBootstrapTest.kt @@ -15,6 +15,7 @@ import org.junit.Rule import org.junit.rules.TemporaryFolder import java.io.File import java.util.concurrent.CountDownLatch +import java.util.concurrent.Executor import java.util.concurrent.Executors import java.util.concurrent.LinkedBlockingQueue import java.util.concurrent.TimeUnit @@ -49,6 +50,7 @@ internal class PostHogBootstrapTest { storagePrefix: String = tmpDir.newFolder().absolutePath, logger: TestLogger? = null, optOut: Boolean = false, + featureFlagsListenerExecutor: Executor? = null, ): PostHogInterface { config = PostHogConfig(PROJECT_TOKEN, host).apply { @@ -60,6 +62,7 @@ internal class PostHogBootstrapTest { this.cachePreferences = cachePreferences this.bootstrap = bootstrap this.optOut = optOut + this.featureFlagsListenerExecutor = featureFlagsListenerExecutor if (logger != null) { this.logger = logger } @@ -368,24 +371,79 @@ internal class PostHogBootstrapTest { http.shutdown() } + private fun heldFlagsServer(release: CountDownLatch): MockWebServer { + val http = MockWebServer() + http.dispatcher = + object : Dispatcher() { + override fun dispatch(request: RecordedRequest): MockResponse { + release.await(10, TimeUnit.SECONDS) + if (request.path!!.contains("/flags")) { + return MockResponse().setBody("""{"featureFlags":{"beta-ui":"test"}}""") + } + return MockResponse().setBody("""{"hasFeatureFlags":true}""") + } + } + http.start() + return http + } + @Test - fun `onFeatureFlags replays bootstrapped flags to a listener registered after setup`() { + fun `onFeatureFlags replays bootstrapped flags to a late listener while setup's load is in flight`() { + val release = CountDownLatch(1) + val http = heldFlagsServer(release) + val listenerExecutor = Executors.newSingleThreadExecutor() val sut = getSut( - host = "http://127.0.0.1:1", - // the replay comes from setup's flag loading, before /config answers - reloadFeatureFlags = true, + host = http.url("/").toString(), + preloadFeatureFlags = true, bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("beta-ui" to true)), + featureFlagsListenerExecutor = listenerExecutor, ) + http.takeRequest(5, TimeUnit.SECONDS)!! val updates = LinkedBlockingQueue() sut.onFeatureFlags { updates.add(it) } - // setup's load to the unreachable host may already have failed, which keeps the bootstrapped flags - val loaded = updates.poll(5, TimeUnit.SECONDS)!! - assertEquals(mapOf("beta-ui" to true), loaded.variants) + val replayed = updates.poll(2, TimeUnit.SECONDS) + assertEquals(mapOf("beta-ui" to true), replayed?.variants) + assertFalse(replayed!!.errorsLoading) + + release.countDown() + val loaded = updates.poll(5, TimeUnit.SECONDS) + assertEquals(mapOf("beta-ui" to "test"), loaded?.variants) + assertFalse(loaded!!.errorsLoading) + assertNull(updates.poll(1, TimeUnit.SECONDS)) sut.close() + listenerExecutor.shutdownAndAwaitTermination() + http.shutdown() + } + + @Test + fun `onFeatureFlags delivers a load that lands before a late listener's replay runs once`() { + val release = CountDownLatch(1) + val http = heldFlagsServer(release) + val queued = LinkedBlockingQueue() + val sut = + getSut( + host = http.url("/").toString(), + preloadFeatureFlags = true, + bootstrap = PostHogBootstrapConfig(featureFlags = mapOf("beta-ui" to true)), + featureFlagsListenerExecutor = Executor { queued.add(it) }, + ) + http.takeRequest(5, TimeUnit.SECONDS)!! + + val updates = mutableListOf() + sut.onFeatureFlags { updates.add(it) } + release.countDown() + http.takeRequest(5, TimeUnit.SECONDS)!! + remoteConfigExecutor.submit {}.get(5, TimeUnit.SECONDS) + generateSequence { queued.poll() }.forEach { it.run() } + + assertEquals(listOf>(mapOf("beta-ui" to "test")), updates.map { it.variants }) + + sut.close() + http.shutdown() } @Test From f8ac7470c043df4dad714f3f72572094a59d2c28 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:29:16 -0500 Subject: [PATCH 29/49] fix(flags): read an empty variant as disabled in getFeatureFlagResult and onFeatureFlags (#949) * fix(flags): read an empty variant as disabled in getFeatureFlagResult and onFeatureFlags * fix(flags): leave a flag with an empty variant out of $active_feature_flags Applies to PostHog and PostHogStateless. $feature/ still carries the raw "" value, matching posthog-js. posthog-server builds its own flag properties and already left "" out. --- .changeset/android-v4-major.md | 1 + docs/migration-3.x-to-4.0.md | 6 +++++ posthog/src/main/java/com/posthog/PostHog.kt | 4 ++-- .../com/posthog/PostHogFeatureFlagsLoaded.kt | 2 +- .../main/java/com/posthog/PostHogStateless.kt | 4 ++-- .../posthog/internal/PostHogRemoteConfig.kt | 2 +- .../com/posthog/PostHogFeatureFlagsTest.kt | 20 ++++++++++++++++ .../java/com/posthog/PostHogStatelessTest.kt | 2 ++ .../src/test/java/com/posthog/PostHogTest.kt | 24 +++++++++++++++++++ 9 files changed, 59 insertions(+), 6 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 2887c319b..87560ebed 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -27,6 +27,7 @@ - **Breaking:** remove `PostHogConfig.onFeatureFlags`; call `PostHog.onFeatureFlags(callback)` before `setup()` instead - **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `reloadFeatureFlags()`, which receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and `errorsLoading` - **Breaking:** return `null` from `getFeatureFlagResult(key)?.payload` for a payload that isn't valid JSON, such as plain text, a malformed or empty string, or a JSON `null` +- **Breaking:** return `enabled = false` from `getFeatureFlagResult()` and leave the flag out of `PostHogFeatureFlagsLoaded` and `$active_feature_flags` for a feature flag whose variant is an empty string, as `isFeatureEnabled()` already does - **Breaking:** remove wireframe session replay and the `screenshot`, `drawableConverter` and `debouncerDelayMs` options of `PostHogSessionReplayConfig` (use `throttleDelayMs` for the last); replay always records masked screenshots, so apps that relied on the default now upload screenshots and should mask custom-drawn views, maps and video, or turn replay off - **Breaking:** apply `Modifier.postHogMask()` and `Modifier.postHogUnmask()` only to the element and its children, mask Compose text that draws past its layout box in full, and mask nodes using `Modifier.clearAndSetSemantics` while text or image masking is on - **Breaking:** send a dialog's dim and a dialog masked whole as screenshot images instead of styled wireframe shapes diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index a5b48948f..4bb60106d 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -267,6 +267,12 @@ If you read a payload as plain text, such as a payload saved as `hello` rather t Apps upgrading from 3.13 or older didn't cache flag details, so until the app's first `/flags` response, a malformed payload cached by 3.x still reads as the raw string, as it did in 3.x. +### Empty variants read as disabled + +A flag whose variant is an empty string now reads as disabled everywhere, as it already did from `isFeatureEnabled()`, with or without `defaultValue`. `getFeatureFlagResult()` and `getAllFeatureFlags()` return `enabled = false` for it, where 3.x returned `true`, `PostHogFeatureFlagsLoaded` leaves it out of `flags` and `variants`, and captured events leave it out of `$active_feature_flags`. `variant`, `getFeatureFlag()` and the event's `$feature/` property still return `""`. + +PostHog no longer accepts an empty variant for new flags, so only flags created earlier through the API, MCP or Terraform are affected. + ### `$locale` and `$app_language` `$locale` now means the first language in the device settings, as a full language tag such as `de-CH` or `zh-Hant-TW`. In 3.x it came from `Locale.getDefault()`, which could be a secondary language, a per-app language or a value your app set with `Locale.setDefault()`, and it dropped the script (`zh-TW`). It's left out when the device reports no language. On older Android versions, 3.x also sent the legacy codes `iw`, `in` and `ji`, so Hebrew, Indonesian and Yiddish values change, such as `in-ID` to `id-ID`. Update filters that match those. Other values mostly stay the same, so otherwise only check filters if your users change these settings. diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 799c111e9..737d70957 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -908,8 +908,8 @@ public class PostHog private constructor( for (entry in it.entries) { props["\$feature/${entry.key}"] = entry.value - // only add active feature flags - val active = entry.value as? Boolean ?: true + // only add active feature flags; an empty variant reads as disabled + val active = entry.value != false && entry.value != "" if (active) { keys.add(entry.key) diff --git a/posthog/src/main/java/com/posthog/PostHogFeatureFlagsLoaded.kt b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsLoaded.kt index 095744361..c22dce324 100644 --- a/posthog/src/main/java/com/posthog/PostHogFeatureFlagsLoaded.kt +++ b/posthog/src/main/java/com/posthog/PostHogFeatureFlagsLoaded.kt @@ -37,7 +37,7 @@ public class PostHogFeatureFlagsLoaded */ public val variants: Map = featureFlags.entries - .mapNotNull { (key, value) -> if (value == true || value is String) key to value else null } + .mapNotNull { (key, value) -> if (value == true || (value is String && value.isNotEmpty())) key to value else null } .toMap() /** diff --git a/posthog/src/main/java/com/posthog/PostHogStateless.kt b/posthog/src/main/java/com/posthog/PostHogStateless.kt index 1d54edb9b..e66b26004 100644 --- a/posthog/src/main/java/com/posthog/PostHogStateless.kt +++ b/posthog/src/main/java/com/posthog/PostHogStateless.kt @@ -189,8 +189,8 @@ public open class PostHogStateless protected constructor( for (entry in it.entries) { props["\$feature/${entry.key}"] = entry.value - // only add active feature flags - val active = entry.value as? Boolean ?: true + // only add active feature flags; an empty variant reads as disabled + val active = entry.value != false && entry.value != "" if (active) { keys.add(entry.key) diff --git a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt index 4e17effde..b60486ee2 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt @@ -1344,7 +1344,7 @@ public class PostHogRemoteConfig( val (enabled, variant) = when (value) { is Boolean -> value to null - is String -> true to value + is String -> value.isNotEmpty() to value else -> return null } diff --git a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt index 9da19fd32..38bcdacd7 100644 --- a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt @@ -403,6 +403,26 @@ internal class PostHogFeatureFlagsTest { assertFalse(sut.isFeatureEnabled("IAmInactive", defaultValue = true)) } + @Test + fun `an empty variant reads as disabled`() { + val flags = + File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText() + .replace("\"variant\": \"SplashV2\"", "\"variant\": \"\"") + val http = mockHttp(response = MockResponse().setBody(flags)) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false) + val updates = LinkedBlockingQueue() + + sut.reloadFeatureFlags { updates.add(it) } + val loaded = updates.poll(5, TimeUnit.SECONDS)!! + + assertFalse(sut.isFeatureEnabled("splashScreenName")) + assertFalse(sut.isFeatureEnabled("splashScreenName", defaultValue = true)) + val result = sut.getFeatureFlagResult("splashScreenName")!! + assertFalse(result.enabled) + assertEquals("", result.variant) + assertEquals(listOf("4535-funnel-bar-viz"), loaded.flags) + } + @Test fun `disabled SDK returns null from getFeatureFlag and the default from isFeatureEnabled`() { val http = diff --git a/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt b/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt index ffab030c4..f1ef60725 100644 --- a/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogStatelessTest.kt @@ -582,6 +582,7 @@ internal class PostHogStatelessTest { val mockQueue = MockQueue() val mockFeatureFlags = MockFeatureFlags() mockFeatureFlags.setFlag("test_flag", true) + mockFeatureFlags.setFlag("empty_variant_flag", "") sut = createStatelessInstance() config = createConfig(sendFeatureFlagEvent = true) @@ -596,6 +597,7 @@ internal class PostHogStatelessTest { assertEquals(1, mockQueue.events.size) val event = mockQueue.events.first() assertEquals(true, event.properties!!["\$feature/test_flag"]) + assertEquals("", event.properties!!["\$feature/empty_variant_flag"]) assertEquals(listOf("test_flag"), event.properties!!["\$active_feature_flags"]) } diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index 7fcc0d3e2..597a7548e 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -591,6 +591,30 @@ internal class PostHogTest { sut.close() } + @Test + fun `captured events leave a flag with an empty variant out of active_feature_flags`() { + val flags = + File("src/test/resources/json/basic-flags-with-non-active-flags.json").readText() + .replace("\"variant\": \"SplashV2\"", "\"variant\": \"\"") + val http = mockHttp(response = MockResponse().setBody(flags)) + http.enqueue(MockResponse().setBody("")) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false) + + sut.reloadFeatureFlags() + remoteConfigExecutor.shutdownAndAwaitTermination() + http.takeRequest() + + sut.capture(EVENT, DISTINCT_ID) + queueExecutor.shutdownAndAwaitTermination() + + val batch = serializer.deserialize(http.takeRequest().body.unGzip().reader()) + val properties = batch.batch.first().properties!! + assertEquals("", properties["\$feature/splashScreenName"]) + assertEquals(listOf("4535-funnel-bar-viz"), properties["\$active_feature_flags"]) + + sut.close() + } + @Test fun `feature flag called event reports has_experiment from flag metadata`() { val file = File("src/test/resources/json/basic-flags-with-non-active-flags.json") From 1e8fdeaa3c02aeca2abbba9bd3bc2b3ee2a048ed Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:29:33 -0500 Subject: [PATCH 30/49] chore(api): hide @PostHogInternal declarations from the API dump (#950) Add `nonPublicMarkers` for `com.posthog.PostHogInternal` so wrapper-only APIs such as `buildEventForWrapper` and `sendBuiltEventForWrapper` are not tracked as public API. --- build.gradle.kts | 2 + posthog-android/api/posthog-android.api | 16 - posthog/api/posthog.api | 836 ------------------------ 3 files changed, 2 insertions(+), 852 deletions(-) diff --git a/build.gradle.kts b/build.gradle.kts index 2d3d940ef..03a93c9b8 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -63,6 +63,8 @@ tasks.withType().configureEach { } apiValidation { + // Wrapper-only APIs (e.g. for Flutter and React Native) are public for cross-module use but not part of the API contract. + nonPublicMarkers.add("com.posthog.PostHogInternal") ignoredProjects.add("posthog-android-sample") // Pre-1.0 (0.x) module — public surface may change between minor versions until 1.0.0. ignoredProjects.add("posthog-android-surveys-compose") diff --git a/posthog-android/api/posthog-android.api b/posthog-android/api/posthog-android.api index 184deda3e..10a19e4f7 100644 --- a/posthog-android/api/posthog-android.api +++ b/posthog-android/api/posthog-android.api @@ -34,7 +34,6 @@ public class com/posthog/android/PostHogAndroidConfig : com/posthog/PostHogConfi public final fun getCapturePushNotificationSubscriptions ()Z public final fun getCaptureRageClicks ()Z public final fun getCaptureScreenViews ()Z - public final fun getDetectAppLanguage ()Z public final fun getSessionReplayConfig ()Lcom/posthog/android/replay/PostHogSessionReplayConfig; public final fun setCaptureApplicationLifecycleEvents (Z)V public final fun setCaptureDeadClicks (Z)V @@ -44,7 +43,6 @@ public class com/posthog/android/PostHogAndroidConfig : com/posthog/PostHogConfi public final fun setCapturePushNotificationSubscriptions (Z)V public final fun setCaptureRageClicks (Z)V public final fun setCaptureScreenViews (Z)V - public final fun setDetectAppLanguage (Z)V public final fun setSessionReplayConfig (Lcom/posthog/android/replay/PostHogSessionReplayConfig;)V } @@ -60,20 +58,6 @@ public final class com/posthog/android/errortracking/PostHogNativeCrashIntegrati public fun uninstall ()V } -public final class com/posthog/android/internal/MainHandler { - public fun ()V - public fun (Landroid/os/Looper;)V - public synthetic fun (Landroid/os/Looper;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun getHandler ()Landroid/os/Handler; - public final fun getMainLooper ()Landroid/os/Looper; -} - -public final class com/posthog/android/internal/PostHogAndroidUtilsKt { - public static final fun base64 (Landroid/graphics/Bitmap;Landroid/graphics/Bitmap$CompressFormat;I)Ljava/lang/String; - public static synthetic fun base64$default (Landroid/graphics/Bitmap;Landroid/graphics/Bitmap$CompressFormat;IILjava/lang/Object;)Ljava/lang/String; - public static final fun getApplicationInfo (Landroid/content/Context;)Landroid/content/pm/ApplicationInfo; -} - public abstract interface annotation class com/posthog/android/replay/PostHogInternalReplayApi : java/lang/annotation/Annotation { } diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index 4cb3d0084..cbdbaf900 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -24,7 +24,6 @@ public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posth public static final field Companion Lcom/posthog/PostHog$Companion; public fun addExceptionStep (Ljava/lang/String;Ljava/util/Map;)V public fun alias (Ljava/lang/String;Ljava/util/Map;)V - public fun buildEventForWrapper (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;)Lcom/posthog/PostHogEvent; public fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)V public fun captureAi (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)Ljava/util/UUID; public fun captureException (Ljava/lang/Throwable;Ljava/util/Map;Ljava/util/Map;)V @@ -56,13 +55,11 @@ public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posth public fun optOut ()V public fun register (Ljava/lang/String;Ljava/lang/Object;)V public fun registerPushNotificationToken (Ljava/lang/String;Ljava/lang/String;)V - public fun registerPushNotificationTokenIfNeeded (Ljava/lang/String;Ljava/lang/String;)V public fun reloadFeatureFlags (Lcom/posthog/PostHogFeatureFlagsCallback;)V public fun reset ()V public fun resetGroupPropertiesForFlags (Ljava/lang/String;Z)V public fun resetPersonPropertiesForFlags (Z)V public fun screen (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V - public fun sendBuiltEventForWrapper (Lcom/posthog/PostHogEvent;Z)Ljava/util/UUID; public fun setAppLanguage (Ljava/lang/String;)V public fun setGroupPropertiesForFlags (Ljava/lang/String;Ljava/util/Map;Z)V public fun setPersonProperties (Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)V @@ -78,7 +75,6 @@ public final class com/posthog/PostHog : com/posthog/PostHogStateless, com/posth public final class com/posthog/PostHog$Companion : com/posthog/PostHogInterface { public fun addExceptionStep (Ljava/lang/String;Ljava/util/Map;)V public fun alias (Ljava/lang/String;Ljava/util/Map;)V - public fun buildEventForWrapper (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;)Lcom/posthog/PostHogEvent; public fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)V public fun captureAi (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)Ljava/util/UUID; public fun captureException (Ljava/lang/Throwable;Ljava/util/Map;Ljava/util/Map;)V @@ -117,7 +113,6 @@ public final class com/posthog/PostHog$Companion : com/posthog/PostHogInterface public fun resetPersonPropertiesForFlags (Z)V public final fun resetSharedInstance ()V public fun screen (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V - public fun sendBuiltEventForWrapper (Lcom/posthog/PostHogEvent;Z)Ljava/util/UUID; public fun setAppLanguage (Ljava/lang/String;)V public fun setGroupPropertiesForFlags (Ljava/lang/String;Ljava/util/Map;Z)V public fun setPersonProperties (Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)V @@ -175,113 +170,75 @@ public class com/posthog/PostHogConfig { public synthetic fun (Ljava/lang/String;Ljava/lang/String;ZZZIZLjava/util/List;ZIIIIIILcom/posthog/PostHogEncryption;ZLkotlin/jvm/functions/Function1;ZLcom/posthog/PersonProfiles;ZLjava/net/Proxy;Lcom/posthog/surveys/PostHogSurveysConfig;Lcom/posthog/logs/PostHogLogsConfig;Lkotlin/jvm/functions/Function6;Lkotlin/jvm/functions/Function5;Lcom/posthog/errortracking/PostHogErrorTrackingConfig;Ljava/lang/String;Lcom/posthog/PostHogBootstrapConfig;Lkotlin/jvm/functions/Function3;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun addBeforeSend (Lcom/posthog/PostHogBeforeSend;)V public final fun addIntegration (Lcom/posthog/PostHogIntegration;)V - public final fun getAiStoragePrefix ()Ljava/lang/String; public final fun getBeforeSendList ()Ljava/util/List; public final fun getBootstrap ()Lcom/posthog/PostHogBootstrapConfig; - public final fun getCachePreferences ()Lcom/posthog/internal/PostHogPreferences; public final fun getCaptureAiCompression ()Lcom/posthog/PostHogCompression; public final fun getCaptureAiMaxEventBytes ()I public final fun getCaptureAiMaxQueueSize ()I public final fun getCaptureAiTimeout ()I public final fun getCompression ()Lcom/posthog/PostHogCompression; - public final fun getContext ()Lcom/posthog/internal/PostHogContext; - public final fun getDateProvider ()Lcom/posthog/internal/PostHogDateProvider; public final fun getDebug ()Z public final fun getEncryption ()Lcom/posthog/PostHogEncryption; public final fun getErrorTrackingConfig ()Lcom/posthog/errortracking/PostHogErrorTrackingConfig; public final fun getEvaluationContexts ()Ljava/util/List; public final fun getFeatureFlagCalledCacheSize ()I public final fun getFeatureFlagRequestMaxRetries ()I - public final fun getFeatureFlagsListenerExecutor ()Ljava/util/concurrent/Executor; public final fun getFlushAt ()I public final fun getFlushIntervalSeconds ()I public final fun getGetAnonymousId ()Lkotlin/jvm/functions/Function1; public final fun getHost ()Ljava/lang/String; - public final fun getHttpClient ()Lokhttp3/OkHttpClient; public final fun getIntegrations ()Ljava/util/List; - public final fun getLegacyStoragePrefix ()Ljava/lang/String; - public final fun getLogger ()Lcom/posthog/internal/PostHogLogger; public final fun getLogs ()Lcom/posthog/logs/PostHogLogsConfig; - public final fun getLogsStoragePrefix ()Ljava/lang/String; public final fun getMaxBatchSize ()I public final fun getMaxQueueSize ()I - public final fun getNetworkStatus ()Lcom/posthog/internal/PostHogNetworkStatus; public final fun getOptOut ()Z - public final fun getPersistOptOut ()Z public final fun getPersonProfiles ()Lcom/posthog/PersonProfiles; public final fun getPreloadFeatureFlags ()Z public final fun getProjectToken ()Ljava/lang/String; public final fun getProxy ()Ljava/net/Proxy; public final fun getPushIdentityProvider ()Lkotlin/jvm/functions/Function3; public final fun getPushNotificationSubscriptionMaxRetries ()I - public final fun getQueueProvider ()Lkotlin/jvm/functions/Function5; public final fun getReleaseIdentifier ()Ljava/lang/String; - public final fun getRemoteConfigHolder ()Lcom/posthog/internal/PostHogRemoteConfig; public final fun getRemoteConfigProvider ()Lkotlin/jvm/functions/Function6; - public final fun getReplayStoragePrefix ()Ljava/lang/String; public final fun getRequestHeaders ()Ljava/util/Map; public final fun getReuseAnonymousId ()Z - public final fun getSampleRateProvider ()Lkotlin/jvm/functions/Function0; - public final fun getSdkName ()Ljava/lang/String; - public final fun getSdkVersion ()Ljava/lang/String; public final fun getSendFeatureFlagEvent ()Z - public final fun getSerializer ()Lcom/posthog/internal/PostHogSerializer; public final fun getSessionReplay ()Z public final fun getSetDefaultPersonProperties ()Z - public final fun getSnapshotEndpoint ()Ljava/lang/String; - public final fun getStoragePrefix ()Ljava/lang/String; public final fun getSurveys ()Z public final fun getSurveysConfig ()Lcom/posthog/surveys/PostHogSurveysConfig; public final synthetic fun getTracingHeaders ()Ljava/util/List; public final fun removeBeforeSend (Lcom/posthog/PostHogBeforeSend;)V public final fun removeIntegration (Lcom/posthog/PostHogIntegration;)V - public final fun setAiStoragePrefix (Ljava/lang/String;)V public final fun setBootstrap (Lcom/posthog/PostHogBootstrapConfig;)V - public final fun setCachePreferences (Lcom/posthog/internal/PostHogPreferences;)V public final fun setCaptureAiCompression (Lcom/posthog/PostHogCompression;)V public final fun setCaptureAiMaxEventBytes (I)V public final fun setCaptureAiMaxQueueSize (I)V public final fun setCaptureAiTimeout (I)V public final fun setCompression (Lcom/posthog/PostHogCompression;)V - public final fun setContext (Lcom/posthog/internal/PostHogContext;)V - public final fun setDateProvider (Lcom/posthog/internal/PostHogDateProvider;)V public final fun setDebug (Z)V public final fun setEncryption (Lcom/posthog/PostHogEncryption;)V public final fun setEvaluationContexts (Ljava/util/List;)V public final fun setFeatureFlagCalledCacheSize (I)V public final fun setFeatureFlagRequestMaxRetries (I)V - public final fun setFeatureFlagsListenerExecutor (Ljava/util/concurrent/Executor;)V public final fun setFlushAt (I)V public final fun setFlushIntervalSeconds (I)V public final fun setGetAnonymousId (Lkotlin/jvm/functions/Function1;)V - public final fun setHttpClient (Lokhttp3/OkHttpClient;)V - public final fun setLegacyStoragePrefix (Ljava/lang/String;)V - public final fun setLogger (Lcom/posthog/internal/PostHogLogger;)V public final fun setLogs (Lcom/posthog/logs/PostHogLogsConfig;)V - public final fun setLogsStoragePrefix (Ljava/lang/String;)V public final fun setMaxBatchSize (I)V public final fun setMaxQueueSize (I)V - public final fun setNetworkStatus (Lcom/posthog/internal/PostHogNetworkStatus;)V public final fun setOptOut (Z)V - public final fun setPersistOptOut (Z)V public final fun setPersonProfiles (Lcom/posthog/PersonProfiles;)V public final fun setPreloadFeatureFlags (Z)V public final fun setProxy (Ljava/net/Proxy;)V public final fun setPushIdentityProvider (Lkotlin/jvm/functions/Function3;)V public final fun setPushNotificationSubscriptionMaxRetries (I)V public final fun setReleaseIdentifier (Ljava/lang/String;)V - public final fun setRemoteConfigHolder (Lcom/posthog/internal/PostHogRemoteConfig;)V - public final fun setReplayStoragePrefix (Ljava/lang/String;)V public final fun setRequestHeaders (Ljava/util/Map;)V public final fun setReuseAnonymousId (Z)V - public final fun setSampleRateProvider (Lkotlin/jvm/functions/Function0;)V - public final fun setSdkName (Ljava/lang/String;)V - public final fun setSdkVersion (Ljava/lang/String;)V public final fun setSendFeatureFlagEvent (Z)V public final fun setSessionReplay (Z)V public final fun setSetDefaultPersonProperties (Z)V - public final fun setSnapshotEndpoint (Ljava/lang/String;)V - public final fun setStoragePrefix (Ljava/lang/String;)V public final fun setSurveys (Z)V public final fun setSurveysConfig (Lcom/posthog/surveys/PostHogSurveysConfig;)V public final fun setTracingHeaders (Ljava/util/List;)V @@ -373,14 +330,12 @@ public abstract interface class com/posthog/PostHogFeatureFlagsCallback { } public final class com/posthog/PostHogFeatureFlagsLoaded { - public fun (Ljava/util/Map;Z)V public final fun getErrorsLoading ()Z public final fun getFlags ()Ljava/util/List; public final fun getVariants ()Ljava/util/Map; } public final class com/posthog/PostHogFeatureFlagsSubscription { - public fun (Lkotlin/jvm/functions/Function0;)V public final fun unsubscribe ()V } @@ -405,8 +360,6 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public static synthetic fun addExceptionStep$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V public abstract fun alias (Ljava/lang/String;Ljava/util/Map;)V public static synthetic fun alias$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V - public fun buildEventForWrapper (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;)Lcom/posthog/PostHogEvent; - public static synthetic fun buildEventForWrapper$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;ILjava/lang/Object;)Lcom/posthog/PostHogEvent; public abstract fun capture (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)V public static synthetic fun capture$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;ILjava/lang/Object;)V public abstract fun captureAi (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;)Ljava/util/UUID; @@ -425,7 +378,6 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public abstract fun endSession ()V public abstract fun getAllFeatureFlags ()Ljava/util/List; public abstract fun getAnonymousId ()Ljava/lang/String; - public abstract fun getConfig ()Lcom/posthog/PostHogConfig; public abstract fun getDeviceId ()Ljava/lang/String; public abstract fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Boolean;)Ljava/lang/Object; public static synthetic fun getFeatureFlag$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/Boolean;ILjava/lang/Object;)Ljava/lang/Object; @@ -453,8 +405,6 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public static synthetic fun resetPersonPropertiesForFlags$default (Lcom/posthog/PostHogInterface;ZILjava/lang/Object;)V public abstract fun screen (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;)V public static synthetic fun screen$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V - public fun sendBuiltEventForWrapper (Lcom/posthog/PostHogEvent;Z)Ljava/util/UUID; - public static synthetic fun sendBuiltEventForWrapper$default (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogEvent;ZILjava/lang/Object;)Ljava/util/UUID; public abstract fun setAppLanguage (Ljava/lang/String;)V public abstract fun setGroupPropertiesForFlags (Ljava/lang/String;Ljava/util/Map;Z)V public static synthetic fun setGroupPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ZILjava/lang/Object;)V @@ -473,8 +423,6 @@ public abstract interface class com/posthog/PostHogInterface : com/posthog/PostH public final class com/posthog/PostHogInterface$DefaultImpls { public static synthetic fun addExceptionStep$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V public static synthetic fun alias$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V - public static fun buildEventForWrapper (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;)Lcom/posthog/PostHogEvent; - public static synthetic fun buildEventForWrapper$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ZLjava/util/Date;ILjava/lang/Object;)Lcom/posthog/PostHogEvent; public static synthetic fun capture$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;ILjava/lang/Object;)V public static synthetic fun captureAi$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;ILjava/lang/Object;)Ljava/util/UUID; public static synthetic fun captureException$default (Lcom/posthog/PostHogInterface;Ljava/lang/Throwable;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V @@ -491,8 +439,6 @@ public final class com/posthog/PostHogInterface$DefaultImpls { public static synthetic fun resetGroupPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;ZILjava/lang/Object;)V public static synthetic fun resetPersonPropertiesForFlags$default (Lcom/posthog/PostHogInterface;ZILjava/lang/Object;)V public static synthetic fun screen$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V - public static fun sendBuiltEventForWrapper (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogEvent;Z)Ljava/util/UUID; - public static synthetic fun sendBuiltEventForWrapper$default (Lcom/posthog/PostHogInterface;Lcom/posthog/PostHogEvent;ZILjava/lang/Object;)Ljava/util/UUID; public static synthetic fun setGroupPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/lang/String;Ljava/util/Map;ZILjava/lang/Object;)V public static synthetic fun setPersonProperties$default (Lcom/posthog/PostHogInterface;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public static synthetic fun setPersonPropertiesForFlags$default (Lcom/posthog/PostHogInterface;Ljava/util/Map;ZILjava/lang/Object;)V @@ -524,11 +470,7 @@ public class com/posthog/PostHogStateless : com/posthog/PostHogStatelessInterfac public fun aliasStateless (Ljava/lang/String;Ljava/lang/String;)V protected final fun buildEvent (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;Ljava/util/UUID;)Lcom/posthog/PostHogEvent; public static synthetic fun buildEvent$default (Lcom/posthog/PostHogStateless;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Date;Ljava/util/Map;Ljava/util/UUID;ILjava/lang/Object;)Lcom/posthog/PostHogEvent; - protected final fun captureExceptionEvent (Ljava/lang/Throwable;Ljava/lang/String;Ljava/util/Map;Ljava/util/Date;Lkotlin/jvm/functions/Function0;)V public fun captureExceptionStateless (Ljava/lang/Throwable;Ljava/lang/String;Ljava/util/Map;)V - protected final fun captureFeatureFlagCalledEvent (Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;Ljava/util/Map;)V - protected final fun captureFeatureFlagCalledEvent (Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;Ljava/util/Map;Ljava/util/Map;)V - public static synthetic fun captureFeatureFlagCalledEvent$default (Lcom/posthog/PostHogStateless;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Object;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)V public fun captureStateless (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/Date;)V public fun close ()V public fun debug (Z)V @@ -620,19 +562,12 @@ public abstract interface annotation class com/posthog/PostHogVisibleForTesting public final class com/posthog/errortracking/PostHogErrorTrackingAutoCaptureIntegration : com/posthog/PostHogIntegration, java/lang/Thread$UncaughtExceptionHandler { public fun (Lcom/posthog/PostHogConfig;)V - public fun (Lcom/posthog/PostHogConfig;Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;)V public fun install (Lcom/posthog/PostHogInterface;)V - public final fun installWith (Lcom/posthog/errortracking/PostHogErrorTrackingAutoCaptureIntegration$CaptureTarget;)V public fun onRemoteConfig (Z)V public fun uncaughtException (Ljava/lang/Thread;Ljava/lang/Throwable;)V public fun uninstall ()V } -public abstract interface class com/posthog/errortracking/PostHogErrorTrackingAutoCaptureIntegration$CaptureTarget { - public abstract fun capture (Ljava/lang/Throwable;)V - public abstract fun flush ()V -} - public final class com/posthog/errortracking/PostHogErrorTrackingConfig { public fun ()V public fun (Z)V @@ -661,14 +596,6 @@ public final class com/posthog/errortracking/PostHogExceptionStepsConfig { public final fun setMaxBytes (I)V } -public final class com/posthog/internal/EndpointSpec { - public static final field Companion Lcom/posthog/internal/EndpointSpec$Companion; - public static final fun ai (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; - public static final fun batch (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; - public static final fun logs (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; - public static final fun snapshot (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; -} - public final class com/posthog/internal/EndpointSpec$Companion { public final fun ai (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; public final fun batch (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; @@ -676,304 +603,11 @@ public final class com/posthog/internal/EndpointSpec$Companion { public final fun snapshot (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/lang/String;)Lcom/posthog/internal/EndpointSpec; } -public final class com/posthog/internal/EvaluationReason { - public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Ljava/lang/String; - public final fun component3 ()Ljava/lang/Integer; - public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;)Lcom/posthog/internal/EvaluationReason; - public static synthetic fun copy$default (Lcom/posthog/internal/EvaluationReason;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Integer;ILjava/lang/Object;)Lcom/posthog/internal/EvaluationReason; - public fun equals (Ljava/lang/Object;)Z - public final fun getCode ()Ljava/lang/String; - public final fun getCondition_index ()Ljava/lang/Integer; - public final fun getDescription ()Ljava/lang/String; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class com/posthog/internal/FeatureFlag { - public fun (Ljava/lang/String;ZLjava/lang/String;Lcom/posthog/internal/FeatureFlagMetadata;Lcom/posthog/internal/EvaluationReason;Ljava/lang/Boolean;)V - public synthetic fun (Ljava/lang/String;ZLjava/lang/String;Lcom/posthog/internal/FeatureFlagMetadata;Lcom/posthog/internal/EvaluationReason;Ljava/lang/Boolean;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Z - public final fun component3 ()Ljava/lang/String; - public final fun component4 ()Lcom/posthog/internal/FeatureFlagMetadata; - public final fun component5 ()Lcom/posthog/internal/EvaluationReason; - public final fun component6 ()Ljava/lang/Boolean; - public final fun copy (Ljava/lang/String;ZLjava/lang/String;Lcom/posthog/internal/FeatureFlagMetadata;Lcom/posthog/internal/EvaluationReason;Ljava/lang/Boolean;)Lcom/posthog/internal/FeatureFlag; - public static synthetic fun copy$default (Lcom/posthog/internal/FeatureFlag;Ljava/lang/String;ZLjava/lang/String;Lcom/posthog/internal/FeatureFlagMetadata;Lcom/posthog/internal/EvaluationReason;Ljava/lang/Boolean;ILjava/lang/Object;)Lcom/posthog/internal/FeatureFlag; - public fun equals (Ljava/lang/Object;)Z - public final fun getEnabled ()Z - public final fun getFailed ()Ljava/lang/Boolean; - public final fun getKey ()Ljava/lang/String; - public final fun getMetadata ()Lcom/posthog/internal/FeatureFlagMetadata; - public final fun getReason ()Lcom/posthog/internal/EvaluationReason; - public final fun getVariant ()Ljava/lang/String; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class com/posthog/internal/FeatureFlagMetadata { - public fun (ILjava/lang/String;ILjava/lang/Boolean;Ljava/lang/String;)V - public synthetic fun (ILjava/lang/String;ILjava/lang/Boolean;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()I - public final fun component2 ()Ljava/lang/String; - public final fun component3 ()I - public final fun component4 ()Ljava/lang/Boolean; - public final fun component5 ()Ljava/lang/String; - public final fun copy (ILjava/lang/String;ILjava/lang/Boolean;Ljava/lang/String;)Lcom/posthog/internal/FeatureFlagMetadata; - public static synthetic fun copy$default (Lcom/posthog/internal/FeatureFlagMetadata;ILjava/lang/String;ILjava/lang/Boolean;Ljava/lang/String;ILjava/lang/Object;)Lcom/posthog/internal/FeatureFlagMetadata; - public fun equals (Ljava/lang/Object;)Z - public final fun getEvaluationRuntime ()Ljava/lang/String; - public final fun getHasExperiment ()Ljava/lang/Boolean; - public final fun getId ()I - public final fun getPayload ()Ljava/lang/String; - public final fun getVersion ()I - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class com/posthog/internal/FlagConditionGroup { - public fun (Ljava/util/List;Ljava/lang/Double;Ljava/lang/String;)V - public final fun getProperties ()Ljava/util/List; - public final fun getRolloutPercentage ()Ljava/lang/Double; - public final fun getVariant ()Ljava/lang/String; -} - -public final class com/posthog/internal/FlagDefinition { - public fun (ILjava/lang/String;Ljava/lang/String;ZLcom/posthog/internal/FlagFilters;IZLjava/lang/Boolean;Ljava/lang/String;)V - public synthetic fun (ILjava/lang/String;Ljava/lang/String;ZLcom/posthog/internal/FlagFilters;IZLjava/lang/Boolean;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun getActive ()Z - public final fun getEnsureExperienceContinuity ()Z - public final fun getEvaluationRuntime ()Ljava/lang/String; - public final fun getFilters ()Lcom/posthog/internal/FlagFilters; - public final fun getHasExperiment ()Ljava/lang/Boolean; - public final fun getId ()I - public final fun getKey ()Ljava/lang/String; - public final fun getName ()Ljava/lang/String; - public final fun getVersion ()I -} - -public final class com/posthog/internal/FlagFilters { - public fun (Ljava/util/List;Lcom/posthog/internal/MultiVariateConfig;Ljava/util/Map;Ljava/lang/Integer;)V - public final fun getAggregationGroupTypeIndex ()Ljava/lang/Integer; - public final fun getGroups ()Ljava/util/List; - public final fun getMultivariate ()Lcom/posthog/internal/MultiVariateConfig; - public final fun getPayloads ()Ljava/util/Map; -} - -public final class com/posthog/internal/FlagProperty { - public fun (Ljava/lang/String;Ljava/lang/Object;Lcom/posthog/internal/PropertyOperator;Lcom/posthog/internal/PropertyType;Ljava/lang/Boolean;Ljava/util/List;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Ljava/lang/Object; - public final fun component3 ()Lcom/posthog/internal/PropertyOperator; - public final fun component4 ()Lcom/posthog/internal/PropertyType; - public final fun component5 ()Ljava/lang/Boolean; - public final fun component6 ()Ljava/util/List; - public final fun copy (Ljava/lang/String;Ljava/lang/Object;Lcom/posthog/internal/PropertyOperator;Lcom/posthog/internal/PropertyType;Ljava/lang/Boolean;Ljava/util/List;)Lcom/posthog/internal/FlagProperty; - public static synthetic fun copy$default (Lcom/posthog/internal/FlagProperty;Ljava/lang/String;Ljava/lang/Object;Lcom/posthog/internal/PropertyOperator;Lcom/posthog/internal/PropertyType;Ljava/lang/Boolean;Ljava/util/List;ILjava/lang/Object;)Lcom/posthog/internal/FlagProperty; - public fun equals (Ljava/lang/Object;)Z - public final fun getDependencyChain ()Ljava/util/List; - public final fun getKey ()Ljava/lang/String; - public final fun getNegation ()Ljava/lang/Boolean; - public final fun getPropertyOperator ()Lcom/posthog/internal/PropertyOperator; - public final fun getPropertyValue ()Ljava/lang/Object; - public final fun getType ()Lcom/posthog/internal/PropertyType; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class com/posthog/internal/GzipRequestInterceptor : okhttp3/Interceptor { - public fun (Lcom/posthog/PostHogConfig;)V - public fun (Lcom/posthog/PostHogConfig;Lkotlin/jvm/functions/Function0;)V - public synthetic fun (Lcom/posthog/PostHogConfig;Lkotlin/jvm/functions/Function0;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public fun intercept (Lokhttp3/Interceptor$Chain;)Lokhttp3/Response; -} - -public final class com/posthog/internal/LocalEvaluationApiResponse { - public static final field Companion Lcom/posthog/internal/LocalEvaluationApiResponse$Companion; - public synthetic fun (Lcom/posthog/internal/LocalEvaluationResponse;Ljava/lang/String;ZLkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun getEtag ()Ljava/lang/String; - public final fun getResult ()Lcom/posthog/internal/LocalEvaluationResponse; - public final fun getWasModified ()Z -} - public final class com/posthog/internal/LocalEvaluationApiResponse$Companion { public final fun notModified (Ljava/lang/String;)Lcom/posthog/internal/LocalEvaluationApiResponse; public final fun success (Lcom/posthog/internal/LocalEvaluationResponse;Ljava/lang/String;)Lcom/posthog/internal/LocalEvaluationApiResponse; } -public final class com/posthog/internal/LocalEvaluationResponse { - public fun (Ljava/util/List;Ljava/util/Map;Ljava/util/Map;)V - public fun (Ljava/util/List;Ljava/util/Map;Ljava/util/Map;Ljava/lang/Integer;)V - public synthetic fun (Ljava/util/List;Ljava/util/Map;Ljava/util/Map;Ljava/lang/Integer;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Ljava/util/List; - public final fun component2 ()Ljava/util/Map; - public final fun component3 ()Ljava/util/Map; - public final fun component4 ()Ljava/lang/Integer; - public final fun copy (Ljava/util/List;Ljava/util/Map;Ljava/util/Map;Ljava/lang/Integer;)Lcom/posthog/internal/LocalEvaluationResponse; - public static synthetic fun copy$default (Lcom/posthog/internal/LocalEvaluationResponse;Ljava/util/List;Ljava/util/Map;Ljava/util/Map;Ljava/lang/Integer;ILjava/lang/Object;)Lcom/posthog/internal/LocalEvaluationResponse; - public fun equals (Ljava/lang/Object;)Z - public final fun getCohorts ()Ljava/util/Map; - public final fun getFlags ()Ljava/util/List; - public final fun getGroupTypeMapping ()Ljava/util/Map; - public final fun getPropertyMatchingVersion ()Ljava/lang/Integer; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class com/posthog/internal/LogicalOperator : java/lang/Enum { - public static final field AND Lcom/posthog/internal/LogicalOperator; - public static final field OR Lcom/posthog/internal/LogicalOperator; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public static fun valueOf (Ljava/lang/String;)Lcom/posthog/internal/LogicalOperator; - public static fun values ()[Lcom/posthog/internal/LogicalOperator; -} - -public final class com/posthog/internal/MultiVariateConfig { - public fun (Ljava/util/List;)V - public final fun component1 ()Ljava/util/List; - public final fun copy (Ljava/util/List;)Lcom/posthog/internal/MultiVariateConfig; - public static synthetic fun copy$default (Lcom/posthog/internal/MultiVariateConfig;Ljava/util/List;ILjava/lang/Object;)Lcom/posthog/internal/MultiVariateConfig; - public fun equals (Ljava/lang/Object;)Z - public final fun getVariants ()Ljava/util/List; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class com/posthog/internal/PostHogApi { - public fun (Lcom/posthog/PostHogConfig;)V - public final fun batch (Ljava/util/List;)V - public final fun flags (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/List;Z)Lcom/posthog/internal/PostHogFlagsResponse; - public static synthetic fun flags$default (Lcom/posthog/internal/PostHogApi;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/util/List;ZILjava/lang/Object;)Lcom/posthog/internal/PostHogFlagsResponse; - public final fun localEvaluation (Ljava/lang/String;Ljava/lang/String;)Lcom/posthog/internal/LocalEvaluationApiResponse; - public static synthetic fun localEvaluation$default (Lcom/posthog/internal/PostHogApi;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lcom/posthog/internal/LocalEvaluationApiResponse; - public final fun pushSubscription (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V - public static synthetic fun pushSubscription$default (Lcom/posthog/internal/PostHogApi;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)V - public final fun pushUnsubscription (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V - public static synthetic fun pushUnsubscription$default (Lcom/posthog/internal/PostHogApi;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILjava/lang/Object;)V - public final fun remoteConfig ()Lcom/posthog/internal/PostHogRemoteConfigResponse; - public final fun snapshot (Ljava/util/List;)V -} - -public final class com/posthog/internal/PostHogApiEndpoint : java/lang/Enum { - public static final field BATCH Lcom/posthog/internal/PostHogApiEndpoint; - public static final field SNAPSHOT Lcom/posthog/internal/PostHogApiEndpoint; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public static fun valueOf (Ljava/lang/String;)Lcom/posthog/internal/PostHogApiEndpoint; - public static fun values ()[Lcom/posthog/internal/PostHogApiEndpoint; -} - -public final class com/posthog/internal/PostHogApiError : java/lang/RuntimeException { - public fun (ILjava/lang/String;Lokhttp3/ResponseBody;Ljava/lang/Integer;Ljava/lang/String;)V - public synthetic fun (ILjava/lang/String;Lokhttp3/ResponseBody;Ljava/lang/Integer;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun getBody ()Lokhttp3/ResponseBody; - public final fun getErrorCode ()Ljava/lang/String; - public fun getMessage ()Ljava/lang/String; - public final fun getRetryAfterSeconds ()Ljava/lang/Integer; - public final fun getStatusCode ()I - public fun toString ()Ljava/lang/String; -} - -public abstract interface class com/posthog/internal/PostHogContext { - public abstract fun getDynamicContext ()Ljava/util/Map; - public abstract fun getSdkInfo ()Ljava/util/Map; - public abstract fun getStaticContext ()Ljava/util/Map; -} - -public abstract interface class com/posthog/internal/PostHogDateProvider { - public abstract fun addSecondsToCurrentDate (I)Ljava/util/Date; - public abstract fun currentDate ()Ljava/util/Date; - public abstract fun currentTimeMillis ()J - public abstract fun nanoTime ()J -} - -public final class com/posthog/internal/PostHogDateUtilsKt { - public static final fun formatISO8601Date (Ljava/util/Date;)Ljava/lang/String; - public static final fun parseISO8601Date (Ljava/lang/String;)Ljava/util/Date; -} - -public abstract interface class com/posthog/internal/PostHogDefaultPersonPropertiesProvider { - public abstract fun getDefaultPersonProperties ()Ljava/util/Map; -} - -public final class com/posthog/internal/PostHogDeviceDateProvider : com/posthog/internal/PostHogDateProvider { - public fun ()V - public fun addSecondsToCurrentDate (I)Ljava/util/Date; - public fun currentDate ()Ljava/util/Date; - public fun currentTimeMillis ()J - public fun nanoTime ()J -} - -public abstract interface class com/posthog/internal/PostHogFeatureFlagCalledProvider { - public abstract fun onFeatureFlagCalled (Ljava/lang/String;Ljava/lang/Object;)V -} - -public abstract interface class com/posthog/internal/PostHogFeatureFlagsInterface { - public abstract fun clear ()V - public abstract fun getEvaluatedAt (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Ljava/lang/Long; - public static synthetic fun getEvaluatedAt$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/lang/Long; - public fun getFeatureFlagDetails (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Lcom/posthog/internal/FeatureFlag; - public static synthetic fun getFeatureFlagDetails$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Lcom/posthog/internal/FeatureFlag; - public fun getFeatureFlagError (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Ljava/lang/String; - public static synthetic fun getFeatureFlagError$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/lang/String; - public abstract fun getFeatureFlagResult (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Lcom/posthog/FeatureFlagResult; - public static synthetic fun getFeatureFlagResult$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Lcom/posthog/FeatureFlagResult; - public abstract fun getFeatureFlags (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Ljava/util/Map; - public static synthetic fun getFeatureFlags$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/util/Map; - public abstract fun getRequestId (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Ljava/lang/String; - public static synthetic fun getRequestId$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/lang/String; - public fun isMinimalFlagCalledEventsEnabled ()Z - public fun shutDown ()V -} - -public final class com/posthog/internal/PostHogFeatureFlagsInterface$DefaultImpls { - public static synthetic fun getEvaluatedAt$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/lang/Long; - public static fun getFeatureFlagDetails (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Lcom/posthog/internal/FeatureFlag; - public static synthetic fun getFeatureFlagDetails$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Lcom/posthog/internal/FeatureFlag; - public static fun getFeatureFlagError (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Ljava/lang/String; - public static synthetic fun getFeatureFlagError$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/lang/String; - public static synthetic fun getFeatureFlagResult$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Lcom/posthog/FeatureFlagResult; - public static synthetic fun getFeatureFlags$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/util/Map; - public static synthetic fun getRequestId$default (Lcom/posthog/internal/PostHogFeatureFlagsInterface;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/lang/String; - public static fun isMinimalFlagCalledEventsEnabled (Lcom/posthog/internal/PostHogFeatureFlagsInterface;)Z - public static fun shutDown (Lcom/posthog/internal/PostHogFeatureFlagsInterface;)V -} - -public final class com/posthog/internal/PostHogFlagsResponse : com/posthog/internal/PostHogRemoteConfigResponse { - public fun (ZLjava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/lang/String;Ljava/lang/Long;Ljava/lang/Boolean;)V - public synthetic fun (ZLjava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/lang/String;Ljava/lang/Long;Ljava/lang/Boolean;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()Z - public final fun component2 ()Ljava/util/Map; - public final fun component3 ()Ljava/util/Map; - public final fun component4 ()Ljava/util/Map; - public final fun component5 ()Ljava/lang/String; - public final fun component6 ()Ljava/lang/Long; - public final fun component7 ()Ljava/lang/Boolean; - public final fun copy (ZLjava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/lang/String;Ljava/lang/Long;Ljava/lang/Boolean;)Lcom/posthog/internal/PostHogFlagsResponse; - public static synthetic fun copy$default (Lcom/posthog/internal/PostHogFlagsResponse;ZLjava/util/Map;Ljava/util/Map;Ljava/util/Map;Ljava/lang/String;Ljava/lang/Long;Ljava/lang/Boolean;ILjava/lang/Object;)Lcom/posthog/internal/PostHogFlagsResponse; - public fun equals (Ljava/lang/Object;)Z - public final fun getErrorsWhileComputingFlags ()Z - public final fun getEvaluatedAt ()Ljava/lang/Long; - public final fun getFeatureFlagPayloads ()Ljava/util/Map; - public final fun getFeatureFlags ()Ljava/util/Map; - public final fun getFlags ()Ljava/util/Map; - public final fun getMinimalFlagCalledEvents ()Ljava/lang/Boolean; - public final fun getRequestId ()Ljava/lang/String; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public abstract interface class com/posthog/internal/PostHogLogger { - public abstract fun isEnabled ()Z - public abstract fun log (Ljava/lang/String;)V - public fun logWarning (Ljava/lang/String;)V -} - -public final class com/posthog/internal/PostHogLogger$DefaultImpls { - public static fun logWarning (Lcom/posthog/internal/PostHogLogger;Ljava/lang/String;)V -} - public final class com/posthog/internal/PostHogMemoryPreferences : com/posthog/internal/PostHogPreferences { public fun ()V public fun clear (Ljava/util/List;)V @@ -983,50 +617,6 @@ public final class com/posthog/internal/PostHogMemoryPreferences : com/posthog/i public fun setValue (Ljava/lang/String;Ljava/lang/Object;)V } -public abstract interface class com/posthog/internal/PostHogNetworkStatus { - public abstract fun isConnected ()Z - public fun register (Lkotlin/jvm/functions/Function0;)V - public fun unregister ()V -} - -public final class com/posthog/internal/PostHogNetworkStatus$DefaultImpls { - public static fun register (Lcom/posthog/internal/PostHogNetworkStatus;Lkotlin/jvm/functions/Function0;)V - public static fun unregister (Lcom/posthog/internal/PostHogNetworkStatus;)V -} - -public final class com/posthog/internal/PostHogNoOpLogger : com/posthog/internal/PostHogLogger { - public fun ()V - public fun isEnabled ()Z - public fun log (Ljava/lang/String;)V -} - -public abstract interface class com/posthog/internal/PostHogOnRemoteConfigLoaded { - public abstract fun loaded ()V -} - -public abstract interface class com/posthog/internal/PostHogPreferences { - public static final field ANONYMOUS_ID Ljava/lang/String; - public static final field BUILD Ljava/lang/String; - public static final field Companion Lcom/posthog/internal/PostHogPreferences$Companion; - public static final field DEVICE_ID Ljava/lang/String; - public static final field DISTINCT_ID Ljava/lang/String; - public static final field GROUPS Ljava/lang/String; - public static final field LAST_SEEN_SURVEY_DATE Ljava/lang/String; - public static final field PUSH_OPENED_MESSAGE_IDS Ljava/lang/String; - public static final field STRINGIFIED_KEYS Ljava/lang/String; - public static final field SURVEY_PROGRESS Ljava/lang/String; - public static final field SURVEY_SEEN Ljava/lang/String; - public static final field VERSION Ljava/lang/String; - public abstract fun clear (Ljava/util/List;)V - public static synthetic fun clear$default (Lcom/posthog/internal/PostHogPreferences;Ljava/util/List;ILjava/lang/Object;)V - public abstract fun getAll ()Ljava/util/Map; - public abstract fun getValue (Ljava/lang/String;Ljava/lang/Object;)Ljava/lang/Object; - public static synthetic fun getValue$default (Lcom/posthog/internal/PostHogPreferences;Ljava/lang/String;Ljava/lang/Object;ILjava/lang/Object;)Ljava/lang/Object; - public fun isAvailable ()Z - public abstract fun remove (Ljava/lang/String;)V - public abstract fun setValue (Ljava/lang/String;Ljava/lang/Object;)V -} - public final class com/posthog/internal/PostHogPreferences$Companion { public static final field ANONYMOUS_ID Ljava/lang/String; public static final field BUILD Ljava/lang/String; @@ -1034,7 +624,6 @@ public final class com/posthog/internal/PostHogPreferences$Companion { public static final field DISTINCT_ID Ljava/lang/String; public static final field GROUPS Ljava/lang/String; public static final field LAST_SEEN_SURVEY_DATE Ljava/lang/String; - public static final field PUSH_OPENED_MESSAGE_IDS Ljava/lang/String; public static final field STRINGIFIED_KEYS Ljava/lang/String; public static final field SURVEY_PROGRESS Ljava/lang/String; public static final field SURVEY_SEEN Ljava/lang/String; @@ -1042,85 +631,6 @@ public final class com/posthog/internal/PostHogPreferences$Companion { public final fun getALL_INTERNAL_KEYS ()Ljava/util/Set; } -public final class com/posthog/internal/PostHogPreferences$DefaultImpls { - public static synthetic fun clear$default (Lcom/posthog/internal/PostHogPreferences;Ljava/util/List;ILjava/lang/Object;)V - public static synthetic fun getValue$default (Lcom/posthog/internal/PostHogPreferences;Ljava/lang/String;Ljava/lang/Object;ILjava/lang/Object;)Ljava/lang/Object; - public static fun isAvailable (Lcom/posthog/internal/PostHogPreferences;)Z -} - -public abstract interface class com/posthog/internal/PostHogPushSubscriptionReceiver { - public abstract fun registerPushNotificationTokenIfNeeded (Ljava/lang/String;Ljava/lang/String;)V -} - -public final class com/posthog/internal/PostHogQueue : com/posthog/internal/PostHogQueueInterface { - public fun (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/EndpointSpec;Ljava/util/concurrent/ExecutorService;)V - public fun add (Ljava/lang/Object;)V - public fun clear ()V - public fun flush ()V - public final fun getQueueDirectory ()Ljava/io/File; - public fun getSize ()I - public final fun reloadFromDisk ()V - public fun start ()V - public fun stop ()V -} - -public abstract interface class com/posthog/internal/PostHogQueueInterface { - public abstract fun add (Ljava/lang/Object;)V - public abstract fun clear ()V - public abstract fun flush ()V - public fun flushForShutdown ()V - public abstract fun getSize ()I - public abstract fun start ()V - public abstract fun stop ()V -} - -public final class com/posthog/internal/PostHogQueueInterface$DefaultImpls { - public static fun flushForShutdown (Lcom/posthog/internal/PostHogQueueInterface;)V -} - -public final class com/posthog/internal/PostHogRemoteConfig : com/posthog/internal/PostHogFeatureFlagsInterface { - public fun (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/util/concurrent/ExecutorService;Lcom/posthog/internal/PostHogDefaultPersonPropertiesProvider;Lcom/posthog/internal/PostHogFeatureFlagCalledProvider;Lcom/posthog/internal/PostHogOnRemoteConfigLoaded;)V - public synthetic fun (Lcom/posthog/PostHogConfig;Lcom/posthog/internal/PostHogApi;Ljava/util/concurrent/ExecutorService;Lcom/posthog/internal/PostHogDefaultPersonPropertiesProvider;Lcom/posthog/internal/PostHogFeatureFlagCalledProvider;Lcom/posthog/internal/PostHogOnRemoteConfigLoaded;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public fun clear ()V - public final fun consumeNewlyRegisterablePushAppIds ()Ljava/util/Set; - public final fun getActiveFeatureFlagKeys ()Ljava/util/List; - public fun getEvaluatedAt (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Ljava/lang/Long; - public final fun getEventTriggers ()Ljava/util/Set; - public final fun getFeatureFlag (Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Ljava/lang/Object; - public static synthetic fun getFeatureFlag$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/lang/Object; - public final fun getFeatureFlagPayload (Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Ljava/lang/Object; - public static synthetic fun getFeatureFlagPayload$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/Object;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;ILjava/lang/Object;)Ljava/lang/Object; - public fun getFeatureFlagResult (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Lcom/posthog/FeatureFlagResult; - public fun getFeatureFlags (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Ljava/util/Map; - public final fun getFlagDetails (Ljava/lang/String;)Lcom/posthog/internal/FeatureFlag; - public final fun getPersonPropertiesForFlags ()Ljava/util/Map; - public final fun getPushAppIds ()Ljava/util/List; - public final fun getRecordingMinimumDurationMs ()Ljava/lang/Long; - public fun getRequestId (Ljava/lang/String;Ljava/util/Map;Ljava/util/Map;Ljava/util/Map;)Ljava/lang/String; - public final fun getSessionRecordingSampleRate ()Ljava/lang/Double; - public final fun getSurveys ()Ljava/util/List; - public final fun hasCachedErrorTrackingConfig ()Z - public final fun hasRemoteConfigFetched ()Z - public final fun isAutocaptureExceptionsEnabled ()Z - public final fun isCaptureNetworkTimingEnabled ()Z - public final fun isConsoleLogRecordingEnabled ()Z - public fun isMinimalFlagCalledEventsEnabled ()Z - public final fun isNativeCrashCaptureEnabled ()Z - public final fun isSessionReplayFlagActive ()Z - public final fun loadFeatureFlags (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function1;Lcom/posthog/PostHogFeatureFlagsCallback;)V - public static synthetic fun loadFeatureFlags$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function1;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V - public final fun loadRemoteConfig (Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function1;Lcom/posthog/PostHogFeatureFlagsCallback;)V - public static synthetic fun loadRemoteConfig$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;Lkotlin/jvm/functions/Function1;Lcom/posthog/PostHogFeatureFlagsCallback;ILjava/lang/Object;)V - public final fun makeSamplingDecision (Ljava/lang/String;)Z - public final fun persistPushConfigCache ()V - public final fun resetGroupPropertiesForFlags (Ljava/lang/String;)V - public static synthetic fun resetGroupPropertiesForFlags$default (Lcom/posthog/internal/PostHogRemoteConfig;Ljava/lang/String;ILjava/lang/Object;)V - public final fun resetPersonPropertiesForFlags ()V - public final fun sessionReplayLinkedFlagSnapshot ()Lcom/posthog/internal/PostHogRemoteConfig$SessionReplayLinkedFlagSnapshot; - public final fun setGroupPropertiesForFlags (Ljava/lang/String;Ljava/util/Map;)V - public final fun setPersonPropertiesForFlags (Ljava/util/Map;)V -} - public final class com/posthog/internal/PostHogRemoteConfig$SessionReplayLinkedFlagSnapshot { public fun (ZZ)V public final fun component1 ()Z @@ -1134,129 +644,16 @@ public final class com/posthog/internal/PostHogRemoteConfig$SessionReplayLinkedF public fun toString ()Ljava/lang/String; } -public class com/posthog/internal/PostHogRemoteConfigResponse { - public fun ()V - public fun (Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Boolean;Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;Ljava/util/List;)V - public synthetic fun (Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Boolean;Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun getCapturePerformance ()Ljava/lang/Object; - public final fun getErrorTracking ()Ljava/lang/Object; - public final fun getHasFeatureFlags ()Ljava/lang/Boolean; - public final fun getPush ()Ljava/lang/Object; - public final fun getQuotaLimited ()Ljava/util/List; - public final fun getSessionRecording ()Ljava/lang/Object; - public final fun getSurveys ()Ljava/lang/Object; -} - -public final class com/posthog/internal/PostHogSerializer { - public fun (Lcom/posthog/PostHogConfig;)V - public final fun deserializeString (Ljava/lang/String;)Ljava/lang/Object; - public final fun getGson ()Lcom/google/gson/Gson; - public final fun serializeObject (Ljava/lang/Object;)Ljava/lang/String; -} - -public final class com/posthog/internal/PostHogSessionManager { - public static final field INSTANCE Lcom/posthog/internal/PostHogSessionManager; - public final fun endSession ()V - public final fun getActiveSessionId ()Ljava/util/UUID; - public final fun isReactNative ()Z - public final fun isSessionActive ()Z - public final fun isSessionExceedingMaxDuration (J)Z - public final fun peekSessionId ()Ljava/util/UUID; - public final fun setAppInBackground (Z)V - public final fun setDateProvider (Lcom/posthog/internal/PostHogDateProvider;)V - public final fun setReactNative (Z)V - public final fun setSessionId (Ljava/util/UUID;)V - public final fun startSession ()V - public final fun touchSession ()V -} - -public final class com/posthog/internal/PostHogThreadFactory : java/util/concurrent/ThreadFactory { - public fun (Ljava/lang/String;)V - public fun newThread (Ljava/lang/Runnable;)Ljava/lang/Thread; -} - -public final class com/posthog/internal/PostHogUtilsKt { - public static final fun executeSafely (Ljava/util/concurrent/Executor;Ljava/lang/Runnable;)V - public static final fun interruptSafely (Ljava/lang/Thread;)V - public static final fun isNetworkingError (Ljava/lang/Throwable;)Z - public static final fun logIntegrationFailure (Lcom/posthog/PostHogConfig;Ljava/lang/String;Ljava/lang/Throwable;)V - public static final fun submitSyncSafely (Ljava/util/concurrent/ExecutorService;Ljava/lang/Runnable;)V -} - -public final class com/posthog/internal/PropertyGroup { - public fun (Lcom/posthog/internal/LogicalOperator;Lcom/posthog/internal/PropertyValue;)V - public final fun component1 ()Lcom/posthog/internal/LogicalOperator; - public final fun component2 ()Lcom/posthog/internal/PropertyValue; - public final fun copy (Lcom/posthog/internal/LogicalOperator;Lcom/posthog/internal/PropertyValue;)Lcom/posthog/internal/PropertyGroup; - public static synthetic fun copy$default (Lcom/posthog/internal/PropertyGroup;Lcom/posthog/internal/LogicalOperator;Lcom/posthog/internal/PropertyValue;ILjava/lang/Object;)Lcom/posthog/internal/PropertyGroup; - public fun equals (Ljava/lang/Object;)Z - public final fun getType ()Lcom/posthog/internal/LogicalOperator; - public final fun getValues ()Lcom/posthog/internal/PropertyValue; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class com/posthog/internal/PropertyOperator : java/lang/Enum { - public static final field Companion Lcom/posthog/internal/PropertyOperator$Companion; - public static final field ENDS_WITH Lcom/posthog/internal/PropertyOperator; - public static final field EXACT Lcom/posthog/internal/PropertyOperator; - public static final field FLAG_EVALUATES_TO Lcom/posthog/internal/PropertyOperator; - public static final field GT Lcom/posthog/internal/PropertyOperator; - public static final field GTE Lcom/posthog/internal/PropertyOperator; - public static final field ICONTAINS Lcom/posthog/internal/PropertyOperator; - public static final field IN Lcom/posthog/internal/PropertyOperator; - public static final field IS_DATE_AFTER Lcom/posthog/internal/PropertyOperator; - public static final field IS_DATE_BEFORE Lcom/posthog/internal/PropertyOperator; - public static final field IS_NOT Lcom/posthog/internal/PropertyOperator; - public static final field IS_NOT_SET Lcom/posthog/internal/PropertyOperator; - public static final field IS_SET Lcom/posthog/internal/PropertyOperator; - public static final field LT Lcom/posthog/internal/PropertyOperator; - public static final field LTE Lcom/posthog/internal/PropertyOperator; - public static final field NOT_ENDS_WITH Lcom/posthog/internal/PropertyOperator; - public static final field NOT_ICONTAINS Lcom/posthog/internal/PropertyOperator; - public static final field NOT_REGEX Lcom/posthog/internal/PropertyOperator; - public static final field NOT_STARTS_WITH Lcom/posthog/internal/PropertyOperator; - public static final field REGEX Lcom/posthog/internal/PropertyOperator; - public static final field SEMVER_CARET Lcom/posthog/internal/PropertyOperator; - public static final field SEMVER_EQ Lcom/posthog/internal/PropertyOperator; - public static final field SEMVER_GT Lcom/posthog/internal/PropertyOperator; - public static final field SEMVER_GTE Lcom/posthog/internal/PropertyOperator; - public static final field SEMVER_LT Lcom/posthog/internal/PropertyOperator; - public static final field SEMVER_LTE Lcom/posthog/internal/PropertyOperator; - public static final field SEMVER_NEQ Lcom/posthog/internal/PropertyOperator; - public static final field SEMVER_TILDE Lcom/posthog/internal/PropertyOperator; - public static final field SEMVER_WILDCARD Lcom/posthog/internal/PropertyOperator; - public static final field STARTS_WITH Lcom/posthog/internal/PropertyOperator; - public static final field UNKNOWN Lcom/posthog/internal/PropertyOperator; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public static fun valueOf (Ljava/lang/String;)Lcom/posthog/internal/PropertyOperator; - public static fun values ()[Lcom/posthog/internal/PropertyOperator; -} - public final class com/posthog/internal/PropertyOperator$Companion { public final fun fromString (Ljava/lang/String;)Lcom/posthog/internal/PropertyOperator; public final fun fromStringOrNull (Ljava/lang/String;)Lcom/posthog/internal/PropertyOperator; } -public final class com/posthog/internal/PropertyType : java/lang/Enum { - public static final field COHORT Lcom/posthog/internal/PropertyType; - public static final field Companion Lcom/posthog/internal/PropertyType$Companion; - public static final field FLAG Lcom/posthog/internal/PropertyType; - public static final field PERSON Lcom/posthog/internal/PropertyType; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public static fun valueOf (Ljava/lang/String;)Lcom/posthog/internal/PropertyType; - public static fun values ()[Lcom/posthog/internal/PropertyType; -} - public final class com/posthog/internal/PropertyType$Companion { public final fun fromString (Ljava/lang/String;)Lcom/posthog/internal/PropertyType; public final fun fromStringOrNull (Ljava/lang/String;)Lcom/posthog/internal/PropertyType; } -public abstract interface class com/posthog/internal/PropertyValue { - public abstract fun isEmpty ()Z -} - public final class com/posthog/internal/PropertyValue$FlagProperties : com/posthog/internal/PropertyValue { public fun (Ljava/util/List;)V public final fun component1 ()Ljava/util/List; @@ -1281,153 +678,14 @@ public final class com/posthog/internal/PropertyValue$PropertyGroups : com/posth public fun toString ()Ljava/lang/String; } -public final class com/posthog/internal/VariantDefinition { - public fun (Ljava/lang/String;D)V - public final fun getKey ()Ljava/lang/String; - public final fun getRolloutPercentage ()D -} - -public final class com/posthog/internal/errortracking/ThrowableCoercer { - public static final field EXCEPTION_LEVEL_ATTRIBUTE Ljava/lang/String; - public static final field EXCEPTION_LEVEL_FATAL Ljava/lang/String; - public static final field MAX_EXCEPTION_LIST_SIZE I - public static final field MAX_FRAMES_PER_STACKTRACE I - public fun ()V -} - -public abstract interface class com/posthog/internal/replay/PostHogSessionReplayHandler { - public abstract fun debugProperties ()Ljava/util/Map; - public abstract fun isActive ()Z - public abstract fun onEvent (Ljava/lang/String;Ljava/util/Map;)V - public static synthetic fun onEvent$default (Lcom/posthog/internal/replay/PostHogSessionReplayHandler;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V - public abstract fun onSessionIdChanged ()V - public abstract fun start (Z)V - public abstract fun stop ()V -} - -public final class com/posthog/internal/replay/PostHogSessionReplayHandler$DefaultImpls { - public static synthetic fun onEvent$default (Lcom/posthog/internal/replay/PostHogSessionReplayHandler;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V -} - -public final class com/posthog/internal/replay/RRCustomEvent : com/posthog/internal/replay/RREvent { - public fun (Ljava/lang/String;Ljava/lang/Object;J)V -} - -public class com/posthog/internal/replay/RREvent { - public fun (Lcom/posthog/internal/replay/RREventType;JLjava/lang/Object;)V - public synthetic fun (Lcom/posthog/internal/replay/RREventType;JLjava/lang/Object;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun getData ()Ljava/lang/Object; - public final fun getTimestamp ()J - public final fun getType ()Lcom/posthog/internal/replay/RREventType; -} - -public final class com/posthog/internal/replay/RREventType : java/lang/Enum { - public static final field Companion Lcom/posthog/internal/replay/RREventType$Companion; - public static final field Custom Lcom/posthog/internal/replay/RREventType; - public static final field DomContentLoaded Lcom/posthog/internal/replay/RREventType; - public static final field FullSnapshot Lcom/posthog/internal/replay/RREventType; - public static final field IncrementalSnapshot Lcom/posthog/internal/replay/RREventType; - public static final field Load Lcom/posthog/internal/replay/RREventType; - public static final field Meta Lcom/posthog/internal/replay/RREventType; - public static final field Plugin Lcom/posthog/internal/replay/RREventType; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public final fun getValue ()I - public static fun valueOf (Ljava/lang/String;)Lcom/posthog/internal/replay/RREventType; - public static fun values ()[Lcom/posthog/internal/replay/RREventType; -} - public final class com/posthog/internal/replay/RREventType$Companion { public final fun fromValue (I)Lcom/posthog/internal/replay/RREventType; } -public final class com/posthog/internal/replay/RRFullSnapshotEvent : com/posthog/internal/replay/RREvent { - public fun (Ljava/util/List;IIJ)V -} - -public final class com/posthog/internal/replay/RRIncrementalMouseInteractionData { - public fun (ILcom/posthog/internal/replay/RRMouseInteraction;IILcom/posthog/internal/replay/RRIncrementalSource;ILjava/util/List;)V - public synthetic fun (ILcom/posthog/internal/replay/RRMouseInteraction;IILcom/posthog/internal/replay/RRIncrementalSource;ILjava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun getId ()I - public final fun getPointerType ()I - public final fun getPositions ()Ljava/util/List; - public final fun getSource ()Lcom/posthog/internal/replay/RRIncrementalSource; - public final fun getType ()Lcom/posthog/internal/replay/RRMouseInteraction; - public final fun getX ()I - public final fun getY ()I -} - -public final class com/posthog/internal/replay/RRIncrementalMouseInteractionEvent : com/posthog/internal/replay/RREvent { - public fun (Lcom/posthog/internal/replay/RRIncrementalMouseInteractionData;J)V - public synthetic fun (Lcom/posthog/internal/replay/RRIncrementalMouseInteractionData;JILkotlin/jvm/internal/DefaultConstructorMarker;)V -} - -public final class com/posthog/internal/replay/RRIncrementalMutationData { - public fun ()V - public fun (Ljava/util/List;Ljava/util/List;Ljava/util/List;Lcom/posthog/internal/replay/RRIncrementalSource;)V - public synthetic fun (Ljava/util/List;Ljava/util/List;Ljava/util/List;Lcom/posthog/internal/replay/RRIncrementalSource;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun getAdds ()Ljava/util/List; - public final fun getRemoves ()Ljava/util/List; - public final fun getSource ()Lcom/posthog/internal/replay/RRIncrementalSource; - public final fun getUpdates ()Ljava/util/List; -} - -public final class com/posthog/internal/replay/RRIncrementalSnapshotEvent : com/posthog/internal/replay/RREvent { - public fun (Lcom/posthog/internal/replay/RRIncrementalMutationData;J)V - public synthetic fun (Lcom/posthog/internal/replay/RRIncrementalMutationData;JILkotlin/jvm/internal/DefaultConstructorMarker;)V -} - -public final class com/posthog/internal/replay/RRIncrementalSource : java/lang/Enum { - public static final field AdoptedStyleSheet Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field CanvasMutation Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field Companion Lcom/posthog/internal/replay/RRIncrementalSource$Companion; - public static final field CustomElement Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field Drag Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field Font Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field Input Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field Log Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field MediaInteraction Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field MouseInteraction Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field MouseMove Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field Mutation Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field Scroll Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field Selection Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field StyleDeclaration Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field StyleSheetRule Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field TouchMove Lcom/posthog/internal/replay/RRIncrementalSource; - public static final field ViewportResize Lcom/posthog/internal/replay/RRIncrementalSource; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public final fun getValue ()I - public static fun valueOf (Ljava/lang/String;)Lcom/posthog/internal/replay/RRIncrementalSource; - public static fun values ()[Lcom/posthog/internal/replay/RRIncrementalSource; -} - public final class com/posthog/internal/replay/RRIncrementalSource$Companion { public final fun fromValue (I)Lcom/posthog/internal/replay/RRIncrementalSource; } -public final class com/posthog/internal/replay/RRMetaEvent : com/posthog/internal/replay/RREvent { - public fun (IIJLjava/lang/String;)V -} - -public final class com/posthog/internal/replay/RRMouseInteraction : java/lang/Enum { - public static final field Blur Lcom/posthog/internal/replay/RRMouseInteraction; - public static final field Click Lcom/posthog/internal/replay/RRMouseInteraction; - public static final field Companion Lcom/posthog/internal/replay/RRMouseInteraction$Companion; - public static final field ContextMenu Lcom/posthog/internal/replay/RRMouseInteraction; - public static final field DblClick Lcom/posthog/internal/replay/RRMouseInteraction; - public static final field Focus Lcom/posthog/internal/replay/RRMouseInteraction; - public static final field MouseDown Lcom/posthog/internal/replay/RRMouseInteraction; - public static final field MouseUp Lcom/posthog/internal/replay/RRMouseInteraction; - public static final field TouchCancel Lcom/posthog/internal/replay/RRMouseInteraction; - public static final field TouchEnd Lcom/posthog/internal/replay/RRMouseInteraction; - public static final field TouchMoveDeparted Lcom/posthog/internal/replay/RRMouseInteraction; - public static final field TouchStart Lcom/posthog/internal/replay/RRMouseInteraction; - public static fun getEntries ()Lkotlin/enums/EnumEntries; - public final fun getValue ()I - public static fun valueOf (Ljava/lang/String;)Lcom/posthog/internal/replay/RRMouseInteraction; - public static fun values ()[Lcom/posthog/internal/replay/RRMouseInteraction; -} - public final class com/posthog/internal/replay/RRMouseInteraction$Companion { public final fun fromValue (I)Lcom/posthog/internal/replay/RRMouseInteraction; } @@ -1441,94 +699,6 @@ public final class com/posthog/internal/replay/RRMousePosition { public final fun getY ()I } -public final class com/posthog/internal/replay/RRMutatedNode { - public fun (Lcom/posthog/internal/replay/RRWireframe;Ljava/lang/Integer;)V - public synthetic fun (Lcom/posthog/internal/replay/RRWireframe;Ljava/lang/Integer;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun getParentId ()Ljava/lang/Integer; - public final fun getWireframe ()Lcom/posthog/internal/replay/RRWireframe; -} - -public final class com/posthog/internal/replay/RRPluginEvent : com/posthog/internal/replay/RREvent { - public fun (Ljava/lang/String;Ljava/util/Map;J)V -} - -public final class com/posthog/internal/replay/RRRemovedNode { - public fun (ILjava/lang/Integer;)V - public synthetic fun (ILjava/lang/Integer;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun getId ()I - public final fun getParentId ()Ljava/lang/Integer; -} - -public final class com/posthog/internal/replay/RRUtilsKt { - public static final fun capture (Ljava/util/List;)V - public static final fun capture (Ljava/util/List;Lcom/posthog/PostHogInterface;)V - public static synthetic fun capture$default (Ljava/util/List;Lcom/posthog/PostHogInterface;ILjava/lang/Object;)V -} - -public final class com/posthog/internal/replay/RRWireframe { - public fun (IIIIILjava/lang/String;Ljava/lang/String;)V - public synthetic fun (IIIIILjava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V - public final fun component1 ()I - public final fun component2 ()I - public final fun component3 ()I - public final fun component4 ()I - public final fun component5 ()I - public final fun component6 ()Ljava/lang/String; - public final fun component7 ()Ljava/lang/String; - public final fun copy (IIIIILjava/lang/String;Ljava/lang/String;)Lcom/posthog/internal/replay/RRWireframe; - public static synthetic fun copy$default (Lcom/posthog/internal/replay/RRWireframe;IIIIILjava/lang/String;Ljava/lang/String;ILjava/lang/Object;)Lcom/posthog/internal/replay/RRWireframe; - public fun equals (Ljava/lang/Object;)Z - public final fun getBase64 ()Ljava/lang/String; - public final fun getHeight ()I - public final fun getId ()I - public final fun getType ()Ljava/lang/String; - public final fun getWidth ()I - public final fun getX ()I - public final fun getY ()I - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public abstract interface class com/posthog/internal/surveys/PostHogSurveysHandler { - public abstract fun onEvent (Ljava/lang/String;Ljava/util/Map;)V - public static synthetic fun onEvent$default (Lcom/posthog/internal/surveys/PostHogSurveysHandler;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V - public abstract fun onReset ()V - public abstract fun onSurveysLoaded (Ljava/util/List;)V -} - -public final class com/posthog/internal/surveys/PostHogSurveysHandler$DefaultImpls { - public static synthetic fun onEvent$default (Lcom/posthog/internal/surveys/PostHogSurveysHandler;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)V -} - -public final class com/posthog/internal/surveys/ResolvedSurveyTranslations { - public fun (Ljava/lang/String;Lcom/posthog/surveys/SurveyTranslation;Ljava/util/List;)V - public final fun component1 ()Ljava/lang/String; - public final fun component2 ()Lcom/posthog/surveys/SurveyTranslation; - public final fun component3 ()Ljava/util/List; - public final fun copy (Ljava/lang/String;Lcom/posthog/surveys/SurveyTranslation;Ljava/util/List;)Lcom/posthog/internal/surveys/ResolvedSurveyTranslations; - public static synthetic fun copy$default (Lcom/posthog/internal/surveys/ResolvedSurveyTranslations;Ljava/lang/String;Lcom/posthog/surveys/SurveyTranslation;Ljava/util/List;ILjava/lang/Object;)Lcom/posthog/internal/surveys/ResolvedSurveyTranslations; - public fun equals (Ljava/lang/Object;)Z - public final fun getMatchedKey ()Ljava/lang/String; - public final fun getQuestions ()Ljava/util/List; - public final fun getSurvey ()Lcom/posthog/surveys/SurveyTranslation; - public fun hashCode ()I - public fun toString ()Ljava/lang/String; -} - -public final class com/posthog/internal/surveys/SurveyLanguageDetectionKt { - public static final fun detectSurveyLanguage (Ljava/lang/String;Ljava/util/Map;Ljava/lang/String;)Ljava/lang/String; -} - -public final class com/posthog/internal/surveys/SurveyTranslationApplierKt { - public static final fun resolveSurveyTranslations (Lcom/posthog/surveys/Survey;Ljava/lang/String;)Lcom/posthog/internal/surveys/ResolvedSurveyTranslations; -} - -public final class com/posthog/internal/surveys/SurveyUtilsKt { - public static final fun canActivateRepeatedly (Lcom/posthog/surveys/Survey;)Z - public static final fun hasEvents (Lcom/posthog/surveys/Survey;)Z - public static final fun hasWaitPeriodPassed (Lcom/posthog/surveys/Survey;Ljava/util/Date;Ljava/util/Date;)Z -} - public abstract interface class com/posthog/logs/PostHogBeforeSendLog { public abstract fun run (Lcom/posthog/logs/PostHogLogRecord;)Lcom/posthog/logs/PostHogLogRecord; } @@ -2361,9 +1531,3 @@ public final class com/posthog/surveys/SurveyType$Companion { public final fun fromValue (Ljava/lang/String;)Lcom/posthog/surveys/SurveyType; } -public final class com/posthog/vendor/uuid/TimeBasedEpochGenerator { - public static final field INSTANCE Lcom/posthog/vendor/uuid/TimeBasedEpochGenerator; - public final fun generate ()Ljava/util/UUID; - public final fun setDateProvider (Lcom/posthog/internal/PostHogDateProvider;)V -} - From 693e2d2664912c9d3dad5e8f753ae6c9bfb9893c Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:29:50 -0500 Subject: [PATCH 31/49] fix!: omit $feature_flag_response for a missing flag (#951) * fix!: omit $feature_flag_response for a missing flag In 4.0 an empty string means an empty variant, so the client no longer reports a missing flag as "". Matches iOS (null) and JS (omitted). posthog-server's stateless path is unchanged. * test(flags): report an empty variant as an empty string, unlike a missing flag --- .changeset/android-v4-major.md | 1 + docs/migration-3.x-to-4.0.md | 2 +- posthog/src/main/java/com/posthog/PostHog.kt | 4 +- .../com/posthog/PostHogFeatureFlagsTest.kt | 40 ++++++++++++++++++- 4 files changed, 43 insertions(+), 4 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 87560ebed..ae2f13583 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -24,6 +24,7 @@ - **Breaking:** remove the deprecated `remoteConfig` option; the SDK always loads remote config at setup - **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload` - **Breaking:** remove the `defaultValue` parameter from `getFeatureFlag()`, which returns `null` for a missing flag or a disabled SDK; a positional `Boolean` second argument now sets `sendFeatureFlagEvent`, and `$feature_flag_called` no longer reports a fallback as the flag's value +- **Breaking:** leave `$feature_flag_response` out of `$feature_flag_called` for a missing flag instead of sending an empty string - **Breaking:** remove `PostHogConfig.onFeatureFlags`; call `PostHog.onFeatureFlags(callback)` before `setup()` instead - **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `reloadFeatureFlags()`, which receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and `errorsLoading` - **Breaking:** return `null` from `getFeatureFlagResult(key)?.payload` for a payload that isn't valid JSON, such as plain text, a malformed or empty string, or a JSON `null` diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 4bb60106d..9f01a222b 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -144,7 +144,7 @@ The second parameter is now `sendFeatureFlagEvent`, which affects code that stil - `getFeatureFlag("checkout", true)` compiles, but `true` now means `sendFeatureFlagEvent` rather than the default value. - A disabled SDK now returns `null`, not your default. -- `$feature_flag_called` no longer reports a fallback as the flag's value. `isFeatureEnabled("missing", true)` still returns `true`, but its event reports an empty response. +- `$feature_flag_called` no longer reports a fallback as the flag's value. `isFeatureEnabled("missing", true)` still returns `true`, but its event leaves out `$feature_flag_response`, because an empty string now means an empty variant. Classes that implement `PostHogInterface` update the signature. diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 737d70957..f84898623 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -2710,8 +2710,8 @@ public class PostHog private constructor( val props = mutableMapOf() props["\$feature_flag"] = key - // value should never be nullabe anyway - props["\$feature_flag_response"] = value ?: "" + // omit for a missing flag: "" means an empty variant + value?.let { props["\$feature_flag_response"] = it } requestId?.let { props["\$feature_flag_request_id"] = it } evaluatedAt?.let { props["\$feature_flag_evaluated_at"] = it } flagDetails?.let { diff --git a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt index 38bcdacd7..64e385c30 100644 --- a/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogFeatureFlagsTest.kt @@ -369,7 +369,7 @@ internal class PostHogFeatureFlagsTest { val theEvent = batch.batch.first() assertEquals("\$feature_flag_called", theEvent.event) assertEquals("nonExistentFlag", theEvent.properties!!["\$feature_flag"]) - assertEquals("", theEvent.properties!!["\$feature_flag_response"]) + assertFalse(theEvent.properties!!.containsKey("\$feature_flag_response")) sut.close() } @@ -387,6 +387,44 @@ internal class PostHogFeatureFlagsTest { } } + @Test + fun `getFeatureFlag reports an empty string for an empty variant`() { + val http = + mockHttp( + response = + MockResponse().setBody( + """ + { + "flags": { + "emptyVariant": { + "key": "emptyVariant", + "enabled": true, + "variant": "", + "metadata": {"id": 1, "version": 1, "payload": null} + } + } + } + """.trimIndent(), + ), + ) + http.enqueue(MockResponse().setBody("")) + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false, sendFeatureFlagEvent = true) + + sut.reloadFeatureFlags() + remoteConfigExecutor.shutdownAndAwaitTermination() + http.takeRequest() + + assertEquals("", sut.getFeatureFlag("emptyVariant")) + queueExecutor.shutdownAndAwaitTermination() + + val batch = serializer.deserialize(http.takeRequest().body.unGzip().reader()) + val theEvent = batch.batch.first() + assertEquals("\$feature_flag_called", theEvent.event) + assertEquals("emptyVariant", theEvent.properties!!["\$feature_flag"]) + assertEquals("", theEvent.properties!!["\$feature_flag_response"]) + sut.close() + } + @Test fun `isFeatureEnabled prefers a false flag value over the default`() { val http = From 8b63a1352d325e716b0e44d3f13b2bbcbfe1ea31 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Mon, 9 Nov 2026 09:58:32 -0500 Subject: [PATCH 32/49] docs(migration): cover missing-flag response, posthog-server 2.25 and retry scope Add a behavior change and checklist line for $feature_flag_response being left out for a missing flag, name posthog-server 2.25.0 and its conflict with posthog-android 3.x, scope the retries section to capture requests, introduce the Java snippet and drop the TODO() fake. --- docs/migration-3.x-to-4.0.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 9f01a222b..9df5fc7e0 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -30,12 +30,13 @@ You need to change code if your app does any of these: - uses `apiKey`, `propertiesSanitizer`, `evaluationEnvironments`, `debouncerDelayMs`, `screenshot`, `drawableConverter` or `remoteConfig` - passes `PostHogConfig` or `PostHogSessionReplayConfig` constructor arguments by position - calls `getFeatureFlagPayload()`, or passes a default value to `getFeatureFlag()` +- filters insights, cohorts or actions on the `$feature_flag_response` of `$feature_flag_called`, such as `""` or `false` for a missing flag (see [`$feature_flag_response` for a missing flag](#feature_flag_response-for-a-missing-flag)) - sets `PostHogConfig.onFeatureFlags` or `PostHogOnFeatureFlags`, or passes a callback to `reloadFeatureFlags()` - uses session replay (see [Session replay records screenshots](#session-replay-records-screenshots)) - reads a feature flag payload that isn't valid JSON, such as plain text saved as `hello` - breaks down by `$locale` for the language your app shows (use `$app_language`, and call `setAppLanguage()` if you need it on Android 6–12) - reads event content or request bodies from the SDK's debug log, or matches its log text -- depends only on `posthog-android-surveys-compose`, or uses `posthog-server` +- depends only on `posthog-android-surveys-compose`, or uses `posthog-server` (2.25.0 and later need `posthog-android` 4.0 in the same project) ## Requirements and versions @@ -44,7 +45,7 @@ You need to change code if your app does any of these: | `com.posthog:posthog-android` | 3.x to 4.0 | | `com.posthog:posthog` (core) | 6.x to 7.0 | | `com.posthog:posthog-android-surveys-compose` | keep your version, and declare `com.posthog:posthog-android` 4.0.0 or later in your build so Gradle resolves 4.x instead of the 3.x version it pulls in | -| `com.posthog:posthog-server` | see [`posthog-server`](#posthog-server) | +| `com.posthog:posthog-server` | 2.25.0, together with `posthog-android` 4.0; see [`posthog-server`](#posthog-server) | These are unchanged, so you don't need to change your build for them: @@ -144,7 +145,7 @@ The second parameter is now `sendFeatureFlagEvent`, which affects code that stil - `getFeatureFlag("checkout", true)` compiles, but `true` now means `sendFeatureFlagEvent` rather than the default value. - A disabled SDK now returns `null`, not your default. -- `$feature_flag_called` no longer reports a fallback as the flag's value. `isFeatureEnabled("missing", true)` still returns `true`, but its event leaves out `$feature_flag_response`, because an empty string now means an empty variant. +- `$feature_flag_called` no longer reports a fallback as the flag's value. `isFeatureEnabled("missing", true)` still returns `true`, but its event leaves out `$feature_flag_response` (see [`$feature_flag_response` for a missing flag](#feature_flag_response-for-a-missing-flag)). Classes that implement `PostHogInterface` update the signature. @@ -203,6 +204,8 @@ The listener differs from the removed option in three ways: - Bootstrapped flags arrive just after `setup()` is called, not synchronously inside it. - A reload on a disabled SDK doesn't call listeners. `reloadFeatureFlags(callback)` still gets `errorsLoading = true` in that case. +From Java, the `reloadFeatureFlags()` lambda now takes the `PostHogFeatureFlagsLoaded` argument: + ```java // 3.x PostHog.Companion.reloadFeatureFlags(() -> refreshUi()); @@ -225,14 +228,14 @@ The `reloadFeatureFlags()` callback still runs on a background thread, or right class FakePostHog : PostHogInterface { override fun reloadFeatureFlags(onFeatureFlags: PostHogFeatureFlagsCallback?) {} - override fun onFeatureFlags(callback: PostHogFeatureFlagsCallback): PostHogFeatureFlagsSubscription = - TODO("Return a subscription from your own fake") + // mock() from mockito-kotlin, or your mocking library's equivalent + override fun onFeatureFlags(callback: PostHogFeatureFlagsCallback): PostHogFeatureFlagsSubscription = mock() // ... } ``` -`PostHogFeatureFlagsSubscription` and `PostHogFeatureFlagsLoaded` have constructors marked `@PostHogInternal`, which aren't intended for app code, so prefer a mocking library for these types if you can. +`PostHogFeatureFlagsSubscription` and `PostHogFeatureFlagsLoaded` have constructors marked `@PostHogInternal`, which aren't intended for app code, so create them with a mocking library. ## Internal APIs @@ -273,6 +276,12 @@ A flag whose variant is an empty string now reads as disabled everywhere, as it PostHog no longer accepts an empty variant for new flags, so only flags created earlier through the API, MCP or Terraform are affected. +### `$feature_flag_response` for a missing flag + +When a flag is missing, `$feature_flag_called` now leaves out `$feature_flag_response`. 3.x sent `""` from `getFeatureFlag()` and `false` from `isFeatureEnabled()`, or your default value when you passed one. In 4.0 an empty string means a flag with an empty variant, so a missing flag no longer reports one. + +Insights, cohorts and actions that filter on `$feature_flag_response = ""` or `false` to find missing flags stop matching new events without any error. Use an `is not set` filter on `$feature_flag_response` instead. Events already stored keep their old values. + ### `$locale` and `$app_language` `$locale` now means the first language in the device settings, as a full language tag such as `de-CH` or `zh-Hant-TW`. In 3.x it came from `Locale.getDefault()`, which could be a secondary language, a per-app language or a value your app set with `Locale.setDefault()`, and it dropped the script (`zh-TW`). It's left out when the device reports no language. On older Android versions, 3.x also sent the legacy codes `iw`, `in` and `ji`, so Hebrew, Indonesian and Yiddish values change, such as `in-ID` to `id-ID`. Update filters that match those. Other values mostly stay the same, so otherwise only check filters if your users change these settings. @@ -503,6 +512,8 @@ PostHog.captureAi( ## Retries +These apply to analytics and AI event requests, unless a bullet names session replay or logs. Session replay and logs keep their 3.x status handling: they still retry 3xx and don't retry 404. + - The SDK retries network errors and 404, 408, 429, 500, 502, 503 and 504 responses. Other statuses drop the events, including 3xx, and a 402 (billing limit) drops the whole batch. A product quota, such as for exceptions or AI events, drops only those events inside a 200 response. 3.x also retried 3xx responses, and didn't retry 404. - When the response asks to retry only some events, the SDK keeps those events queued and removes the rest. - A failed request is resent with the same events, request ID and `created_at`, and the next attempt number, before newer events are sent. The request ID and attempt number reset after an app restart. OkHttp doesn't retry capture requests on its own. @@ -543,4 +554,7 @@ A personal API key (`phx_...`) in `projectToken` now disables the client at setu Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. -Its next release depends on core 7.0, so update it if your project also uses core 7.0 or `posthog-android` 4.0. Older `posthog-server` versions aren't compatible with core 7.0 at runtime. +`posthog-server` 2.25.0 depends on core 7.0, so upgrade it and `posthog-android` together: + +- If your project uses `posthog-android` 4.0 or core 7.0, use `posthog-server` 2.25.0 or later. Older `posthog-server` versions aren't compatible with core 7.0 at runtime. +- If your project still uses `posthog-android` 3.x, stay on `posthog-server` 2.24.x. Gradle resolves core 7.0 for both, and `posthog-android` 3.x fails at runtime against it with errors such as `NoSuchMethodError`. From 6b546165a6feda5c079aa64d7059b8c392d9d546 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 9 Nov 2026 15:30:52 -0500 Subject: [PATCH 33/49] fix: keep null array elements in event properties (#955) GsonSafeMapSerializer skipped null list elements, so the disk queue compacted arrays before capture v1 and posthog-server's /batch sent them. Write JSON null in place instead, also for an element that can't be serialized, so every element keeps its index. Null-valued map members are still left out, as the sdk-specs capture contract requires. Co-authored-by: Claude Opus 5.5 --- .changeset/android-v4-major.md | 1 + .changeset/server-keep-on-feature-flags.md | 1 + docs/migration-3.x-to-4.0.md | 4 +- .../json/server-safe-properties.json | 5 ++- .../posthog/internal/GsonSafeMapSerializer.kt | 18 ++++---- .../posthog/internal/PostHogCaptureV1Test.kt | 43 +++++++++++++++++++ .../posthog/internal/PostHogSerializerTest.kt | 6 ++- 7 files changed, 65 insertions(+), 13 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index ae2f13583..1f6ac3a4c 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -45,4 +45,5 @@ - Stop storing or matching the person-properties deduplication hash for a `$set` sent with `process_person_profile: false` - Stop printing analytics and AI event request and response bodies, property values and `beforeSend` exception messages in debug logs, and log per-batch drop and retry counts instead - Fix losing an event whose properties hold a nested map with non-string keys; number, boolean and `null` keys are converted to strings +- Fix removing `null` elements from lists and arrays in event properties, which moved later elements to lower indexes; they're sent as JSON `null` at their position, as is an element that can't be serialized - Fix `beforeSend` edits reaching the caller's nested maps and lists, by giving each hook its own copy diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md index 93ab75b6c..2fd76b890 100644 --- a/.changeset/server-keep-on-feature-flags.md +++ b/.changeset/server-keep-on-feature-flags.md @@ -10,4 +10,5 @@ - Merge `userProperties`, `userPropertiesSetOnce` and `groups` key by key over a `$set`, `$set_once` or `$groups` map in `properties` - Stop printing unserializable property values and `beforeSend` exception messages in debug logs - Fix losing an event whose properties hold a nested map with non-string keys; number, boolean and `null` keys are converted to strings +- Fix removing `null` elements from lists and arrays in event properties, which moved later elements to lower indexes; they're sent as JSON `null` at their position, as is an element that can't be serialized - Fix `beforeSend` edits reaching the caller's nested maps and lists, by giving each hook its own copy diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index 9df5fc7e0..d6e6dc258 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -407,6 +407,8 @@ A `NaN` or infinite number in the properties is dropped from the event, and the A map key in the properties that isn't a string is converted to one when it's a number, a boolean or `null`. Any other key is dropped with its value, and the rest of the event is sent. With `debug` on, the SDK logs the key's type. In 3.x, a nested map with a non-string key lost the whole event. +A `null` element in a list or array in the properties is now sent as JSON `null` at its position, and so is an element that can't be serialized, such as `NaN`. In 3.x, both were removed, which moved the later elements to lower indexes. A property or map entry whose value is `null` is still left out. + The distinct ID can come from `identify()`, the `distinctId` argument of `capture` or `beforeSend`. If you identify users with a long ID, such as a JWT or a long email address, shorten or hash it before you upgrade. Otherwise every event for that user is dropped. `identify()` with an empty or whitespace-only distinct ID is still ignored, as in 3.x. @@ -552,7 +554,7 @@ It still sends events to `/batch`, not to capture v1, so the endpoint, proxy, re A personal API key (`phx_...`) in `projectToken` now disables the client at setup, as an empty token does, and both print why even when `debug` is off. -Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. +Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. A `null` element in a list or array in the properties is sent as JSON `null` at its position instead of being removed. `posthog-server` 2.25.0 depends on core 7.0, so upgrade it and `posthog-android` together: diff --git a/posthog-server/src/test/resources/json/server-safe-properties.json b/posthog-server/src/test/resources/json/server-safe-properties.json index 8f87e3a65..58828934b 100644 --- a/posthog-server/src/test/resources/json/server-safe-properties.json +++ b/posthog-server/src/test/resources/json/server-safe-properties.json @@ -18,11 +18,14 @@ }, "ordered_array": [ "alpha", + null, "omega" ], "ordered_list": [ "first", - "third" + null, + "third", + null ] }, "timestamp": "2023-09-20T11:58:49.000Z", diff --git a/posthog/src/main/java/com/posthog/internal/GsonSafeMapSerializer.kt b/posthog/src/main/java/com/posthog/internal/GsonSafeMapSerializer.kt index 7ad5b9f52..7d0ae03d1 100644 --- a/posthog/src/main/java/com/posthog/internal/GsonSafeMapSerializer.kt +++ b/posthog/src/main/java/com/posthog/internal/GsonSafeMapSerializer.kt @@ -2,6 +2,7 @@ package com.posthog.internal import com.google.gson.JsonArray import com.google.gson.JsonElement +import com.google.gson.JsonNull import com.google.gson.JsonObject import com.google.gson.JsonSerializationContext import com.google.gson.JsonSerializer @@ -14,7 +15,8 @@ import java.lang.reflect.Type * unserializable values instead of throwing exceptions. * * Performs depth-first serialization to ensure only unserializable leaf values - * are dropped, not entire branches containing them. + * are dropped, not entire branches containing them. Null-valued map members are + * omitted; list elements keep their indices (see [safeSerializeList]). * * @property config the Config */ @@ -66,6 +68,7 @@ internal class GsonSafeMapSerializer(private val config: PostHogConfig) : JsonSe targetValue: Any?, key: String, context: JsonSerializationContext, + inList: Boolean = false, ): JsonElement? { return when (targetValue) { null -> null @@ -82,7 +85,8 @@ internal class GsonSafeMapSerializer(private val config: PostHogConfig) : JsonSe // the value's type only: properties can hold prompts and other user content config.logger.log( "Property '$key' of type ${targetValue.javaClass.name} cannot be serialized to JSON " + - "(${e.javaClass.simpleName}). This property will be ignored.", + "(${e.javaClass.simpleName}). " + + (if (inList) "It will be sent as null." else "This property will be ignored."), ) null } @@ -91,7 +95,8 @@ internal class GsonSafeMapSerializer(private val config: PostHogConfig) : JsonSe } /** - * Safely serializes a list, filtering out unserializable elements. + * Safely serializes a list, keeping every element at its index: a null element is written as + * JSON `null`, and so is an element that can't be serialized, so the array is never compacted. */ private fun safeSerializeList( list: List<*>, @@ -100,12 +105,7 @@ internal class GsonSafeMapSerializer(private val config: PostHogConfig) : JsonSe val jsonArray = JsonArray() list.forEach { element -> - if (element != null) { - val serialized = safeSerializeValue(element, "list-element", context) - if (serialized != null) { - jsonArray.add(serialized) - } - } + jsonArray.add(safeSerializeValue(element, "list-element", context, inList = true) ?: JsonNull.INSTANCE) } return jsonArray diff --git a/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt b/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt index d4d878a92..7a3941195 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt @@ -1,5 +1,6 @@ package com.posthog.internal +import com.google.gson.JsonParser import com.posthog.BuildConfig import com.posthog.PROJECT_TOKEN import com.posthog.PostHogConfig @@ -861,6 +862,48 @@ internal class PostHogCaptureV1Test { assertFalse(logger.messages.any { it.contains("successfully") }) } + // The capture spec's example: null object members are dropped, null array elements keep their index. + private fun assertQueuedNullsMatchSpec(ai: Boolean) { + @Suppress("UNCHECKED_CAST") + val properties = + mutableMapOf( + "test" to null, + "items" to listOf("1", null, 2, mapOf("drop" to null), listOf(null)), + "nested" to mapOf("drop" to null, "keep" to 1), + "top" to listOf(null), + "empty" to "", + "zero" to 0, + "enabled" to false, + "literal" to "null", + "emptyArray" to emptyList(), + ) as MutableMap + val event = event(if (ai) "\$ai_generation" else "event").copy(properties = properties) + val http = httpServers.mockHttp(response = resultsResponse(event.uuid!! to "ok")) + val sut = queue(http, ai = ai) + + sut.add(event) + executor.awaitExecution() + + val sent = JsonParser.parseString(http.takeRequest().body.unGzip()).asJsonObject["batch"].asJsonArray.single() + assertEquals( + JsonParser.parseString( + "{\"items\":[\"1\",null,2,{},[null]],\"nested\":{\"keep\":1},\"top\":[null]," + + "\"empty\":\"\",\"zero\":0,\"enabled\":false,\"literal\":\"null\",\"emptyArray\":[]}", + ), + sent.asJsonObject["properties"], + ) + } + + @Test + fun `queued events keep null array elements at their index and drop null object members`() { + assertQueuedNullsMatchSpec(ai = false) + } + + @Test + fun `queued AI events keep null array elements at their index and drop null object members`() { + assertQueuedNullsMatchSpec(ai = true) + } + @Test fun `queued events round-trip their options through disk`() { val http = httpServers.mockHttp(response = MockResponse().setResponseCode(503)) diff --git a/posthog/src/test/java/com/posthog/internal/PostHogSerializerTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogSerializerTest.kt index 883026d76..a6ac88e7d 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogSerializerTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogSerializerTest.kt @@ -293,7 +293,8 @@ internal class PostHogSerializerTest { sut.serialize(event, serialized) val actualJson = serialized.toString() - // The result should preserve the nested "bad" map but only drop the unserializable leaf value + // The result should preserve the nested "bad" map but only drop the unserializable leaf value; + // in an array it becomes null so later elements keep their index val expectedJson = """ { @@ -305,7 +306,8 @@ internal class PostHogSerializerTest { "good": "yes" }, "in_an_array": [ - "good" + "good", + null ] }, "timestamp": "2009-02-13T23:31:30.000Z", From 7bb27571c18e84e1c5afb89cfa637c424eeb9d05 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Mon, 9 Nov 2026 15:43:05 -0500 Subject: [PATCH 34/49] docs(migration): tell users to rename empty flag variants before upgrading /flags still returns enabled: true for a flag with an empty variant, so other PostHog SDKs can still report it as enabled after this upgrade. Co-Authored-By: Claude Opus 5.5 --- docs/migration-3.x-to-4.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration-3.x-to-4.0.md b/docs/migration-3.x-to-4.0.md index d6e6dc258..96bf8f40e 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/docs/migration-3.x-to-4.0.md @@ -274,7 +274,7 @@ Apps upgrading from 3.13 or older didn't cache flag details, so until the app's A flag whose variant is an empty string now reads as disabled everywhere, as it already did from `isFeatureEnabled()`, with or without `defaultValue`. `getFeatureFlagResult()` and `getAllFeatureFlags()` return `enabled = false` for it, where 3.x returned `true`, `PostHogFeatureFlagsLoaded` leaves it out of `flags` and `variants`, and captured events leave it out of `$active_feature_flags`. `variant`, `getFeatureFlag()` and the event's `$feature/` property still return `""`. -PostHog no longer accepts an empty variant for new flags, so only flags created earlier through the API, MCP or Terraform are affected. +PostHog no longer accepts empty variants for new flags, so only flags created earlier through the API, MCP or Terraform are affected. `/flags` still returns `enabled: true` for them, and other PostHog SDKs can still report them as enabled, so rename the variant before you upgrade. ### `$feature_flag_response` for a missing flag From 61ba47cdc007476bcff6728d542ca63b9992bd7f Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 9 Nov 2026 15:46:15 -0500 Subject: [PATCH 35/49] feat: let wrapper SDKs register capture options for every event (#954) * feat: let wrapper SDKs register capture options for every event Adds registerOptionsForWrapper and unregisterOptionsForWrapper behind @PostHogInternal, so posthog-flutter can offer global options without adding public API to posthog-android. Registered options are persisted, cleared by reset(), and filled under each event's own options before beforeSend runs. Co-Authored-By: Claude Opus 5.5 * fix: let an explicit null option override the registered one in the $set dedup check --------- Co-authored-by: Claude Opus 5.5 --- .changeset/android-v4-major.md | 1 + posthog/src/main/java/com/posthog/PostHog.kt | 74 ++++++++++++++--- .../main/java/com/posthog/PostHogInterface.kt | 22 +++++ .../posthog/internal/PostHogPreferences.kt | 2 + .../com/posthog/PostHogWrapperEventTest.kt | 80 +++++++++++++++++++ 5 files changed, 168 insertions(+), 11 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 1f6ac3a4c..8b7fbbfbb 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -39,6 +39,7 @@ - Add `onFeatureFlags()` to listen for every feature flags load (on the main thread on Android), returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` - Add the `$app_language` property with the language the app displays on Android 13+, and `setAppLanguage()` to set it on every version - Add internal APIs so wrapper SDKs can run their own `beforeSend` on the fully built event +- Add internal APIs so wrapper SDKs can register capture options sent with every event - Send events queued on disk by 3.x through capture v1 after the update - Cap a capture request at about 5 MiB of events and send as soon as that much is queued - Use the current distinct ID when the `distinctId` argument to `capture` is empty or whitespace-only, instead of dropping the event diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index f84898623..03dfa8069 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -21,6 +21,7 @@ import com.posthog.internal.PostHogPreferences.Companion.OPT_OUT import com.posthog.internal.PostHogPreferences.Companion.PERSON_PROCESSING import com.posthog.internal.PostHogPreferences.Companion.PUSH_OPENED_MESSAGE_IDS import com.posthog.internal.PostHogPreferences.Companion.PUSH_SUBSCRIPTION_REJECTED +import com.posthog.internal.PostHogPreferences.Companion.REGISTERED_OPTIONS import com.posthog.internal.PostHogPreferences.Companion.SESSION_REPLAY import com.posthog.internal.PostHogPreferences.Companion.SURVEYS import com.posthog.internal.PostHogPreferences.Companion.VERSION @@ -137,6 +138,7 @@ public class PostHog private constructor( private val deviceIdLock = Any() private val identifiedLock = Any() private val groupsLock = Any() + private val registeredOptionsLock = Any() private val personProcessingLock: Any = Any() private val featureFlagsCalledLock = Any() @@ -924,7 +926,7 @@ public class PostHog private constructor( props["\$is_identified"] = isIdentified // No `$process_person_profile`: person processing is sent as the `process_person_profile` - // option, only when it's off (see personProcessingOptions). A registered or caller + // option, only when it's off (see optionsForEvent). A registered or caller // `$process_person_profile` wins over it when the send hoists the property. } @@ -1104,19 +1106,25 @@ public class PostHog private constructor( } /** - * Adds `process_person_profile: false` when the SDK doesn't process person profiles for this - * event, unless the caller set that option or [properties] carry a non-null legacy - * `$process_person_profile` property (per call or registered). Nothing is added otherwise: - * PostHog processes person profiles by default. [personProcessingPending] counts a person - * processing change a wrapper build defers to its send. Returns a copy, so `beforeSend` edits - * never reach the caller's map. + * The event's [options] over the wrapper-registered ones, plus `process_person_profile: false` + * when the SDK doesn't process person profiles for this event, unless an option or a non-null + * legacy `$process_person_profile` property in [properties] (per call or registered) already + * says otherwise. Nothing is added otherwise: PostHog processes person profiles by default. + * [personProcessingPending] counts a person processing change a wrapper build defers to its + * send. Returns a copy, so `beforeSend` edits never reach the caller's map. */ - private fun personProcessingOptions( + private fun optionsForEvent( options: Map?, properties: Map, personProcessingPending: Boolean = false, ): MutableMap? { - val eventOptions = options?.toMutableMap() + val registered = getRegisteredOptions() + val eventOptions = + if (registered.isEmpty()) { + options?.toMutableMap() + } else { + registered.toMutableMap().apply { options?.let { putAll(it) } } + } if ((personProcessingPending && config?.personProfiles != PersonProfiles.NEVER) || hasPersonProcessing() || properties["\$process_person_profile"] != null @@ -1135,7 +1143,13 @@ public class PostHog private constructor( * neither stores nor matches the person-properties hash. */ private fun isPersonProcessed(options: Map?): Boolean { - val option = options?.get("process_person_profile") + // An explicit null in [options] replaces the registered option, as in optionsForEvent. + val option = + if (options?.containsKey("process_person_profile") == true) { + options["process_person_profile"] + } else { + getRegisteredOptions()["process_person_profile"] + } if (option != null) { return !isFalseOptionValue(option) } @@ -1412,7 +1426,7 @@ public class PostHog private constructor( if (isSnapshotEvent) { options?.toMutableMap() } else { - personProcessingOptions(options, mergedProperties, deferPersonProcessing && requiresPersonProcessing) + optionsForEvent(options, mergedProperties, deferPersonProcessing && requiresPersonProcessing) } // This capture's identity, kept through beforeSend. @@ -2946,6 +2960,34 @@ public class PostHog private constructor( getPreferences().remove(key) } + @Suppress("UNCHECKED_CAST") + private fun getRegisteredOptions(): Map = getPreferences().getValue(REGISTERED_OPTIONS) as? Map ?: emptyMap() + + @PostHogInternal + override fun registerOptionsForWrapper(options: Map) { + if (!isEnabled()) { + return + } + synchronized(registeredOptionsLock) { + getPreferences().setValue(REGISTERED_OPTIONS, getRegisteredOptions() + options) + } + } + + @PostHogInternal + override fun unregisterOptionsForWrapper(key: String) { + if (!isEnabled()) { + return + } + synchronized(registeredOptionsLock) { + val remaining = getRegisteredOptions() - key + if (remaining.isEmpty()) { + getPreferences().remove(REGISTERED_OPTIONS) + } else { + getPreferences().setValue(REGISTERED_OPTIONS, remaining) + } + } + } + public override fun setAppLanguage(language: String?) { appLanguage = language?.trim()?.replace('_', '-')?.ifEmpty { null } } @@ -3624,6 +3666,16 @@ public class PostHog private constructor( ai: Boolean, ): UUID? = shared.sendBuiltEventForWrapper(event, ai) + @PostHogInternal + override fun registerOptionsForWrapper(options: Map) { + shared.registerOptionsForWrapper(options) + } + + @PostHogInternal + override fun unregisterOptionsForWrapper(key: String) { + shared.unregisterOptionsForWrapper(key) + } + override fun isSessionActive(): Boolean { return shared.isSessionActive() } diff --git a/posthog/src/main/java/com/posthog/PostHogInterface.kt b/posthog/src/main/java/com/posthog/PostHogInterface.kt index 3d250da0a..d515736a1 100644 --- a/posthog/src/main/java/com/posthog/PostHogInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogInterface.kt @@ -700,4 +700,26 @@ public interface PostHogInterface : PostHogCoreInterface { event: PostHogEvent, ai: Boolean = false, ): UUID? = null + + /** + * For wrapper SDKs only (Flutter, React Native); not for app code. + * + * Registers capture options sent with every later event, under each event's own options. New + * values overwrite existing ones for the same keys and persist across app restarts until removed + * with [unregisterOptionsForWrapper] or cleared by `reset()`. + * + * @suppress + */ + @PostHogInternal + public fun registerOptionsForWrapper(options: Map) {} + + /** + * For wrapper SDKs only (Flutter, React Native); not for app code. + * + * Removes an option registered with [registerOptionsForWrapper]. + * + * @suppress + */ + @PostHogInternal + public fun unregisterOptionsForWrapper(key: String) {} } diff --git a/posthog/src/main/java/com/posthog/internal/PostHogPreferences.kt b/posthog/src/main/java/com/posthog/internal/PostHogPreferences.kt index 9d29d9f99..6fc480541 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogPreferences.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogPreferences.kt @@ -40,6 +40,7 @@ public interface PostHogPreferences { public const val DISTINCT_ID: String = "distinctId" internal const val IS_IDENTIFIED = "isIdentified" internal const val PERSON_PROCESSING = "personProcessingEnabled" + internal const val REGISTERED_OPTIONS = "registeredOptions" internal const val OPT_OUT = "opt-out" internal const val FLAGS = "flags" internal const val FEATURE_FLAGS = "featureFlags" @@ -76,6 +77,7 @@ public interface PostHogPreferences { DISTINCT_ID, IS_IDENTIFIED, PERSON_PROCESSING, + REGISTERED_OPTIONS, OPT_OUT, FEATURE_FLAGS, FEATURE_FLAGS_PAYLOAD, diff --git a/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt b/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt index bbda6457f..07995d3a1 100644 --- a/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt @@ -479,4 +479,84 @@ internal class PostHogWrapperEventTest { assertEquals(false, assertNotNull(sut.buildEventForWrapper("tap")).options?.get("process_person_profile")) } + + @Suppress("UNCHECKED_CAST") + private fun Map.options(): Map? = this["options"] as Map? + + @Test + fun `registered options are sent on every event, under the event's own options`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + sut.registerOptionsForWrapper(mapOf("cookieless_mode" to false, "disable_skew_correction" to true)) + + sut.capture("plain") + queueExecutor.awaitExecution() + val plain = events(takeRequest(http)).single() + sut.capture("own", options = mapOf("cookieless_mode" to true)) + queueExecutor.awaitExecution() + val own = events(takeRequest(http)).single() + + assertEquals(false, plain.options()?.get("cookieless_mode")) + assertEquals(true, plain.options()?.get("disable_skew_correction")) + assertEquals(true, own.options()?.get("cookieless_mode")) + assertEquals(true, own.options()?.get("disable_skew_correction")) + assertFalse(plain.properties().containsKey("registeredOptions")) + } + + @Test + fun `a wrapper build carries the registered options, so the wrapper's beforeSend sees them`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + sut.registerOptionsForWrapper(mapOf("disable_skew_correction" to true, "cookieless_mode" to false)) + + val built = assertNotNull(sut.buildEventForWrapper("e", options = mapOf("cookieless_mode" to true))) + + assertEquals(true, built.options?.get("disable_skew_correction")) + assertEquals(true, built.options?.get("cookieless_mode")) + } + + @Test + fun `a registered process_person_profile replaces the SDK's personless default`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + sut.registerOptionsForWrapper(mapOf("process_person_profile" to true)) + + sut.capture("anonymous") + queueExecutor.awaitExecution() + + assertEquals(true, events(takeRequest(http)).single().options()?.get("process_person_profile")) + } + + @Test + fun `an explicit null option over a registered one doesn't mark a personless $set as processed`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + sut.registerOptionsForWrapper(mapOf("process_person_profile" to true)) + sut.register("\$process_person_profile", false) + + sut.setPersonProperties(mapOf("plan" to "pro"), null, mapOf("process_person_profile" to null)) + queueExecutor.awaitExecution() + val personless = events(takeRequest(http)).single() + sut.setPersonProperties(mapOf("plan" to "pro"), null, null) + queueExecutor.awaitExecution() + + assertEquals(false, personless.options()?.get("process_person_profile")) + assertEquals(2, http.requestCount) + } + + @Test + fun `unregister and reset remove registered options`() { + val http = httpServers.mockHttp() + val sut = getSut(http) + sut.registerOptionsForWrapper(mapOf("cookieless_mode" to true, "disable_skew_correction" to true)) + + sut.unregisterOptionsForWrapper("cookieless_mode") + val afterUnregister = assertNotNull(sut.buildEventForWrapper("e")) + assertNull(afterUnregister.options?.get("cookieless_mode")) + assertEquals(true, afterUnregister.options?.get("disable_skew_correction")) + + sut.reset() + val afterReset = assertNotNull(sut.buildEventForWrapper("e")) + assertNull(afterReset.options?.get("disable_skew_correction")) + } } From bc7fdf6f8db0821ff0bd80f4fd143b519c07641e Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Mon, 9 Nov 2026 15:46:44 -0500 Subject: [PATCH 36/49] docs: move the 4.0 guide to MIGRATION.md and fill its gaps MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename docs/migration-3.x-to-4.0.md to a root MIGRATION.md with a general title and a 3.x → 4.0 / core 7.0 section, so later majors add a section instead of a new file; update the README and changeset links. - Add a note for core-only JVM users listing the Android-only sections. - Document that a `true` person-processing option or property now overrides PersonProfiles.NEVER, that beforeSend gets deep copies, how to register onFeatureFlags() on a PostHogAndroid.with() instance, and that the AI disk queue is Android-only. - Split the Android-only lines (replay, Compose masking, dialogs, $locale, deep links, android internals) into their own changeset so they don't land in core's CHANGELOG. - Add the NEVER, PostHog-Request-Id and $sdk_debug_replay_capture_mode lines, and the posthog-server 2.25 / core 7.0 compatibility line. --- .changeset/android-v4-major.md | 11 +-- .changeset/android-v4-replay-and-device.md | 11 +++ .changeset/server-keep-on-feature-flags.md | 1 + docs/migration-3.x-to-4.0.md => MIGRATION.md | 82 +++++++++++--------- README.md | 2 +- 5 files changed, 61 insertions(+), 46 deletions(-) create mode 100644 .changeset/android-v4-replay-and-device.md rename docs/migration-3.x-to-4.0.md => MIGRATION.md (92%) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 8b7fbbfbb..eeee9c9d5 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -3,7 +3,7 @@ 'posthog-android': major --- -- See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/docs/migration-3.x-to-4.0.md) for upgrade steps +- See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/MIGRATION.md) for upgrade steps - **Breaking:** send analytics events to capture v1 (`/i/v1/analytics/events`) with the project token in an `Authorization: Bearer` header, replacing any `Authorization` header in `requestHeaders`; self-hosted instances and reverse proxies must serve the path, and a 404 keeps events queued, retries them and prints one warning even when `debug` is off - **Breaking:** drop events when a capture request gets a non-retryable status (including 3xx), a 2xx without per-event results, or a redirect other than a 307 or 308 to the same origin as `host` (followed at most 5 times); retry 404, 408, 429, 500, 502, 503 and 504 - **Breaking:** cap a `Retry-After` wait at 30 seconds, read it as a minimum wait and accept an HTTP date, and add up to 25% random jitter to the backoff, which still doubles from 1 to 30 seconds, for events, session replay and logs @@ -11,6 +11,7 @@ - **Breaking:** send `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, dropping non-string values - **Breaking:** send `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id` as capture options instead of properties; PostHog drops an event whose option value it can't read - **Breaking:** set the `process_person_profile` option to `false` only when person processing is off, instead of adding a `$process_person_profile` property to every event +- **Breaking:** let a `process_person_profile` option or `$process_person_profile` property set to `true` turn person processing on for an event even with `PersonProfiles.NEVER` - **Breaking:** let registered super properties override properties the SDK sets, such as `$os_name`, and let super and event properties override `$is_identified`, `$process_person_profile` and the session replay debug properties - **Breaking:** let `userProperties`, `userPropertiesSetOnce` and `groups` win key by key over `$set`, `$set_once` and `$groups` maps in the same call's properties, and merge a `$groups` map in properties into the groups set with `group()` - **Breaking:** keep the event's own uuid when `beforeSend` returns an event with another uuid @@ -29,18 +30,14 @@ - **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `reloadFeatureFlags()`, which receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and `errorsLoading` - **Breaking:** return `null` from `getFeatureFlagResult(key)?.payload` for a payload that isn't valid JSON, such as plain text, a malformed or empty string, or a JSON `null` - **Breaking:** return `enabled = false` from `getFeatureFlagResult()` and leave the flag out of `PostHogFeatureFlagsLoaded` and `$active_feature_flags` for a feature flag whose variant is an empty string, as `isFeatureEnabled()` already does -- **Breaking:** remove wireframe session replay and the `screenshot`, `drawableConverter` and `debouncerDelayMs` options of `PostHogSessionReplayConfig` (use `throttleDelayMs` for the last); replay always records masked screenshots, so apps that relied on the default now upload screenshots and should mask custom-drawn views, maps and video, or turn replay off -- **Breaking:** apply `Modifier.postHogMask()` and `Modifier.postHogUnmask()` only to the element and its children, mask Compose text that draws past its layout box in full, and mask nodes using `Modifier.clearAndSetSemantics` while text or image masking is on -- **Breaking:** send a dialog's dim and a dialog masked whole as screenshot images instead of styled wireframe shapes -- **Breaking:** change `$locale` to the first language in the device settings as a full language tag, such as `zh-Hant-TW`, instead of `Locale.getDefault()` -- **Breaking:** skip deep link query parameters whose name starts with `$` in the `Deep Link Opened` event -- **Breaking:** make SDK-internal helpers in `com.posthog.internal`, `com.posthog.android.internal` and `com.posthog.android.replay.internal` non-public +- **Breaking:** make SDK-internal helpers in `com.posthog.internal` non-public - Add `captureAi()` to send AI events such as `$ai_generation` to `/i/v1/ai/events` on their own disk queue, returning the event uuid or `null` when the event isn't queued, with the `captureAiCompression`, `captureAiMaxQueueSize`, `captureAiTimeout` and `captureAiMaxEventBytes` options - Add `onFeatureFlags()` to listen for every feature flags load (on the main thread on Android), returning a `PostHogFeatureFlagsSubscription` you can `unsubscribe()` - Add the `$app_language` property with the language the app displays on Android 13+, and `setAppLanguage()` to set it on every version - Add internal APIs so wrapper SDKs can run their own `beforeSend` on the fully built event - Add internal APIs so wrapper SDKs can register capture options sent with every event - Send events queued on disk by 3.x through capture v1 after the update +- Send a `PostHog-Request-Id` header with each capture request, which reverse proxies must pass through - Cap a capture request at about 5 MiB of events and send as soon as that much is queued - Use the current distinct ID when the `distinctId` argument to `capture` is empty or whitespace-only, instead of dropping the event - Stop storing or matching the person-properties deduplication hash for a `$set` sent with `process_person_profile: false` diff --git a/.changeset/android-v4-replay-and-device.md b/.changeset/android-v4-replay-and-device.md new file mode 100644 index 000000000..61e5f704c --- /dev/null +++ b/.changeset/android-v4-replay-and-device.md @@ -0,0 +1,11 @@ +--- +'posthog-android': major +--- + +- **Breaking:** remove wireframe session replay and the `screenshot`, `drawableConverter` and `debouncerDelayMs` options of `PostHogSessionReplayConfig` (use `throttleDelayMs` for the last); replay always records masked screenshots, so apps that relied on the default now upload screenshots and should mask custom-drawn views, maps and video, or turn replay off +- **Breaking:** apply `Modifier.postHogMask()` and `Modifier.postHogUnmask()` only to the element and its children, mask Compose text that draws past its layout box in full, and mask nodes using `Modifier.clearAndSetSemantics` while text or image masking is on +- **Breaking:** send a dialog's dim and a dialog masked whole as screenshot images instead of styled wireframe shapes +- **Breaking:** change `$locale` to the first language in the device settings as a full language tag, such as `zh-Hant-TW`, instead of `Locale.getDefault()` +- **Breaking:** skip deep link query parameters whose name starts with `$` in the `Deep Link Opened` event +- **Breaking:** make SDK-internal helpers in `com.posthog.android.internal` and `com.posthog.android.replay.internal` non-public +- Always set `$sdk_debug_replay_capture_mode` to `screenshot` diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md index 2fd76b890..5fe35962f 100644 --- a/.changeset/server-keep-on-feature-flags.md +++ b/.changeset/server-keep-on-feature-flags.md @@ -2,6 +2,7 @@ 'posthog-server': minor --- +- Require `posthog-android` 4.0 in the same project, since core 7.0 fails at runtime with `posthog-android` 3.x; stay on 2.24.x until you upgrade (see the [migration guide](https://github.com/PostHog/posthog-android/blob/main/MIGRATION.md#posthog-server)) - Bump the `posthog` core dependency to 7.0; `posthog-server` keeps its API, `/batch` endpoint and retry behavior - Move `PostHogOnFeatureFlags` into `posthog-server` with the same name and API - Add an `options` property to `PostHogEvent`, which `beforeSend` can read; `posthog-server` still sends to `/batch`, which doesn't use it, so setting it in `beforeSend` has no effect diff --git a/docs/migration-3.x-to-4.0.md b/MIGRATION.md similarity index 92% rename from docs/migration-3.x-to-4.0.md rename to MIGRATION.md index 96bf8f40e..97dec6fa5 100644 --- a/docs/migration-3.x-to-4.0.md +++ b/MIGRATION.md @@ -1,14 +1,18 @@ -# Migrating from PostHog Android 3.x to 4.0 +# Migration guide + +## posthog-android 3.x → 4.0 and posthog (core) 7.0 4.0 sends analytics events to capture v1 (`/i/v1/analytics/events`) instead of `/batch`, removes APIs deprecated in 3.x and changes the feature flags callback. Most removals are compile errors with a direct replacement. [Behavior changes](#behavior-changes) won't show up at build time. Read the checklist first, then the sections that apply to you. +If you use core `posthog` 7.0 on the JVM without `posthog-android`, the API, endpoint, event and retry changes apply, but these don't: [`$locale` and `$app_language`](#locale-and-app_language), [Session replay records screenshots](#session-replay-records-screenshots), [Deep link query parameters](#deep-link-query-parameters) and the AI events disk queue (core keeps AI events in memory). `onFeatureFlags()` listeners run on a background thread. + For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/libraries/capture-v1). For the full list of 4.0 changes, see the [changelog](https://github.com/PostHog/posthog-android/blob/main/posthog-android/CHANGELOG.md). -## Checklist +### Checklist You need to change code if your app does any of these: @@ -38,7 +42,7 @@ You need to change code if your app does any of these: - reads event content or request bodies from the SDK's debug log, or matches its log text - depends only on `posthog-android-surveys-compose`, or uses `posthog-server` (2.25.0 and later need `posthog-android` 4.0 in the same project) -## Requirements and versions +### Requirements and versions | Artifact | Upgrade | | --- | --- | @@ -56,7 +60,7 @@ These are unchanged, so you don't need to change your build for them: Upgrade PostHog artifacts together. Core 7.0 is not binary compatible with SDK versions built against core 6.x, except `posthog-android-surveys-compose`, which works with both. A mismatch fails at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. -## Removed APIs +### Removed APIs All of these are compile errors. Calling them from an already-compiled library that you haven't updated fails at runtime. @@ -76,7 +80,7 @@ All of these are compile errors. Calling them from an already-compiled library t The constructor parameters of `PostHogConfig` and `PostHogSessionReplayConfig` move up where these were removed. If you pass arguments by position, check them, or switch to named arguments. -### `apiKey` +#### `apiKey` ```kotlin // 3.x @@ -90,7 +94,7 @@ val token = config.projectToken `PostHogAndroidConfig("phc_your_project_token")`, with no parameter name, still works. From Java, replace `getApiKey()` with `getProjectToken()`. -### `propertiesSanitizer` +#### `propertiesSanitizer` ```kotlin // 3.x @@ -107,7 +111,7 @@ config.addBeforeSend { event -> `addBeforeSend` gets the whole `PostHogEvent`. Return `null` to drop the event. If the hook throws, the event is dropped. -### `evaluationEnvironments` +#### `evaluationEnvironments` ```kotlin // 3.x @@ -117,7 +121,7 @@ config.evaluationEnvironments = listOf("production") config.evaluationContexts = listOf("production") ``` -### `getFeatureFlagPayload()` +#### `getFeatureFlagPayload()` `getFeatureFlagPayload()` never sent `$feature_flag_called`. `getFeatureFlagResult()` sends it by default, following `sendFeatureFlagEvent`, so pass `sendFeatureFlagEvent = false` to keep your event volume and experiment exposures unchanged. If you drop that argument, nothing fails, but you'll send new events. @@ -131,7 +135,7 @@ val payload = PostHog.getFeatureFlagPayload("checkout", defaultValue = "fallback val payload = PostHog.getFeatureFlagResult("checkout", sendFeatureFlagEvent = false)?.payload ?: "fallback" ``` -### `getFeatureFlag()` default value +#### `getFeatureFlag()` default value ```kotlin // 3.x @@ -149,7 +153,7 @@ The second parameter is now `sendFeatureFlagEvent`, which affects code that stil Classes that implement `PostHogInterface` update the signature. -### `debouncerDelayMs` +#### `debouncerDelayMs` ```kotlin // 3.x @@ -159,7 +163,7 @@ PostHogSessionReplayConfig(debouncerDelayMs = 500) PostHogSessionReplayConfig(throttleDelayMs = 500) ``` -### `remoteConfig` +#### `remoteConfig` Delete the option. Apps that left it at its default of `true` see no behavior change. @@ -176,9 +180,9 @@ If you set it to `false`, your app's behavior changes: - The settings in `/config` now apply, including the session replay, surveys, error tracking and push settings from your project. - With `preloadFeatureFlags = true`, the SDK requests `/flags` only if `/config` reports that the project has feature flags. In 3.x it always requested `/flags`. If the project has none, the cached flags are cleared. -## Feature flags callback +### Feature flags callback -`PostHogConfig.onFeatureFlags` is removed. Call `PostHog.onFeatureFlags()` before `setup()` instead, which also covers the first load. `reloadFeatureFlags()` now takes a `PostHogFeatureFlagsCallback`. Both callbacks receive a `PostHogFeatureFlagsLoaded`: +`PostHogConfig.onFeatureFlags` is removed. Call `PostHog.onFeatureFlags()` before `setup()` instead, which also covers the first load. An instance from `PostHogAndroid.with()` is set up as it's created, so call `onFeatureFlags()` on it right after `with()`; if flags have already loaded, the listener gets the current values shortly after it registers. `reloadFeatureFlags()` now takes a `PostHogFeatureFlagsCallback`. Both callbacks receive a `PostHogFeatureFlagsLoaded`: - `flags`: the keys of the enabled flags - `variants`: their values, either `true` or the variant string @@ -220,7 +224,7 @@ A Kotlin trailing lambda such as `PostHog.reloadFeatureFlags { refreshUi() }` co The `reloadFeatureFlags()` callback still runs on a background thread, or right away on the calling thread when no load is attempted, so switch to the main thread before touching UI. -## `PostHogInterface` implementations +### `PostHogInterface` implementations `PostHogInterface` lost `getFeatureFlagPayload()`, gained the abstract `onFeatureFlags()` and `setAppLanguage()`, and changed the callback type of `reloadFeatureFlags()`. Classes that implement it, such as hand-written fakes for tests, no longer compile until they're updated. They also add the `options` parameter and `captureAi()` (see [Event options](#event-options) and [AI events](#ai-events)). @@ -237,7 +241,7 @@ class FakePostHog : PostHogInterface { `PostHogFeatureFlagsSubscription` and `PostHogFeatureFlagsLoaded` have constructors marked `@PostHogInternal`, which aren't intended for app code, so create them with a mocking library. -## Internal APIs +### Internal APIs These helpers were public only by accident and were marked `@PostHogInternal`. They're no longer visible outside the SDK and have no replacement. Apps that don't use `@PostHogInternal` APIs aren't affected. @@ -250,9 +254,9 @@ These helpers were public only by accident and were marked `@PostHogInternal`. T If you call `PostHogRemoteConfig.loadFeatureFlags()` or `loadRemoteConfig()`, their callback parameters changed too. The internal callback is now `(errorsLoading: Boolean) -> Unit`, and the other is a `PostHogFeatureFlagsCallback`. -## Behavior changes +### Behavior changes -### Feature flag payloads must be valid JSON +#### Feature flag payloads must be valid JSON A payload that isn't valid JSON now reads as `null` from `getFeatureFlagResult(key)?.payload` and `getAllFeatureFlags()`, instead of the raw string. With `debug` on, the SDK logs the flag key. @@ -270,19 +274,19 @@ If you read a payload as plain text, such as a payload saved as `hello` rather t Apps upgrading from 3.13 or older didn't cache flag details, so until the app's first `/flags` response, a malformed payload cached by 3.x still reads as the raw string, as it did in 3.x. -### Empty variants read as disabled +#### Empty variants read as disabled A flag whose variant is an empty string now reads as disabled everywhere, as it already did from `isFeatureEnabled()`, with or without `defaultValue`. `getFeatureFlagResult()` and `getAllFeatureFlags()` return `enabled = false` for it, where 3.x returned `true`, `PostHogFeatureFlagsLoaded` leaves it out of `flags` and `variants`, and captured events leave it out of `$active_feature_flags`. `variant`, `getFeatureFlag()` and the event's `$feature/` property still return `""`. PostHog no longer accepts empty variants for new flags, so only flags created earlier through the API, MCP or Terraform are affected. `/flags` still returns `enabled: true` for them, and other PostHog SDKs can still report them as enabled, so rename the variant before you upgrade. -### `$feature_flag_response` for a missing flag +#### `$feature_flag_response` for a missing flag When a flag is missing, `$feature_flag_called` now leaves out `$feature_flag_response`. 3.x sent `""` from `getFeatureFlag()` and `false` from `isFeatureEnabled()`, or your default value when you passed one. In 4.0 an empty string means a flag with an empty variant, so a missing flag no longer reports one. Insights, cohorts and actions that filter on `$feature_flag_response = ""` or `false` to find missing flags stop matching new events without any error. Use an `is not set` filter on `$feature_flag_response` instead. Events already stored keep their old values. -### `$locale` and `$app_language` +#### `$locale` and `$app_language` `$locale` now means the first language in the device settings, as a full language tag such as `de-CH` or `zh-Hant-TW`. In 3.x it came from `Locale.getDefault()`, which could be a secondary language, a per-app language or a value your app set with `Locale.setDefault()`, and it dropped the script (`zh-TW`). It's left out when the device reports no language. On older Android versions, 3.x also sent the legacy codes `iw`, `in` and `ji`, so Hebrew, Indonesian and Yiddish values change, such as `in-ID` to `id-ID`. Update filters that match those. Other values mostly stay the same, so otherwise only check filters if your users change these settings. @@ -298,7 +302,7 @@ The SDK reads both languages in the background when an event is captured and use Strings you don't translate fall back per string, so the value is the app's language, not a guarantee for every string. Call `PostHog.setAppLanguage("de")` at startup and whenever the language changes to send it on every version, or if you translate some other way, such as with an in-app language setting. It's kept in memory only. -### Session replay records screenshots +#### Session replay records screenshots 4.0 removes wireframe session replay. Replay always records masked screenshots, which is what `screenshot = true` already did. @@ -326,18 +330,18 @@ A dialog's dim, and a dialog masked whole on Android 8.1 and lower, are sent as The `$sdk_debug_replay_capture_mode` property is now always `screenshot`. -### Deep link query parameters +#### Deep link query parameters The `Deep Link Opened` event leaves out query parameters whose name starts with `$`, such as `$process_person_profile`, so a link can't set PostHog's own properties. Other parameters and the `url` property are sent as in 3.x. -### Other changes that don't fail the build +#### Other changes that don't fail the build The code you end up with after these two migrations compiles, so they're easy to miss: - [`getFeatureFlagResult()` sends `$feature_flag_called` by default](#getfeatureflagpayload), unlike `getFeatureFlagPayload()`. - [Apps that set `remoteConfig = false` now load `/config`](#remoteconfig) and apply its settings. -## Endpoints +### Endpoints | Data | 3.x | 4.0 | | --- | --- | --- | @@ -356,7 +360,7 @@ Analytics requests are gzipped unless you set `compression` to `PostHogCompressi A personal API key (`phx_...`) in `projectToken` now disables the SDK at setup, as an empty or whitespace-only token does. Both print why, even when `debug` is off. To turn the SDK off in tests, use an empty token. In 3.x, the SDK started and PostHog rejected every event with a 401. Use your project token (`phc_...`). -### Hosts without capture v1 +#### Hosts without capture v1 If you self-host PostHog, make sure `/i/v1/analytics/events` is served before you upgrade, and `/i/v1/ai/events` if you use `captureAi`. PostHog Cloud (`us.i.posthog.com`, `eu.i.posthog.com`) serves it. @@ -372,7 +376,7 @@ PostHog's managed reverse proxy already does this and needs no change. A proxy s The SDK doesn't fall back to `/batch`. A 404 is retried, so the events stay queued until the path is served, and the SDK prints one warning, even with `debug` off. Any other error status that isn't retried, such as 403 or 405, drops the events. -### Redirects +#### Redirects The SDK follows a 307 or 308 redirect only to the origin of `host` (same scheme, host and port), at most 5 times, and resends the same body and headers. Any other redirect is not followed and the events are dropped. @@ -380,7 +384,7 @@ In 3.x, OkHttp followed redirects to any host. If a proxy redirects capture requests to another host, point `host` at the final host. This also applies when you set your own `httpClient`: for capture requests, the SDK turns off its redirect following and OkHttp's connection retries, and keeps your other settings. Other requests, such as session replay and logs, behave as in 3.x. -## Event validation +### Event validation Capture v1 checks each event on its own and drops only the invalid ones, so the rest of the batch is delivered. @@ -413,7 +417,7 @@ The distinct ID can come from `identify()`, the `distinctId` argument of `captur If you identify users with a long ID, such as a JWT or a long email address, shorten or hash it before you upgrade. Otherwise every event for that user is dropped. `identify()` with an empty or whitespace-only distinct ID is still ignored, as in 3.x. -## Property precedence +### Property precedence An event's properties are merged in this order, and later values win: @@ -428,7 +432,7 @@ A registered `$session_id` now overrides the SDK's session ID, which can detach A caller `$screen_name` or `$session_id` still replaces the SDK's value even when it's blank, as in 3.x, so a blank `$session_id` is sent as an empty `session_id`. In 3.x, a `$set`, `$set_once` or `$groups` map in properties replaced the per-call values and the groups set with `group()`. A `$set` or `$set_once` you pass, or `userProperties`, still replaces a registered one whole. -## Session and window IDs +### Session and window IDs Capture v1 sends `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, not as properties. The SDK moves them out of `properties` for you. @@ -437,14 +441,14 @@ Any other value is removed and not sent. With `debug` on, the SDK logs the key a A null value counts as unset and is removed without a log. In PostHog, the events still have `$session_id` and `$window_id`, so insights, filters and session replay work as before. -## Timestamps and IDs +### Timestamps and IDs The SDK sends every timestamp in UTC with 3 fractional digits, for example `2026-01-01T00:00:00.000Z`, as 3.x did. It doesn't check for future timestamps. PostHog replaces a timestamp more than 23 hours ahead with the time it received the event. Event uuids and anonymous distinct IDs are UUID v7, as in 3.x. An anonymous ID you change with `getAnonymousId` is sent as you return it. Each capture request also sends a UUID v7 request ID in the `PostHog-Request-Id` header, which 3.x didn't send. -## Event options +### Event options Capture v1 reads processing settings from an `options` object sent next to `properties`. `capture` takes a new `options` argument, and `beforeSend` can read and change `PostHogEvent.options`. @@ -477,7 +481,9 @@ When the event is sent, the SDK removes each one from `properties` and uses it f - An option you pass to any of these methods or set in `beforeSend` wins over its legacy property. An option set to `null` counts as unset, so the legacy property fills it. - To change person processing in `beforeSend`, edit `event.options`. A `$process_person_profile` property the hook adds only fills an option that is still unset, so it doesn't override the `false` the SDK set for an anonymous event. - When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither, because PostHog processes person profiles by default. In 3.x, every event carried a `$process_person_profile` property. To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. A registered `$process_person_profile` changes it for every event. +- This also applies with `personProfiles = PersonProfiles.NEVER`: a `process_person_profile` option or `$process_person_profile` property set to `true`, passed or registered, turns person processing on for that event. In 3.x, `NEVER` always won. If you rely on `NEVER` to keep events personless, make sure neither is set to `true`, or remove it in `beforeSend`. - Review your `beforeSend` hooks for the new event shape. In 3.x, the SDK marked person processing with the `$process_person_profile` property. In 4.0, it's the `process_person_profile` option, and the property isn't set. A hook that assigns a new map to `event.options` without keeping that key loses the `false` the SDK set. That turns person processing on for anonymous users, overriding `personProfiles`. Editing `event.options` in place keeps it. +- `beforeSend` gets its own copy of the event's nested maps, lists and arrays, in `properties` and `options`. Changes a hook makes no longer reach the objects you passed to `capture` or registered, and identity checks against them (`===`) no longer match. In 3.x, hooks edited the caller's objects. - `options` is a property of `PostHogEvent`, not a constructor parameter, so the constructor and `copy` are unchanged from 3.x. When `beforeSend` returns a different event whose `options` is `null`, such as one made with `event.copy(…)` or the constructor, it gets the options of the event the hook was given. To send an event with no options, set `options` to an empty map. - A `$set` sent with `process_person_profile: false` doesn't update the person, so it no longer suppresses a later `setPersonProperties` or `identify` call with the same properties as a duplicate. - The SDK sends option values as given. PostHog reads common forms of a value, such as `"false"` or `0` for a boolean, and drops an event whose option value it can't read. @@ -490,7 +496,7 @@ When the event is sent, the SDK removes each one from `properties` and uses it f - The event `beforeSend` returns keeps the uuid of the capture it came from. A uuid you set in `beforeSend`, for example with `copy(uuid = …)`, is replaced, so a hook that returns an event kept from an earlier call still sends one uuid per capture. - Events still queued on disk by 3.x are sent to capture v1 after the update, with their legacy properties moved to options. -## AI events +### AI events 4.0 adds `captureAi`, which sends AI events, such as `$ai_generation`, to PostHog's AI endpoint (`/i/v1/ai/events`) instead of the analytics endpoint. It takes the same arguments as `capture`, and the events go through the same `beforeSend` hooks. @@ -506,13 +512,13 @@ PostHog.captureAi( - An AI event's properties can be up to 8 MiB. The SDK drops a serialized event over 8 MiB + 64 KiB, measured before `encryption`. With `debug` on, it logs the event name and the limit, never the content. Set `captureAiMaxEventBytes` to lower that limit; a larger value uses 8 MiB + 64 KiB, and with `debug` on the SDK logs that it did. - PostHog drops an event sent with `captureAi` whose name doesn't start with `$ai_`. `capture` never sends events to the AI endpoint, even ones named `$ai_*`. - AI requests time out after 60 seconds without network activity, or `captureAiTimeout`. Other requests keep OkHttp's 10-second defaults. -- AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. -- `flush()` and `close()` also send the AI queue, and AI events left on disk are sent at the next launch. +- On Android, AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Core alone keeps them in memory. Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. +- `flush()` and `close()` also send the AI queue. On Android, AI events left on disk are sent at the next launch. - AI requests are gzipped unless you set `captureAiCompression` to `PostHogCompression.NONE`. `compression` doesn't apply. - AI events use `flushAt`, `maxBatchSize` and `flushIntervalSeconds`, like other events. A request carries up to about 5 MiB, as for analytics events (see [Retries](#retries)). - The SDK sends AI events unchanged. It doesn't redact or truncate prompts, outputs or media, so use `beforeSend` to remove anything you don't want to send. -## Retries +### Retries These apply to analytics and AI event requests, unless a bullet names session replay or logs. Session replay and logs keep their 3.x status handling: they still retry 3xx and don't retry 404. @@ -529,7 +535,7 @@ These apply to analytics and AI event requests, unless a bullet names session re - A 413 still halves the batch until it fits, as in 3.x. An event that gets a 413 on its own is dropped. - `beforeSend` still runs when you capture the event, before it's queued, not when the batch is sent. -## New: `onFeatureFlags()` +### New: `onFeatureFlags()` `onFeatureFlags()` is now the way to listen for flag loads, for example from a screen or a library. You can remove the listener later: @@ -546,7 +552,7 @@ subscription.unsubscribe() On Android, listeners run on the main thread. On the JVM, they run on a background thread. If flags have already loaded, a new listener also gets the current values shortly after it registers. You can register before `setup()`, and listeners stay registered across `close()` and `setup()`. -## `posthog-server` +### `posthog-server` `posthog-server` isn't having a major release, and its API is unchanged: it keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` now ships in `posthog-server` itself. None of the API changes above apply to it. `PostHogEvent`, which `beforeSend` gets, keeps its 3.x constructor and `copy`, and gains an `options` property; `posthog-server` still sends to `/batch`, which doesn't use it, so a value set in `beforeSend` is sent but has no effect. @@ -554,7 +560,7 @@ It still sends events to `/batch`, not to capture v1, so the endpoint, proxy, re A personal API key (`phx_...`) in `projectToken` now disables the client at setup, as an empty token does, and both print why even when `debug` is off. -Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. A `null` element in a list or array in the properties is sent as JSON `null` at its position instead of being removed. +Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. A `null` element in a list or array in the properties is sent as JSON `null` at its position instead of being removed. `beforeSend` gets its own copy of the event's nested maps, lists and arrays, so its changes no longer reach the objects you passed to `capture`. `posthog-server` 2.25.0 depends on core 7.0, so upgrade it and `posthog-android` together: diff --git a/README.md b/README.md index 50f723040..aed9912d9 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ SDK usage examples and code snippets live in the official documentation so they - [Android library docs](https://posthog.com/docs/libraries/android) - [Java/JVM library docs](https://posthog.com/docs/libraries/java) -- [Migrating from 3.x to 4.0](docs/migration-3.x-to-4.0.md) +- [Migrating from 3.x to 4.0](MIGRATION.md) ## Required dependencies From 67ad27b21ee7b565479fca0a03dfb94fd762de15 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Tue, 10 Nov 2026 08:57:44 -0500 Subject: [PATCH 37/49] fix: fill $lib and $lib_version as a pair after every other layer (#956) * fix: fill $lib and $lib_version as a pair after every other layer A registered $lib or $lib_version half now wins over the SDK info, so an event could pair another library's name with this SDK's version. Fill the SDK's own pair last and only where the event doesn't name its library. Co-Authored-By: Claude Opus 5.5 * docs: say standalone PostHogStateless isn't a supported entry point Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/android-v4-major.md | 1 + MIGRATION.md | 8 +++ posthog/src/main/java/com/posthog/PostHog.kt | 12 ++-- .../internal/PostHogLibraryIdentity.kt | 29 +++++++++ .../src/test/java/com/posthog/PostHogTest.kt | 60 +++++++++++++++++++ 5 files changed, 104 insertions(+), 6 deletions(-) create mode 100644 posthog/src/main/java/com/posthog/internal/PostHogLibraryIdentity.kt diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index eeee9c9d5..fafa4214d 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -13,6 +13,7 @@ - **Breaking:** set the `process_person_profile` option to `false` only when person processing is off, instead of adding a `$process_person_profile` property to every event - **Breaking:** let a `process_person_profile` option or `$process_person_profile` property set to `true` turn person processing on for an event even with `PersonProfiles.NEVER` - **Breaking:** let registered super properties override properties the SDK sets, such as `$os_name`, and let super and event properties override `$is_identified`, `$process_person_profile` and the session replay debug properties +- **Breaking:** fill `$lib` and `$lib_version` last and as a pair, only when the event doesn't name its library; a `$lib` you register or pass is sent as it is, without the SDK's version - **Breaking:** let `userProperties`, `userPropertiesSetOnce` and `groups` win key by key over `$set`, `$set_once` and `$groups` maps in the same call's properties, and merge a `$groups` map in properties into the groups set with `group()` - **Breaking:** keep the event's own uuid when `beforeSend` returns an event with another uuid - **Breaking:** disable the SDK at setup when `projectToken` is a personal API key (`phx_...`), as for an empty token, and print a warning for both even when `debug` is off diff --git a/MIGRATION.md b/MIGRATION.md index 97dec6fa5..a45fdb476 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -432,6 +432,12 @@ A registered `$session_id` now overrides the SDK's session ID, which can detach A caller `$screen_name` or `$session_id` still replaces the SDK's value even when it's blank, as in 3.x, so a blank `$session_id` is sent as an empty `session_id`. In 3.x, a `$set`, `$set_once` or `$groups` map in properties replaced the per-call values and the groups set with `group()`. A `$set` or `$set_once` you pass, or `userProperties`, still replaces a registered one whole. +`$lib` and `$lib_version` name the library that produced the event, and the SDK fills them last, as a pair, only where nothing above named the library. +When neither is set, or only `$lib_version` is, the SDK sends its own `$lib` and `$lib_version`. +When `$lib` is the SDK's own name without a version, the SDK adds its version. +When `$lib` names another library, the SDK leaves both as they are and never adds its own version, so set both keys together. +In 3.x, a registered `$lib` or `$lib_version` was replaced by the SDK's, and a `$lib` you passed was sent with the SDK's `$lib_version`. + ### Session and window IDs Capture v1 sends `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, not as properties. @@ -558,6 +564,8 @@ On Android, listeners run on the main thread. On the JVM, they run on a backgrou It still sends events to `/batch`, not to capture v1, so the endpoint, proxy, retry and event option changes above don't apply to it either. +Using core `posthog` on its own through `PostHogStateless.with` isn't a supported entry point in core 7.0. Without its own queue it gets Android's capture v1 behavior, including the persisted-queue retries, which isn't a server-side contract. Use `posthog-server` for server-side JVM apps. + A personal API key (`phx_...`) in `projectToken` now disables the client at setup, as an empty token does, and both print why even when `debug` is off. Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. A `null` element in a list or array in the properties is sent as JSON `null` at its position instead of being removed. `beforeSend` gets its own copy of the event's nested maps, lists and arrays, so its changes no longer reach the objects you passed to `capture`. diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 03dfa8069..70bbe5125 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -38,6 +38,7 @@ import com.posthog.internal.PostHogThreadFactory import com.posthog.internal.captureAiMaxStoredEventBytes import com.posthog.internal.errortracking.PostHogExceptionStepsBuffer import com.posthog.internal.executeSafely +import com.posthog.internal.fillLibraryIdentity import com.posthog.internal.isFalseOptionValue import com.posthog.internal.logIntegrationFailure import com.posthog.internal.personPropertiesContext @@ -889,7 +890,8 @@ public class PostHog private constructor( val props = mutableMapOf() // Values the SDK sets itself. Registered super properties and then the caller's properties - // override them below, and beforeSend has the final say. + // override them below, and beforeSend has the final say. `$lib` and `$lib_version` are the + // exception: they're filled last, as a pair (see fillLibraryIdentity). if (appendSharedProps) { config?.context?.getStaticContext()?.let { props.putAll(it) @@ -930,11 +932,6 @@ public class PostHog private constructor( // `$process_person_profile` wins over it when the send hoists the property. } - // Session replay should have the SDK info as well - config?.context?.getSdkInfo()?.let { - props.putAll(it) - } - val isSessionReplayActive = isSessionReplayActive() // Skip the getter when caller pre-attached an id: getActiveSessionId() can @@ -1006,6 +1003,9 @@ public class PostHog private constructor( props["distinct_id"] = distinctId } + // Last, so it fills only what every layer above left unset. Session replay needs it too. + config?.context?.getSdkInfo()?.let { fillLibraryIdentity(props, it) } + return props } diff --git a/posthog/src/main/java/com/posthog/internal/PostHogLibraryIdentity.kt b/posthog/src/main/java/com/posthog/internal/PostHogLibraryIdentity.kt new file mode 100644 index 000000000..2ef71863b --- /dev/null +++ b/posthog/src/main/java/com/posthog/internal/PostHogLibraryIdentity.kt @@ -0,0 +1,29 @@ +package com.posthog.internal + +private const val LIB = "\$lib" +private const val LIB_VERSION = "\$lib_version" + +/** + * Fills `$lib` and `$lib_version` from [sdkInfo] as a pair, only where the event doesn't already + * name its library, so an event never pairs another library's name with this SDK's version: + * - no `$lib` (or one that isn't a non-empty string): sets both, replacing a lone `$lib_version` + * - `$lib` is this SDK's name and `$lib_version` is unset: sets `$lib_version` + * - otherwise: leaves both as they are + */ +internal fun fillLibraryIdentity( + props: MutableMap, + sdkInfo: Map, +) { + val ownLib = (sdkInfo[LIB] as? String)?.takeIf { it.isNotEmpty() } ?: return + val ownVersion = (sdkInfo[LIB_VERSION] as? String)?.takeIf { it.isNotEmpty() } + val lib = (props[LIB] as? String)?.takeIf { it.isNotEmpty() } + val version = (props[LIB_VERSION] as? String)?.takeIf { it.isNotEmpty() } + + when { + lib == null -> { + props[LIB] = ownLib + if (ownVersion != null) props[LIB_VERSION] = ownVersion else props.remove(LIB_VERSION) + } + lib == ownLib && version == null && ownVersion != null -> props[LIB_VERSION] = ownVersion + } +} diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index 597a7548e..8bc6c6eb1 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -2902,6 +2902,66 @@ internal class PostHogTest { sut.close() } + @Test + fun `fills the SDK library identity as a pair over a registered half`() { + val http = mockHttp() + val url = http.url("/") + val sut = getSut(url.toString(), flushAt = 2, preloadFeatureFlags = false, context = TestPostHogContext()) + + sut.register("\$lib", "custom-wrapper") + sut.capture(EVENT, DISTINCT_ID) + sut.unregister("\$lib") + sut.register("\$lib_version", "orphan-version") + sut.capture(EVENT, DISTINCT_ID) + + queueExecutor.shutdownAndAwaitTermination() + + val batch = serializer.deserialize(http.takeRequest().body.unGzip().reader()) + val identities = batch.batch.map { it.properties!!["\$lib"] to it.properties!!["\$lib_version"] } + assertEquals( + listOf>( + // another library's name never gets this SDK's version + "custom-wrapper" to null, + // a lone version doesn't replace the SDK's own pair + "posthog-android" to "1.2.3", + ), + identities, + ) + + sut.close() + http.shutdown() + } + + @Test + fun `fills the SDK library identity as a pair over a per-call half`() { + val http = mockHttp() + val url = http.url("/") + val sut = getSut(url.toString(), flushAt = 4, preloadFeatureFlags = false, context = TestPostHogContext()) + + sut.capture(EVENT, DISTINCT_ID, mapOf("\$lib" to "custom-wrapper")) + sut.capture(EVENT, DISTINCT_ID, mapOf("\$lib_version" to "orphan-version")) + sut.capture(EVENT, DISTINCT_ID, mapOf("\$lib" to "posthog-android")) + sut.capture(EVENT, DISTINCT_ID, mapOf("\$lib" to "custom-wrapper", "\$lib_version" to "9.9.9")) + + queueExecutor.shutdownAndAwaitTermination() + + val batch = serializer.deserialize(http.takeRequest().body.unGzip().reader()) + val identities = batch.batch.map { it.properties!!["\$lib"] to it.properties!!["\$lib_version"] } + assertEquals( + listOf>( + "custom-wrapper" to null, + "posthog-android" to "1.2.3", + // this SDK's own name only gets the missing version + "posthog-android" to "1.2.3", + "custom-wrapper" to "9.9.9", + ), + identities, + ) + + sut.close() + http.shutdown() + } + @Test fun `setAppLanguage sends the normalized language, survives reset and clears`() { val http = mockHttp() From aaa23d39af4424978bd2439028282e47417490b8 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Tue, 10 Nov 2026 11:32:35 -0500 Subject: [PATCH 38/49] docs: say core 7.0 isn't supported on its own throughout the migration guide The intro, AI queue and onFeatureFlags sections still described using core `posthog` without `posthog-android`, which the posthog-server section says isn't supported. The core changeset now says so too. Claude-Session: https://claude.ai/code/session_019xLynttdFZAHfqTem5BhPQ --- .changeset/android-v4-major.md | 1 + MIGRATION.md | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index fafa4214d..eed8f414c 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -4,6 +4,7 @@ --- - See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/MIGRATION.md) for upgrade steps +- **Breaking:** stop supporting core `posthog` on its own through `PostHogStateless.with`; use it through `posthog-android` or `posthog-server` - **Breaking:** send analytics events to capture v1 (`/i/v1/analytics/events`) with the project token in an `Authorization: Bearer` header, replacing any `Authorization` header in `requestHeaders`; self-hosted instances and reverse proxies must serve the path, and a 404 keeps events queued, retries them and prints one warning even when `debug` is off - **Breaking:** drop events when a capture request gets a non-retryable status (including 3xx), a 2xx without per-event results, or a redirect other than a 307 or 308 to the same origin as `host` (followed at most 5 times); retry 404, 408, 429, 500, 502, 503 and 504 - **Breaking:** cap a `Retry-After` wait at 30 seconds, read it as a minimum wait and accept an HTTP date, and add up to 25% random jitter to the backoff, which still doubles from 1 to 30 seconds, for events, session replay and logs diff --git a/MIGRATION.md b/MIGRATION.md index a45fdb476..83407a48a 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -6,7 +6,7 @@ Most removals are compile errors with a direct replacement. [Behavior changes](#behavior-changes) won't show up at build time. Read the checklist first, then the sections that apply to you. -If you use core `posthog` 7.0 on the JVM without `posthog-android`, the API, endpoint, event and retry changes apply, but these don't: [`$locale` and `$app_language`](#locale-and-app_language), [Session replay records screenshots](#session-replay-records-screenshots), [Deep link query parameters](#deep-link-query-parameters) and the AI events disk queue (core keeps AI events in memory). `onFeatureFlags()` listeners run on a background thread. +Core `posthog` 7.0 is only supported through `posthog-android` 4.0 and `posthog-server`. Using it on its own through `PostHogStateless.with` isn't supported; see [`posthog-server`](#posthog-server). For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/libraries/capture-v1). @@ -518,7 +518,7 @@ PostHog.captureAi( - An AI event's properties can be up to 8 MiB. The SDK drops a serialized event over 8 MiB + 64 KiB, measured before `encryption`. With `debug` on, it logs the event name and the limit, never the content. Set `captureAiMaxEventBytes` to lower that limit; a larger value uses 8 MiB + 64 KiB, and with `debug` on the SDK logs that it did. - PostHog drops an event sent with `captureAi` whose name doesn't start with `$ai_`. `capture` never sends events to the AI endpoint, even ones named `$ai_*`. - AI requests time out after 60 seconds without network activity, or `captureAiTimeout`. Other requests keep OkHttp's 10-second defaults. -- On Android, AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Core alone keeps them in memory. Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. +- On Android, AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. - `flush()` and `close()` also send the AI queue. On Android, AI events left on disk are sent at the next launch. - AI requests are gzipped unless you set `captureAiCompression` to `PostHogCompression.NONE`. `compression` doesn't apply. - AI events use `flushAt`, `maxBatchSize` and `flushIntervalSeconds`, like other events. A request carries up to about 5 MiB, as for analytics events (see [Retries](#retries)). @@ -556,7 +556,7 @@ val subscription = PostHog.onFeatureFlags { loaded -> subscription.unsubscribe() ``` -On Android, listeners run on the main thread. On the JVM, they run on a background thread. If flags have already loaded, a new listener also gets the current values shortly after it registers. You can register before `setup()`, and listeners stay registered across `close()` and `setup()`. +On Android, listeners run on the main thread. If flags have already loaded, a new listener also gets the current values shortly after it registers. You can register before `setup()`, and listeners stay registered across `close()` and `setup()`. ### `posthog-server` From 5f161b831b48d3db0799f7d4c4d86171415ce679 Mon Sep 17 00:00:00 2001 From: Eli Reisman Date: Tue, 10 Nov 2026 17:10:36 -0800 Subject: [PATCH 39/49] docs: show how to keep identity calls under a registered personless setting (#966) * docs: show how to keep identity calls under a registered personless setting Co-Authored-By: Claude Opus 5.5 * docs: point registered personless users to identifiedOnly and note billing --------- Co-authored-by: Claude Opus 5.5 Co-authored-by: Anna Garcia --- MIGRATION.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 83407a48a..67ace54c0 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -26,6 +26,7 @@ You need to change code if your app does any of these: - sets `projectToken` to a personal API key (`phx_...`) - reads `$session_id` or `$window_id` from the raw request body, for example in a proxy - sets `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` or `$product_tour_id` to a value PostHog can't read, such as `"maybe"` +- registers `$process_person_profile` as `false` and still calls `identify`, `alias`, `group` or `setPersonProperties` (see [Event options](#event-options)) - registers a super property, or passes an event property, with the same key as one the SDK sets, such as `$os_name` or `$is_identified`, and expects the SDK's value to win - calls `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` or `captureException` from Java, implements `PostHogInterface`, or calls `identify` through a `PostHogCoreInterface` reference - sets the event `uuid` in `beforeSend` @@ -486,7 +487,7 @@ When the event is sent, the SDK removes each one from `properties` and uses it f - An option you pass to any of these methods or set in `beforeSend` wins over its legacy property. An option set to `null` counts as unset, so the legacy property fills it. - To change person processing in `beforeSend`, edit `event.options`. A `$process_person_profile` property the hook adds only fills an option that is still unset, so it doesn't override the `false` the SDK set for an anonymous event. -- When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither, because PostHog processes person profiles by default. In 3.x, every event carried a `$process_person_profile` property. To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. A registered `$process_person_profile` changes it for every event. +- When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither, because PostHog processes person profiles by default. In 3.x, every event carried a `$process_person_profile` property. To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. A registered `$process_person_profile` changes it for every event. In 3.x, the SDK's value replaced a registered `$process_person_profile`, so a registered `false` had no effect. In 4.0 it applies, also after `identify` and with `PersonProfiles.ALWAYS`: those events don't change the person profile, and their `$set` is ignored. They are still linked to the person and billed as identified events. - This also applies with `personProfiles = PersonProfiles.NEVER`: a `process_person_profile` option or `$process_person_profile` property set to `true`, passed or registered, turns person processing on for that event. In 3.x, `NEVER` always won. If you rely on `NEVER` to keep events personless, make sure neither is set to `true`, or remove it in `beforeSend`. - Review your `beforeSend` hooks for the new event shape. In 3.x, the SDK marked person processing with the `$process_person_profile` property. In 4.0, it's the `process_person_profile` option, and the property isn't set. A hook that assigns a new map to `event.options` without keeping that key loses the `false` the SDK set. That turns person processing on for anonymous users, overriding `personProfiles`. Editing `event.options` in place keeps it. - `beforeSend` gets its own copy of the event's nested maps, lists and arrays, in `properties` and `options`. Changes a hook makes no longer reach the objects you passed to `capture` or registered, and identity checks against them (`===`) no longer match. In 3.x, hooks edited the caller's objects. @@ -494,10 +495,22 @@ When the event is sent, the SDK removes each one from `properties` and uses it f - A `$set` sent with `process_person_profile: false` doesn't update the person, so it no longer suppresses a later `setPersonProperties` or `identify` call with the same properties as a duplicate. - The SDK sends option values as given. PostHog reads common forms of a value, such as `"false"` or `0` for a boolean, and drops an event whose option value it can't read. - Other option keys are sent unchanged, and PostHog ignores keys it doesn't know. -- There are no global or context options. To set an option on every event, register its legacy property, for example `register("\$process_person_profile", false)`. +- There are no global or context options. To set an option on every event, register its legacy property, for example `register("\$cookieless_mode", true)`. - There's no setting for GeoIP lookup or `historical_migration` on events, as in 3.x. - With `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, `identify`, `alias`, `group` and `setPersonProperties` still turn on person processing for the user's later events, as in 3.x. -- A registered option also reaches `$identify`, `$create_alias` and `$groupidentify`. If it turns person processing off, for example `register("\$process_person_profile", false)`, PostHog accepts those events and then drops them with an ingestion warning, and the SDK doesn't report it. +- A registered `$process_person_profile` set to `false` also reaches the events `identify`, `alias`, `group` and `setPersonProperties` send. PostHog accepts `$identify`, `$create_alias` and `$groupidentify` and then drops them with an ingestion warning, and the SDK doesn't report it. A `$set` event is kept, but the person isn't updated. To keep identifying, pass the option on the call, or set it in `beforeSend`: + + ```kotlin + PostHog.register("\$process_person_profile", false) + + PostHog.identify( + distinctId = "user-123", + userProperties = mapOf("plan" to "pro"), + options = mapOf("process_person_profile" to true), + ) + ``` + + If you registered `false` to skip person profiles for anonymous users, remove it: `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, the default, already does that and still lets `identify` create the person. To create no person profiles at all, set `personProfiles = PersonProfiles.NEVER` instead. The SDK then skips these calls. - An empty or whitespace-only `distinctId` argument to `capture` now uses the current distinct ID, like `null`. In 3.x, the event was dropped. - The event `beforeSend` returns keeps the uuid of the capture it came from. A uuid you set in `beforeSend`, for example with `copy(uuid = …)`, is replaced, so a hook that returns an event kept from an earlier call still sends one uuid per capture. - Events still queued on disk by 3.x are sent to capture v1 after the update, with their legacy properties moved to options. From 358f9fe6245bffc09c226875098b02a04c74673e Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 12 Nov 2026 09:11:23 -0500 Subject: [PATCH 40/49] fix: skip the person-properties hash for maybe-personless updates (#965) * fix: skip the person-properties hash for maybe-personless updates A process_person_profile value capture can't read as false, such as "maybe" or "true", counted as person-processed, so the $set stored and matched the dedupe hash. PostHog may drop or not apply that update, so the same properties sent later were dropped as a duplicate. Mirror posthog-ios #1050: only a missing setting or a Boolean true uses the hash, and an update PostHog might apply clears it. A setting capture reads as false still leaves the hash as it is. Claude-Session: https://claude.ai/code/session_019xLynttdFZAHfqTem5BhPQ * fix: clear the person-properties hash for every update that may be personless Match posthog-ios #1050: only a missing process_person_profile or a Boolean true checks and records the hash. Any other value, including a definite false, is sent and clears the stored hash, so the SDK no longer depends on parsing false spellings the way the server does. Claude-Session: https://claude.ai/code/session_019xLynttdFZAHfqTem5BhPQ --- posthog/src/main/java/com/posthog/PostHog.kt | 55 ++++++++++++++----- .../com/posthog/PostHogCaptureOptionsTest.kt | 10 ++-- 2 files changed, 45 insertions(+), 20 deletions(-) diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 8e246d82f..87a9fa504 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -39,7 +39,6 @@ import com.posthog.internal.captureAiMaxStoredEventBytes import com.posthog.internal.errortracking.PostHogExceptionStepsBuffer import com.posthog.internal.executeSafely import com.posthog.internal.fillLibraryIdentity -import com.posthog.internal.isFalseOptionValue import com.posthog.internal.logIntegrationFailure import com.posthog.internal.personPropertiesContext import com.posthog.internal.replay.PostHogSessionReplayHandler @@ -1145,10 +1144,10 @@ public class PostHog private constructor( } /** - * Whether a `$set` sent with [options] updates the person. A personless one doesn't, so it - * neither stores nor matches the person-properties hash. + * Whether a `$set` sent with [options] surely updates the person: the setting is missing or a + * Boolean `true`. Any other value, including a false one, might not, so it never records a hash. */ - private fun isPersonProcessed(options: Map?): Boolean { + private fun surelyProcessesPersonProfile(options: Map?): Boolean { // An explicit null in [options] replaces the registered option, as in optionsForEvent. val option = if (options?.containsKey("process_person_profile") == true) { @@ -1156,10 +1155,8 @@ public class PostHog private constructor( } else { getRegisteredOptions()["process_person_profile"] } - if (option != null) { - return !isFalseOptionValue(option) - } - return !isFalseOptionValue(getPreferences().getValue("\$process_person_profile")) + val value = option ?: getPreferences().getValue("\$process_person_profile") + return value == null || value == true } /** @@ -2336,10 +2333,17 @@ public class PostHog private constructor( // The transition event must fire even when an identical property call was cached // earlier; cache only after capture so deduplication cannot suppress it. - if (isPersonProcessed(options)) { - synchronized(cachedPersonPropertiesLock) { - cachedPersonPropertiesHash = getPersonPropertiesHash(distinctId, userProperties, userPropertiesSetOnce) + val hash = + if (surelyProcessesPersonProfile( + options, + ) + ) { + getPersonPropertiesHash(distinctId, userProperties, userPropertiesSetOnce) + } else { + null } + synchronized(cachedPersonPropertiesLock) { + cachedPersonPropertiesHash = hash } // The identified state itself is not part of the flags request; reload only when the @@ -2348,11 +2352,11 @@ public class PostHog private constructor( reloadFeatureFlags() } } else if (!hasDifferentDistinctId && (userProperties?.isNotEmpty() == true || userPropertiesSetOnce?.isNotEmpty() == true)) { - if (!isPersonProcessed(options) || - shouldCapturePersonPropertiesEvent( + if (shouldCapturePersonPropertiesUpdate( distinctId, userProperties, userPropertiesSetOnce, + options, "A duplicate identify call was made with the same properties. The \$set event has been ignored.", ) ) { @@ -2389,11 +2393,11 @@ public class PostHog private constructor( val currentDistinctId = this.distinctId - if (isPersonProcessed(options) && - !shouldCapturePersonPropertiesEvent( + if (!shouldCapturePersonPropertiesUpdate( currentDistinctId, userPropertiesToSet, userPropertiesToSetOnce, + options, "A duplicate setPersonProperties call was made with the same properties. It has been ignored.", ) ) { @@ -2442,6 +2446,27 @@ public class PostHog private constructor( return config?.serializer?.serializeObject(hashData) ?: hashData.toString() } + /** + * Whether to capture a person properties update sent with [options]. One that surely updates the + * person is skipped when it repeats the last one. Any other one is sent and clears the hash, so a + * later update back to the previous properties is sent too. + */ + private fun shouldCapturePersonPropertiesUpdate( + distinctId: String, + userPropertiesToSet: Map?, + userPropertiesToSetOnce: Map?, + options: Map?, + duplicateLogMessage: String, + ): Boolean { + if (surelyProcessesPersonProfile(options)) { + return shouldCapturePersonPropertiesEvent(distinctId, userPropertiesToSet, userPropertiesToSetOnce, duplicateLogMessage) + } + synchronized(cachedPersonPropertiesLock) { + cachedPersonPropertiesHash = null + } + return true + } + /** * Checks if person properties have changed by comparing hash values. * Updates the cached hash if different and returns true if the event should be captured. diff --git a/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt b/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt index 35e68f521..0d6a32aad 100644 --- a/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt @@ -359,22 +359,22 @@ internal class PostHogCaptureOptionsTest { sut.setPersonProperties(userProps, options = personless) sut.setPersonProperties(userProps) - // only the second processed call is a duplicate - assertEquals(3, captured.count { it.event == PostHogEventName.SET.event }) + assertEquals(4, captured.count { it.event == PostHogEventName.SET.event }) sut.close() } @Test - fun `a set with a false value capture reads leniently is personless too`() { - for (value in listOf("false", " Off ", 0, "0.0")) { + fun `a set that may be personless neither matches nor keeps the person properties hash`() { + for (value in listOf(false, "false", " Off ", 0, "0.0", "maybe", "true", 1)) { val sut = getSut() sut.identify("user_id") captured.clear() + sut.setPersonProperties(userProps) sut.setPersonProperties(userProps, options = mapOf("process_person_profile" to value)) sut.setPersonProperties(userProps) - assertEquals(2, captured.count { it.event == PostHogEventName.SET.event }, "for $value") + assertEquals(3, captured.count { it.event == PostHogEventName.SET.event }, "for $value") sut.close() } } From 3ed80dbc9b9001f8c4074156325cb1b76c59d2d4 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Thu, 12 Nov 2026 11:11:41 -0500 Subject: [PATCH 41/49] docs: fix capture v1 link and cover PostHogStateless subclasses in the migration guide Capture v1 moved to /docs/api/capture-v1 (posthog.com#21385). --- MIGRATION.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 67ace54c0..2cb00671d 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -8,7 +8,7 @@ Read the checklist first, then the sections that apply to you. Core `posthog` 7.0 is only supported through `posthog-android` 4.0 and `posthog-server`. Using it on its own through `PostHogStateless.with` isn't supported; see [`posthog-server`](#posthog-server). -For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/libraries/capture-v1). +For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/api/capture-v1). For the full list of 4.0 changes, see the [changelog](https://github.com/PostHog/posthog-android/blob/main/posthog-android/CHANGELOG.md). @@ -577,7 +577,7 @@ On Android, listeners run on the main thread. If flags have already loaded, a ne It still sends events to `/batch`, not to capture v1, so the endpoint, proxy, retry and event option changes above don't apply to it either. -Using core `posthog` on its own through `PostHogStateless.with` isn't a supported entry point in core 7.0. Without its own queue it gets Android's capture v1 behavior, including the persisted-queue retries, which isn't a server-side contract. Use `posthog-server` for server-side JVM apps. +Using core `posthog` on its own through `PostHogStateless.with` isn't a supported entry point in core 7.0. Without its own queue it gets Android's capture v1 behavior, including the persisted-queue retries, which isn't a server-side contract. Use `posthog-server` for server-side JVM apps. A class that extends `PostHogStateless` also needs updating: the protected `buildEvent()` gained `options` and `uuid` parameters, and `captureFeatureFlagCalledEvent()` is no longer protected. A personal API key (`phx_...`) in `projectToken` now disables the client at setup, as an empty token does, and both print why even when `debug` is off. From e5fe7a4d3f2208d2230e0807f39425a624614fa3 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 12 Nov 2026 14:17:18 -0500 Subject: [PATCH 42/49] fix: align posthog-android to core's major with a Gradle constraint (#974) posthog-android 3.x calls core APIs that 7.0 removes, so an app that pins core 7.x next to posthog-android 3.x crashes with NoSuchMethodError when it builds PostHogAndroidConfig. Publish a constraint from core to posthog-android at the matching major so Gradle upgrades posthog-android instead. Co-authored-by: Claude Opus 5.5 --- .changeset/android-v4-major.md | 1 + posthog/build.gradle.kts | 10 ++++++++++ 2 files changed, 11 insertions(+) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index eed8f414c..e159e8d76 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -39,6 +39,7 @@ - Add internal APIs so wrapper SDKs can run their own `beforeSend` on the fully built event - Add internal APIs so wrapper SDKs can register capture options sent with every event - Send events queued on disk by 3.x through capture v1 after the update +- Upgrade `posthog-android` to 4.0 when an app pins core `posthog` 7.x next to `posthog-android` 3.x, which would otherwise crash with `NoSuchMethodError` (Gradle builds only) - Send a `PostHog-Request-Id` header with each capture request, which reverse proxies must pass through - Cap a capture request at about 5 MiB of events and send as soon as that much is queued - Use the current distinct ID when the `distinctId` argument to `capture` is empty or whitespace-only, instead of dropping the event diff --git a/posthog/build.gradle.kts b/posthog/build.gradle.kts index 651a4d11f..744a6f79c 100644 --- a/posthog/build.gradle.kts +++ b/posthog/build.gradle.kts @@ -109,6 +109,16 @@ dependencies { implementation("com.squareup.okhttp3:okhttp") // Fixes DeflaterSink buffer reuse under JNI array copying: https://github.com/square/okio/issues/1608 implementation("com.squareup.okio:okio:${PosthogBuildConfig.Dependencies.OKIO}") + + // An app that pins this core next to an older posthog-android major crashes at runtime with + // NoSuchMethodError, since that posthog-android calls core APIs this major removed. The constraint + // only applies when posthog-android is already in the graph, and raises it to the matching major. + constraints { + val androidMajor = properties["androidVersion"].toString().substringBefore(".") + api("com.posthog:posthog-android:$androidMajor.0.0") { + because("posthog-android must match the major of the core posthog artifact") + } + } compileOnly("org.codehaus.mojo:animal-sniffer-annotations:${PosthogBuildConfig.Plugins.ANIMAL_SNIFFER_SDK_ANNOTATION}") // compatibility From 6c88c132595304f5a6db36bca6df6ff9ceffe0e9 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Thu, 12 Nov 2026 15:11:32 -0500 Subject: [PATCH 43/49] fix: release review follow-ups for posthog-android 4.0 (#976) * docs: publish MIGRATION.md as the SDK's migration guide page The reference generator read docs/migration-*.md, which the 4.0 branch no longer has since the guide moved to MIGRATION.md, so a release kept the old generated page. That page now becomes the Android migration guide on posthog.com, so read MIGRATION.md and regenerate it. Co-Authored-By: Claude Opus 5.5 * docs: say Gradle upgrades posthog-android 3.x to 4.0 next to core 7.0 Since the core-to-android constraint, core 7.0 or posthog-server 2.25 next to posthog-android 3.x resolves posthog-android 4.0 instead of failing at runtime. Co-Authored-By: Claude Opus 5.5 * test: queue events in the personless hash tests and fix a Retry-After flake The two personless dedup tests dropped every event in beforeSend, so no hash was ever stored and they passed with personless detection switched off. They now queue events to a mock server, and fail under that mutation. The HTTP-date Retry-After test compared against the real clock, so it read 19 instead of 20 when the request crossed a second boundary. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/server-keep-on-feature-flags.md | 2 +- MIGRATION.md | 4 +- bin/docs_scripts/generate_markdown.py | 13 +- .../com/posthog/PostHogCaptureOptionsTest.kt | 17 ++- .../posthog/internal/PostHogCaptureV1Test.kt | 5 +- references/posthog-android-migration.md | 119 +++++++++++------- 6 files changed, 104 insertions(+), 56 deletions(-) diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md index 5fe35962f..40be12bef 100644 --- a/.changeset/server-keep-on-feature-flags.md +++ b/.changeset/server-keep-on-feature-flags.md @@ -2,7 +2,7 @@ 'posthog-server': minor --- -- Require `posthog-android` 4.0 in the same project, since core 7.0 fails at runtime with `posthog-android` 3.x; stay on 2.24.x until you upgrade (see the [migration guide](https://github.com/PostHog/posthog-android/blob/main/MIGRATION.md#posthog-server)) +- Require `posthog-android` 4.0 in the same project, since core 7.0 makes Gradle upgrade `posthog-android` 3.x to 4.0; stay on 2.24.x until you upgrade (see the [migration guide](https://github.com/PostHog/posthog-android/blob/main/MIGRATION.md#posthog-server)) - Bump the `posthog` core dependency to 7.0; `posthog-server` keeps its API, `/batch` endpoint and retry behavior - Move `PostHogOnFeatureFlags` into `posthog-server` with the same name and API - Add an `options` property to `PostHogEvent`, which `beforeSend` can read; `posthog-server` still sends to `/batch`, which doesn't use it, so setting it in `beforeSend` has no effect diff --git a/MIGRATION.md b/MIGRATION.md index 2cb00671d..f8b7a9b25 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -59,7 +59,7 @@ These are unchanged, so you don't need to change your build for them: - Kotlin language and API compatibility: 2.0 - `posthog-android-gradle-plugin` -Upgrade PostHog artifacts together. Core 7.0 is not binary compatible with SDK versions built against core 6.x, except `posthog-android-surveys-compose`, which works with both. A mismatch fails at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. +Upgrade PostHog artifacts together. Core 7.0 is not binary compatible with SDK versions built against core 6.x, except `posthog-android-surveys-compose`, which works with both. When core 7.0 is in a Gradle build, for example through `posthog-server` 2.25, Gradle upgrades `posthog-android` to 4.0, even over a range such as `[3.75.0,4.0.0)`, so code that still uses removed APIs fails to compile. Other mismatches fail at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. ### Removed APIs @@ -586,4 +586,4 @@ Events with an empty name are dropped before sending. `userProperties`, `userPro `posthog-server` 2.25.0 depends on core 7.0, so upgrade it and `posthog-android` together: - If your project uses `posthog-android` 4.0 or core 7.0, use `posthog-server` 2.25.0 or later. Older `posthog-server` versions aren't compatible with core 7.0 at runtime. -- If your project still uses `posthog-android` 3.x, stay on `posthog-server` 2.24.x. Gradle resolves core 7.0 for both, and `posthog-android` 3.x fails at runtime against it with errors such as `NoSuchMethodError`. +- If your project still uses `posthog-android` 3.x, stay on `posthog-server` 2.24.x. `posthog-server` 2.25 brings in core 7.0, and Gradle then upgrades `posthog-android` to 4.0. diff --git a/bin/docs_scripts/generate_markdown.py b/bin/docs_scripts/generate_markdown.py index fb9067f06..d95ba8026 100644 --- a/bin/docs_scripts/generate_markdown.py +++ b/bin/docs_scripts/generate_markdown.py @@ -251,9 +251,16 @@ def main() -> None: write(f"posthog-android-{major}.md", [front_matter(title, body), *body]) if not opts.experimental: write("posthog-android-reference.md", [front_matter("PostHog Android SDK", body), *body]) - if guides := sorted((ROOT / "docs").glob("migration-*.md"), reverse=True): - head = "---\ntitle: PostHog Android SDK migration guides\nsidebar: Docs\nshowTitle: true\n---" - write("posthog-android-migration.md", [head, *(g.read_text().strip() for g in guides)]) + write_migration() + + +def write_migration() -> None: + """Writes MIGRATION.md as the migration guides page, without its title, which the front matter replaces.""" + guide = (ROOT / "MIGRATION.md").read_text().strip() + if guide.startswith("# "): + guide = guide.split("\n", 1)[1].strip() + head = "---\ntitle: PostHog Android SDK migration guides\nsidebar: Docs\nshowTitle: true\n---" + write("posthog-android-migration.md", [head, guide]) if __name__ == "__main__": diff --git a/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt b/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt index 0d6a32aad..e6c9d0eed 100644 --- a/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogCaptureOptionsTest.kt @@ -68,6 +68,19 @@ internal class PostHogCaptureOptionsTest { ) } + // The person properties hash is only stored once an event is queued, so dedup tests need + // beforeSend to keep events. + private fun getQueueingSut(): PostHogInterface { + val http = httpServers.mockHttp(total = 10) + return getSut( + http.url("/").toString(), + beforeSend = { event -> + captured.add(event) + event + }, + ) + } + @AfterTest fun `set down`() { tmpDir.root.deleteRecursively() @@ -350,7 +363,7 @@ internal class PostHogCaptureOptionsTest { @Test fun `a personless set neither stores nor matches the person properties hash`() { val personless = mapOf("process_person_profile" to false) - val sut = getSut() + val sut = getQueueingSut() sut.identify("user_id") captured.clear() @@ -366,7 +379,7 @@ internal class PostHogCaptureOptionsTest { @Test fun `a set that may be personless neither matches nor keeps the person properties hash`() { for (value in listOf(false, "false", " Off ", 0, "0.0", "maybe", "true", 1)) { - val sut = getSut() + val sut = getQueueingSut() sut.identify("user_id") captured.clear() diff --git a/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt b/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt index 7a3941195..03c4c4b26 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogCaptureV1Test.kt @@ -661,12 +661,13 @@ internal class PostHogCaptureV1Test { fun `reads an HTTP-date Retry-After as seconds from now`() { val format = SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss 'GMT'", Locale.US).apply { timeZone = TimeZone.getTimeZone("GMT") } val now = clock.currentTimeMillis() - for ((date, seconds) in listOf(Date(now + 20_000) to 20, Date(now - 60_000) to 0)) { + // The clock is real and an HTTP-date has no milliseconds, so a future date can read one second short. + for ((date, seconds) in listOf(Date(now + 20_000) to 19..20, Date(now - 60_000) to 0..0)) { val http = httpServers.mockHttp(response = MockResponse().setResponseCode(503).setHeader("Retry-After", format.format(date))) val error = assertThrows(PostHogApiError::class.java) { api(http.url("/").toString()).captureV1(listOf(event())) } - assertEquals(seconds, error.retryAfterSeconds) + assertTrue(error.retryAfterSeconds in seconds, "${error.retryAfterSeconds} not in $seconds") } } diff --git a/references/posthog-android-migration.md b/references/posthog-android-migration.md index ebf6ac320..15c781ceb 100644 --- a/references/posthog-android-migration.md +++ b/references/posthog-android-migration.md @@ -4,17 +4,19 @@ sidebar: Docs showTitle: true --- -# Migrating from PostHog Android 3.x to 4.0 +## posthog-android 3.x → 4.0 and posthog (core) 7.0 4.0 sends analytics events to capture v1 (`/i/v1/analytics/events`) instead of `/batch`, removes APIs deprecated in 3.x and changes the feature flags callback. Most removals are compile errors with a direct replacement. [Behavior changes](#behavior-changes) won't show up at build time. Read the checklist first, then the sections that apply to you. -For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/libraries/capture-v1). +Core `posthog` 7.0 is only supported through `posthog-android` 4.0 and `posthog-server`. Using it on its own through `PostHogStateless.with` isn't supported; see [`posthog-server`](#posthog-server). + +For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/api/capture-v1). For the full list of 4.0 changes, see the [changelog](https://github.com/PostHog/posthog-android/blob/main/posthog-android/CHANGELOG.md). -## Checklist +### Checklist You need to change code if your app does any of these: @@ -28,6 +30,7 @@ You need to change code if your app does any of these: - sets `projectToken` to a personal API key (`phx_...`) - reads `$session_id` or `$window_id` from the raw request body, for example in a proxy - sets `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` or `$product_tour_id` to a value PostHog can't read, such as `"maybe"` +- registers `$process_person_profile` as `false` and still calls `identify`, `alias`, `group` or `setPersonProperties` (see [Event options](#event-options)) - registers a super property, or passes an event property, with the same key as one the SDK sets, such as `$os_name` or `$is_identified`, and expects the SDK's value to win - calls `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` or `captureException` from Java, implements `PostHogInterface`, or calls `identify` through a `PostHogCoreInterface` reference - sets the event `uuid` in `beforeSend` @@ -44,7 +47,7 @@ You need to change code if your app does any of these: - reads event content or request bodies from the SDK's debug log, or matches its log text - depends only on `posthog-android-surveys-compose`, or uses `posthog-server` (2.25.0 and later need `posthog-android` 4.0 in the same project) -## Requirements and versions +### Requirements and versions | Artifact | Upgrade | | --- | --- | @@ -60,9 +63,9 @@ These are unchanged, so you don't need to change your build for them: - Kotlin language and API compatibility: 2.0 - `posthog-android-gradle-plugin` -Upgrade PostHog artifacts together. Core 7.0 is not binary compatible with SDK versions built against core 6.x, except `posthog-android-surveys-compose`, which works with both. A mismatch fails at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. +Upgrade PostHog artifacts together. Core 7.0 is not binary compatible with SDK versions built against core 6.x, except `posthog-android-surveys-compose`, which works with both. When core 7.0 is in a Gradle build, for example through `posthog-server` 2.25, Gradle upgrades `posthog-android` to 4.0, even over a range such as `[3.75.0,4.0.0)`, so code that still uses removed APIs fails to compile. Other mismatches fail at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. -## Removed APIs +### Removed APIs All of these are compile errors. Calling them from an already-compiled library that you haven't updated fails at runtime. @@ -82,7 +85,7 @@ All of these are compile errors. Calling them from an already-compiled library t The constructor parameters of `PostHogConfig` and `PostHogSessionReplayConfig` move up where these were removed. If you pass arguments by position, check them, or switch to named arguments. -### `apiKey` +#### `apiKey` ```kotlin // 3.x @@ -96,7 +99,7 @@ val token = config.projectToken `PostHogAndroidConfig("phc_your_project_token")`, with no parameter name, still works. From Java, replace `getApiKey()` with `getProjectToken()`. -### `propertiesSanitizer` +#### `propertiesSanitizer` ```kotlin // 3.x @@ -113,7 +116,7 @@ config.addBeforeSend { event -> `addBeforeSend` gets the whole `PostHogEvent`. Return `null` to drop the event. If the hook throws, the event is dropped. -### `evaluationEnvironments` +#### `evaluationEnvironments` ```kotlin // 3.x @@ -123,7 +126,7 @@ config.evaluationEnvironments = listOf("production") config.evaluationContexts = listOf("production") ``` -### `getFeatureFlagPayload()` +#### `getFeatureFlagPayload()` `getFeatureFlagPayload()` never sent `$feature_flag_called`. `getFeatureFlagResult()` sends it by default, following `sendFeatureFlagEvent`, so pass `sendFeatureFlagEvent = false` to keep your event volume and experiment exposures unchanged. If you drop that argument, nothing fails, but you'll send new events. @@ -137,7 +140,7 @@ val payload = PostHog.getFeatureFlagPayload("checkout", defaultValue = "fallback val payload = PostHog.getFeatureFlagResult("checkout", sendFeatureFlagEvent = false)?.payload ?: "fallback" ``` -### `getFeatureFlag()` default value +#### `getFeatureFlag()` default value ```kotlin // 3.x @@ -155,7 +158,7 @@ The second parameter is now `sendFeatureFlagEvent`, which affects code that stil Classes that implement `PostHogInterface` update the signature. -### `debouncerDelayMs` +#### `debouncerDelayMs` ```kotlin // 3.x @@ -165,7 +168,7 @@ PostHogSessionReplayConfig(debouncerDelayMs = 500) PostHogSessionReplayConfig(throttleDelayMs = 500) ``` -### `remoteConfig` +#### `remoteConfig` Delete the option. Apps that left it at its default of `true` see no behavior change. @@ -182,9 +185,9 @@ If you set it to `false`, your app's behavior changes: - The settings in `/config` now apply, including the session replay, surveys, error tracking and push settings from your project. - With `preloadFeatureFlags = true`, the SDK requests `/flags` only if `/config` reports that the project has feature flags. In 3.x it always requested `/flags`. If the project has none, the cached flags are cleared. -## Feature flags callback +### Feature flags callback -`PostHogConfig.onFeatureFlags` is removed. Call `PostHog.onFeatureFlags()` before `setup()` instead, which also covers the first load. `reloadFeatureFlags()` now takes a `PostHogFeatureFlagsCallback`. Both callbacks receive a `PostHogFeatureFlagsLoaded`: +`PostHogConfig.onFeatureFlags` is removed. Call `PostHog.onFeatureFlags()` before `setup()` instead, which also covers the first load. An instance from `PostHogAndroid.with()` is set up as it's created, so call `onFeatureFlags()` on it right after `with()`; if flags have already loaded, the listener gets the current values shortly after it registers. `reloadFeatureFlags()` now takes a `PostHogFeatureFlagsCallback`. Both callbacks receive a `PostHogFeatureFlagsLoaded`: - `flags`: the keys of the enabled flags - `variants`: their values, either `true` or the variant string @@ -226,7 +229,7 @@ A Kotlin trailing lambda such as `PostHog.reloadFeatureFlags { refreshUi() }` co The `reloadFeatureFlags()` callback still runs on a background thread, or right away on the calling thread when no load is attempted, so switch to the main thread before touching UI. -## `PostHogInterface` implementations +### `PostHogInterface` implementations `PostHogInterface` lost `getFeatureFlagPayload()`, gained the abstract `onFeatureFlags()` and `setAppLanguage()`, and changed the callback type of `reloadFeatureFlags()`. Classes that implement it, such as hand-written fakes for tests, no longer compile until they're updated. They also add the `options` parameter and `captureAi()` (see [Event options](#event-options) and [AI events](#ai-events)). @@ -243,7 +246,7 @@ class FakePostHog : PostHogInterface { `PostHogFeatureFlagsSubscription` and `PostHogFeatureFlagsLoaded` have constructors marked `@PostHogInternal`, which aren't intended for app code, so create them with a mocking library. -## Internal APIs +### Internal APIs These helpers were public only by accident and were marked `@PostHogInternal`. They're no longer visible outside the SDK and have no replacement. Apps that don't use `@PostHogInternal` APIs aren't affected. @@ -256,9 +259,9 @@ These helpers were public only by accident and were marked `@PostHogInternal`. T If you call `PostHogRemoteConfig.loadFeatureFlags()` or `loadRemoteConfig()`, their callback parameters changed too. The internal callback is now `(errorsLoading: Boolean) -> Unit`, and the other is a `PostHogFeatureFlagsCallback`. -## Behavior changes +### Behavior changes -### Feature flag payloads must be valid JSON +#### Feature flag payloads must be valid JSON A payload that isn't valid JSON now reads as `null` from `getFeatureFlagResult(key)?.payload` and `getAllFeatureFlags()`, instead of the raw string. With `debug` on, the SDK logs the flag key. @@ -276,19 +279,19 @@ If you read a payload as plain text, such as a payload saved as `hello` rather t Apps upgrading from 3.13 or older didn't cache flag details, so until the app's first `/flags` response, a malformed payload cached by 3.x still reads as the raw string, as it did in 3.x. -### Empty variants read as disabled +#### Empty variants read as disabled A flag whose variant is an empty string now reads as disabled everywhere, as it already did from `isFeatureEnabled()`, with or without `defaultValue`. `getFeatureFlagResult()` and `getAllFeatureFlags()` return `enabled = false` for it, where 3.x returned `true`, `PostHogFeatureFlagsLoaded` leaves it out of `flags` and `variants`, and captured events leave it out of `$active_feature_flags`. `variant`, `getFeatureFlag()` and the event's `$feature/` property still return `""`. -PostHog no longer accepts an empty variant for new flags, so only flags created earlier through the API, MCP or Terraform are affected. +PostHog no longer accepts empty variants for new flags, so only flags created earlier through the API, MCP or Terraform are affected. `/flags` still returns `enabled: true` for them, and other PostHog SDKs can still report them as enabled, so rename the variant before you upgrade. -### `$feature_flag_response` for a missing flag +#### `$feature_flag_response` for a missing flag When a flag is missing, `$feature_flag_called` now leaves out `$feature_flag_response`. 3.x sent `""` from `getFeatureFlag()` and `false` from `isFeatureEnabled()`, or your default value when you passed one. In 4.0 an empty string means a flag with an empty variant, so a missing flag no longer reports one. Insights, cohorts and actions that filter on `$feature_flag_response = ""` or `false` to find missing flags stop matching new events without any error. Use an `is not set` filter on `$feature_flag_response` instead. Events already stored keep their old values. -### `$locale` and `$app_language` +#### `$locale` and `$app_language` `$locale` now means the first language in the device settings, as a full language tag such as `de-CH` or `zh-Hant-TW`. In 3.x it came from `Locale.getDefault()`, which could be a secondary language, a per-app language or a value your app set with `Locale.setDefault()`, and it dropped the script (`zh-TW`). It's left out when the device reports no language. On older Android versions, 3.x also sent the legacy codes `iw`, `in` and `ji`, so Hebrew, Indonesian and Yiddish values change, such as `in-ID` to `id-ID`. Update filters that match those. Other values mostly stay the same, so otherwise only check filters if your users change these settings. @@ -304,7 +307,7 @@ The SDK reads both languages in the background when an event is captured and use Strings you don't translate fall back per string, so the value is the app's language, not a guarantee for every string. Call `PostHog.setAppLanguage("de")` at startup and whenever the language changes to send it on every version, or if you translate some other way, such as with an in-app language setting. It's kept in memory only. -### Session replay records screenshots +#### Session replay records screenshots 4.0 removes wireframe session replay. Replay always records masked screenshots, which is what `screenshot = true` already did. @@ -332,18 +335,18 @@ A dialog's dim, and a dialog masked whole on Android 8.1 and lower, are sent as The `$sdk_debug_replay_capture_mode` property is now always `screenshot`. -### Deep link query parameters +#### Deep link query parameters The `Deep Link Opened` event leaves out query parameters whose name starts with `$`, such as `$process_person_profile`, so a link can't set PostHog's own properties. Other parameters and the `url` property are sent as in 3.x. -### Other changes that don't fail the build +#### Other changes that don't fail the build The code you end up with after these two migrations compiles, so they're easy to miss: - [`getFeatureFlagResult()` sends `$feature_flag_called` by default](#getfeatureflagpayload), unlike `getFeatureFlagPayload()`. - [Apps that set `remoteConfig = false` now load `/config`](#remoteconfig) and apply its settings. -## Endpoints +### Endpoints | Data | 3.x | 4.0 | | --- | --- | --- | @@ -362,7 +365,7 @@ Analytics requests are gzipped unless you set `compression` to `PostHogCompressi A personal API key (`phx_...`) in `projectToken` now disables the SDK at setup, as an empty or whitespace-only token does. Both print why, even when `debug` is off. To turn the SDK off in tests, use an empty token. In 3.x, the SDK started and PostHog rejected every event with a 401. Use your project token (`phc_...`). -### Hosts without capture v1 +#### Hosts without capture v1 If you self-host PostHog, make sure `/i/v1/analytics/events` is served before you upgrade, and `/i/v1/ai/events` if you use `captureAi`. PostHog Cloud (`us.i.posthog.com`, `eu.i.posthog.com`) serves it. @@ -378,7 +381,7 @@ PostHog's managed reverse proxy already does this and needs no change. A proxy s The SDK doesn't fall back to `/batch`. A 404 is retried, so the events stay queued until the path is served, and the SDK prints one warning, even with `debug` off. Any other error status that isn't retried, such as 403 or 405, drops the events. -### Redirects +#### Redirects The SDK follows a 307 or 308 redirect only to the origin of `host` (same scheme, host and port), at most 5 times, and resends the same body and headers. Any other redirect is not followed and the events are dropped. @@ -386,7 +389,7 @@ In 3.x, OkHttp followed redirects to any host. If a proxy redirects capture requests to another host, point `host` at the final host. This also applies when you set your own `httpClient`: for capture requests, the SDK turns off its redirect following and OkHttp's connection retries, and keeps your other settings. Other requests, such as session replay and logs, behave as in 3.x. -## Event validation +### Event validation Capture v1 checks each event on its own and drops only the invalid ones, so the rest of the batch is delivered. @@ -413,11 +416,13 @@ A `NaN` or infinite number in the properties is dropped from the event, and the A map key in the properties that isn't a string is converted to one when it's a number, a boolean or `null`. Any other key is dropped with its value, and the rest of the event is sent. With `debug` on, the SDK logs the key's type. In 3.x, a nested map with a non-string key lost the whole event. +A `null` element in a list or array in the properties is now sent as JSON `null` at its position, and so is an element that can't be serialized, such as `NaN`. In 3.x, both were removed, which moved the later elements to lower indexes. A property or map entry whose value is `null` is still left out. + The distinct ID can come from `identify()`, the `distinctId` argument of `capture` or `beforeSend`. If you identify users with a long ID, such as a JWT or a long email address, shorten or hash it before you upgrade. Otherwise every event for that user is dropped. `identify()` with an empty or whitespace-only distinct ID is still ignored, as in 3.x. -## Property precedence +### Property precedence An event's properties are merged in this order, and later values win: @@ -432,7 +437,13 @@ A registered `$session_id` now overrides the SDK's session ID, which can detach A caller `$screen_name` or `$session_id` still replaces the SDK's value even when it's blank, as in 3.x, so a blank `$session_id` is sent as an empty `session_id`. In 3.x, a `$set`, `$set_once` or `$groups` map in properties replaced the per-call values and the groups set with `group()`. A `$set` or `$set_once` you pass, or `userProperties`, still replaces a registered one whole. -## Session and window IDs +`$lib` and `$lib_version` name the library that produced the event, and the SDK fills them last, as a pair, only where nothing above named the library. +When neither is set, or only `$lib_version` is, the SDK sends its own `$lib` and `$lib_version`. +When `$lib` is the SDK's own name without a version, the SDK adds its version. +When `$lib` names another library, the SDK leaves both as they are and never adds its own version, so set both keys together. +In 3.x, a registered `$lib` or `$lib_version` was replaced by the SDK's, and a `$lib` you passed was sent with the SDK's `$lib_version`. + +### Session and window IDs Capture v1 sends `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, not as properties. The SDK moves them out of `properties` for you. @@ -441,14 +452,14 @@ Any other value is removed and not sent. With `debug` on, the SDK logs the key a A null value counts as unset and is removed without a log. In PostHog, the events still have `$session_id` and `$window_id`, so insights, filters and session replay work as before. -## Timestamps and IDs +### Timestamps and IDs The SDK sends every timestamp in UTC with 3 fractional digits, for example `2026-01-01T00:00:00.000Z`, as 3.x did. It doesn't check for future timestamps. PostHog replaces a timestamp more than 23 hours ahead with the time it received the event. Event uuids and anonymous distinct IDs are UUID v7, as in 3.x. An anonymous ID you change with `getAnonymousId` is sent as you return it. Each capture request also sends a UUID v7 request ID in the `PostHog-Request-Id` header, which 3.x didn't send. -## Event options +### Event options Capture v1 reads processing settings from an `options` object sent next to `properties`. `capture` takes a new `options` argument, and `beforeSend` can read and change `PostHogEvent.options`. @@ -480,21 +491,35 @@ When the event is sent, the SDK removes each one from `properties` and uses it f - An option you pass to any of these methods or set in `beforeSend` wins over its legacy property. An option set to `null` counts as unset, so the legacy property fills it. - To change person processing in `beforeSend`, edit `event.options`. A `$process_person_profile` property the hook adds only fills an option that is still unset, so it doesn't override the `false` the SDK set for an anonymous event. -- When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither, because PostHog processes person profiles by default. In 3.x, every event carried a `$process_person_profile` property. To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. A registered `$process_person_profile` changes it for every event. +- When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither, because PostHog processes person profiles by default. In 3.x, every event carried a `$process_person_profile` property. To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. A registered `$process_person_profile` changes it for every event. In 3.x, the SDK's value replaced a registered `$process_person_profile`, so a registered `false` had no effect. In 4.0 it applies, also after `identify` and with `PersonProfiles.ALWAYS`: those events don't change the person profile, and their `$set` is ignored. They are still linked to the person and billed as identified events. +- This also applies with `personProfiles = PersonProfiles.NEVER`: a `process_person_profile` option or `$process_person_profile` property set to `true`, passed or registered, turns person processing on for that event. In 3.x, `NEVER` always won. If you rely on `NEVER` to keep events personless, make sure neither is set to `true`, or remove it in `beforeSend`. - Review your `beforeSend` hooks for the new event shape. In 3.x, the SDK marked person processing with the `$process_person_profile` property. In 4.0, it's the `process_person_profile` option, and the property isn't set. A hook that assigns a new map to `event.options` without keeping that key loses the `false` the SDK set. That turns person processing on for anonymous users, overriding `personProfiles`. Editing `event.options` in place keeps it. +- `beforeSend` gets its own copy of the event's nested maps, lists and arrays, in `properties` and `options`. Changes a hook makes no longer reach the objects you passed to `capture` or registered, and identity checks against them (`===`) no longer match. In 3.x, hooks edited the caller's objects. - `options` is a property of `PostHogEvent`, not a constructor parameter, so the constructor and `copy` are unchanged from 3.x. When `beforeSend` returns a different event whose `options` is `null`, such as one made with `event.copy(…)` or the constructor, it gets the options of the event the hook was given. To send an event with no options, set `options` to an empty map. - A `$set` sent with `process_person_profile: false` doesn't update the person, so it no longer suppresses a later `setPersonProperties` or `identify` call with the same properties as a duplicate. - The SDK sends option values as given. PostHog reads common forms of a value, such as `"false"` or `0` for a boolean, and drops an event whose option value it can't read. - Other option keys are sent unchanged, and PostHog ignores keys it doesn't know. -- There are no global or context options. To set an option on every event, register its legacy property, for example `register("\$process_person_profile", false)`. +- There are no global or context options. To set an option on every event, register its legacy property, for example `register("\$cookieless_mode", true)`. - There's no setting for GeoIP lookup or `historical_migration` on events, as in 3.x. - With `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, `identify`, `alias`, `group` and `setPersonProperties` still turn on person processing for the user's later events, as in 3.x. -- A registered option also reaches `$identify`, `$create_alias` and `$groupidentify`. If it turns person processing off, for example `register("\$process_person_profile", false)`, PostHog accepts those events and then drops them with an ingestion warning, and the SDK doesn't report it. +- A registered `$process_person_profile` set to `false` also reaches the events `identify`, `alias`, `group` and `setPersonProperties` send. PostHog accepts `$identify`, `$create_alias` and `$groupidentify` and then drops them with an ingestion warning, and the SDK doesn't report it. A `$set` event is kept, but the person isn't updated. To keep identifying, pass the option on the call, or set it in `beforeSend`: + + ```kotlin + PostHog.register("\$process_person_profile", false) + + PostHog.identify( + distinctId = "user-123", + userProperties = mapOf("plan" to "pro"), + options = mapOf("process_person_profile" to true), + ) + ``` + + If you registered `false` to skip person profiles for anonymous users, remove it: `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, the default, already does that and still lets `identify` create the person. To create no person profiles at all, set `personProfiles = PersonProfiles.NEVER` instead. The SDK then skips these calls. - An empty or whitespace-only `distinctId` argument to `capture` now uses the current distinct ID, like `null`. In 3.x, the event was dropped. - The event `beforeSend` returns keeps the uuid of the capture it came from. A uuid you set in `beforeSend`, for example with `copy(uuid = …)`, is replaced, so a hook that returns an event kept from an earlier call still sends one uuid per capture. - Events still queued on disk by 3.x are sent to capture v1 after the update, with their legacy properties moved to options. -## AI events +### AI events 4.0 adds `captureAi`, which sends AI events, such as `$ai_generation`, to PostHog's AI endpoint (`/i/v1/ai/events`) instead of the analytics endpoint. It takes the same arguments as `capture`, and the events go through the same `beforeSend` hooks. @@ -510,13 +535,13 @@ PostHog.captureAi( - An AI event's properties can be up to 8 MiB. The SDK drops a serialized event over 8 MiB + 64 KiB, measured before `encryption`. With `debug` on, it logs the event name and the limit, never the content. Set `captureAiMaxEventBytes` to lower that limit; a larger value uses 8 MiB + 64 KiB, and with `debug` on the SDK logs that it did. - PostHog drops an event sent with `captureAi` whose name doesn't start with `$ai_`. `capture` never sends events to the AI endpoint, even ones named `$ai_*`. - AI requests time out after 60 seconds without network activity, or `captureAiTimeout`. Other requests keep OkHttp's 10-second defaults. -- AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. -- `flush()` and `close()` also send the AI queue, and AI events left on disk are sent at the next launch. +- On Android, AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. +- `flush()` and `close()` also send the AI queue. On Android, AI events left on disk are sent at the next launch. - AI requests are gzipped unless you set `captureAiCompression` to `PostHogCompression.NONE`. `compression` doesn't apply. - AI events use `flushAt`, `maxBatchSize` and `flushIntervalSeconds`, like other events. A request carries up to about 5 MiB, as for analytics events (see [Retries](#retries)). - The SDK sends AI events unchanged. It doesn't redact or truncate prompts, outputs or media, so use `beforeSend` to remove anything you don't want to send. -## Retries +### Retries These apply to analytics and AI event requests, unless a bullet names session replay or logs. Session replay and logs keep their 3.x status handling: they still retry 3xx and don't retry 404. @@ -533,7 +558,7 @@ These apply to analytics and AI event requests, unless a bullet names session re - A 413 still halves the batch until it fits, as in 3.x. An event that gets a 413 on its own is dropped. - `beforeSend` still runs when you capture the event, before it's queued, not when the batch is sent. -## New: `onFeatureFlags()` +### New: `onFeatureFlags()` `onFeatureFlags()` is now the way to listen for flag loads, for example from a screen or a library. You can remove the listener later: @@ -548,19 +573,21 @@ val subscription = PostHog.onFeatureFlags { loaded -> subscription.unsubscribe() ``` -On Android, listeners run on the main thread. On the JVM, they run on a background thread. If flags have already loaded, a new listener also gets the current values shortly after it registers. You can register before `setup()`, and listeners stay registered across `close()` and `setup()`. +On Android, listeners run on the main thread. If flags have already loaded, a new listener also gets the current values shortly after it registers. You can register before `setup()`, and listeners stay registered across `close()` and `setup()`. -## `posthog-server` +### `posthog-server` `posthog-server` isn't having a major release, and its API is unchanged: it keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` now ships in `posthog-server` itself. None of the API changes above apply to it. `PostHogEvent`, which `beforeSend` gets, keeps its 3.x constructor and `copy`, and gains an `options` property; `posthog-server` still sends to `/batch`, which doesn't use it, so a value set in `beforeSend` is sent but has no effect. It still sends events to `/batch`, not to capture v1, so the endpoint, proxy, retry and event option changes above don't apply to it either. +Using core `posthog` on its own through `PostHogStateless.with` isn't a supported entry point in core 7.0. Without its own queue it gets Android's capture v1 behavior, including the persisted-queue retries, which isn't a server-side contract. Use `posthog-server` for server-side JVM apps. A class that extends `PostHogStateless` also needs updating: the protected `buildEvent()` gained `options` and `uuid` parameters, and `captureFeatureFlagCalledEvent()` is no longer protected. + A personal API key (`phx_...`) in `projectToken` now disables the client at setup, as an empty token does, and both print why even when `debug` is off. -Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. +Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. A `null` element in a list or array in the properties is sent as JSON `null` at its position instead of being removed. `beforeSend` gets its own copy of the event's nested maps, lists and arrays, so its changes no longer reach the objects you passed to `capture`. `posthog-server` 2.25.0 depends on core 7.0, so upgrade it and `posthog-android` together: - If your project uses `posthog-android` 4.0 or core 7.0, use `posthog-server` 2.25.0 or later. Older `posthog-server` versions aren't compatible with core 7.0 at runtime. -- If your project still uses `posthog-android` 3.x, stay on `posthog-server` 2.24.x. Gradle resolves core 7.0 for both, and `posthog-android` 3.x fails at runtime against it with errors such as `NoSuchMethodError`. +- If your project still uses `posthog-android` 3.x, stay on `posthog-server` 2.24.x. `posthog-server` 2.25 brings in core 7.0, and Gradle then upgrades `posthog-android` to 4.0. From 3cf406d4d1443c6e18b0a9cfd0653ece8a21aa8c Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 13 Nov 2026 11:10:28 -0500 Subject: [PATCH 44/49] fix: read cached failed flags without metadata from an in-memory cache Gson can build a failed FeatureFlag record without its metadata object, and the 3.x payload migration read flag.metadata.payload unguarded, so the first flag read after reopening a PostHogMemoryPreferences cache threw a NullPointerException to the caller. Co-Authored-By: Claude Opus 5.5 --- .../posthog/internal/PostHogRemoteConfig.kt | 3 ++- .../src/test/java/com/posthog/PostHogTest.kt | 26 +++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt index 48294f534..4b5604899 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogRemoteConfig.kt @@ -1275,7 +1275,8 @@ public class PostHogRemoteConfig( val serializedPayloads = flags.mapNotNull { (key, flag) -> when (flag) { - is FeatureFlag -> key to flag.metadata.payload + // Gson can hydrate retained failed records without the non-null metadata object. + is FeatureFlag -> flag.metadata?.let { key to it.payload } is Map<*, *> -> (flag["metadata"] as? Map<*, *>)?.let { key to (it["payload"] as? String) } else -> null } diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index b836bbaf8..694b08bcb 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -1281,6 +1281,32 @@ internal class PostHogTest { } } + @Test + fun `failed flag without metadata reads as missing after reopening an in-memory cache`() { + val body = """{"flags":{ + "checkout":{"key":"checkout","enabled":false,"failed":true,"variant":"placeholder"}, + "healthy":{"key":"healthy","enabled":true,"metadata":{"id":1,"version":1,"payload":"\"good\""}} + }}""" + val http = mockHttp(response = MockResponse().setBody(body)) + val cache = PostHogMemoryPreferences() + val sut = getSut(http.url("/").toString(), preloadFeatureFlags = false, cachePreferences = cache) + val loaded = CountDownLatch(1) + sut.reloadFeatureFlags { loaded.countDown() } + assertTrue(loaded.await(5, TimeUnit.SECONDS)) + sut.close() + + // The in-memory cache keeps the Gson-built FeatureFlag objects, whose metadata is null here. + val reopened = + getSut(http.url("/").toString(), preloadFeatureFlags = false, reloadFeatureFlags = false, cachePreferences = cache) + try { + assertNull(reopened.getFeatureFlagResult("checkout", sendFeatureFlagEvent = false)) + assertEquals("good", reopened.getFeatureFlagResult("healthy", sendFeatureFlagEvent = false)?.payload) + } finally { + reopened.close() + http.shutdown() + } + } + @Test fun `scalar reads safely track failed metadata from JSON`() { assertFailedMetadataReads(structuredFirst = false, reopen = false) From b8e5ca7adb1d6ca9232ae232f1767377b6dc2823 Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" <29069505+gewenyu99@users.noreply.github.com> Date: Fri, 13 Nov 2026 14:16:29 -0500 Subject: [PATCH 45/49] docs: sort the Android 4.0.0 migration guide by when you make each change (#973) * docs: sort the Android 4.0.0 migration guide by when you make each change Co-Authored-By: Claude Opus 5.5 * docs: keep the 4.0.0 guide's table cells to one value Co-Authored-By: Claude Opus 5.5 * docs: move the posthog.com Android SDK page into the reference The posthog.com Android SDK page redirects to this reference once 4.0.0 ships, so its setup, how-to, and configuration sections now live in docs/getting-started.md. Co-Authored-By: Claude Opus 5.5 * docs: title a single migration guide's page with its H1 Co-Authored-By: Claude Opus 5.5 (cherry picked from commit 2eeb772d6f5a8406474438737e7b8a2c1c82b050) * docs: publish the root MIGRATION.md as the migration page Co-Authored-By: Claude Opus 5.5 (cherry picked from commit f7650a747028cf3de36959acb0262f84fe625e40) * Revert "docs: move the posthog.com Android SDK page into the reference" This reverts commit 0e67e30b7aa7be5f3505ba67cdf8aeff85d63a22. * docs: add the Android facts from the retired posthog.com page that no other page has Co-Authored-By: Claude Opus 5.5 * docs: move the Android one-API facts from getting-started into KDoc Co-Authored-By: Claude Opus 5.5 * docs: preserve Android tracing setup * docs: name the SDK in versions, cut self-hosted notes, and split dashes and semicolons Co-Authored-By: Claude Opus 5.5 * docs: address review on the reordered 4.0 migration guide - Move "Upgrade your dependencies" and "Upgrade posthog-server" to During: both come down to declaring posthog-android 4.0.0. - Give the PostHogStateless break its own During section and checklist item. - Drop "Check timestamps and IDs": nothing in it changes but the request ID header, which the proxy section covers. - Say what staying on capture costs for $ai_* events, scope the intro to analytics and AI events, and say why follow ups can wait. - disableGeoIp exists now (main's #971), so the guide no longer says there's no GeoIP setting. Name the real remote config path. - Regenerate references/posthog-android-migration.md. Co-Authored-By: Claude Opus 5.5 * docs: say flush doesn't block, and register persists across app restarts Co-Authored-By: Claude Opus 5.5 * docs: pass the migration page generator one guide Co-Authored-By: Claude Opus 5.5 * docs: point the copy page button at posthog.com and reword the change categories Co-Authored-By: Claude Opus 5.5 * docs: restore the self-hosted note on serving capture v1 Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 Co-authored-by: Anna Garcia --- .changeset/android-v4-major.md | 40 +- .changeset/android-v4-replay-and-device.md | 2 +- .changeset/server-keep-on-feature-flags.md | 10 +- MIGRATION.md | 854 ++++++++++-------- README.md | 6 +- bin/docs_scripts/generate_markdown.py | 17 +- docs/getting-started.md | 26 + .../main/java/com/posthog/PostHogConfig.kt | 6 +- .../java/com/posthog/PostHogCoreInterface.kt | 3 + .../main/java/com/posthog/PostHogInterface.kt | 5 +- references/posthog-android-4.md | 34 +- references/posthog-android-migration.md | 854 ++++++++++-------- 12 files changed, 1101 insertions(+), 756 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index e159e8d76..43be95729 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -3,32 +3,32 @@ 'posthog-android': major --- -- See the [3.x to 4.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/MIGRATION.md) for upgrade steps -- **Breaking:** stop supporting core `posthog` on its own through `PostHogStateless.with`; use it through `posthog-android` or `posthog-server` -- **Breaking:** send analytics events to capture v1 (`/i/v1/analytics/events`) with the project token in an `Authorization: Bearer` header, replacing any `Authorization` header in `requestHeaders`; self-hosted instances and reverse proxies must serve the path, and a 404 keeps events queued, retries them and prints one warning even when `debug` is off -- **Breaking:** drop events when a capture request gets a non-retryable status (including 3xx), a 2xx without per-event results, or a redirect other than a 307 or 308 to the same origin as `host` (followed at most 5 times); retry 404, 408, 429, 500, 502, 503 and 504 +- See the [posthog-android 3.x.x to 4.0.0 migration guide](https://github.com/PostHog/posthog-android/blob/main/MIGRATION.md) for upgrade steps +- **Breaking:** stop supporting core `posthog` on its own through `PostHogStateless.with`. Use it through `posthog-android` or `posthog-server` +- **Breaking:** send analytics events to capture v1 (`/i/v1/analytics/events`) with the project token in an `Authorization: Bearer` header, replacing any `Authorization` header in `requestHeaders`. Reverse proxies must serve the path. A 404 keeps events queued, retries them and prints one warning even when `debug` is off +- **Breaking:** drop events when a capture request gets a non-retryable status (including 3xx), a 2xx without per-event results, or a redirect other than a 307 or 308 to the same origin as `host` (followed at most 5 times). Retry 404, 408, 429, 500, 502, 503 and 504 - **Breaking:** cap a `Retry-After` wait at 30 seconds, read it as a minimum wait and accept an HTTP date, and add up to 25% random jitter to the backoff, which still doubles from 1 to 30 seconds, for events, session replay and logs -- **Breaking:** drop events with an empty name before sending them, including one `beforeSend` renames to `""`; PostHog also drops events with an empty distinct ID or a name or distinct ID over 200 bytes +- **Breaking:** drop events with an empty name before sending them, including one `beforeSend` renames to `""`. PostHog also drops events with an empty distinct ID or a name or distinct ID over 200 bytes - **Breaking:** send `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, dropping non-string values -- **Breaking:** send `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id` as capture options instead of properties; PostHog drops an event whose option value it can't read +- **Breaking:** send `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and `$product_tour_id` as capture options instead of properties. PostHog drops an event whose option value it can't read - **Breaking:** set the `process_person_profile` option to `false` only when person processing is off, instead of adding a `$process_person_profile` property to every event - **Breaking:** let a `process_person_profile` option or `$process_person_profile` property set to `true` turn person processing on for an event even with `PersonProfiles.NEVER` - **Breaking:** let registered super properties override properties the SDK sets, such as `$os_name`, and let super and event properties override `$is_identified`, `$process_person_profile` and the session replay debug properties -- **Breaking:** fill `$lib` and `$lib_version` last and as a pair, only when the event doesn't name its library; a `$lib` you register or pass is sent as it is, without the SDK's version +- **Breaking:** fill `$lib` and `$lib_version` last and as a pair, only when the event doesn't name its library. A `$lib` you register or pass is sent as it is, without the SDK's version - **Breaking:** let `userProperties`, `userPropertiesSetOnce` and `groups` win key by key over `$set`, `$set_once` and `$groups` maps in the same call's properties, and merge a `$groups` map in properties into the groups set with `group()` - **Breaking:** keep the event's own uuid when `beforeSend` returns an event with another uuid - **Breaking:** disable the SDK at setup when `projectToken` is a personal API key (`phx_...`), as for an empty token, and print a warning for both even when `debug` is off -- **Breaking:** add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`; Java callers pass `null` for it -- **Breaking:** add `onFeatureFlags()`, `setAppLanguage()`, `captureAi()` and the `options` parameters to `PostHogInterface`, and move `identify(distinctId, userProperties, userPropertiesSetOnce)` from `PostHogCoreInterface` to `PostHogStatelessInterface`; classes that implement these interfaces must add them +- **Breaking:** add an `options` parameter to `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException`. Java callers pass `null` for it +- **Breaking:** add `onFeatureFlags()`, `setAppLanguage()`, `captureAi()` and the `options` parameters to `PostHogInterface`, and move `identify(distinctId, userProperties, userPropertiesSetOnce)` from `PostHogCoreInterface` to `PostHogStatelessInterface`. Classes that implement these interfaces must add them - **Breaking:** rename `PostHogConfig.maxRetries` to `pushNotificationSubscriptionMaxRetries` -- **Breaking:** remove the deprecated `apiKey` property and the `PostHogConfig(apiKey = …)` and `PostHogAndroidConfig(apiKey = …)` factories; use `projectToken` -- **Breaking:** remove the deprecated `propertiesSanitizer` option and `PostHogPropertiesSanitizer`; use `addBeforeSend` -- **Breaking:** remove the deprecated `evaluationEnvironments` option; use `evaluationContexts` -- **Breaking:** remove the deprecated `remoteConfig` option; the SDK always loads remote config at setup -- **Breaking:** remove the deprecated `getFeatureFlagPayload()`; use `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload` -- **Breaking:** remove the `defaultValue` parameter from `getFeatureFlag()`, which returns `null` for a missing flag or a disabled SDK; a positional `Boolean` second argument now sets `sendFeatureFlagEvent`, and `$feature_flag_called` no longer reports a fallback as the flag's value +- **Breaking:** remove the deprecated `apiKey` property and the `PostHogConfig(apiKey = …)` and `PostHogAndroidConfig(apiKey = …)` factories. Use `projectToken` +- **Breaking:** remove the deprecated `propertiesSanitizer` option and `PostHogPropertiesSanitizer`. Use `addBeforeSend` +- **Breaking:** remove the deprecated `evaluationEnvironments` option. Use `evaluationContexts` +- **Breaking:** remove the deprecated `remoteConfig` option. The SDK always loads remote config at setup +- **Breaking:** remove the deprecated `getFeatureFlagPayload()`. Use `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload` +- **Breaking:** remove the `defaultValue` parameter from `getFeatureFlag()`, which returns `null` for a missing flag or a disabled SDK. A positional `Boolean` second argument now sets `sendFeatureFlagEvent`, and `$feature_flag_called` no longer reports a fallback as the flag's value - **Breaking:** leave `$feature_flag_response` out of `$feature_flag_called` for a missing flag instead of sending an empty string -- **Breaking:** remove `PostHogConfig.onFeatureFlags`; call `PostHog.onFeatureFlags(callback)` before `setup()` instead +- **Breaking:** remove `PostHogConfig.onFeatureFlags`. Call `PostHog.onFeatureFlags(callback)` before `setup()` instead - **Breaking:** replace `PostHogOnFeatureFlags` with `PostHogFeatureFlagsCallback` in `reloadFeatureFlags()`, which receives a `PostHogFeatureFlagsLoaded` with the enabled flags, their values and `errorsLoading` - **Breaking:** return `null` from `getFeatureFlagResult(key)?.payload` for a payload that isn't valid JSON, such as plain text, a malformed or empty string, or a JSON `null` - **Breaking:** return `enabled = false` from `getFeatureFlagResult()` and leave the flag out of `PostHogFeatureFlagsLoaded` and `$active_feature_flags` for a feature flag whose variant is an empty string, as `isFeatureEnabled()` already does @@ -38,13 +38,13 @@ - Add the `$app_language` property with the language the app displays on Android 13+, and `setAppLanguage()` to set it on every version - Add internal APIs so wrapper SDKs can run their own `beforeSend` on the fully built event - Add internal APIs so wrapper SDKs can register capture options sent with every event -- Send events queued on disk by 3.x through capture v1 after the update -- Upgrade `posthog-android` to 4.0 when an app pins core `posthog` 7.x next to `posthog-android` 3.x, which would otherwise crash with `NoSuchMethodError` (Gradle builds only) +- Send events queued on disk by 3.x.x through capture v1 after the update +- Upgrade `posthog-android` to 4.0.0 when an app pins core `posthog` 7.x.x next to `posthog-android` 3.x.x, which would otherwise crash with `NoSuchMethodError` (Gradle builds only) - Send a `PostHog-Request-Id` header with each capture request, which reverse proxies must pass through - Cap a capture request at about 5 MiB of events and send as soon as that much is queued - Use the current distinct ID when the `distinctId` argument to `capture` is empty or whitespace-only, instead of dropping the event - Stop storing or matching the person-properties deduplication hash for a `$set` sent with `process_person_profile: false` - Stop printing analytics and AI event request and response bodies, property values and `beforeSend` exception messages in debug logs, and log per-batch drop and retry counts instead -- Fix losing an event whose properties hold a nested map with non-string keys; number, boolean and `null` keys are converted to strings -- Fix removing `null` elements from lists and arrays in event properties, which moved later elements to lower indexes; they're sent as JSON `null` at their position, as is an element that can't be serialized +- Fix losing an event whose properties hold a nested map with non-string keys. Number, boolean and `null` keys are converted to strings +- Fix removing `null` elements from lists and arrays in event properties, which moved later elements to lower indexes. They're sent as JSON `null` at their position, as is an element that can't be serialized - Fix `beforeSend` edits reaching the caller's nested maps and lists, by giving each hook its own copy diff --git a/.changeset/android-v4-replay-and-device.md b/.changeset/android-v4-replay-and-device.md index 61e5f704c..fa4a5b276 100644 --- a/.changeset/android-v4-replay-and-device.md +++ b/.changeset/android-v4-replay-and-device.md @@ -2,7 +2,7 @@ 'posthog-android': major --- -- **Breaking:** remove wireframe session replay and the `screenshot`, `drawableConverter` and `debouncerDelayMs` options of `PostHogSessionReplayConfig` (use `throttleDelayMs` for the last); replay always records masked screenshots, so apps that relied on the default now upload screenshots and should mask custom-drawn views, maps and video, or turn replay off +- **Breaking:** remove wireframe session replay and the `screenshot`, `drawableConverter` and `debouncerDelayMs` options of `PostHogSessionReplayConfig`. Use `throttleDelayMs` instead of `debouncerDelayMs`. Replay always records masked screenshots, so apps that relied on the default now upload screenshots and should mask custom-drawn views, maps and video, or turn replay off - **Breaking:** apply `Modifier.postHogMask()` and `Modifier.postHogUnmask()` only to the element and its children, mask Compose text that draws past its layout box in full, and mask nodes using `Modifier.clearAndSetSemantics` while text or image masking is on - **Breaking:** send a dialog's dim and a dialog masked whole as screenshot images instead of styled wireframe shapes - **Breaking:** change `$locale` to the first language in the device settings as a full language tag, such as `zh-Hant-TW`, instead of `Locale.getDefault()` diff --git a/.changeset/server-keep-on-feature-flags.md b/.changeset/server-keep-on-feature-flags.md index 40be12bef..165bf9b78 100644 --- a/.changeset/server-keep-on-feature-flags.md +++ b/.changeset/server-keep-on-feature-flags.md @@ -2,14 +2,14 @@ 'posthog-server': minor --- -- Require `posthog-android` 4.0 in the same project, since core 7.0 makes Gradle upgrade `posthog-android` 3.x to 4.0; stay on 2.24.x until you upgrade (see the [migration guide](https://github.com/PostHog/posthog-android/blob/main/MIGRATION.md#posthog-server)) -- Bump the `posthog` core dependency to 7.0; `posthog-server` keeps its API, `/batch` endpoint and retry behavior +- Require `posthog-android` 4.0.0 or later in the same project, since core `posthog` 7.0.0 makes Gradle upgrade `posthog-android` 3.x.x to 4.0.0. Stay on `posthog-server` 2.24.x until you upgrade (see the [migration guide](https://github.com/PostHog/posthog-android/blob/main/MIGRATION.md#upgrade-posthog-server)) +- Bump the `posthog` core dependency to 7.0.0. `posthog-server` keeps its API, `/batch` endpoint and retry behavior - Move `PostHogOnFeatureFlags` into `posthog-server` with the same name and API -- Add an `options` property to `PostHogEvent`, which `beforeSend` can read; `posthog-server` still sends to `/batch`, which doesn't use it, so setting it in `beforeSend` has no effect +- Add an `options` property to `PostHogEvent`, which `beforeSend` can read. `posthog-server` still sends to `/batch`, which doesn't use it, so setting it in `beforeSend` has no effect - Disable the client at setup when `projectToken` is a personal API key (`phx_...`), as for an empty token, and print why for both even when `debug` is off - Drop events with an empty name before sending them - Merge `userProperties`, `userPropertiesSetOnce` and `groups` key by key over a `$set`, `$set_once` or `$groups` map in `properties` - Stop printing unserializable property values and `beforeSend` exception messages in debug logs -- Fix losing an event whose properties hold a nested map with non-string keys; number, boolean and `null` keys are converted to strings -- Fix removing `null` elements from lists and arrays in event properties, which moved later elements to lower indexes; they're sent as JSON `null` at their position, as is an element that can't be serialized +- Fix losing an event whose properties hold a nested map with non-string keys. Number, boolean and `null` keys are converted to strings +- Fix removing `null` elements from lists and arrays in event properties, which moved later elements to lower indexes. They're sent as JSON `null` at their position, as is an element that can't be serialized - Fix `beforeSend` edits reaching the caller's nested maps and lists, by giving each hook its own copy diff --git a/MIGRATION.md b/MIGRATION.md index f8b7a9b25..3bb90c8c3 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,109 +1,257 @@ -# Migration guide +# Migrate the Android SDK from 3.x.x to 4.0.0 -## posthog-android 3.x → 4.0 and posthog (core) 7.0 +The Android SDK 4.x.x sends analytics and AI events to the [capture v1](https://posthog.com/docs/api/capture-v1) endpoints, `/i/v1/analytics/events` and `/i/v1/ai/events`. + +On posthog.com, use the copy page button at the top right to work through this with your agents. + +You don't need to make every change on the day you upgrade your SDK. Changes fall in these categories: + +- **Before you upgrade**: These are changes you should make before you upgrade your SDK to 4.x.x. +- **During your upgrade**: These are changes that you need to make in the same PR that upgrades your SDK version. +- **Follow ups**: These are changes that can come in follow up PRs, because 4.x.x still accepts the old names and options. + +## Checklist -4.0 sends analytics events to capture v1 (`/i/v1/analytics/events`) instead of `/batch`, removes APIs deprecated in 3.x and changes the feature flags callback. -Most removals are compile errors with a direct replacement. [Behavior changes](#behavior-changes) won't show up at build time. Read the checklist first, then the sections that apply to you. -Core `posthog` 7.0 is only supported through `posthog-android` 4.0 and `posthog-server`. Using it on its own through `PostHogStateless.with` isn't supported; see [`posthog-server`](#posthog-server). - -For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/api/capture-v1). - -For the full list of 4.0 changes, see the [changelog](https://github.com/PostHog/posthog-android/blob/main/posthog-android/CHANGELOG.md). - -### Checklist - -You need to change code if your app does any of these: - -- sends events to a self-hosted PostHog or a reverse proxy that doesn't serve `/i/v1/analytics/events` -- authenticates its proxy with an `Authorization` header in `requestHeaders` -- sends events through a reverse proxy set up from PostHog's proxy guides before 29 October 2026, which strips `Authorization` -- sends events through a proxy that redirects capture requests, other than with a 307 or 308 to the same origin as `host` -- captures events with an empty event name, or with an event name or distinct ID over 200 bytes -- sets an empty distinct ID in `beforeSend` -- assigns a new map to `event.options` in `beforeSend` (see [Event options](#event-options)) -- sets `projectToken` to a personal API key (`phx_...`) -- reads `$session_id` or `$window_id` from the raw request body, for example in a proxy -- sets `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` or `$product_tour_id` to a value PostHog can't read, such as `"maybe"` -- registers `$process_person_profile` as `false` and still calls `identify`, `alias`, `group` or `setPersonProperties` (see [Event options](#event-options)) -- registers a super property, or passes an event property, with the same key as one the SDK sets, such as `$os_name` or `$is_identified`, and expects the SDK's value to win -- calls `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` or `captureException` from Java, implements `PostHogInterface`, or calls `identify` through a `PostHogCoreInterface` reference -- sets the event `uuid` in `beforeSend` -- relies on a `Retry-After` longer than 30 seconds -- sets `maxRetries` on `PostHogConfig` or `PostHogAndroidConfig` -- uses `apiKey`, `propertiesSanitizer`, `evaluationEnvironments`, `debouncerDelayMs`, `screenshot`, `drawableConverter` or `remoteConfig` -- passes `PostHogConfig` or `PostHogSessionReplayConfig` constructor arguments by position -- calls `getFeatureFlagPayload()`, or passes a default value to `getFeatureFlag()` -- filters insights, cohorts or actions on the `$feature_flag_response` of `$feature_flag_called`, such as `""` or `false` for a missing flag (see [`$feature_flag_response` for a missing flag](#feature_flag_response-for-a-missing-flag)) -- sets `PostHogConfig.onFeatureFlags` or `PostHogOnFeatureFlags`, or passes a callback to `reloadFeatureFlags()` -- uses session replay (see [Session replay records screenshots](#session-replay-records-screenshots)) -- reads a feature flag payload that isn't valid JSON, such as plain text saved as `hello` -- breaks down by `$locale` for the language your app shows (use `$app_language`, and call `setAppLanguage()` if you need it on Android 6–12) -- reads event content or request bodies from the SDK's debug log, or matches its log text -- depends only on `posthog-android-surveys-compose`, or uses `posthog-server` (2.25.0 and later need `posthog-android` 4.0 in the same project) - -### Requirements and versions +**Before you upgrade** + +- [ ] You send events to a self-hosted PostHog or a reverse proxy that doesn't serve `/i/v1/analytics/events` → [Prepare your proxy](#prepare-your-proxy) +- [ ] You authenticate your proxy with an `Authorization` header in `requestHeaders` → [Prepare your proxy](#prepare-your-proxy) +- [ ] You send events through a reverse proxy set up from PostHog's proxy guides before 29 October 2026, which strips `Authorization` → [Prepare your proxy](#prepare-your-proxy) +- [ ] You send events through a proxy that redirects capture requests, other than with a 307 or 308 to the same origin as `host` → [Prepare your proxy](#prepare-your-proxy) +- [ ] You set `projectToken` to a personal API key (`phx_...`) → [Use a project token](#use-a-project-token) +- [ ] You read a feature flag payload that isn't valid JSON, such as plain text saved as `hello` → [Fix flag payloads](#fix-flag-payloads) +- [ ] A feature flag has an empty string as a variant → [Rename empty variants](#rename-empty-variants) +- [ ] You capture events with a distinct ID over 200 bytes → [Shorten long IDs](#shorten-long-ids) + +**During your upgrade** + +- [ ] You depend only on `posthog-android-surveys-compose` → [Upgrade your dependencies](#upgrade-your-dependencies) +- [ ] You use `posthog-server` (2.25.0 and later need `posthog-android` 4.0.0 in the same project) → [Upgrade posthog-server](#upgrade-posthog-server) +- [ ] You call `PostHogStateless.with`, or extend `PostHogStateless` → [Update PostHogStateless code](#update-posthogstateless-code) +- [ ] You use `apiKey`, `propertiesSanitizer`, `evaluationEnvironments`, `debouncerDelayMs`, `screenshot`, or `drawableConverter` → [Fix removed APIs](#fix-removed-apis) +- [ ] You pass `PostHogConfig` or `PostHogSessionReplayConfig` constructor arguments by position → [Fix removed APIs](#fix-removed-apis) +- [ ] You call `getFeatureFlagPayload()`, or pass a default value to `getFeatureFlag()` → [Fix flag calls](#fix-flag-calls) +- [ ] You use `remoteConfig` → [Remove remoteConfig](#remove-remoteconfig) +- [ ] You set `PostHogConfig.onFeatureFlags` or `PostHogOnFeatureFlags`, or pass a callback to `reloadFeatureFlags()` → [Move the flags callback](#move-the-flags-callback) +- [ ] You call `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group`, or `captureException` from Java, or call `identify` through a `PostHogCoreInterface` reference → [Add the options argument](#add-the-options-argument) +- [ ] You implement `PostHogInterface` → [Update interface implementations](#update-interface-implementations) +- [ ] You use `@PostHogInternal` APIs → [Drop internal APIs](#drop-internal-apis) +- [ ] You filter insights, cohorts, or actions on the `$feature_flag_response` of `$feature_flag_called`, such as `""` or `false` for a missing flag → [Check flag events](#check-flag-events) +- [ ] You break down by `$locale` for the language your app shows (use `$app_language`, and call `setAppLanguage()` if you need it on Android 6 to 12) → [Check locale properties](#check-locale-properties) +- [ ] You use session replay → [Check session replay](#check-session-replay) +- [ ] You read `$`-prefixed query parameters from `Deep Link Opened` events → [Check deep links](#check-deep-links) +- [ ] You capture events with an empty event name, or with an event name over 200 bytes → [Check dropped events](#check-dropped-events) +- [ ] You set an empty distinct ID in `beforeSend` → [Check dropped events](#check-dropped-events) +- [ ] You set `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at`, or `$product_tour_id` to a value PostHog can't read, such as `"maybe"` → [Check dropped events](#check-dropped-events) +- [ ] You read event content or request bodies from the SDK's debug log, or match its log text → [Update log checks](#update-log-checks) +- [ ] You register a super property, or pass an event property, with the same key as one the SDK sets, such as `$os_name` or `$is_identified`, and expect the SDK's value to win → [Check property precedence](#check-property-precedence) +- [ ] You read `$session_id` or `$window_id` from the raw request body, for example in a proxy → [Check session IDs](#check-session-ids) +- [ ] You assign a new map to `event.options` in `beforeSend` → [Review beforeSend hooks](#review-beforesend-hooks) +- [ ] You set the event `uuid` in `beforeSend` → [Review beforeSend hooks](#review-beforesend-hooks) +- [ ] You register `$process_person_profile` as `false` and still call `identify`, `alias`, `group`, or `setPersonProperties` → [Check person processing](#check-person-processing) +- [ ] You rely on a `Retry-After` longer than 30 seconds → [Check retries](#check-retries) +- [ ] You set `maxRetries` on `PostHogConfig` or `PostHogAndroidConfig` → [Check retries](#check-retries) + +**Follow ups** + +- [ ] You set legacy option properties like `$process_person_profile` → [Move to event options](#move-to-event-options) +- [ ] You capture `$ai_` events with `capture()` → [Send AI events with captureAi](#send-ai-events-with-captureai) + +## Before you upgrade + +### Prepare your proxy + +posthog-android 4.x.x sends data to these endpoints: + +| Data | 3.x.x | 4.x.x | +| --- | --- | --- | +| Analytics events | `/batch` | `/i/v1/analytics/events` | +| Session replay | `/s/` | `/s/`, unchanged | +| AI events (`captureAi`) | None | `/i/v1/ai/events` (see [Send AI events with captureAi](#send-ai-events-with-captureai)) | +| Logs | `/i/v1/logs` | `/i/v1/logs`, unchanged | +| Feature flags | `/flags` | `/flags`, unchanged | + +Capture v1 requests send the project token in an `Authorization: Bearer ` header instead of an `api_key` body field. + +This header replaces any `Authorization` header you set in `PostHogConfig.requestHeaders`, so authenticate your proxy with a different header, such as `X-Proxy-Token`. Other requests still send your `Authorization` header. + +Analytics requests are gzipped unless you set `compression` to `PostHogCompression.NONE`, as in 3.x.x. + +If you self-host PostHog, make sure your instance serves `/i/v1/analytics/events`, and `/i/v1/ai/events` if you use `captureAi`, before you upgrade. + +If you send events through your own reverse proxy, update it before you upgrade: + +- **Forward both routes.** Forward `/i/v1/analytics/events` and `/i/v1/ai/events` to PostHog. +- **Pass the headers through unchanged.** Pass `Authorization`, every `PostHog-*` header, `Content-Type`, `Content-Encoding`, and `User-Agent`. `Authorization` holds the project token, sent as `Bearer `. PostHog answers `401` without `Authorization` and `400` without the others, and the events are dropped. +- **Keep PostHog's credentials.** If your proxy strips other credentials, keep `Authorization` values that start with `Bearer phc_`, `Bearer phs_`, or `Bearer phx_`. Keep the exact `Bearer ` of an older key without a prefix too. +- **Accept request bodies up to 20 MB.** AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx. A `413` from the proxy makes the SDK halve the batch until it fits. The SDK drops an event that doesn't fit on its own. +- **Pass PostHog's response body through unchanged.** A 2xx response whose body isn't PostHog's `{"results": {...}}` drops the events instead of retrying them. + +PostHog's managed reverse proxy already does this and needs no change. + +A proxy set up from PostHog's [proxy guides](https://posthog.com/docs/advanced/proxy) before 29 October 2026 strips `Authorization`, so PostHog answers `401` and the events are dropped. Update it from the current guide. + +The SDK doesn't fall back to `/batch`. It retries a 404, so the events stay queued until the path is served. The SDK prints one warning, even with `debug` off. + +Any other error status that isn't retried, such as 403 or 405, drops the events. + +The SDK follows a 307 or 308 redirect only to the origin of `host`, at most 5 times. The origin is the same scheme, host, and port. The SDK resends the same body and headers. + +The SDK doesn't follow any other redirect, and the events are dropped. In 3.x.x, OkHttp followed redirects to any host. + +If a proxy redirects capture requests to another host, point `host` at the final host. + +This also applies when you set your own `httpClient`. For capture requests, the SDK turns off its redirect following and OkHttp's connection retries, and keeps your other settings. Other requests, such as session replay and logs, behave as in 3.x.x. + +### Use a project token + +A personal API key (`phx_...`) in `projectToken` disables the SDK at setup, as an empty or whitespace-only token does. Both print why, even when `debug` is off. + +In 3.x.x, the SDK started and PostHog rejected every event with a 401. Use your project token (`phc_...`). + +To turn the SDK off in tests, use an empty token. + +### Fix flag payloads + +In 4.x.x, a payload that isn't valid JSON reads as `null` from `getFeatureFlagResult(key)?.payload` and `getAllFeatureFlags()`. 3.x.x returned the raw string. With `debug` on, the SDK logs the flag key. + +| Payload | 3.x.x | 4.x.x | +| --- | --- | --- | +| Malformed (`{broken`, `[1, 2`), empty or whitespace-only | the raw string | `null` | +| Only valid in lenient mode (unquoted `hello`, single quotes, comments) | decoded leniently | `null` | +| JSON `null` | the string `"null"` | `null` | +| Valid JSON (`"hello"`, `""`, `false`, `0`, objects, arrays) | decoded | decoded, unchanged | +| Bootstrapped payloads | as passed | as passed, unchanged | + +The flag's value, enabled state, variant, and any other flag's payload aren't affected. + +You might read a payload as plain text, such as a payload saved as `hello` rather than `"hello"`. Update it in PostHog to valid JSON before you upgrade, or your code gets `null`. + +PostHog no longer saves a new payload that isn't valid JSON, so only payloads saved earlier are affected. + +Apps that upgrade from 3.13.x or older didn't cache flag details. Until the app's first `/flags` response, a malformed payload cached by 3.x.x still reads as the raw string, as it did in 3.x.x. + +### Rename empty variants + +In 4.x.x, a flag whose variant is an empty string reads as disabled everywhere. `isFeatureEnabled()` already read it as disabled in 3.x.x, with or without `defaultValue`. + +- **Flag results.** `getFeatureFlagResult()` and `getAllFeatureFlags()` return `enabled = false` for it. 3.x.x returned `true`. +- **Loaded flags.** `PostHogFeatureFlagsLoaded` leaves it out of `flags` and `variants`. +- **Captured events.** Captured events leave it out of `$active_feature_flags`. +- **Variant values.** `variant`, `getFeatureFlag()`, and the event's `$feature/` property still return `""`. + +PostHog no longer accepts empty variants for new flags, so only flags created earlier through the API, MCP, or Terraform are affected. + +`/flags` still returns `enabled: true` for them, and other PostHog SDKs can still report them as enabled, so rename the variant before you upgrade. + +### Shorten long IDs + +PostHog drops an event whose distinct ID is over 200 UTF-8 bytes. Legacy capture shortened the ID to 200 characters and kept the event. + +The distinct ID can come from `identify()`, the `distinctId` argument of `capture`, or `beforeSend`. + +If you identify users with a long ID, such as a JWT or a long email address, shorten or hash it before you upgrade. Otherwise every event for that user is dropped. + +## During your upgrade + +### Upgrade your dependencies + +Upgrade PostHog artifacts together: | Artifact | Upgrade | | --- | --- | -| `com.posthog:posthog-android` | 3.x to 4.0 | -| `com.posthog:posthog` (core) | 6.x to 7.0 | -| `com.posthog:posthog-android-surveys-compose` | keep your version, and declare `com.posthog:posthog-android` 4.0.0 or later in your build so Gradle resolves 4.x instead of the 3.x version it pulls in | -| `com.posthog:posthog-server` | 2.25.0, together with `posthog-android` 4.0; see [`posthog-server`](#posthog-server) | +| `com.posthog:posthog-android` | 3.x.x to 4.0.0 | +| `com.posthog:posthog` (core) | 6.x.x to 7.0.0 | +| `com.posthog:posthog-android-surveys-compose` | Keep your version | +| `com.posthog:posthog-server` | 2.25.0, together with `posthog-android` 4.0.0 (see [Upgrade posthog-server](#upgrade-posthog-server)) | + +With `posthog-android-surveys-compose`, declare `com.posthog:posthog-android` 4.0.0 or later in your build, so Gradle resolves 4.x.x instead of the 3.x.x version it pulls in. + +Core `posthog` 7.x.x isn't binary compatible with SDK versions built against core 6.x.x. The exception is `posthog-android-surveys-compose`, which works with both. + +When core 7.x.x is in a Gradle build, for example through `posthog-server` 2.25.0, Gradle upgrades `posthog-android` to 4.x.x, even over a range such as `[3.75.0,4.0.0)`. Code that still uses removed APIs then fails to compile. + +Other mismatches fail at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. + +The Android minimum API level (23), the Java bytecode target (Java 8), the Kotlin language and API compatibility (2.0), and `posthog-android-gradle-plugin` are unchanged. You don't need to change your build for them. + +The [changelog](https://github.com/PostHog/posthog-android/blob/main/posthog-android/CHANGELOG.md) lists every 4.0.0 change. + +### Upgrade posthog-server + +`posthog-server` has no major release, and its API is unchanged. It keeps its own `apiKey`, `getFeatureFlagPayload`, and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` ships in `posthog-server` itself. -These are unchanged, so you don't need to change your build for them: +It still sends events to `/batch`, not to capture v1. The API, endpoint, proxy, retry, and event option changes in this guide don't apply to it. -- Android minimum API level: 23 -- Java bytecode target: Java 8 -- Kotlin language and API compatibility: 2.0 -- `posthog-android-gradle-plugin` +`posthog-server` 2.25.0 depends on core `posthog` 7.0.0, so upgrade it and `posthog-android` together: -Upgrade PostHog artifacts together. Core 7.0 is not binary compatible with SDK versions built against core 6.x, except `posthog-android-surveys-compose`, which works with both. When core 7.0 is in a Gradle build, for example through `posthog-server` 2.25, Gradle upgrades `posthog-android` to 4.0, even over a range such as `[3.75.0,4.0.0)`, so code that still uses removed APIs fails to compile. Other mismatches fail at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. +- **With `posthog-android` 4.x.x or core 7.x.x.** Use `posthog-server` 2.25.0 or later. Older `posthog-server` versions aren't compatible with core 7.x.x at runtime. +- **With `posthog-android` 3.x.x.** Stay on `posthog-server` 2.24.x. `posthog-server` 2.25.0 brings in core 7.0.0, and Gradle then upgrades `posthog-android` to 4.x.x. -### Removed APIs +These changes apply to `posthog-server` too: -All of these are compile errors. Calling them from an already-compiled library that you haven't updated fails at runtime. +- **Personal API keys.** A personal API key (`phx_...`) in `projectToken` disables the client at setup, as an empty token does. Both print why, even when `debug` is off. +- **Empty names.** The client drops events with an empty name before sending. +- **Merged maps.** `userProperties`, `userPropertiesSetOnce`, and `groups` merge key by key over a `$set`, `$set_once`, or `$groups` map in `properties`. +- **`null` elements.** A `null` element in a list or array in the properties is sent as JSON `null` at its position instead of being removed. +- **`beforeSend` copies.** `beforeSend` gets its own copy of the event's nested maps, lists, and arrays, so its changes no longer reach the objects you passed to `capture`. +- **Event options.** `PostHogEvent`, which `beforeSend` gets, keeps its 3.x.x constructor and `copy`, and gains an `options` property. `/batch` doesn't use it, so a value set in `beforeSend` is sent but has no effect. + +### Update PostHogStateless code + +Core `posthog` 7.x.x is only supported through `posthog-android` 4.x.x and `posthog-server`. `PostHogStateless.with` isn't a supported entry point in core 7.x.x. + +`PostHogStateless` has no queue of its own, so it gets Android's capture v1 behavior, including the persisted-queue retries, which isn't a server-side contract. Use `posthog-server` for server-side JVM apps. + +A class that extends `PostHogStateless` also needs an update. The protected `buildEvent()` gained `options` and `uuid` parameters, and `captureFeatureFlagCalledEvent()` is no longer protected. + +### Fix removed APIs + +posthog-android 4.x.x removes these APIs. Each one is a compile error. A call from an already-compiled library that you haven't updated fails at runtime. | Removed | Use instead | | --- | --- | | `PostHogConfig.apiKey`, `PostHogConfig(apiKey = …)`, `PostHogAndroidConfig(apiKey = …)` | `projectToken` | | `PostHogConfig.propertiesSanitizer`, `PostHogPropertiesSanitizer` | `addBeforeSend` | | `PostHogConfig.evaluationEnvironments` | `evaluationContexts` | -| `getFeatureFlagPayload()`, on the instance and on `PostHog` | `getFeatureFlagResult()` | -| `defaultValue` on `getFeatureFlag()` | `getFeatureFlag(key) ?: default` | +| `getFeatureFlagPayload()`, on the instance and on `PostHog` | `getFeatureFlagResult()` (see [Fix flag calls](#fix-flag-calls)) | +| `defaultValue` on `getFeatureFlag()` | `getFeatureFlag(key) ?: default` (see [Fix flag calls](#fix-flag-calls)) | | `PostHogSessionReplayConfig.debouncerDelayMs` | `throttleDelayMs` | -| `PostHogSessionReplayConfig.screenshot`, `drawableConverter`, `PostHogDrawableConverter` | nothing; replay always records screenshots | -| `PostHogConfig.remoteConfig` | nothing; remote config always loads | -| `PostHogConfig.onFeatureFlags` | `PostHog.onFeatureFlags()` before `setup()` | +| `PostHogSessionReplayConfig.screenshot`, `drawableConverter`, `PostHogDrawableConverter` | Nothing | +| `PostHogConfig.remoteConfig` | Nothing | +| `PostHogConfig.onFeatureFlags` | `PostHog.onFeatureFlags()` before `setup()` (see [Move the flags callback](#move-the-flags-callback)) | | `PostHogOnFeatureFlags` | `PostHogFeatureFlagsCallback` | -| `PostHogConfig.maxRetries` | `pushNotificationSubscriptionMaxRetries` (see [Retries](#retries)) | +| `PostHogConfig.maxRetries` | `pushNotificationSubscriptionMaxRetries` (see [Check retries](#check-retries)) | + +Replay always records screenshots (see [Check session replay](#check-session-replay)). Remote config always loads (see [Remove remoteConfig](#remove-remoteconfig)). The constructor parameters of `PostHogConfig` and `PostHogSessionReplayConfig` move up where these were removed. If you pass arguments by position, check them, or switch to named arguments. -#### `apiKey` +Replace `apiKey` with `projectToken`: ```kotlin -// 3.x +// 3.x.x val config = PostHogAndroidConfig(apiKey = "phc_your_project_token") val token = config.apiKey -// 4.0 +// 4.x.x val config = PostHogAndroidConfig(projectToken = "phc_your_project_token") val token = config.projectToken ``` `PostHogAndroidConfig("phc_your_project_token")`, with no parameter name, still works. From Java, replace `getApiKey()` with `getProjectToken()`. -#### `propertiesSanitizer` +Replace `propertiesSanitizer` with `addBeforeSend`: ```kotlin -// 3.x +// 3.x.x config.propertiesSanitizer = PostHogPropertiesSanitizer { properties -> properties.apply { remove("email") } } -// 4.0 +// 4.x.x config.addBeforeSend { event -> event.properties?.remove("email") event @@ -112,90 +260,102 @@ config.addBeforeSend { event -> `addBeforeSend` gets the whole `PostHogEvent`. Return `null` to drop the event. If the hook throws, the event is dropped. -#### `evaluationEnvironments` +Replace `evaluationEnvironments` with `evaluationContexts`: ```kotlin -// 3.x +// 3.x.x config.evaluationEnvironments = listOf("production") -// 4.0 +// 4.x.x config.evaluationContexts = listOf("production") ``` -#### `getFeatureFlagPayload()` +Replace `debouncerDelayMs` with `throttleDelayMs`: -`getFeatureFlagPayload()` never sent `$feature_flag_called`. `getFeatureFlagResult()` sends it by default, following `sendFeatureFlagEvent`, so pass `sendFeatureFlagEvent = false` to keep your event volume and experiment exposures unchanged. If you drop that argument, nothing fails, but you'll send new events. +```kotlin +// 3.x.x +PostHogSessionReplayConfig(debouncerDelayMs = 500) -The new call has no `defaultValue` parameter, so apply your default with `?:`. +// 4.x.x +PostHogSessionReplayConfig(throttleDelayMs = 500) +``` + +### Fix flag calls + +`getFeatureFlagPayload()` never sent `$feature_flag_called`. `getFeatureFlagResult()` sends it by default, following `sendFeatureFlagEvent`. + +Pass `sendFeatureFlagEvent = false` to keep your event volume and experiment exposures unchanged. If you drop that argument, nothing fails, but you'll send new events. + +`getFeatureFlagResult()` has no `defaultValue` parameter, so apply your default with `?:`: ```kotlin -// 3.x +// 3.x.x val payload = PostHog.getFeatureFlagPayload("checkout", defaultValue = "fallback") -// 4.0 +// 4.x.x val payload = PostHog.getFeatureFlagResult("checkout", sendFeatureFlagEvent = false)?.payload ?: "fallback" ``` -#### `getFeatureFlag()` default value +`getFeatureFlag()` has no `defaultValue` parameter either: ```kotlin -// 3.x +// 3.x.x val value = PostHog.getFeatureFlag("checkout", defaultValue = "fallback") -// 4.0 +// 4.x.x val value = PostHog.getFeatureFlag("checkout") ?: "fallback" ``` -The second parameter is now `sendFeatureFlagEvent`, which affects code that still compiles: +The second parameter of `getFeatureFlag()` is `sendFeatureFlagEvent` in 4.x.x, which affects code that still compiles: -- `getFeatureFlag("checkout", true)` compiles, but `true` now means `sendFeatureFlagEvent` rather than the default value. -- A disabled SDK now returns `null`, not your default. -- `$feature_flag_called` no longer reports a fallback as the flag's value. `isFeatureEnabled("missing", true)` still returns `true`, but its event leaves out `$feature_flag_response` (see [`$feature_flag_response` for a missing flag](#feature_flag_response-for-a-missing-flag)). +- **Boolean arguments.** `getFeatureFlag("checkout", true)` compiles, but `true` means `sendFeatureFlagEvent` rather than the default value. +- **A disabled SDK.** A disabled SDK returns `null`, not your default. +- **Fallback values.** `$feature_flag_called` no longer reports a fallback as the flag's value. `isFeatureEnabled("missing", true)` still returns `true`, but its event leaves out `$feature_flag_response` (see [Check flag events](#check-flag-events)). Classes that implement `PostHogInterface` update the signature. -#### `debouncerDelayMs` +### Remove remoteConfig + +Apps that left `remoteConfig` at its default of `true` see no behavior change. Delete the option: ```kotlin -// 3.x -PostHogSessionReplayConfig(debouncerDelayMs = 500) +// 3.x.x +config.remoteConfig = false -// 4.0 -PostHogSessionReplayConfig(throttleDelayMs = 500) +// 4.x.x: remove the line ``` -#### `remoteConfig` +If you set it to `false`, your app's behavior changes: -Delete the option. Apps that left it at its default of `true` see no behavior change. +- **Requests at setup.** The SDK requests remote config (`/array//config`) at setup, even if `preloadFeatureFlags` is also `false`. 3.x.x sent no request at all. +- **Project settings.** The settings in `/config` apply, including the session replay, surveys, error tracking, and push settings from your project. +- **Flag requests.** With `preloadFeatureFlags = true`, the SDK requests `/flags` only if `/config` reports that the project has feature flags. 3.x.x always requested `/flags`. If the project has none, the cached flags are cleared. -```kotlin -// 3.x -config.remoteConfig = false +### Move the flags callback -// 4.0: remove the line -``` +`PostHogConfig.onFeatureFlags` is removed. Call `PostHog.onFeatureFlags()` before `setup()` instead, which also covers the first load. -If you set it to `false`, your app's behavior changes: +An instance from `PostHogAndroid.with()` is set up as it's created, so call `onFeatureFlags()` on it right after `with()`. If flags have already loaded, the listener gets the current values shortly after it registers. -- The SDK now requests `/config` at setup, even if `preloadFeatureFlags` is also `false`, when 3.x sent no request at all. -- The settings in `/config` now apply, including the session replay, surveys, error tracking and push settings from your project. -- With `preloadFeatureFlags = true`, the SDK requests `/flags` only if `/config` reports that the project has feature flags. In 3.x it always requested `/flags`. If the project has none, the cached flags are cleared. +`reloadFeatureFlags()` takes a `PostHogFeatureFlagsCallback`. Both callbacks receive a `PostHogFeatureFlagsLoaded`: -### Feature flags callback +| Field | Holds | +| --- | --- | +| `flags` | The keys of the enabled flags | +| `variants` | Their values, either `true` or the variant string | +| `errorsLoading` | Whether the latest load failed | -`PostHogConfig.onFeatureFlags` is removed. Call `PostHog.onFeatureFlags()` before `setup()` instead, which also covers the first load. An instance from `PostHogAndroid.with()` is set up as it's created, so call `onFeatureFlags()` on it right after `with()`; if flags have already loaded, the listener gets the current values shortly after it registers. `reloadFeatureFlags()` now takes a `PostHogFeatureFlagsCallback`. Both callbacks receive a `PostHogFeatureFlagsLoaded`: +When the latest load failed, the values are the last known ones, which can be empty. -- `flags`: the keys of the enabled flags -- `variants`: their values, either `true` or the variant string -- `errorsLoading`: whether the latest load failed. The values are then the last known ones, which can be empty +Register the listener before `setup()`: ```kotlin -// 3.x +// 3.x.x config.onFeatureFlags = PostHogOnFeatureFlags { refreshUi() } -// 4.0, before PostHogAndroid.setup() +// 4.x.x, before PostHogAndroid.setup() PostHog.onFeatureFlags { loaded -> if (!loaded.errorsLoading) { refreshUi() @@ -205,29 +365,60 @@ PostHog.onFeatureFlags { loaded -> The listener differs from the removed option in three ways: -- It runs on the main thread on Android. The option ran on a background thread. -- Bootstrapped flags arrive just after `setup()` is called, not synchronously inside it. -- A reload on a disabled SDK doesn't call listeners. `reloadFeatureFlags(callback)` still gets `errorsLoading = true` in that case. +- **Thread.** It runs on the main thread on Android. The option ran on a background thread. +- **Bootstrapped flags.** They arrive just after `setup()` is called, not synchronously inside it. +- **Disabled SDK.** A reload on a disabled SDK doesn't call listeners. `reloadFeatureFlags(callback)` still gets `errorsLoading = true` in that case. + +`onFeatureFlags()` is the way to listen for flag loads, for example from a screen or a library. You can remove the listener later: -From Java, the `reloadFeatureFlags()` lambda now takes the `PostHogFeatureFlagsLoaded` argument: +```kotlin +val subscription = PostHog.onFeatureFlags { loaded -> + if (loaded.variants["new-checkout"] == "test") { + showTestVariant() + } +} + +// later +subscription.unsubscribe() +``` + +You can register before `setup()`, and listeners stay registered across `close()` and `setup()`. + +From Java, the `reloadFeatureFlags()` lambda takes the `PostHogFeatureFlagsLoaded` argument: ```java -// 3.x +// 3.x.x PostHog.Companion.reloadFeatureFlags(() -> refreshUi()); -// 4.0 +// 4.x.x PostHog.Companion.reloadFeatureFlags(loaded -> refreshUi()); ``` -A Kotlin trailing lambda such as `PostHog.reloadFeatureFlags { refreshUi() }` compiles unchanged, so it won't show up as an error. Check whether it should now read `errorsLoading`: the callback has always also run after a failed load. +A Kotlin trailing lambda such as `PostHog.reloadFeatureFlags { refreshUi() }` compiles unchanged, so it won't show up as an error. Check whether it should read `errorsLoading`. The callback has always also run after a failed load. + +`errorsLoading` depends on why the load ended: + +- **`false`.** PostHog answers that the project is over its feature flags quota. The values are the cached flags. +- **`true`.** No request was made, such as when the device is offline or the distinct ID is blank. It's also `true` when the SDK is disabled or isn't set up, with no values in that last case. + +The `reloadFeatureFlags()` callback still runs on a background thread, or right away on the calling thread when no load is attempted. Switch to the main thread before you touch UI. + +### Add the options argument -`errorsLoading` is `false` when PostHog answers that the project is over its feature flags quota, and the values are the cached flags. It's `true` when no request was made, such as when the device is offline or the distinct ID is blank, and when the SDK is disabled or isn't set up, with no values in that last case. +`capture` takes a new `options` argument. `screen`, `identify`, `setPersonProperties`, `alias`, `group`, and `captureException` take the same argument, as their last parameter (see [Move to event options](#move-to-event-options)). -The `reloadFeatureFlags()` callback still runs on a background thread, or right away on the calling thread when no load is attempted, so switch to the main thread before touching UI. +- **Kotlin callers.** Callers that use named or positional arguments for the existing parameters keep compiling. +- **Java callers.** Pass the new trailing `options` argument, or `null`. +- **`PostHogInterface` implementations.** Add the parameter. +- **`identify` on `PostHogCoreInterface`.** `identify(distinctId, userProperties, userPropertiesSetOnce)` moved from `PostHogCoreInterface` to `PostHogStatelessInterface`. Call it through `PostHogInterface` or `PostHogStatelessInterface`. -### `PostHogInterface` implementations +### Update interface implementations -`PostHogInterface` lost `getFeatureFlagPayload()`, gained the abstract `onFeatureFlags()` and `setAppLanguage()`, and changed the callback type of `reloadFeatureFlags()`. Classes that implement it, such as hand-written fakes for tests, no longer compile until they're updated. They also add the `options` parameter and `captureAi()` (see [Event options](#event-options) and [AI events](#ai-events)). +`PostHogInterface` lost `getFeatureFlagPayload()`, gained the abstract `onFeatureFlags()` and `setAppLanguage()`, and changed the callback type of `reloadFeatureFlags()`. + +Implementations also add the `options` parameter and `captureAi()` (see [Add the options argument](#add-the-options-argument) and [Send AI events with captureAi](#send-ai-events-with-captureai)). + +Classes that implement it, such as hand-written fakes for tests, don't compile until you update them: ```kotlin class FakePostHog : PostHogInterface { @@ -242,241 +433,257 @@ class FakePostHog : PostHogInterface { `PostHogFeatureFlagsSubscription` and `PostHogFeatureFlagsLoaded` have constructors marked `@PostHogInternal`, which aren't intended for app code, so create them with a mocking library. -### Internal APIs +### Drop internal APIs These helpers were public only by accident and were marked `@PostHogInternal`. They're no longer visible outside the SDK and have no replacement. Apps that don't use `@PostHogInternal` APIs aren't affected. -- `com.posthog.internal`: `CustomHeadersInterceptor`, `PostHogPrintLogger`, `PropertyGroupDeserializer`, `PropertyValueDeserializer`, `personPropertiesContext()`, `PostHogPreferences.PUSH_SUBSCRIPTION_REJECTED` -- `com.posthog.internal.errortracking`: `ThrowableCoercer.fromThrowableToPostHogProperties()` -- `com.posthog.internal.replay`: `RRDocumentNode`, `RRDomContentLoadedEvent`, `RRLoadedEvent`, `RRStyle`; `RRWireframe` keeps only `id`, `x`, `y`, `width`, `height`, `type` and `base64` -- `com.posthog.internal.surveys`: `findBestTranslationMatch()` -- `com.posthog.android.internal`: `Bitmap.isValid()`, `Bitmap.webpBase64()` -- `com.posthog.android.replay.internal`: `LogLine`, `LogcatParser` +| No longer visible | Package | +| --- | --- | +| `CustomHeadersInterceptor` | `com.posthog.internal` | +| `PostHogPrintLogger` | `com.posthog.internal` | +| `PropertyGroupDeserializer` | `com.posthog.internal` | +| `PropertyValueDeserializer` | `com.posthog.internal` | +| `personPropertiesContext()` | `com.posthog.internal` | +| `PostHogPreferences.PUSH_SUBSCRIPTION_REJECTED` | `com.posthog.internal` | +| `ThrowableCoercer.fromThrowableToPostHogProperties()` | `com.posthog.internal.errortracking` | +| `RRDocumentNode` | `com.posthog.internal.replay` | +| `RRDomContentLoadedEvent` | `com.posthog.internal.replay` | +| `RRLoadedEvent` | `com.posthog.internal.replay` | +| `RRStyle` | `com.posthog.internal.replay` | +| `findBestTranslationMatch()` | `com.posthog.internal.surveys` | +| `Bitmap.isValid()` | `com.posthog.android.internal` | +| `Bitmap.webpBase64()` | `com.posthog.android.internal` | +| `LogLine` | `com.posthog.android.replay.internal` | +| `LogcatParser` | `com.posthog.android.replay.internal` | -If you call `PostHogRemoteConfig.loadFeatureFlags()` or `loadRemoteConfig()`, their callback parameters changed too. The internal callback is now `(errorsLoading: Boolean) -> Unit`, and the other is a `PostHogFeatureFlagsCallback`. +In `com.posthog.internal.replay`, `RRWireframe` keeps only `id`, `x`, `y`, `width`, `height`, `type`, and `base64`. -### Behavior changes +If you call `PostHogRemoteConfig.loadFeatureFlags()` or `loadRemoteConfig()`, their callback parameters changed too. The internal callback is `(errorsLoading: Boolean) -> Unit`, and the other is a `PostHogFeatureFlagsCallback`. -#### Feature flag payloads must be valid JSON +### Check flag events -A payload that isn't valid JSON now reads as `null` from `getFeatureFlagResult(key)?.payload` and `getAllFeatureFlags()`, instead of the raw string. With `debug` on, the SDK logs the flag key. +When a flag is missing, `$feature_flag_called` leaves out `$feature_flag_response`. -| Payload | 3.x | 4.0 | -| --- | --- | --- | -| Malformed (`{broken`, `[1, 2`), empty or whitespace-only | the raw string | `null` | -| Only valid in lenient mode (unquoted `hello`, single quotes, comments) | decoded leniently | `null` | -| JSON `null` | the string `"null"` | `null` | -| Valid JSON (`"hello"`, `""`, `false`, `0`, objects, arrays) | decoded | decoded, unchanged | -| Bootstrapped payloads | as passed | as passed, unchanged | +3.x.x sent `""` from `getFeatureFlag()` and `false` from `isFeatureEnabled()`, or your default value when you passed one. In 4.x.x an empty string means a flag with an empty variant, so a missing flag no longer reports one. -The flag's value, enabled state, variant and any other flag's payload aren't affected. +Insights, cohorts, and actions that filter on `$feature_flag_response = ""` or `false` to find missing flags stop matching new events without any error. Use an `is not set` filter on `$feature_flag_response` instead. -If you read a payload as plain text, such as a payload saved as `hello` rather than `"hello"`, update it in PostHog to valid JSON before you upgrade, or your code gets `null`. PostHog no longer saves a new payload that isn't valid JSON, so only payloads saved earlier are affected. +Events already stored keep their old values. -Apps upgrading from 3.13 or older didn't cache flag details, so until the app's first `/flags` response, a malformed payload cached by 3.x still reads as the raw string, as it did in 3.x. +### Check locale properties -#### Empty variants read as disabled +In 4.x.x, `$locale` means the first language in the device settings, as a full language tag such as `de-CH` or `zh-Hant-TW`. It's left out when the device reports no language. -A flag whose variant is an empty string now reads as disabled everywhere, as it already did from `isFeatureEnabled()`, with or without `defaultValue`. `getFeatureFlagResult()` and `getAllFeatureFlags()` return `enabled = false` for it, where 3.x returned `true`, `PostHogFeatureFlagsLoaded` leaves it out of `flags` and `variants`, and captured events leave it out of `$active_feature_flags`. `variant`, `getFeatureFlag()` and the event's `$feature/` property still return `""`. +In 3.x.x it came from `Locale.getDefault()`. That could be a secondary language, a per-app language, or a value your app set with `Locale.setDefault()`, and it dropped the script (`zh-TW`). -PostHog no longer accepts empty variants for new flags, so only flags created earlier through the API, MCP or Terraform are affected. `/flags` still returns `enabled: true` for them, and other PostHog SDKs can still report them as enabled, so rename the variant before you upgrade. +On older Android versions, 3.x.x also sent the legacy codes `iw`, `in`, and `ji`, so Hebrew, Indonesian, and Yiddish values change, such as `in-ID` to `id-ID`. Update filters that match those. -#### `$feature_flag_response` for a missing flag +Other values mostly stay the same, so otherwise only check filters if your users change these settings. -When a flag is missing, `$feature_flag_called` now leaves out `$feature_flag_response`. 3.x sent `""` from `getFeatureFlag()` and `false` from `isFeatureEnabled()`, or your default value when you passed one. In 4.0 an empty string means a flag with an empty variant, so a missing flag no longer reports one. +The new `$app_language` property is the language your app shows. Android has no API that reports it exactly, so what you get depends on the version: -Insights, cohorts and actions that filter on `$feature_flag_response = ""` or `false` to find missing flags stop matching new events without any error. Use an `is not set` filter on `$feature_flag_response` instead. Events already stored keep their old values. +| Android | `$app_language` | +|---|---| +| 13+ with `android:localeConfig` declared | The per-app language or the first device language | +| 13+ without `localeConfig` | The per-app language, if one is set | +| 6 to 12 | Not sent | -#### `$locale` and `$app_language` +You can declare `android:localeConfig` by hand or with AGP `generateLocaleConfig`. With it, the value is the per-app language or, without one, the first device language, as you declare it. -`$locale` now means the first language in the device settings, as a full language tag such as `de-CH` or `zh-Hant-TW`. In 3.x it came from `Locale.getDefault()`, which could be a secondary language, a per-app language or a value your app set with `Locale.setDefault()`, and it dropped the script (`zh-TW`). It's left out when the device reports no language. On older Android versions, 3.x also sent the legacy codes `iw`, `in` and `ji`, so Hebrew, Indonesian and Yiddish values change, such as `in-ID` to `id-ID`. Update filters that match those. Other values mostly stay the same, so otherwise only check filters if your users change these settings. +If you don't declare that language, the value is your `android:defaultLocale` (Android 15+) or your language if you only declare one. -The new `$app_language` property is the language your app shows. Android has no API that reports it exactly, so what you get depends on the version: +It's not sent if several of your declared languages could match, such as `pt` and `pt-PT` for a `pt-MZ` device, or if nothing matches and you declare several languages without a default. -| Android | `$app_language` | -|---|---| -| 13+ with `android:localeConfig` declared (by hand or with AGP `generateLocaleConfig`) | The per-app language or, without one, the first device language, as you declare it. If you don't declare that language, your `android:defaultLocale` (Android 15+) or your language if you only declare one. Not sent if several of your declared languages could match, such as `pt` and `pt-PT` for a `pt-MZ` device, or if nothing matches and you declare several languages without a default. | -| 13+ without `localeConfig` | The per-app language, if one is set. Otherwise not sent. | -| 6–12 | Not sent. | +On Android 13+ without `localeConfig`, it's not sent when no per-app language is set. + +The SDK reads both languages in the background when an event is captured and uses them from the next event on. The first event after a language change carries the previous value. -The SDK reads both languages in the background when an event is captured and uses them from the next event on, so the first event after a language change carries the previous value. Changing only the runtime override (`LocaleManager.setOverrideLocaleConfig`) isn't picked up until the device or per-app language changes; call `PostHog.setAppLanguage()` if your app changes it. +A change to only the runtime override (`LocaleManager.setOverrideLocaleConfig`) isn't picked up until the device or per-app language changes. Call `PostHog.setAppLanguage()` if your app changes it. -Strings you don't translate fall back per string, so the value is the app's language, not a guarantee for every string. Call `PostHog.setAppLanguage("de")` at startup and whenever the language changes to send it on every version, or if you translate some other way, such as with an in-app language setting. It's kept in memory only. +Strings you don't translate fall back per string, so the value is the app's language, not a guarantee for every string. -#### Session replay records screenshots +Call `PostHog.setAppLanguage("de")` at startup and whenever the language changes to send it on every version, or if you translate some other way, such as with an in-app language setting. It's kept in memory only. -4.0 removes wireframe session replay. Replay always records masked screenshots, which is what `screenshot = true` already did. +### Check session replay + +posthog-android 4.x.x removes wireframe session replay. Replay always records masked screenshots, which is what `screenshot = true` already did. Remove the `screenshot` option: ```kotlin -// 3.x +// 3.x.x config.sessionReplayConfig.screenshot = true -// 4.0: remove the line +// 4.x.x: remove the line ``` Apps that relied on the default now upload screenshots: -- Masking still covers text inputs, images, Compose semantics, `ph-no-capture` views and `Modifier.postHogMask()`. `WebView`s are masked whole while `maskAllTextInputs` or `maskAllImages` is on. -- Custom-drawn views and other content the SDK doesn't recognize, such as maps or video, can now appear in recordings. Mask them, or turn replay off with `sessionReplay = false`. -- Jetpack Compose screens, which wireframe captured as empty boxes, are now recorded. That can count against your replay quota and may need a consent or privacy disclosure update. -- Each frame uses more bandwidth and CPU than a wireframe. +- **Masking.** Masking still covers text inputs, images, Compose semantics, `ph-no-capture` views, and `Modifier.postHogMask()`. `WebView`s are masked whole while `maskAllTextInputs` or `maskAllImages` is on. +- **Unrecognized content.** Custom-drawn views and other content the SDK doesn't recognize, such as maps or video, can now appear in recordings. Mask them, or turn replay off with `sessionReplay = false`. +- **Jetpack Compose screens.** Wireframe captured them as empty boxes. 4.x.x records them. That can count against your replay quota and may need a consent or privacy disclosure update. +- **Frame cost.** Each frame uses more bandwidth and CPU than a wireframe. Compose masking also changed, including for apps that already set `screenshot = true`: -- `Modifier.postHogMask()` and `Modifier.postHogUnmask()` apply only to the element and its children, not to siblings merged into the same clickable row. -- Text that draws past its layout box is masked in full. -- Nodes using `Modifier.clearAndSetSemantics` are masked while text or image masking is on. Use `Modifier.postHogUnmask()` to show them. +- **Mask scope.** `Modifier.postHogMask()` and `Modifier.postHogUnmask()` apply only to the element and its children, not to siblings merged into the same clickable row. +- **Overflowing text.** Text that draws past its layout box is masked in full. +- **Cleared semantics.** Nodes that use `Modifier.clearAndSetSemantics` are masked while text or image masking is on. Use `Modifier.postHogUnmask()` to show them. A dialog's dim, and a dialog masked whole on Android 8.1 and lower, are sent as screenshot images instead of styled wireframe shapes. -The `$sdk_debug_replay_capture_mode` property is now always `screenshot`. +The `$sdk_debug_replay_capture_mode` property is always `screenshot`. -#### Deep link query parameters +### Check deep links -The `Deep Link Opened` event leaves out query parameters whose name starts with `$`, such as `$process_person_profile`, so a link can't set PostHog's own properties. Other parameters and the `url` property are sent as in 3.x. +The `Deep Link Opened` event leaves out query parameters whose name starts with `$`, such as `$process_person_profile`, so a link can't set PostHog's own properties. -#### Other changes that don't fail the build +Other parameters and the `url` property are sent as in 3.x.x. -The code you end up with after these two migrations compiles, so they're easy to miss: +### Check dropped events -- [`getFeatureFlagResult()` sends `$feature_flag_called` by default](#getfeatureflagpayload), unlike `getFeatureFlagPayload()`. -- [Apps that set `remoteConfig = false` now load `/config`](#remoteconfig) and apply its settings. +Capture v1 checks each event on its own and drops only the invalid ones, so the rest of the batch is delivered. In 3.x.x, an empty event name or distinct ID made legacy capture reject the whole batch it was in. -### Endpoints +- **Empty names.** The SDK drops an event whose name is empty before sending it, for example `capture("")` or one `beforeSend` renames to `""`. With `debug` on, it logs this once. +- **Empty distinct IDs.** PostHog drops an event with an empty or whitespace-only distinct ID, for example one `beforeSend` sets to `""`. +- **Long names.** PostHog drops an event whose name is over 200 UTF-8 bytes. Legacy capture had no limit on event name length. +- **Long distinct IDs.** PostHog drops an event whose distinct ID is over 200 UTF-8 bytes (see [Shorten long IDs](#shorten-long-ids)). +- **Empty IDs in `identify()`.** `identify()` with an empty or whitespace-only distinct ID is still ignored, as in 3.x.x. +- **Option values.** The SDK sends option values as given. PostHog reads common forms of a value, such as `"false"` or `0` for a boolean, and drops an event whose option value it can't read. -| Data | 3.x | 4.0 | -| --- | --- | --- | -| Analytics events | `/batch` | `/i/v1/analytics/events` | -| Session replay | `/s/` | `/s/`, unchanged | -| AI events (`captureAi`) | – | `/i/v1/ai/events` (see [AI events](#ai-events)) | -| Logs | `/i/v1/logs` | `/i/v1/logs`, unchanged | -| Feature flags | `/flags` | `/flags`, unchanged | +The SDK checks only the event name before sending. For the other checks, PostHog drops the event, and the SDK removes it from the queue. -Capture v1 requests send the project token in an `Authorization: Bearer ` header instead of an `api_key` body field. -This header replaces any `Authorization` header you set in `PostHogConfig.requestHeaders`, so authenticate your proxy with a different header, such as `X-Proxy-Token`. -Other requests still send your `Authorization` header. +There's no error callback, as in 3.x.x. The SDK reports dropped and failed events only in its debug log (see [Update log checks](#update-log-checks)). -Analytics requests are gzipped unless you set `compression` to `PostHogCompression.NONE`, as in 3.x. +The SDK sends these events and changes the value: -A personal API key (`phx_...`) in `projectToken` now disables the SDK at setup, as an empty or whitespace-only token does. Both print why, even when `debug` is off. To turn the SDK off in tests, use an empty token. -In 3.x, the SDK started and PostHog rejected every event with a 401. Use your project token (`phc_...`). +- **`NaN` and infinite numbers.** A `NaN` or infinite number in the properties is dropped from the event, and the event is sent without it. +- **Map keys.** A map key in the properties that isn't a string is converted to one when it's a number, a boolean, or `null`. Any other key is dropped with its value, and the rest of the event is sent. With `debug` on, the SDK logs the key's type. In 3.x.x, a nested map with a non-string key lost the whole event. +- **`null` elements.** A `null` element in a list or array in the properties is sent as JSON `null` at its position. So is an element that can't be serialized, such as `NaN`. In 3.x.x, both were removed, which moved the later elements to lower indexes. A property or map entry whose value is `null` is still left out. +- **Empty `distinctId` arguments.** An empty or whitespace-only `distinctId` argument to `capture` uses the current distinct ID, like `null`. In 3.x.x, the event was dropped. -#### Hosts without capture v1 +### Update log checks -If you self-host PostHog, make sure `/i/v1/analytics/events` is served before you upgrade, and `/i/v1/ai/events` if you use `captureAi`. -PostHog Cloud (`us.i.posthog.com`, `eu.i.posthog.com`) serves it. +Update any log-based checks that match the 3.x.x text. -If you send events through your own reverse proxy, update it before you upgrade: +- **Batch results.** With `debug` on, the SDK logs one line per batch. The line says how many events PostHog dropped, how many duplicate copies it dropped, and how many it asked to retry. It has the reasons PostHog gave, never the event names or properties. +- **Queued events.** The SDK no longer logs a line for each queued event. +- **Capture requests.** Debug logs for capture requests name the event count and the response status. They no longer print the request and response bodies. +- **Hook errors.** When a `beforeSend` hook throws, the debug log names the event and the exception type, not the exception message. The message can hold the data the hook was removing. In 3.x.x it printed the exception. +- **Values that can't be serialized.** When a property value can't be serialized, the debug log names the key and the value's type, not the value. In 3.x.x it printed the value. -- Forward `/i/v1/analytics/events` and `/i/v1/ai/events` to PostHog. -- Pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged. PostHog answers `401` without `Authorization` and `400` without the others, and the events are dropped. If your proxy strips other credentials, keep `Authorization` values that start with `Bearer phc_`, `Bearer phs_` or `Bearer phx_`, plus the exact `Bearer ` of an older key without a prefix. -- Accept request bodies up to 20 MB. AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx. A `413` from the proxy makes the SDK halve the batch until it fits, and drops an event that doesn't fit on its own. -- Pass PostHog's response body through unchanged. A 2xx response whose body isn't PostHog's `{"results": {...}}` drops the events instead of retrying them. +### Check property precedence -PostHog's managed reverse proxy already does this and needs no change. A proxy set up from PostHog's [proxy guides](https://posthog.com/docs/advanced/proxy) before 29 October 2026 strips `Authorization`, so PostHog answers `401` and the events are dropped. Update it from the current guide. +An event's properties are merged in this order, and later values win: -The SDK doesn't fall back to `/batch`. A 404 is retried, so the events stay queued until the path is served, and the SDK prints one warning, even with `debug` off. Any other error status that isn't retried, such as 403 or 405, drops the events. +1. Properties the SDK sets itself, such as `$os_name`, `$app_version`, `$screen_name`, `$is_identified`, `$session_id`, and the session replay debug properties (`$recording_status`, `$sdk_debug_*`). +2. Registered super properties (`register`). +3. The properties you pass to `capture` or another event-sending method. `userProperties`, `userPropertiesSetOnce`, and `groups` are placed as `$set`, `$set_once`, and `$groups` here. When you also pass that key in properties, the arguments win key by key. A `$groups` map in properties adds to the groups set with `group()` instead of replacing them. +4. `beforeSend`. -#### Redirects +These changes follow from this order: -The SDK follows a 307 or 308 redirect only to the origin of `host` (same scheme, host and port), at most 5 times, and resends the same body and headers. -Any other redirect is not followed and the events are dropped. -In 3.x, OkHttp followed redirects to any host. -If a proxy redirects capture requests to another host, point `host` at the final host. -This also applies when you set your own `httpClient`: for capture requests, the SDK turns off its redirect following and OkHttp's connection retries, and keeps your other settings. Other requests, such as session replay and logs, behave as in 3.x. +- **SDK values.** In 3.x.x, the SDK's own values won over super properties. `$is_identified`, `$process_person_profile`, and the session replay debug properties also won over the properties you pass. In 4.x.x a value you register or pass wins. For example, `register("\$os_name", "custom")` sends every event with that value. +- **Session IDs.** A registered `$session_id` overrides the SDK's session ID, which can detach events from their session replay. +- **Blank values.** A caller `$screen_name` or `$session_id` still replaces the SDK's value even when it's blank, as in 3.x.x, so a blank `$session_id` is sent as an empty `session_id`. +- **Merged maps.** In 3.x.x, a `$set`, `$set_once`, or `$groups` map in properties replaced the per-call values and the groups set with `group()`. A `$set` or `$set_once` you pass, or `userProperties`, still replaces a registered one whole. -### Event validation +`$lib` and `$lib_version` name the library that produced the event. The SDK fills them last, as a pair, only where nothing above named the library: -Capture v1 checks each event on its own and drops only the invalid ones, so the rest of the batch is delivered. +| You set | The SDK sends | +| --- | --- | +| Neither, or only `$lib_version` | Its own `$lib` and `$lib_version` | +| `$lib` as the SDK's own name, without a version | Your `$lib`, and it adds its version | +| `$lib` as another library's name | Both as they are | -The SDK drops an event whose name is empty before sending it, for example `capture("")` or one `beforeSend` renames to `""`. -With `debug` on, it logs this once. +When `$lib` names another library, the SDK never adds its own version, so set both keys together. -There's no error callback, as in 3.x. The SDK reports dropped and failed events only in its debug log. +In 3.x.x, a registered `$lib` or `$lib_version` was replaced by the SDK's, and a `$lib` you passed was sent with the SDK's `$lib_version`. -The SDK doesn't check the rest before sending. PostHog drops the event, and the SDK removes it from the queue. -With `debug` on, the SDK logs one line per batch with how many events PostHog dropped, how many duplicate copies it dropped and how many it asked to retry, with the reasons PostHog gave, never the event names or properties. -It no longer logs a line for each queued event. -Debug logs for capture requests name the event count and the response status, and no longer print the request and response bodies. -When a `beforeSend` hook throws, the debug log names the event and the exception type, not the exception message, which can hold the data the hook was removing. In 3.x it printed the exception. -When a property value can't be serialized, the debug log names the key and the value's type, not the value. In 3.x it printed the value. -Update any log-based checks that match the 3.x text. +### Check session IDs -- An event with an empty or whitespace-only distinct ID is dropped, for example one `beforeSend` sets to `""`. -- An event whose name is over 200 UTF-8 bytes is dropped. Legacy capture had no limit on event name length. -- An event whose distinct ID is over 200 UTF-8 bytes is dropped. Legacy capture shortened the ID to 200 characters and kept the event. +Capture v1 sends `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, not as properties. The SDK moves them out of `properties` for you, by the value's type: -In 3.x, an empty event name or distinct ID made legacy capture reject the whole batch it was in. +- **A string.** The SDK sends it unchanged, including an empty string. +- **`null`.** It counts as unset, and the SDK removes it without a log. +- **Any other value.** The SDK removes it and doesn't send it. With `debug` on, the SDK logs the key and the value's JSON type, never the value. -A `NaN` or infinite number in the properties is dropped from the event, and the event is sent without it. +In PostHog, the events still have `$session_id` and `$window_id`, so insights, filters, and session replay work as before. -A map key in the properties that isn't a string is converted to one when it's a number, a boolean or `null`. Any other key is dropped with its value, and the rest of the event is sent. With `debug` on, the SDK logs the key's type. In 3.x, a nested map with a non-string key lost the whole event. +### Review beforeSend hooks -A `null` element in a list or array in the properties is now sent as JSON `null` at its position, and so is an element that can't be serialized, such as `NaN`. In 3.x, both were removed, which moved the later elements to lower indexes. A property or map entry whose value is `null` is still left out. +Review your `beforeSend` hooks for the new event shape. Capture v1 reads processing settings from an `options` object sent next to `properties`, and `beforeSend` can read and change `PostHogEvent.options`. -The distinct ID can come from `identify()`, the `distinctId` argument of `capture` or `beforeSend`. -If you identify users with a long ID, such as a JWT or a long email address, shorten or hash it before you upgrade. Otherwise every event for that user is dropped. -`identify()` with an empty or whitespace-only distinct ID is still ignored, as in 3.x. +- **Person processing.** In 3.x.x, the SDK marked person processing with the `$process_person_profile` property. In 4.x.x, it's the `process_person_profile` option, and the property isn't set. To change person processing in `beforeSend`, edit `event.options`. +- **Properties a hook adds.** A `$process_person_profile` property the hook adds only fills an option that is still unset. It doesn't override the `false` the SDK set for an anonymous event. +- **New option maps.** A hook that assigns a new map to `event.options` without keeping that key loses the `false` the SDK set. That turns person processing on for anonymous users, overriding `personProfiles`. Editing `event.options` in place keeps it. +- **Copies.** `beforeSend` gets its own copy of the event's nested maps, lists, and arrays, in `properties` and `options`. Changes a hook makes no longer reach the objects you passed to `capture` or registered, and identity checks against them (`===`) no longer match. In 3.x.x, hooks edited the caller's objects. +- **Returned events.** `options` is a property of `PostHogEvent`, not a constructor parameter, so the constructor and `copy` are unchanged from 3.x.x. When `beforeSend` returns a different event whose `options` is `null`, such as one made with `event.copy(…)` or the constructor, it gets the options of the event the hook was given. To send an event with no options, set `options` to an empty map. +- **Event uuids.** The event `beforeSend` returns keeps the uuid of the capture it came from. A uuid you set in `beforeSend`, for example with `copy(uuid = …)`, is replaced. A hook that returns an event kept from an earlier call still sends one uuid per capture. +- **Timing.** `beforeSend` still runs when you capture the event, before it's queued, not when the batch is sent. -### Property precedence +### Check person processing -An event's properties are merged in this order, and later values win: +- **The SDK's value.** When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither the option nor the property, since PostHog processes person profiles by default. In 3.x.x, every event carried a `$process_person_profile` property. +- **One event.** To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. +- **Every event.** A registered `$process_person_profile` changes it for every event. In 3.x.x, the SDK's value replaced a registered `$process_person_profile`, so a registered `false` had no effect. +- **A registered `false`.** In 4.x.x it applies, also after `identify` and with `PersonProfiles.ALWAYS`. Those events don't change the person profile, and their `$set` is ignored. They are still linked to the person and billed as identified events. +- **`PersonProfiles.NEVER`.** A `process_person_profile` option or `$process_person_profile` property set to `true`, passed or registered, turns person processing on for that event. In 3.x.x, `NEVER` always won. If you rely on `NEVER` to keep events personless, make sure neither is set to `true`, or remove it in `beforeSend`. +- **`PersonProfiles.IDENTIFIED_ONLY`.** `identify`, `alias`, `group`, and `setPersonProperties` still turn on person processing for the user's later events, as in 3.x.x. +- **Duplicate checks.** A `$set` sent with `process_person_profile: false` doesn't update the person, so it no longer suppresses a later `setPersonProperties` or `identify` call with the same properties as a duplicate. -1. properties the SDK sets itself, such as `$os_name`, `$app_version`, `$screen_name`, `$is_identified`, `$session_id` and the session replay debug properties (`$recording_status`, `$sdk_debug_*`) -2. registered super properties (`register`) -3. the properties you pass to `capture` or another event-sending method; `userProperties`, `userPropertiesSetOnce` and `groups` are placed as `$set`, `$set_once` and `$groups` here, and when you also pass that key in properties they win key by key; a `$groups` map in properties adds to the groups set with `group()` instead of replacing them -4. `beforeSend` +A registered `$process_person_profile` set to `false` also reaches the events `identify`, `alias`, `group`, and `setPersonProperties` send. -In 3.x, the SDK's own values won over super properties, and `$is_identified`, `$process_person_profile` and the session replay debug properties also won over the properties you pass. -In 4.0 a value you register or pass wins, for example `register("\$os_name", "custom")` sends every event with that value. -A registered `$session_id` now overrides the SDK's session ID, which can detach events from their session replay. -A caller `$screen_name` or `$session_id` still replaces the SDK's value even when it's blank, as in 3.x, so a blank `$session_id` is sent as an empty `session_id`. -In 3.x, a `$set`, `$set_once` or `$groups` map in properties replaced the per-call values and the groups set with `group()`. A `$set` or `$set_once` you pass, or `userProperties`, still replaces a registered one whole. +PostHog accepts `$identify`, `$create_alias`, and `$groupidentify` and then drops them with an ingestion warning, and the SDK doesn't report it. A `$set` event is kept, but the person isn't updated. -`$lib` and `$lib_version` name the library that produced the event, and the SDK fills them last, as a pair, only where nothing above named the library. -When neither is set, or only `$lib_version` is, the SDK sends its own `$lib` and `$lib_version`. -When `$lib` is the SDK's own name without a version, the SDK adds its version. -When `$lib` names another library, the SDK leaves both as they are and never adds its own version, so set both keys together. -In 3.x, a registered `$lib` or `$lib_version` was replaced by the SDK's, and a `$lib` you passed was sent with the SDK's `$lib_version`. +To keep identifying, pass the option on the call, or set it in `beforeSend`: -### Session and window IDs +```kotlin +PostHog.register("\$process_person_profile", false) -Capture v1 sends `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, not as properties. -The SDK moves them out of `properties` for you. -A string value, including an empty string, is sent unchanged. -Any other value is removed and not sent. With `debug` on, the SDK logs the key and the value's JSON type, never the value. -A null value counts as unset and is removed without a log. -In PostHog, the events still have `$session_id` and `$window_id`, so insights, filters and session replay work as before. +PostHog.identify( + distinctId = "user-123", + userProperties = mapOf("plan" to "pro"), + options = mapOf("process_person_profile" to true), +) +``` -### Timestamps and IDs +If you registered `false` to skip person profiles for anonymous users, remove it. `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, the default, already does that and still lets `identify` create the person. -The SDK sends every timestamp in UTC with 3 fractional digits, for example `2026-01-01T00:00:00.000Z`, as 3.x did. -It doesn't check for future timestamps. PostHog replaces a timestamp more than 23 hours ahead with the time it received the event. -Event uuids and anonymous distinct IDs are UUID v7, as in 3.x. An anonymous ID you change with `getAnonymousId` is sent as you return it. -Each capture request also sends a UUID v7 request ID in the `PostHog-Request-Id` header, which 3.x didn't send. +To create no person profiles at all, set `personProfiles = PersonProfiles.NEVER` instead. The SDK then skips these calls. -### Event options +### Check retries -Capture v1 reads processing settings from an `options` object sent next to `properties`. -`capture` takes a new `options` argument, and `beforeSend` can read and change `PostHogEvent.options`. -`screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException` take the same argument, as their last parameter. -For `identify`, the options apply to the `$identify` or `$set` event the call sends. +These apply to analytics and AI event requests, unless a bullet names session replay or logs. Session replay and logs keep their 3.x.x status handling: they still retry 3xx and don't retry 404. + +- **Statuses retried.** The SDK retries network errors and 404, 408, 429, 500, 502, 503, and 504 responses. Other statuses drop the events, including 3xx. 3.x.x also retried 3xx responses, and didn't retry 404. +- **Billing limits and quotas.** A 402 (billing limit) drops the whole batch. A product quota, such as for exceptions or AI events, drops only those events inside a 200 response. +- **Partial retries.** When the response asks to retry only some events, the SDK keeps those events queued and removes the rest. +- **Resent requests.** A failed request is resent with the same events, request ID, and `created_at`, and the next attempt number, before newer events are sent. The request ID and attempt number reset after an app restart. OkHttp doesn't retry capture requests on its own. +- **The `Retry-After` cap.** A `Retry-After` header sets the minimum wait before the next send, up to 30 seconds. This also applies to session replay and logs. In 3.x.x there was no cap. +- **`Retry-After` formats.** `Retry-After` can be a number of seconds or an HTTP date. 3.x.x read only a number of seconds. +- **Backoff.** After a failed send, the wait before the next one doubles from 1 second up to 30 seconds, with up to 25% random jitter at millisecond precision. In 3.x.x it doubled without jitter and a `Retry-After` replaced it. This applies to events, session replay, and logs. +- **Retry limit.** Event, session replay, and log retries have no limit, as in 3.x.x. Queued records stay until they're delivered or a full queue evicts them (`maxQueueSize`, or `logs.maxBufferSize` for logs). +- **`maxRetries`.** `maxRetries` is renamed to `pushNotificationSubscriptionMaxRetries`, with no deprecated alias. It only limits push-notification subscription retries. +- **Request size.** A request carries at most `maxBatchSize` events and about 5 MiB. The SDK sends as soon as about 5 MiB of events is queued, even before `flushAt` is reached. In 3.x.x, batches were limited by event count only. +- **Event size.** There's no size limit for one analytics event in the SDK, as in 3.x.x. An event larger than about 5 MiB is sent in a request of its own. +- **413 responses.** A 413 still halves the batch until it fits, as in 3.x.x. An event that gets a 413 on its own is dropped. + +## Follow ups + +### Move to event options + +Capture v1 reads processing settings from an `options` object sent next to `properties`. `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group`, and `captureException` take an `options` argument. For `identify`, the options apply to the `$identify` or `$set` event the call sends. + +Pass an option in `options` instead of its `$`-prefixed property: ```kotlin -// 3.x +// 3.x.x PostHog.capture("signed_up", properties = mapOf("\$cookieless_mode" to true)) -// 4.0 +// 4.x.x PostHog.capture("signed_up", options = mapOf("cookieless_mode" to true)) ``` -Kotlin callers that use named or positional arguments for the existing parameters keep compiling. -Java callers pass the new trailing `options` argument, or `null`. -Classes that implement `PostHogInterface` add the parameter. -`identify(distinctId, userProperties, userPropertiesSetOnce)` moved from `PostHogCoreInterface` to `PostHogStatelessInterface`; call it through `PostHogInterface` or `PostHogStatelessInterface`. - -The legacy option properties, the `$`-prefixed properties legacy capture reads as settings, still work. -When the event is sent, the SDK removes each one from `properties` and uses it for its option: +The legacy option properties still work. They're the `$`-prefixed properties legacy capture reads as settings. When the event is sent, the SDK removes each one from `properties` and uses it for its option: | Legacy option property | Option | | --- | --- | @@ -485,40 +692,20 @@ When the event is sent, the SDK removes each one from `properties` and uses it f | `$ignore_sent_at` | `disable_skew_correction` | | `$product_tour_id` | `product_tour_id` | -- An option you pass to any of these methods or set in `beforeSend` wins over its legacy property. An option set to `null` counts as unset, so the legacy property fills it. -- To change person processing in `beforeSend`, edit `event.options`. A `$process_person_profile` property the hook adds only fills an option that is still unset, so it doesn't override the `false` the SDK set for an anonymous event. -- When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither, because PostHog processes person profiles by default. In 3.x, every event carried a `$process_person_profile` property. To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. A registered `$process_person_profile` changes it for every event. In 3.x, the SDK's value replaced a registered `$process_person_profile`, so a registered `false` had no effect. In 4.0 it applies, also after `identify` and with `PersonProfiles.ALWAYS`: those events don't change the person profile, and their `$set` is ignored. They are still linked to the person and billed as identified events. -- This also applies with `personProfiles = PersonProfiles.NEVER`: a `process_person_profile` option or `$process_person_profile` property set to `true`, passed or registered, turns person processing on for that event. In 3.x, `NEVER` always won. If you rely on `NEVER` to keep events personless, make sure neither is set to `true`, or remove it in `beforeSend`. -- Review your `beforeSend` hooks for the new event shape. In 3.x, the SDK marked person processing with the `$process_person_profile` property. In 4.0, it's the `process_person_profile` option, and the property isn't set. A hook that assigns a new map to `event.options` without keeping that key loses the `false` the SDK set. That turns person processing on for anonymous users, overriding `personProfiles`. Editing `event.options` in place keeps it. -- `beforeSend` gets its own copy of the event's nested maps, lists and arrays, in `properties` and `options`. Changes a hook makes no longer reach the objects you passed to `capture` or registered, and identity checks against them (`===`) no longer match. In 3.x, hooks edited the caller's objects. -- `options` is a property of `PostHogEvent`, not a constructor parameter, so the constructor and `copy` are unchanged from 3.x. When `beforeSend` returns a different event whose `options` is `null`, such as one made with `event.copy(…)` or the constructor, it gets the options of the event the hook was given. To send an event with no options, set `options` to an empty map. -- A `$set` sent with `process_person_profile: false` doesn't update the person, so it no longer suppresses a later `setPersonProperties` or `identify` call with the same properties as a duplicate. -- The SDK sends option values as given. PostHog reads common forms of a value, such as `"false"` or `0` for a boolean, and drops an event whose option value it can't read. -- Other option keys are sent unchanged, and PostHog ignores keys it doesn't know. -- There are no global or context options. To set an option on every event, register its legacy property, for example `register("\$cookieless_mode", true)`. -- There's no setting for GeoIP lookup or `historical_migration` on events, as in 3.x. -- With `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, `identify`, `alias`, `group` and `setPersonProperties` still turn on person processing for the user's later events, as in 3.x. -- A registered `$process_person_profile` set to `false` also reaches the events `identify`, `alias`, `group` and `setPersonProperties` send. PostHog accepts `$identify`, `$create_alias` and `$groupidentify` and then drops them with an ingestion warning, and the SDK doesn't report it. A `$set` event is kept, but the person isn't updated. To keep identifying, pass the option on the call, or set it in `beforeSend`: - - ```kotlin - PostHog.register("\$process_person_profile", false) - - PostHog.identify( - distinctId = "user-123", - userProperties = mapOf("plan" to "pro"), - options = mapOf("process_person_profile" to true), - ) - ``` - - If you registered `false` to skip person profiles for anonymous users, remove it: `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, the default, already does that and still lets `identify` create the person. To create no person profiles at all, set `personProfiles = PersonProfiles.NEVER` instead. The SDK then skips these calls. -- An empty or whitespace-only `distinctId` argument to `capture` now uses the current distinct ID, like `null`. In 3.x, the event was dropped. -- The event `beforeSend` returns keeps the uuid of the capture it came from. A uuid you set in `beforeSend`, for example with `copy(uuid = …)`, is replaced, so a hook that returns an event kept from an earlier call still sends one uuid per capture. -- Events still queued on disk by 3.x are sent to capture v1 after the update, with their legacy properties moved to options. - -### AI events - -4.0 adds `captureAi`, which sends AI events, such as `$ai_generation`, to PostHog's AI endpoint (`/i/v1/ai/events`) instead of the analytics endpoint. -It takes the same arguments as `capture`, and the events go through the same `beforeSend` hooks. +An option you pass to any of these methods or set in `beforeSend` wins over its legacy property. An option set to `null` counts as unset, so the legacy property fills it. + +- **Other keys.** Other option keys are sent unchanged, and PostHog ignores keys it doesn't know. +- **Every event.** There are no global or context options. To set an option on every event, register its legacy property, for example `register("\$cookieless_mode", true)`. +- **GeoIP and migrations.** To turn off GeoIP lookup, set `disableGeoIp`. It sends `$geoip_disable` as an event property, not an option. There's no setting for `historical_migration` on events, as in 3.x.x. +- **Queued events.** Events still queued on disk by 3.x.x are sent to capture v1 after the update, with their legacy properties moved to options. + +### Send AI events with captureAi + +`captureAi` sends AI events, such as `$ai_generation`, to PostHog's AI endpoint (`/i/v1/ai/events`) instead of the analytics endpoint. `capture` never sends events to the AI endpoint, even ones named `$ai_*`. + +`$ai_*` events you keep sending with `capture` still reach PostHog through the analytics endpoint, as in 3.x.x. Moving them to `captureAi` gets you the AI endpoint's much larger event size limit, and a queue of their own, so large AI events don't hold up your other events. + +`captureAi` takes the same arguments as `capture`, and the events go through the same `beforeSend` hooks: ```kotlin PostHog.captureAi( @@ -527,63 +714,14 @@ PostHog.captureAi( ) ``` -- `captureAi` returns the event's uuid, or `null` when the event isn't queued: the SDK is disabled or opted out, the event name is empty, `beforeSend` dropped it, or it's over the size limit. Once 100 AI events (`captureAiMaxQueueSize`) or 50 MiB are queued, including events still waiting to be written to disk during a slow upload, the oldest are dropped. -- An AI event's properties can be up to 8 MiB. The SDK drops a serialized event over 8 MiB + 64 KiB, measured before `encryption`. With `debug` on, it logs the event name and the limit, never the content. Set `captureAiMaxEventBytes` to lower that limit; a larger value uses 8 MiB + 64 KiB, and with `debug` on the SDK logs that it did. -- PostHog drops an event sent with `captureAi` whose name doesn't start with `$ai_`. `capture` never sends events to the AI endpoint, even ones named `$ai_*`. -- AI requests time out after 60 seconds without network activity, or `captureAiTimeout`. Other requests keep OkHttp's 10-second defaults. -- On Android, AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. -- `flush()` and `close()` also send the AI queue. On Android, AI events left on disk are sent at the next launch. -- AI requests are gzipped unless you set `captureAiCompression` to `PostHogCompression.NONE`. `compression` doesn't apply. -- AI events use `flushAt`, `maxBatchSize` and `flushIntervalSeconds`, like other events. A request carries up to about 5 MiB, as for analytics events (see [Retries](#retries)). -- The SDK sends AI events unchanged. It doesn't redact or truncate prompts, outputs or media, so use `beforeSend` to remove anything you don't want to send. - -### Retries - -These apply to analytics and AI event requests, unless a bullet names session replay or logs. Session replay and logs keep their 3.x status handling: they still retry 3xx and don't retry 404. - -- The SDK retries network errors and 404, 408, 429, 500, 502, 503 and 504 responses. Other statuses drop the events, including 3xx, and a 402 (billing limit) drops the whole batch. A product quota, such as for exceptions or AI events, drops only those events inside a 200 response. 3.x also retried 3xx responses, and didn't retry 404. -- When the response asks to retry only some events, the SDK keeps those events queued and removes the rest. -- A failed request is resent with the same events, request ID and `created_at`, and the next attempt number, before newer events are sent. The request ID and attempt number reset after an app restart. OkHttp doesn't retry capture requests on its own. -- A `Retry-After` header sets the minimum wait before the next send, up to 30 seconds. This also applies to session replay and logs. In 3.x there was no cap. -- `Retry-After` can be a number of seconds or an HTTP date. 3.x read only a number of seconds. -- After a failed send, the wait before the next one doubles from 1 second up to 30 seconds, with up to 25% random jitter at millisecond precision. In 3.x it doubled without jitter and a `Retry-After` replaced it. This applies to events, session replay and logs. -- Event, session replay and log retries have no limit, as in 3.x: queued records stay until they're delivered or a full queue evicts them (`maxQueueSize`, or `logs.maxBufferSize` for logs). -- `maxRetries` is renamed to `pushNotificationSubscriptionMaxRetries`, with no deprecated alias. It only limits push-notification subscription retries. -- A request carries at most `maxBatchSize` events and about 5 MiB, and the SDK sends as soon as about 5 MiB of events is queued, even before `flushAt` is reached. In 3.x, batches were limited by event count only. -- There's no size limit for one analytics event in the SDK, as in 3.x. An event larger than about 5 MiB is sent in a request of its own. -- A 413 still halves the batch until it fits, as in 3.x. An event that gets a 413 on its own is dropped. -- `beforeSend` still runs when you capture the event, before it's queued, not when the batch is sent. - -### New: `onFeatureFlags()` - -`onFeatureFlags()` is now the way to listen for flag loads, for example from a screen or a library. You can remove the listener later: - -```kotlin -val subscription = PostHog.onFeatureFlags { loaded -> - if (loaded.variants["new-checkout"] == "test") { - showTestVariant() - } -} - -// later -subscription.unsubscribe() -``` - -On Android, listeners run on the main thread. If flags have already loaded, a new listener also gets the current values shortly after it registers. You can register before `setup()`, and listeners stay registered across `close()` and `setup()`. - -### `posthog-server` - -`posthog-server` isn't having a major release, and its API is unchanged: it keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` now ships in `posthog-server` itself. None of the API changes above apply to it. `PostHogEvent`, which `beforeSend` gets, keeps its 3.x constructor and `copy`, and gains an `options` property; `posthog-server` still sends to `/batch`, which doesn't use it, so a value set in `beforeSend` is sent but has no effect. - -It still sends events to `/batch`, not to capture v1, so the endpoint, proxy, retry and event option changes above don't apply to it either. - -Using core `posthog` on its own through `PostHogStateless.with` isn't a supported entry point in core 7.0. Without its own queue it gets Android's capture v1 behavior, including the persisted-queue retries, which isn't a server-side contract. Use `posthog-server` for server-side JVM apps. A class that extends `PostHogStateless` also needs updating: the protected `buildEvent()` gained `options` and `uuid` parameters, and `captureFeatureFlagCalledEvent()` is no longer protected. - -A personal API key (`phx_...`) in `projectToken` now disables the client at setup, as an empty token does, and both print why even when `debug` is off. - -Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. A `null` element in a list or array in the properties is sent as JSON `null` at its position instead of being removed. `beforeSend` gets its own copy of the event's nested maps, lists and arrays, so its changes no longer reach the objects you passed to `capture`. - -`posthog-server` 2.25.0 depends on core 7.0, so upgrade it and `posthog-android` together: - -- If your project uses `posthog-android` 4.0 or core 7.0, use `posthog-server` 2.25.0 or later. Older `posthog-server` versions aren't compatible with core 7.0 at runtime. -- If your project still uses `posthog-android` 3.x, stay on `posthog-server` 2.24.x. `posthog-server` 2.25 brings in core 7.0, and Gradle then upgrades `posthog-android` to 4.0. +- **Return value.** `captureAi` returns the event's uuid, or `null` when the event isn't queued. That happens when the SDK is disabled or opted out, the event name is empty, `beforeSend` dropped it, or it's over the size limit. +- **Queue limits.** Once 100 AI events (`captureAiMaxQueueSize`) or 50 MiB are queued, the oldest are dropped. The count includes events still waiting to be written to disk during a slow upload. +- **Event size.** An AI event's properties can be up to 8 MiB. The SDK drops a serialized event over 8 MiB + 64 KiB, measured before `encryption`. With `debug` on, it logs the event name and the limit, never the content. +- **A lower size limit.** Set `captureAiMaxEventBytes` to lower that limit. A larger value uses 8 MiB + 64 KiB, and with `debug` on the SDK logs that it did. +- **Event names.** PostHog drops an event sent with `captureAi` whose name doesn't start with `$ai_`. +- **Timeouts.** AI requests time out after 60 seconds without network activity, or `captureAiTimeout`. Other requests keep OkHttp's 10-second defaults. +- **Disk queue.** On Android, AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. +- **Flushing.** `flush()` and `close()` also send the AI queue. On Android, AI events left on disk are sent at the next launch. +- **Compression.** AI requests are gzipped unless you set `captureAiCompression` to `PostHogCompression.NONE`. `compression` doesn't apply. +- **Batching.** AI events use `flushAt`, `maxBatchSize`, and `flushIntervalSeconds`, like other events. A request carries up to about 5 MiB, as for analytics events (see [Check retries](#check-retries)). +- **Content.** The SDK sends AI events unchanged. It doesn't redact or truncate prompts, outputs, or media, so use `beforeSend` to remove anything you don't want to send. diff --git a/README.md b/README.md index aed9912d9..15549dc76 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,10 @@ | Packages | Maven Central | Min Version | |-----------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | posthog-android | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android) | Android API 23 | -| posthog-android-surveys-compose | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-surveys-compose/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-surveys-compose) | Android API 23 · `0.x` | +| posthog-android-surveys-compose | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-surveys-compose/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-surveys-compose) | Android API 23 · `0.x.x` | | posthog (core) | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog) | Java 8 | | posthog-server | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-server/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-server) | Java 8 | -| posthog-server-openfeature | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-server-openfeature/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-server-openfeature) | Java 11 · `0.x` | +| posthog-server-openfeature | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-server-openfeature/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-server-openfeature) | Java 11 · `0.x.x` | | posthog-android-gradle-plugin | [![Maven Central](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-gradle-plugin/badge.svg)](https://maven-badges.herokuapp.com/sonatype-central/com.posthog/posthog-android-gradle-plugin) | Java 8 | # PostHog Android and JVM SDKs @@ -21,7 +21,7 @@ SDK usage examples and code snippets live in the official documentation so they - [Android library docs](https://posthog.com/docs/libraries/android) - [Java/JVM library docs](https://posthog.com/docs/libraries/java) -- [Migrating from 3.x to 4.0](MIGRATION.md) +- [Migrating posthog-android from 3.x.x to 4.0.0](MIGRATION.md) ## Required dependencies diff --git a/bin/docs_scripts/generate_markdown.py b/bin/docs_scripts/generate_markdown.py index d95ba8026..fe946cf6f 100644 --- a/bin/docs_scripts/generate_markdown.py +++ b/bin/docs_scripts/generate_markdown.py @@ -230,6 +230,15 @@ def nest(markdown: str) -> str: return "\n".join(out) +def migration_page(guide: str) -> list[str]: + """The migration page. The guide's H1 becomes the page title, so the page shows one title.""" + title = "PostHog Android SDK migration guides" + if guide.startswith("# "): + heading, _, rest = guide.partition("\n") + title, guide = heading[2:].strip(), rest.strip() + return [f"---\ntitle: {json.dumps(title)}\nsidebar: Docs\nshowTitle: true\n---", guide] + + def write(name: str, sections: list[str]) -> None: (ROOT / "references" / name).write_text("\n\n".join(sections) + "\n") print(f"wrote references/{name}") @@ -255,12 +264,8 @@ def main() -> None: def write_migration() -> None: - """Writes MIGRATION.md as the migration guides page, without its title, which the front matter replaces.""" - guide = (ROOT / "MIGRATION.md").read_text().strip() - if guide.startswith("# "): - guide = guide.split("\n", 1)[1].strip() - head = "---\ntitle: PostHog Android SDK migration guides\nsidebar: Docs\nshowTitle: true\n---" - write("posthog-android-migration.md", [head, guide]) + """Writes MIGRATION.md as the migration guide page. Its H1 becomes the page title, so the page shows one title.""" + write("posthog-android-migration.md", migration_page((ROOT / "MIGRATION.md").read_text().strip())) if __name__ == "__main__": diff --git a/docs/getting-started.md b/docs/getting-started.md index 0333d92ea..83498de51 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -36,3 +36,29 @@ PostHog.close() ``` Every `PostHog.*` method below is also available on the instance that `PostHogAndroid.with(context, config)` returns. + +## Connect requests to backend events + +Set `tracingHeaders` and install `PostHogOkHttpInterceptor` on each `OkHttpClient` whose requests should carry PostHog context. This links requests to backend events, errors and LLM traces captured by a server-side PostHog SDK. + +```kotlin +import com.posthog.PostHogOkHttpInterceptor +import com.posthog.android.PostHogAndroid +import com.posthog.android.PostHogAndroidConfig +import okhttp3.OkHttpClient + +val config = PostHogAndroidConfig("", host = "").apply { + tracingHeaders = listOf("api.example.com") +} +PostHogAndroid.setup(this, config) + +val httpClient = OkHttpClient.Builder() + .addInterceptor(PostHogOkHttpInterceptor()) + .build() +``` + +Use exact hostnames, with no protocol, path, port or wildcard subdomain. Matching requests include `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` only when their values are available. + +## Permissions + +The SDK declares `android.permission.INTERNET` and `android.permission.ACCESS_NETWORK_STATE`, and Android's manifest merger adds them to your app. It doesn't declare or need an Android `Service`. diff --git a/posthog/src/main/java/com/posthog/PostHogConfig.kt b/posthog/src/main/java/com/posthog/PostHogConfig.kt index 6ece833cc..c3531d0f7 100644 --- a/posthog/src/main/java/com/posthog/PostHogConfig.kt +++ b/posthog/src/main/java/com/posthog/PostHogConfig.kt @@ -363,13 +363,15 @@ public open class PostHogConfig( /** * When set, PostHog injects tracing headers into OkHttp requests whose destination hostname - * exactly matches one of the configured hostnames. + * exactly matches one of the configured hostnames. Use it to link the app's network requests + * to the backend events, errors, and LLM traces that a server-side PostHog SDK captures. * - * Injected headers: + * Injected headers, each sent only when its value exists: * - `X-POSTHOG-DISTINCT-ID` * - `X-POSTHOG-SESSION-ID` * * Notes: + * - List hostnames only, with no protocol or path * - Requires installing [PostHogOkHttpInterceptor] on each [OkHttpClient] that should send tracing headers * - Hostname matching is exact and does not include ports or subdomain wildcards * - The Android SDK does not send `X-POSTHOG-WINDOW-ID` because mobile apps do not have a per-window/tab concept diff --git a/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt b/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt index ee6760ec4..4152c8c87 100644 --- a/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogCoreInterface.kt @@ -14,6 +14,9 @@ public interface PostHogCoreInterface { /** * Flushes all the events in the Queue right away + * + * Doesn't block. It starts sending in the background and returns, so it doesn't guarantee + * delivery. Nothing is sent while the device is offline or the SDK is waiting to retry. */ public fun flush() diff --git a/posthog/src/main/java/com/posthog/PostHogInterface.kt b/posthog/src/main/java/com/posthog/PostHogInterface.kt index d515736a1..27147494c 100644 --- a/posthog/src/main/java/com/posthog/PostHogInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogInterface.kt @@ -74,6 +74,9 @@ public interface PostHogInterface : PostHogCoreInterface { * replay debug properties), registered super properties ([register]), [properties], then * `beforeSend`. * + * Events captured while the device is offline are stored on the device. The SDK sends them + * when the connection returns, or when the app next starts with a connection. + * * Example: * ``` * PostHog.capture("signed_up", options = mapOf("cookieless_mode" to true)) @@ -346,7 +349,7 @@ public interface PostHogInterface : PostHogCoreInterface { /** * Register a property to always be sent with all the following events until you call - * [unregister] with the same key + * [unregister] with the same key. The property persists across app restarts. * PostHogPreferences.ALL_INTERNAL_KEYS are not allowed since they are internal and used by * the SDK only. * @param key the Key diff --git a/references/posthog-android-4.md b/references/posthog-android-4.md index de28c1566..7629e179c 100644 --- a/references/posthog-android-4.md +++ b/references/posthog-android-4.md @@ -170,6 +170,32 @@ PostHog.close() Every `PostHog.*` method below is also available on the instance that `PostHogAndroid.with(context, config)` returns. +### Connect requests to backend events + +Set `tracingHeaders` and install `PostHogOkHttpInterceptor` on each `OkHttpClient` whose requests should carry PostHog context. This links requests to backend events, errors and LLM traces captured by a server-side PostHog SDK. + +```kotlin +import com.posthog.PostHogOkHttpInterceptor +import com.posthog.android.PostHogAndroid +import com.posthog.android.PostHogAndroidConfig +import okhttp3.OkHttpClient + +val config = PostHogAndroidConfig("", host = "").apply { + tracingHeaders = listOf("api.example.com") +} +PostHogAndroid.setup(this, config) + +val httpClient = OkHttpClient.Builder() + .addInterceptor(PostHogOkHttpInterceptor()) + .build() +``` + +Use exact hostnames, with no protocol, path, port or wildcard subdomain. Matching requests include `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` only when their values are available. + +### Permissions + +The SDK declares `android.permission.INTERNET` and `android.permission.ACCESS_NETWORK_STATE`, and Android's manifest merger adds them to your app. It doesn't declare or need an Android `Service`. + ## Setup ### `PostHogAndroid.setup` @@ -216,6 +242,8 @@ Captures events The event's properties are merged in this order, and later values win: properties the SDK sets itself (such as `$os`, `$app_version`, `$screen_name`, `$is_identified` and the session replay debug properties), registered super properties (register), properties, then `beforeSend`. +Events captured while the device is offline are stored on the device. The SDK sends them when the connection returns, or when the app next starts with a connection. + Example: ```kotlin @@ -411,6 +439,8 @@ fun flush() Flushes all the events in the Queue right away +Doesn't block. It starts sending in the background and returns, so it doesn't guarantee delivery. Nothing is sent while the device is offline or the SDK is waiting to retry. + ## Get anonymous ID ### `PostHog.getAnonymousId` @@ -635,7 +665,7 @@ Disables the SDK to capture events until you optIn again fun register(key: String, value: Any) ``` -Register a property to always be sent with all the following events until you call unregister with the same key PostHogPreferences.ALL\_INTERNAL\_KEYS are not allowed since they are internal and used by the SDK only. +Register a property to always be sent with all the following events until you call unregister with the same key. The property persists across app restarts. PostHogPreferences.ALL\_INTERNAL\_KEYS are not allowed since they are internal and used by the SDK only. #### Parameters @@ -1291,7 +1321,7 @@ The SDK Config - `var setDefaultPersonProperties: Boolean`: Automatically set common device and app properties as person properties for feature flag evaluation. - `var surveys: Boolean`: Enable Surveys for Android (Intended for internal use only) - `var surveysConfig: PostHogSurveysConfig`: Configuration for PostHog Surveys feature. (Intended for internal use only) -- `var tracingHeaders: List?`: When set, PostHog injects tracing headers into OkHttp requests whose destination hostname exactly matches one of the configured hostnames. +- `var tracingHeaders: List?`: When set, PostHog injects tracing headers into OkHttp requests whose destination hostname exactly matches one of the configured hostnames. Use it to link the app's network requests to the backend events, errors, and LLM traces that a server-side PostHog SDK captures. #### Functions diff --git a/references/posthog-android-migration.md b/references/posthog-android-migration.md index 15c781ceb..fdb5d10e6 100644 --- a/references/posthog-android-migration.md +++ b/references/posthog-android-migration.md @@ -1,113 +1,261 @@ --- -title: PostHog Android SDK migration guides +title: "Migrate the Android SDK from 3.x.x to 4.0.0" sidebar: Docs showTitle: true --- -## posthog-android 3.x → 4.0 and posthog (core) 7.0 +The Android SDK 4.x.x sends analytics and AI events to the [capture v1](https://posthog.com/docs/api/capture-v1) endpoints, `/i/v1/analytics/events` and `/i/v1/ai/events`. + +On posthog.com, use the copy page button at the top right to work through this with your agents. + +You don't need to make every change on the day you upgrade your SDK. Changes fall in these categories: + +- **Before you upgrade**: These are changes you should make before you upgrade your SDK to 4.x.x. +- **During your upgrade**: These are changes that you need to make in the same PR that upgrades your SDK version. +- **Follow ups**: These are changes that can come in follow up PRs, because 4.x.x still accepts the old names and options. + +## Checklist -4.0 sends analytics events to capture v1 (`/i/v1/analytics/events`) instead of `/batch`, removes APIs deprecated in 3.x and changes the feature flags callback. -Most removals are compile errors with a direct replacement. [Behavior changes](#behavior-changes) won't show up at build time. Read the checklist first, then the sections that apply to you. -Core `posthog` 7.0 is only supported through `posthog-android` 4.0 and `posthog-server`. Using it on its own through `PostHogStateless.with` isn't supported; see [`posthog-server`](#posthog-server). - -For the changes every capture v1 SDK shares, such as event options, limits and per-event results, see [Upgrading to capture v1 SDKs](https://posthog.com/docs/api/capture-v1). - -For the full list of 4.0 changes, see the [changelog](https://github.com/PostHog/posthog-android/blob/main/posthog-android/CHANGELOG.md). - -### Checklist - -You need to change code if your app does any of these: - -- sends events to a self-hosted PostHog or a reverse proxy that doesn't serve `/i/v1/analytics/events` -- authenticates its proxy with an `Authorization` header in `requestHeaders` -- sends events through a reverse proxy set up from PostHog's proxy guides before 29 October 2026, which strips `Authorization` -- sends events through a proxy that redirects capture requests, other than with a 307 or 308 to the same origin as `host` -- captures events with an empty event name, or with an event name or distinct ID over 200 bytes -- sets an empty distinct ID in `beforeSend` -- assigns a new map to `event.options` in `beforeSend` (see [Event options](#event-options)) -- sets `projectToken` to a personal API key (`phx_...`) -- reads `$session_id` or `$window_id` from the raw request body, for example in a proxy -- sets `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` or `$product_tour_id` to a value PostHog can't read, such as `"maybe"` -- registers `$process_person_profile` as `false` and still calls `identify`, `alias`, `group` or `setPersonProperties` (see [Event options](#event-options)) -- registers a super property, or passes an event property, with the same key as one the SDK sets, such as `$os_name` or `$is_identified`, and expects the SDK's value to win -- calls `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group` or `captureException` from Java, implements `PostHogInterface`, or calls `identify` through a `PostHogCoreInterface` reference -- sets the event `uuid` in `beforeSend` -- relies on a `Retry-After` longer than 30 seconds -- sets `maxRetries` on `PostHogConfig` or `PostHogAndroidConfig` -- uses `apiKey`, `propertiesSanitizer`, `evaluationEnvironments`, `debouncerDelayMs`, `screenshot`, `drawableConverter` or `remoteConfig` -- passes `PostHogConfig` or `PostHogSessionReplayConfig` constructor arguments by position -- calls `getFeatureFlagPayload()`, or passes a default value to `getFeatureFlag()` -- filters insights, cohorts or actions on the `$feature_flag_response` of `$feature_flag_called`, such as `""` or `false` for a missing flag (see [`$feature_flag_response` for a missing flag](#feature_flag_response-for-a-missing-flag)) -- sets `PostHogConfig.onFeatureFlags` or `PostHogOnFeatureFlags`, or passes a callback to `reloadFeatureFlags()` -- uses session replay (see [Session replay records screenshots](#session-replay-records-screenshots)) -- reads a feature flag payload that isn't valid JSON, such as plain text saved as `hello` -- breaks down by `$locale` for the language your app shows (use `$app_language`, and call `setAppLanguage()` if you need it on Android 6–12) -- reads event content or request bodies from the SDK's debug log, or matches its log text -- depends only on `posthog-android-surveys-compose`, or uses `posthog-server` (2.25.0 and later need `posthog-android` 4.0 in the same project) - -### Requirements and versions +**Before you upgrade** + +- [ ] You send events to a self-hosted PostHog or a reverse proxy that doesn't serve `/i/v1/analytics/events` → [Prepare your proxy](#prepare-your-proxy) +- [ ] You authenticate your proxy with an `Authorization` header in `requestHeaders` → [Prepare your proxy](#prepare-your-proxy) +- [ ] You send events through a reverse proxy set up from PostHog's proxy guides before 29 October 2026, which strips `Authorization` → [Prepare your proxy](#prepare-your-proxy) +- [ ] You send events through a proxy that redirects capture requests, other than with a 307 or 308 to the same origin as `host` → [Prepare your proxy](#prepare-your-proxy) +- [ ] You set `projectToken` to a personal API key (`phx_...`) → [Use a project token](#use-a-project-token) +- [ ] You read a feature flag payload that isn't valid JSON, such as plain text saved as `hello` → [Fix flag payloads](#fix-flag-payloads) +- [ ] A feature flag has an empty string as a variant → [Rename empty variants](#rename-empty-variants) +- [ ] You capture events with a distinct ID over 200 bytes → [Shorten long IDs](#shorten-long-ids) + +**During your upgrade** + +- [ ] You depend only on `posthog-android-surveys-compose` → [Upgrade your dependencies](#upgrade-your-dependencies) +- [ ] You use `posthog-server` (2.25.0 and later need `posthog-android` 4.0.0 in the same project) → [Upgrade posthog-server](#upgrade-posthog-server) +- [ ] You call `PostHogStateless.with`, or extend `PostHogStateless` → [Update PostHogStateless code](#update-posthogstateless-code) +- [ ] You use `apiKey`, `propertiesSanitizer`, `evaluationEnvironments`, `debouncerDelayMs`, `screenshot`, or `drawableConverter` → [Fix removed APIs](#fix-removed-apis) +- [ ] You pass `PostHogConfig` or `PostHogSessionReplayConfig` constructor arguments by position → [Fix removed APIs](#fix-removed-apis) +- [ ] You call `getFeatureFlagPayload()`, or pass a default value to `getFeatureFlag()` → [Fix flag calls](#fix-flag-calls) +- [ ] You use `remoteConfig` → [Remove remoteConfig](#remove-remoteconfig) +- [ ] You set `PostHogConfig.onFeatureFlags` or `PostHogOnFeatureFlags`, or pass a callback to `reloadFeatureFlags()` → [Move the flags callback](#move-the-flags-callback) +- [ ] You call `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group`, or `captureException` from Java, or call `identify` through a `PostHogCoreInterface` reference → [Add the options argument](#add-the-options-argument) +- [ ] You implement `PostHogInterface` → [Update interface implementations](#update-interface-implementations) +- [ ] You use `@PostHogInternal` APIs → [Drop internal APIs](#drop-internal-apis) +- [ ] You filter insights, cohorts, or actions on the `$feature_flag_response` of `$feature_flag_called`, such as `""` or `false` for a missing flag → [Check flag events](#check-flag-events) +- [ ] You break down by `$locale` for the language your app shows (use `$app_language`, and call `setAppLanguage()` if you need it on Android 6 to 12) → [Check locale properties](#check-locale-properties) +- [ ] You use session replay → [Check session replay](#check-session-replay) +- [ ] You read `$`-prefixed query parameters from `Deep Link Opened` events → [Check deep links](#check-deep-links) +- [ ] You capture events with an empty event name, or with an event name over 200 bytes → [Check dropped events](#check-dropped-events) +- [ ] You set an empty distinct ID in `beforeSend` → [Check dropped events](#check-dropped-events) +- [ ] You set `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at`, or `$product_tour_id` to a value PostHog can't read, such as `"maybe"` → [Check dropped events](#check-dropped-events) +- [ ] You read event content or request bodies from the SDK's debug log, or match its log text → [Update log checks](#update-log-checks) +- [ ] You register a super property, or pass an event property, with the same key as one the SDK sets, such as `$os_name` or `$is_identified`, and expect the SDK's value to win → [Check property precedence](#check-property-precedence) +- [ ] You read `$session_id` or `$window_id` from the raw request body, for example in a proxy → [Check session IDs](#check-session-ids) +- [ ] You assign a new map to `event.options` in `beforeSend` → [Review beforeSend hooks](#review-beforesend-hooks) +- [ ] You set the event `uuid` in `beforeSend` → [Review beforeSend hooks](#review-beforesend-hooks) +- [ ] You register `$process_person_profile` as `false` and still call `identify`, `alias`, `group`, or `setPersonProperties` → [Check person processing](#check-person-processing) +- [ ] You rely on a `Retry-After` longer than 30 seconds → [Check retries](#check-retries) +- [ ] You set `maxRetries` on `PostHogConfig` or `PostHogAndroidConfig` → [Check retries](#check-retries) + +**Follow ups** + +- [ ] You set legacy option properties like `$process_person_profile` → [Move to event options](#move-to-event-options) +- [ ] You capture `$ai_` events with `capture()` → [Send AI events with captureAi](#send-ai-events-with-captureai) + +## Before you upgrade + +### Prepare your proxy + +posthog-android 4.x.x sends data to these endpoints: + +| Data | 3.x.x | 4.x.x | +| --- | --- | --- | +| Analytics events | `/batch` | `/i/v1/analytics/events` | +| Session replay | `/s/` | `/s/`, unchanged | +| AI events (`captureAi`) | None | `/i/v1/ai/events` (see [Send AI events with captureAi](#send-ai-events-with-captureai)) | +| Logs | `/i/v1/logs` | `/i/v1/logs`, unchanged | +| Feature flags | `/flags` | `/flags`, unchanged | + +Capture v1 requests send the project token in an `Authorization: Bearer ` header instead of an `api_key` body field. + +This header replaces any `Authorization` header you set in `PostHogConfig.requestHeaders`, so authenticate your proxy with a different header, such as `X-Proxy-Token`. Other requests still send your `Authorization` header. + +Analytics requests are gzipped unless you set `compression` to `PostHogCompression.NONE`, as in 3.x.x. + +If you self-host PostHog, make sure your instance serves `/i/v1/analytics/events`, and `/i/v1/ai/events` if you use `captureAi`, before you upgrade. + +If you send events through your own reverse proxy, update it before you upgrade: + +- **Forward both routes.** Forward `/i/v1/analytics/events` and `/i/v1/ai/events` to PostHog. +- **Pass the headers through unchanged.** Pass `Authorization`, every `PostHog-*` header, `Content-Type`, `Content-Encoding`, and `User-Agent`. `Authorization` holds the project token, sent as `Bearer `. PostHog answers `401` without `Authorization` and `400` without the others, and the events are dropped. +- **Keep PostHog's credentials.** If your proxy strips other credentials, keep `Authorization` values that start with `Bearer phc_`, `Bearer phs_`, or `Bearer phx_`. Keep the exact `Bearer ` of an older key without a prefix too. +- **Accept request bodies up to 20 MB.** AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx. A `413` from the proxy makes the SDK halve the batch until it fits. The SDK drops an event that doesn't fit on its own. +- **Pass PostHog's response body through unchanged.** A 2xx response whose body isn't PostHog's `{"results": {...}}` drops the events instead of retrying them. + +PostHog's managed reverse proxy already does this and needs no change. + +A proxy set up from PostHog's [proxy guides](https://posthog.com/docs/advanced/proxy) before 29 October 2026 strips `Authorization`, so PostHog answers `401` and the events are dropped. Update it from the current guide. + +The SDK doesn't fall back to `/batch`. It retries a 404, so the events stay queued until the path is served. The SDK prints one warning, even with `debug` off. + +Any other error status that isn't retried, such as 403 or 405, drops the events. + +The SDK follows a 307 or 308 redirect only to the origin of `host`, at most 5 times. The origin is the same scheme, host, and port. The SDK resends the same body and headers. + +The SDK doesn't follow any other redirect, and the events are dropped. In 3.x.x, OkHttp followed redirects to any host. + +If a proxy redirects capture requests to another host, point `host` at the final host. + +This also applies when you set your own `httpClient`. For capture requests, the SDK turns off its redirect following and OkHttp's connection retries, and keeps your other settings. Other requests, such as session replay and logs, behave as in 3.x.x. + +### Use a project token + +A personal API key (`phx_...`) in `projectToken` disables the SDK at setup, as an empty or whitespace-only token does. Both print why, even when `debug` is off. + +In 3.x.x, the SDK started and PostHog rejected every event with a 401. Use your project token (`phc_...`). + +To turn the SDK off in tests, use an empty token. + +### Fix flag payloads + +In 4.x.x, a payload that isn't valid JSON reads as `null` from `getFeatureFlagResult(key)?.payload` and `getAllFeatureFlags()`. 3.x.x returned the raw string. With `debug` on, the SDK logs the flag key. + +| Payload | 3.x.x | 4.x.x | +| --- | --- | --- | +| Malformed (`{broken`, `[1, 2`), empty or whitespace-only | the raw string | `null` | +| Only valid in lenient mode (unquoted `hello`, single quotes, comments) | decoded leniently | `null` | +| JSON `null` | the string `"null"` | `null` | +| Valid JSON (`"hello"`, `""`, `false`, `0`, objects, arrays) | decoded | decoded, unchanged | +| Bootstrapped payloads | as passed | as passed, unchanged | + +The flag's value, enabled state, variant, and any other flag's payload aren't affected. + +You might read a payload as plain text, such as a payload saved as `hello` rather than `"hello"`. Update it in PostHog to valid JSON before you upgrade, or your code gets `null`. + +PostHog no longer saves a new payload that isn't valid JSON, so only payloads saved earlier are affected. + +Apps that upgrade from 3.13.x or older didn't cache flag details. Until the app's first `/flags` response, a malformed payload cached by 3.x.x still reads as the raw string, as it did in 3.x.x. + +### Rename empty variants + +In 4.x.x, a flag whose variant is an empty string reads as disabled everywhere. `isFeatureEnabled()` already read it as disabled in 3.x.x, with or without `defaultValue`. + +- **Flag results.** `getFeatureFlagResult()` and `getAllFeatureFlags()` return `enabled = false` for it. 3.x.x returned `true`. +- **Loaded flags.** `PostHogFeatureFlagsLoaded` leaves it out of `flags` and `variants`. +- **Captured events.** Captured events leave it out of `$active_feature_flags`. +- **Variant values.** `variant`, `getFeatureFlag()`, and the event's `$feature/` property still return `""`. + +PostHog no longer accepts empty variants for new flags, so only flags created earlier through the API, MCP, or Terraform are affected. + +`/flags` still returns `enabled: true` for them, and other PostHog SDKs can still report them as enabled, so rename the variant before you upgrade. + +### Shorten long IDs + +PostHog drops an event whose distinct ID is over 200 UTF-8 bytes. Legacy capture shortened the ID to 200 characters and kept the event. + +The distinct ID can come from `identify()`, the `distinctId` argument of `capture`, or `beforeSend`. + +If you identify users with a long ID, such as a JWT or a long email address, shorten or hash it before you upgrade. Otherwise every event for that user is dropped. + +## During your upgrade + +### Upgrade your dependencies + +Upgrade PostHog artifacts together: | Artifact | Upgrade | | --- | --- | -| `com.posthog:posthog-android` | 3.x to 4.0 | -| `com.posthog:posthog` (core) | 6.x to 7.0 | -| `com.posthog:posthog-android-surveys-compose` | keep your version, and declare `com.posthog:posthog-android` 4.0.0 or later in your build so Gradle resolves 4.x instead of the 3.x version it pulls in | -| `com.posthog:posthog-server` | 2.25.0, together with `posthog-android` 4.0; see [`posthog-server`](#posthog-server) | +| `com.posthog:posthog-android` | 3.x.x to 4.0.0 | +| `com.posthog:posthog` (core) | 6.x.x to 7.0.0 | +| `com.posthog:posthog-android-surveys-compose` | Keep your version | +| `com.posthog:posthog-server` | 2.25.0, together with `posthog-android` 4.0.0 (see [Upgrade posthog-server](#upgrade-posthog-server)) | + +With `posthog-android-surveys-compose`, declare `com.posthog:posthog-android` 4.0.0 or later in your build, so Gradle resolves 4.x.x instead of the 3.x.x version it pulls in. + +Core `posthog` 7.x.x isn't binary compatible with SDK versions built against core 6.x.x. The exception is `posthog-android-surveys-compose`, which works with both. + +When core 7.x.x is in a Gradle build, for example through `posthog-server` 2.25.0, Gradle upgrades `posthog-android` to 4.x.x, even over a range such as `[3.75.0,4.0.0)`. Code that still uses removed APIs then fails to compile. + +Other mismatches fail at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. + +The Android minimum API level (23), the Java bytecode target (Java 8), the Kotlin language and API compatibility (2.0), and `posthog-android-gradle-plugin` are unchanged. You don't need to change your build for them. + +The [changelog](https://github.com/PostHog/posthog-android/blob/main/posthog-android/CHANGELOG.md) lists every 4.0.0 change. + +### Upgrade posthog-server + +`posthog-server` has no major release, and its API is unchanged. It keeps its own `apiKey`, `getFeatureFlagPayload`, and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` ships in `posthog-server` itself. -These are unchanged, so you don't need to change your build for them: +It still sends events to `/batch`, not to capture v1. The API, endpoint, proxy, retry, and event option changes in this guide don't apply to it. -- Android minimum API level: 23 -- Java bytecode target: Java 8 -- Kotlin language and API compatibility: 2.0 -- `posthog-android-gradle-plugin` +`posthog-server` 2.25.0 depends on core `posthog` 7.0.0, so upgrade it and `posthog-android` together: -Upgrade PostHog artifacts together. Core 7.0 is not binary compatible with SDK versions built against core 6.x, except `posthog-android-surveys-compose`, which works with both. When core 7.0 is in a Gradle build, for example through `posthog-server` 2.25, Gradle upgrades `posthog-android` to 4.0, even over a range such as `[3.75.0,4.0.0)`, so code that still uses removed APIs fails to compile. Other mismatches fail at runtime with errors such as `NoSuchMethodError` or `NoClassDefFoundError`. +- **With `posthog-android` 4.x.x or core 7.x.x.** Use `posthog-server` 2.25.0 or later. Older `posthog-server` versions aren't compatible with core 7.x.x at runtime. +- **With `posthog-android` 3.x.x.** Stay on `posthog-server` 2.24.x. `posthog-server` 2.25.0 brings in core 7.0.0, and Gradle then upgrades `posthog-android` to 4.x.x. -### Removed APIs +These changes apply to `posthog-server` too: -All of these are compile errors. Calling them from an already-compiled library that you haven't updated fails at runtime. +- **Personal API keys.** A personal API key (`phx_...`) in `projectToken` disables the client at setup, as an empty token does. Both print why, even when `debug` is off. +- **Empty names.** The client drops events with an empty name before sending. +- **Merged maps.** `userProperties`, `userPropertiesSetOnce`, and `groups` merge key by key over a `$set`, `$set_once`, or `$groups` map in `properties`. +- **`null` elements.** A `null` element in a list or array in the properties is sent as JSON `null` at its position instead of being removed. +- **`beforeSend` copies.** `beforeSend` gets its own copy of the event's nested maps, lists, and arrays, so its changes no longer reach the objects you passed to `capture`. +- **Event options.** `PostHogEvent`, which `beforeSend` gets, keeps its 3.x.x constructor and `copy`, and gains an `options` property. `/batch` doesn't use it, so a value set in `beforeSend` is sent but has no effect. + +### Update PostHogStateless code + +Core `posthog` 7.x.x is only supported through `posthog-android` 4.x.x and `posthog-server`. `PostHogStateless.with` isn't a supported entry point in core 7.x.x. + +`PostHogStateless` has no queue of its own, so it gets Android's capture v1 behavior, including the persisted-queue retries, which isn't a server-side contract. Use `posthog-server` for server-side JVM apps. + +A class that extends `PostHogStateless` also needs an update. The protected `buildEvent()` gained `options` and `uuid` parameters, and `captureFeatureFlagCalledEvent()` is no longer protected. + +### Fix removed APIs + +posthog-android 4.x.x removes these APIs. Each one is a compile error. A call from an already-compiled library that you haven't updated fails at runtime. | Removed | Use instead | | --- | --- | | `PostHogConfig.apiKey`, `PostHogConfig(apiKey = …)`, `PostHogAndroidConfig(apiKey = …)` | `projectToken` | | `PostHogConfig.propertiesSanitizer`, `PostHogPropertiesSanitizer` | `addBeforeSend` | | `PostHogConfig.evaluationEnvironments` | `evaluationContexts` | -| `getFeatureFlagPayload()`, on the instance and on `PostHog` | `getFeatureFlagResult()` | -| `defaultValue` on `getFeatureFlag()` | `getFeatureFlag(key) ?: default` | +| `getFeatureFlagPayload()`, on the instance and on `PostHog` | `getFeatureFlagResult()` (see [Fix flag calls](#fix-flag-calls)) | +| `defaultValue` on `getFeatureFlag()` | `getFeatureFlag(key) ?: default` (see [Fix flag calls](#fix-flag-calls)) | | `PostHogSessionReplayConfig.debouncerDelayMs` | `throttleDelayMs` | -| `PostHogSessionReplayConfig.screenshot`, `drawableConverter`, `PostHogDrawableConverter` | nothing; replay always records screenshots | -| `PostHogConfig.remoteConfig` | nothing; remote config always loads | -| `PostHogConfig.onFeatureFlags` | `PostHog.onFeatureFlags()` before `setup()` | +| `PostHogSessionReplayConfig.screenshot`, `drawableConverter`, `PostHogDrawableConverter` | Nothing | +| `PostHogConfig.remoteConfig` | Nothing | +| `PostHogConfig.onFeatureFlags` | `PostHog.onFeatureFlags()` before `setup()` (see [Move the flags callback](#move-the-flags-callback)) | | `PostHogOnFeatureFlags` | `PostHogFeatureFlagsCallback` | -| `PostHogConfig.maxRetries` | `pushNotificationSubscriptionMaxRetries` (see [Retries](#retries)) | +| `PostHogConfig.maxRetries` | `pushNotificationSubscriptionMaxRetries` (see [Check retries](#check-retries)) | + +Replay always records screenshots (see [Check session replay](#check-session-replay)). Remote config always loads (see [Remove remoteConfig](#remove-remoteconfig)). The constructor parameters of `PostHogConfig` and `PostHogSessionReplayConfig` move up where these were removed. If you pass arguments by position, check them, or switch to named arguments. -#### `apiKey` +Replace `apiKey` with `projectToken`: ```kotlin -// 3.x +// 3.x.x val config = PostHogAndroidConfig(apiKey = "phc_your_project_token") val token = config.apiKey -// 4.0 +// 4.x.x val config = PostHogAndroidConfig(projectToken = "phc_your_project_token") val token = config.projectToken ``` `PostHogAndroidConfig("phc_your_project_token")`, with no parameter name, still works. From Java, replace `getApiKey()` with `getProjectToken()`. -#### `propertiesSanitizer` +Replace `propertiesSanitizer` with `addBeforeSend`: ```kotlin -// 3.x +// 3.x.x config.propertiesSanitizer = PostHogPropertiesSanitizer { properties -> properties.apply { remove("email") } } -// 4.0 +// 4.x.x config.addBeforeSend { event -> event.properties?.remove("email") event @@ -116,90 +264,102 @@ config.addBeforeSend { event -> `addBeforeSend` gets the whole `PostHogEvent`. Return `null` to drop the event. If the hook throws, the event is dropped. -#### `evaluationEnvironments` +Replace `evaluationEnvironments` with `evaluationContexts`: ```kotlin -// 3.x +// 3.x.x config.evaluationEnvironments = listOf("production") -// 4.0 +// 4.x.x config.evaluationContexts = listOf("production") ``` -#### `getFeatureFlagPayload()` +Replace `debouncerDelayMs` with `throttleDelayMs`: -`getFeatureFlagPayload()` never sent `$feature_flag_called`. `getFeatureFlagResult()` sends it by default, following `sendFeatureFlagEvent`, so pass `sendFeatureFlagEvent = false` to keep your event volume and experiment exposures unchanged. If you drop that argument, nothing fails, but you'll send new events. +```kotlin +// 3.x.x +PostHogSessionReplayConfig(debouncerDelayMs = 500) -The new call has no `defaultValue` parameter, so apply your default with `?:`. +// 4.x.x +PostHogSessionReplayConfig(throttleDelayMs = 500) +``` + +### Fix flag calls + +`getFeatureFlagPayload()` never sent `$feature_flag_called`. `getFeatureFlagResult()` sends it by default, following `sendFeatureFlagEvent`. + +Pass `sendFeatureFlagEvent = false` to keep your event volume and experiment exposures unchanged. If you drop that argument, nothing fails, but you'll send new events. + +`getFeatureFlagResult()` has no `defaultValue` parameter, so apply your default with `?:`: ```kotlin -// 3.x +// 3.x.x val payload = PostHog.getFeatureFlagPayload("checkout", defaultValue = "fallback") -// 4.0 +// 4.x.x val payload = PostHog.getFeatureFlagResult("checkout", sendFeatureFlagEvent = false)?.payload ?: "fallback" ``` -#### `getFeatureFlag()` default value +`getFeatureFlag()` has no `defaultValue` parameter either: ```kotlin -// 3.x +// 3.x.x val value = PostHog.getFeatureFlag("checkout", defaultValue = "fallback") -// 4.0 +// 4.x.x val value = PostHog.getFeatureFlag("checkout") ?: "fallback" ``` -The second parameter is now `sendFeatureFlagEvent`, which affects code that still compiles: +The second parameter of `getFeatureFlag()` is `sendFeatureFlagEvent` in 4.x.x, which affects code that still compiles: -- `getFeatureFlag("checkout", true)` compiles, but `true` now means `sendFeatureFlagEvent` rather than the default value. -- A disabled SDK now returns `null`, not your default. -- `$feature_flag_called` no longer reports a fallback as the flag's value. `isFeatureEnabled("missing", true)` still returns `true`, but its event leaves out `$feature_flag_response` (see [`$feature_flag_response` for a missing flag](#feature_flag_response-for-a-missing-flag)). +- **Boolean arguments.** `getFeatureFlag("checkout", true)` compiles, but `true` means `sendFeatureFlagEvent` rather than the default value. +- **A disabled SDK.** A disabled SDK returns `null`, not your default. +- **Fallback values.** `$feature_flag_called` no longer reports a fallback as the flag's value. `isFeatureEnabled("missing", true)` still returns `true`, but its event leaves out `$feature_flag_response` (see [Check flag events](#check-flag-events)). Classes that implement `PostHogInterface` update the signature. -#### `debouncerDelayMs` +### Remove remoteConfig + +Apps that left `remoteConfig` at its default of `true` see no behavior change. Delete the option: ```kotlin -// 3.x -PostHogSessionReplayConfig(debouncerDelayMs = 500) +// 3.x.x +config.remoteConfig = false -// 4.0 -PostHogSessionReplayConfig(throttleDelayMs = 500) +// 4.x.x: remove the line ``` -#### `remoteConfig` +If you set it to `false`, your app's behavior changes: -Delete the option. Apps that left it at its default of `true` see no behavior change. +- **Requests at setup.** The SDK requests remote config (`/array//config`) at setup, even if `preloadFeatureFlags` is also `false`. 3.x.x sent no request at all. +- **Project settings.** The settings in `/config` apply, including the session replay, surveys, error tracking, and push settings from your project. +- **Flag requests.** With `preloadFeatureFlags = true`, the SDK requests `/flags` only if `/config` reports that the project has feature flags. 3.x.x always requested `/flags`. If the project has none, the cached flags are cleared. -```kotlin -// 3.x -config.remoteConfig = false +### Move the flags callback -// 4.0: remove the line -``` +`PostHogConfig.onFeatureFlags` is removed. Call `PostHog.onFeatureFlags()` before `setup()` instead, which also covers the first load. -If you set it to `false`, your app's behavior changes: +An instance from `PostHogAndroid.with()` is set up as it's created, so call `onFeatureFlags()` on it right after `with()`. If flags have already loaded, the listener gets the current values shortly after it registers. -- The SDK now requests `/config` at setup, even if `preloadFeatureFlags` is also `false`, when 3.x sent no request at all. -- The settings in `/config` now apply, including the session replay, surveys, error tracking and push settings from your project. -- With `preloadFeatureFlags = true`, the SDK requests `/flags` only if `/config` reports that the project has feature flags. In 3.x it always requested `/flags`. If the project has none, the cached flags are cleared. +`reloadFeatureFlags()` takes a `PostHogFeatureFlagsCallback`. Both callbacks receive a `PostHogFeatureFlagsLoaded`: -### Feature flags callback +| Field | Holds | +| --- | --- | +| `flags` | The keys of the enabled flags | +| `variants` | Their values, either `true` or the variant string | +| `errorsLoading` | Whether the latest load failed | -`PostHogConfig.onFeatureFlags` is removed. Call `PostHog.onFeatureFlags()` before `setup()` instead, which also covers the first load. An instance from `PostHogAndroid.with()` is set up as it's created, so call `onFeatureFlags()` on it right after `with()`; if flags have already loaded, the listener gets the current values shortly after it registers. `reloadFeatureFlags()` now takes a `PostHogFeatureFlagsCallback`. Both callbacks receive a `PostHogFeatureFlagsLoaded`: +When the latest load failed, the values are the last known ones, which can be empty. -- `flags`: the keys of the enabled flags -- `variants`: their values, either `true` or the variant string -- `errorsLoading`: whether the latest load failed. The values are then the last known ones, which can be empty +Register the listener before `setup()`: ```kotlin -// 3.x +// 3.x.x config.onFeatureFlags = PostHogOnFeatureFlags { refreshUi() } -// 4.0, before PostHogAndroid.setup() +// 4.x.x, before PostHogAndroid.setup() PostHog.onFeatureFlags { loaded -> if (!loaded.errorsLoading) { refreshUi() @@ -209,29 +369,60 @@ PostHog.onFeatureFlags { loaded -> The listener differs from the removed option in three ways: -- It runs on the main thread on Android. The option ran on a background thread. -- Bootstrapped flags arrive just after `setup()` is called, not synchronously inside it. -- A reload on a disabled SDK doesn't call listeners. `reloadFeatureFlags(callback)` still gets `errorsLoading = true` in that case. +- **Thread.** It runs on the main thread on Android. The option ran on a background thread. +- **Bootstrapped flags.** They arrive just after `setup()` is called, not synchronously inside it. +- **Disabled SDK.** A reload on a disabled SDK doesn't call listeners. `reloadFeatureFlags(callback)` still gets `errorsLoading = true` in that case. + +`onFeatureFlags()` is the way to listen for flag loads, for example from a screen or a library. You can remove the listener later: -From Java, the `reloadFeatureFlags()` lambda now takes the `PostHogFeatureFlagsLoaded` argument: +```kotlin +val subscription = PostHog.onFeatureFlags { loaded -> + if (loaded.variants["new-checkout"] == "test") { + showTestVariant() + } +} + +// later +subscription.unsubscribe() +``` + +You can register before `setup()`, and listeners stay registered across `close()` and `setup()`. + +From Java, the `reloadFeatureFlags()` lambda takes the `PostHogFeatureFlagsLoaded` argument: ```java -// 3.x +// 3.x.x PostHog.Companion.reloadFeatureFlags(() -> refreshUi()); -// 4.0 +// 4.x.x PostHog.Companion.reloadFeatureFlags(loaded -> refreshUi()); ``` -A Kotlin trailing lambda such as `PostHog.reloadFeatureFlags { refreshUi() }` compiles unchanged, so it won't show up as an error. Check whether it should now read `errorsLoading`: the callback has always also run after a failed load. +A Kotlin trailing lambda such as `PostHog.reloadFeatureFlags { refreshUi() }` compiles unchanged, so it won't show up as an error. Check whether it should read `errorsLoading`. The callback has always also run after a failed load. + +`errorsLoading` depends on why the load ended: + +- **`false`.** PostHog answers that the project is over its feature flags quota. The values are the cached flags. +- **`true`.** No request was made, such as when the device is offline or the distinct ID is blank. It's also `true` when the SDK is disabled or isn't set up, with no values in that last case. + +The `reloadFeatureFlags()` callback still runs on a background thread, or right away on the calling thread when no load is attempted. Switch to the main thread before you touch UI. + +### Add the options argument -`errorsLoading` is `false` when PostHog answers that the project is over its feature flags quota, and the values are the cached flags. It's `true` when no request was made, such as when the device is offline or the distinct ID is blank, and when the SDK is disabled or isn't set up, with no values in that last case. +`capture` takes a new `options` argument. `screen`, `identify`, `setPersonProperties`, `alias`, `group`, and `captureException` take the same argument, as their last parameter (see [Move to event options](#move-to-event-options)). -The `reloadFeatureFlags()` callback still runs on a background thread, or right away on the calling thread when no load is attempted, so switch to the main thread before touching UI. +- **Kotlin callers.** Callers that use named or positional arguments for the existing parameters keep compiling. +- **Java callers.** Pass the new trailing `options` argument, or `null`. +- **`PostHogInterface` implementations.** Add the parameter. +- **`identify` on `PostHogCoreInterface`.** `identify(distinctId, userProperties, userPropertiesSetOnce)` moved from `PostHogCoreInterface` to `PostHogStatelessInterface`. Call it through `PostHogInterface` or `PostHogStatelessInterface`. -### `PostHogInterface` implementations +### Update interface implementations -`PostHogInterface` lost `getFeatureFlagPayload()`, gained the abstract `onFeatureFlags()` and `setAppLanguage()`, and changed the callback type of `reloadFeatureFlags()`. Classes that implement it, such as hand-written fakes for tests, no longer compile until they're updated. They also add the `options` parameter and `captureAi()` (see [Event options](#event-options) and [AI events](#ai-events)). +`PostHogInterface` lost `getFeatureFlagPayload()`, gained the abstract `onFeatureFlags()` and `setAppLanguage()`, and changed the callback type of `reloadFeatureFlags()`. + +Implementations also add the `options` parameter and `captureAi()` (see [Add the options argument](#add-the-options-argument) and [Send AI events with captureAi](#send-ai-events-with-captureai)). + +Classes that implement it, such as hand-written fakes for tests, don't compile until you update them: ```kotlin class FakePostHog : PostHogInterface { @@ -246,241 +437,257 @@ class FakePostHog : PostHogInterface { `PostHogFeatureFlagsSubscription` and `PostHogFeatureFlagsLoaded` have constructors marked `@PostHogInternal`, which aren't intended for app code, so create them with a mocking library. -### Internal APIs +### Drop internal APIs These helpers were public only by accident and were marked `@PostHogInternal`. They're no longer visible outside the SDK and have no replacement. Apps that don't use `@PostHogInternal` APIs aren't affected. -- `com.posthog.internal`: `CustomHeadersInterceptor`, `PostHogPrintLogger`, `PropertyGroupDeserializer`, `PropertyValueDeserializer`, `personPropertiesContext()`, `PostHogPreferences.PUSH_SUBSCRIPTION_REJECTED` -- `com.posthog.internal.errortracking`: `ThrowableCoercer.fromThrowableToPostHogProperties()` -- `com.posthog.internal.replay`: `RRDocumentNode`, `RRDomContentLoadedEvent`, `RRLoadedEvent`, `RRStyle`; `RRWireframe` keeps only `id`, `x`, `y`, `width`, `height`, `type` and `base64` -- `com.posthog.internal.surveys`: `findBestTranslationMatch()` -- `com.posthog.android.internal`: `Bitmap.isValid()`, `Bitmap.webpBase64()` -- `com.posthog.android.replay.internal`: `LogLine`, `LogcatParser` +| No longer visible | Package | +| --- | --- | +| `CustomHeadersInterceptor` | `com.posthog.internal` | +| `PostHogPrintLogger` | `com.posthog.internal` | +| `PropertyGroupDeserializer` | `com.posthog.internal` | +| `PropertyValueDeserializer` | `com.posthog.internal` | +| `personPropertiesContext()` | `com.posthog.internal` | +| `PostHogPreferences.PUSH_SUBSCRIPTION_REJECTED` | `com.posthog.internal` | +| `ThrowableCoercer.fromThrowableToPostHogProperties()` | `com.posthog.internal.errortracking` | +| `RRDocumentNode` | `com.posthog.internal.replay` | +| `RRDomContentLoadedEvent` | `com.posthog.internal.replay` | +| `RRLoadedEvent` | `com.posthog.internal.replay` | +| `RRStyle` | `com.posthog.internal.replay` | +| `findBestTranslationMatch()` | `com.posthog.internal.surveys` | +| `Bitmap.isValid()` | `com.posthog.android.internal` | +| `Bitmap.webpBase64()` | `com.posthog.android.internal` | +| `LogLine` | `com.posthog.android.replay.internal` | +| `LogcatParser` | `com.posthog.android.replay.internal` | -If you call `PostHogRemoteConfig.loadFeatureFlags()` or `loadRemoteConfig()`, their callback parameters changed too. The internal callback is now `(errorsLoading: Boolean) -> Unit`, and the other is a `PostHogFeatureFlagsCallback`. +In `com.posthog.internal.replay`, `RRWireframe` keeps only `id`, `x`, `y`, `width`, `height`, `type`, and `base64`. -### Behavior changes +If you call `PostHogRemoteConfig.loadFeatureFlags()` or `loadRemoteConfig()`, their callback parameters changed too. The internal callback is `(errorsLoading: Boolean) -> Unit`, and the other is a `PostHogFeatureFlagsCallback`. -#### Feature flag payloads must be valid JSON +### Check flag events -A payload that isn't valid JSON now reads as `null` from `getFeatureFlagResult(key)?.payload` and `getAllFeatureFlags()`, instead of the raw string. With `debug` on, the SDK logs the flag key. +When a flag is missing, `$feature_flag_called` leaves out `$feature_flag_response`. -| Payload | 3.x | 4.0 | -| --- | --- | --- | -| Malformed (`{broken`, `[1, 2`), empty or whitespace-only | the raw string | `null` | -| Only valid in lenient mode (unquoted `hello`, single quotes, comments) | decoded leniently | `null` | -| JSON `null` | the string `"null"` | `null` | -| Valid JSON (`"hello"`, `""`, `false`, `0`, objects, arrays) | decoded | decoded, unchanged | -| Bootstrapped payloads | as passed | as passed, unchanged | +3.x.x sent `""` from `getFeatureFlag()` and `false` from `isFeatureEnabled()`, or your default value when you passed one. In 4.x.x an empty string means a flag with an empty variant, so a missing flag no longer reports one. -The flag's value, enabled state, variant and any other flag's payload aren't affected. +Insights, cohorts, and actions that filter on `$feature_flag_response = ""` or `false` to find missing flags stop matching new events without any error. Use an `is not set` filter on `$feature_flag_response` instead. -If you read a payload as plain text, such as a payload saved as `hello` rather than `"hello"`, update it in PostHog to valid JSON before you upgrade, or your code gets `null`. PostHog no longer saves a new payload that isn't valid JSON, so only payloads saved earlier are affected. +Events already stored keep their old values. -Apps upgrading from 3.13 or older didn't cache flag details, so until the app's first `/flags` response, a malformed payload cached by 3.x still reads as the raw string, as it did in 3.x. +### Check locale properties -#### Empty variants read as disabled +In 4.x.x, `$locale` means the first language in the device settings, as a full language tag such as `de-CH` or `zh-Hant-TW`. It's left out when the device reports no language. -A flag whose variant is an empty string now reads as disabled everywhere, as it already did from `isFeatureEnabled()`, with or without `defaultValue`. `getFeatureFlagResult()` and `getAllFeatureFlags()` return `enabled = false` for it, where 3.x returned `true`, `PostHogFeatureFlagsLoaded` leaves it out of `flags` and `variants`, and captured events leave it out of `$active_feature_flags`. `variant`, `getFeatureFlag()` and the event's `$feature/` property still return `""`. +In 3.x.x it came from `Locale.getDefault()`. That could be a secondary language, a per-app language, or a value your app set with `Locale.setDefault()`, and it dropped the script (`zh-TW`). -PostHog no longer accepts empty variants for new flags, so only flags created earlier through the API, MCP or Terraform are affected. `/flags` still returns `enabled: true` for them, and other PostHog SDKs can still report them as enabled, so rename the variant before you upgrade. +On older Android versions, 3.x.x also sent the legacy codes `iw`, `in`, and `ji`, so Hebrew, Indonesian, and Yiddish values change, such as `in-ID` to `id-ID`. Update filters that match those. -#### `$feature_flag_response` for a missing flag +Other values mostly stay the same, so otherwise only check filters if your users change these settings. -When a flag is missing, `$feature_flag_called` now leaves out `$feature_flag_response`. 3.x sent `""` from `getFeatureFlag()` and `false` from `isFeatureEnabled()`, or your default value when you passed one. In 4.0 an empty string means a flag with an empty variant, so a missing flag no longer reports one. +The new `$app_language` property is the language your app shows. Android has no API that reports it exactly, so what you get depends on the version: -Insights, cohorts and actions that filter on `$feature_flag_response = ""` or `false` to find missing flags stop matching new events without any error. Use an `is not set` filter on `$feature_flag_response` instead. Events already stored keep their old values. +| Android | `$app_language` | +|---|---| +| 13+ with `android:localeConfig` declared | The per-app language or the first device language | +| 13+ without `localeConfig` | The per-app language, if one is set | +| 6 to 12 | Not sent | -#### `$locale` and `$app_language` +You can declare `android:localeConfig` by hand or with AGP `generateLocaleConfig`. With it, the value is the per-app language or, without one, the first device language, as you declare it. -`$locale` now means the first language in the device settings, as a full language tag such as `de-CH` or `zh-Hant-TW`. In 3.x it came from `Locale.getDefault()`, which could be a secondary language, a per-app language or a value your app set with `Locale.setDefault()`, and it dropped the script (`zh-TW`). It's left out when the device reports no language. On older Android versions, 3.x also sent the legacy codes `iw`, `in` and `ji`, so Hebrew, Indonesian and Yiddish values change, such as `in-ID` to `id-ID`. Update filters that match those. Other values mostly stay the same, so otherwise only check filters if your users change these settings. +If you don't declare that language, the value is your `android:defaultLocale` (Android 15+) or your language if you only declare one. -The new `$app_language` property is the language your app shows. Android has no API that reports it exactly, so what you get depends on the version: +It's not sent if several of your declared languages could match, such as `pt` and `pt-PT` for a `pt-MZ` device, or if nothing matches and you declare several languages without a default. -| Android | `$app_language` | -|---|---| -| 13+ with `android:localeConfig` declared (by hand or with AGP `generateLocaleConfig`) | The per-app language or, without one, the first device language, as you declare it. If you don't declare that language, your `android:defaultLocale` (Android 15+) or your language if you only declare one. Not sent if several of your declared languages could match, such as `pt` and `pt-PT` for a `pt-MZ` device, or if nothing matches and you declare several languages without a default. | -| 13+ without `localeConfig` | The per-app language, if one is set. Otherwise not sent. | -| 6–12 | Not sent. | +On Android 13+ without `localeConfig`, it's not sent when no per-app language is set. + +The SDK reads both languages in the background when an event is captured and uses them from the next event on. The first event after a language change carries the previous value. -The SDK reads both languages in the background when an event is captured and uses them from the next event on, so the first event after a language change carries the previous value. Changing only the runtime override (`LocaleManager.setOverrideLocaleConfig`) isn't picked up until the device or per-app language changes; call `PostHog.setAppLanguage()` if your app changes it. +A change to only the runtime override (`LocaleManager.setOverrideLocaleConfig`) isn't picked up until the device or per-app language changes. Call `PostHog.setAppLanguage()` if your app changes it. -Strings you don't translate fall back per string, so the value is the app's language, not a guarantee for every string. Call `PostHog.setAppLanguage("de")` at startup and whenever the language changes to send it on every version, or if you translate some other way, such as with an in-app language setting. It's kept in memory only. +Strings you don't translate fall back per string, so the value is the app's language, not a guarantee for every string. -#### Session replay records screenshots +Call `PostHog.setAppLanguage("de")` at startup and whenever the language changes to send it on every version, or if you translate some other way, such as with an in-app language setting. It's kept in memory only. -4.0 removes wireframe session replay. Replay always records masked screenshots, which is what `screenshot = true` already did. +### Check session replay + +posthog-android 4.x.x removes wireframe session replay. Replay always records masked screenshots, which is what `screenshot = true` already did. Remove the `screenshot` option: ```kotlin -// 3.x +// 3.x.x config.sessionReplayConfig.screenshot = true -// 4.0: remove the line +// 4.x.x: remove the line ``` Apps that relied on the default now upload screenshots: -- Masking still covers text inputs, images, Compose semantics, `ph-no-capture` views and `Modifier.postHogMask()`. `WebView`s are masked whole while `maskAllTextInputs` or `maskAllImages` is on. -- Custom-drawn views and other content the SDK doesn't recognize, such as maps or video, can now appear in recordings. Mask them, or turn replay off with `sessionReplay = false`. -- Jetpack Compose screens, which wireframe captured as empty boxes, are now recorded. That can count against your replay quota and may need a consent or privacy disclosure update. -- Each frame uses more bandwidth and CPU than a wireframe. +- **Masking.** Masking still covers text inputs, images, Compose semantics, `ph-no-capture` views, and `Modifier.postHogMask()`. `WebView`s are masked whole while `maskAllTextInputs` or `maskAllImages` is on. +- **Unrecognized content.** Custom-drawn views and other content the SDK doesn't recognize, such as maps or video, can now appear in recordings. Mask them, or turn replay off with `sessionReplay = false`. +- **Jetpack Compose screens.** Wireframe captured them as empty boxes. 4.x.x records them. That can count against your replay quota and may need a consent or privacy disclosure update. +- **Frame cost.** Each frame uses more bandwidth and CPU than a wireframe. Compose masking also changed, including for apps that already set `screenshot = true`: -- `Modifier.postHogMask()` and `Modifier.postHogUnmask()` apply only to the element and its children, not to siblings merged into the same clickable row. -- Text that draws past its layout box is masked in full. -- Nodes using `Modifier.clearAndSetSemantics` are masked while text or image masking is on. Use `Modifier.postHogUnmask()` to show them. +- **Mask scope.** `Modifier.postHogMask()` and `Modifier.postHogUnmask()` apply only to the element and its children, not to siblings merged into the same clickable row. +- **Overflowing text.** Text that draws past its layout box is masked in full. +- **Cleared semantics.** Nodes that use `Modifier.clearAndSetSemantics` are masked while text or image masking is on. Use `Modifier.postHogUnmask()` to show them. A dialog's dim, and a dialog masked whole on Android 8.1 and lower, are sent as screenshot images instead of styled wireframe shapes. -The `$sdk_debug_replay_capture_mode` property is now always `screenshot`. +The `$sdk_debug_replay_capture_mode` property is always `screenshot`. -#### Deep link query parameters +### Check deep links -The `Deep Link Opened` event leaves out query parameters whose name starts with `$`, such as `$process_person_profile`, so a link can't set PostHog's own properties. Other parameters and the `url` property are sent as in 3.x. +The `Deep Link Opened` event leaves out query parameters whose name starts with `$`, such as `$process_person_profile`, so a link can't set PostHog's own properties. -#### Other changes that don't fail the build +Other parameters and the `url` property are sent as in 3.x.x. -The code you end up with after these two migrations compiles, so they're easy to miss: +### Check dropped events -- [`getFeatureFlagResult()` sends `$feature_flag_called` by default](#getfeatureflagpayload), unlike `getFeatureFlagPayload()`. -- [Apps that set `remoteConfig = false` now load `/config`](#remoteconfig) and apply its settings. +Capture v1 checks each event on its own and drops only the invalid ones, so the rest of the batch is delivered. In 3.x.x, an empty event name or distinct ID made legacy capture reject the whole batch it was in. -### Endpoints +- **Empty names.** The SDK drops an event whose name is empty before sending it, for example `capture("")` or one `beforeSend` renames to `""`. With `debug` on, it logs this once. +- **Empty distinct IDs.** PostHog drops an event with an empty or whitespace-only distinct ID, for example one `beforeSend` sets to `""`. +- **Long names.** PostHog drops an event whose name is over 200 UTF-8 bytes. Legacy capture had no limit on event name length. +- **Long distinct IDs.** PostHog drops an event whose distinct ID is over 200 UTF-8 bytes (see [Shorten long IDs](#shorten-long-ids)). +- **Empty IDs in `identify()`.** `identify()` with an empty or whitespace-only distinct ID is still ignored, as in 3.x.x. +- **Option values.** The SDK sends option values as given. PostHog reads common forms of a value, such as `"false"` or `0` for a boolean, and drops an event whose option value it can't read. -| Data | 3.x | 4.0 | -| --- | --- | --- | -| Analytics events | `/batch` | `/i/v1/analytics/events` | -| Session replay | `/s/` | `/s/`, unchanged | -| AI events (`captureAi`) | – | `/i/v1/ai/events` (see [AI events](#ai-events)) | -| Logs | `/i/v1/logs` | `/i/v1/logs`, unchanged | -| Feature flags | `/flags` | `/flags`, unchanged | +The SDK checks only the event name before sending. For the other checks, PostHog drops the event, and the SDK removes it from the queue. -Capture v1 requests send the project token in an `Authorization: Bearer ` header instead of an `api_key` body field. -This header replaces any `Authorization` header you set in `PostHogConfig.requestHeaders`, so authenticate your proxy with a different header, such as `X-Proxy-Token`. -Other requests still send your `Authorization` header. +There's no error callback, as in 3.x.x. The SDK reports dropped and failed events only in its debug log (see [Update log checks](#update-log-checks)). -Analytics requests are gzipped unless you set `compression` to `PostHogCompression.NONE`, as in 3.x. +The SDK sends these events and changes the value: -A personal API key (`phx_...`) in `projectToken` now disables the SDK at setup, as an empty or whitespace-only token does. Both print why, even when `debug` is off. To turn the SDK off in tests, use an empty token. -In 3.x, the SDK started and PostHog rejected every event with a 401. Use your project token (`phc_...`). +- **`NaN` and infinite numbers.** A `NaN` or infinite number in the properties is dropped from the event, and the event is sent without it. +- **Map keys.** A map key in the properties that isn't a string is converted to one when it's a number, a boolean, or `null`. Any other key is dropped with its value, and the rest of the event is sent. With `debug` on, the SDK logs the key's type. In 3.x.x, a nested map with a non-string key lost the whole event. +- **`null` elements.** A `null` element in a list or array in the properties is sent as JSON `null` at its position. So is an element that can't be serialized, such as `NaN`. In 3.x.x, both were removed, which moved the later elements to lower indexes. A property or map entry whose value is `null` is still left out. +- **Empty `distinctId` arguments.** An empty or whitespace-only `distinctId` argument to `capture` uses the current distinct ID, like `null`. In 3.x.x, the event was dropped. -#### Hosts without capture v1 +### Update log checks -If you self-host PostHog, make sure `/i/v1/analytics/events` is served before you upgrade, and `/i/v1/ai/events` if you use `captureAi`. -PostHog Cloud (`us.i.posthog.com`, `eu.i.posthog.com`) serves it. +Update any log-based checks that match the 3.x.x text. -If you send events through your own reverse proxy, update it before you upgrade: +- **Batch results.** With `debug` on, the SDK logs one line per batch. The line says how many events PostHog dropped, how many duplicate copies it dropped, and how many it asked to retry. It has the reasons PostHog gave, never the event names or properties. +- **Queued events.** The SDK no longer logs a line for each queued event. +- **Capture requests.** Debug logs for capture requests name the event count and the response status. They no longer print the request and response bodies. +- **Hook errors.** When a `beforeSend` hook throws, the debug log names the event and the exception type, not the exception message. The message can hold the data the hook was removing. In 3.x.x it printed the exception. +- **Values that can't be serialized.** When a property value can't be serialized, the debug log names the key and the value's type, not the value. In 3.x.x it printed the value. -- Forward `/i/v1/analytics/events` and `/i/v1/ai/events` to PostHog. -- Pass `Authorization` (the project token, sent as `Bearer `), every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged. PostHog answers `401` without `Authorization` and `400` without the others, and the events are dropped. If your proxy strips other credentials, keep `Authorization` values that start with `Bearer phc_`, `Bearer phs_` or `Bearer phx_`, plus the exact `Bearer ` of an older key without a prefix. -- Accept request bodies up to 20 MB. AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx. A `413` from the proxy makes the SDK halve the batch until it fits, and drops an event that doesn't fit on its own. -- Pass PostHog's response body through unchanged. A 2xx response whose body isn't PostHog's `{"results": {...}}` drops the events instead of retrying them. +### Check property precedence -PostHog's managed reverse proxy already does this and needs no change. A proxy set up from PostHog's [proxy guides](https://posthog.com/docs/advanced/proxy) before 29 October 2026 strips `Authorization`, so PostHog answers `401` and the events are dropped. Update it from the current guide. +An event's properties are merged in this order, and later values win: -The SDK doesn't fall back to `/batch`. A 404 is retried, so the events stay queued until the path is served, and the SDK prints one warning, even with `debug` off. Any other error status that isn't retried, such as 403 or 405, drops the events. +1. Properties the SDK sets itself, such as `$os_name`, `$app_version`, `$screen_name`, `$is_identified`, `$session_id`, and the session replay debug properties (`$recording_status`, `$sdk_debug_*`). +2. Registered super properties (`register`). +3. The properties you pass to `capture` or another event-sending method. `userProperties`, `userPropertiesSetOnce`, and `groups` are placed as `$set`, `$set_once`, and `$groups` here. When you also pass that key in properties, the arguments win key by key. A `$groups` map in properties adds to the groups set with `group()` instead of replacing them. +4. `beforeSend`. -#### Redirects +These changes follow from this order: -The SDK follows a 307 or 308 redirect only to the origin of `host` (same scheme, host and port), at most 5 times, and resends the same body and headers. -Any other redirect is not followed and the events are dropped. -In 3.x, OkHttp followed redirects to any host. -If a proxy redirects capture requests to another host, point `host` at the final host. -This also applies when you set your own `httpClient`: for capture requests, the SDK turns off its redirect following and OkHttp's connection retries, and keeps your other settings. Other requests, such as session replay and logs, behave as in 3.x. +- **SDK values.** In 3.x.x, the SDK's own values won over super properties. `$is_identified`, `$process_person_profile`, and the session replay debug properties also won over the properties you pass. In 4.x.x a value you register or pass wins. For example, `register("\$os_name", "custom")` sends every event with that value. +- **Session IDs.** A registered `$session_id` overrides the SDK's session ID, which can detach events from their session replay. +- **Blank values.** A caller `$screen_name` or `$session_id` still replaces the SDK's value even when it's blank, as in 3.x.x, so a blank `$session_id` is sent as an empty `session_id`. +- **Merged maps.** In 3.x.x, a `$set`, `$set_once`, or `$groups` map in properties replaced the per-call values and the groups set with `group()`. A `$set` or `$set_once` you pass, or `userProperties`, still replaces a registered one whole. -### Event validation +`$lib` and `$lib_version` name the library that produced the event. The SDK fills them last, as a pair, only where nothing above named the library: -Capture v1 checks each event on its own and drops only the invalid ones, so the rest of the batch is delivered. +| You set | The SDK sends | +| --- | --- | +| Neither, or only `$lib_version` | Its own `$lib` and `$lib_version` | +| `$lib` as the SDK's own name, without a version | Your `$lib`, and it adds its version | +| `$lib` as another library's name | Both as they are | -The SDK drops an event whose name is empty before sending it, for example `capture("")` or one `beforeSend` renames to `""`. -With `debug` on, it logs this once. +When `$lib` names another library, the SDK never adds its own version, so set both keys together. -There's no error callback, as in 3.x. The SDK reports dropped and failed events only in its debug log. +In 3.x.x, a registered `$lib` or `$lib_version` was replaced by the SDK's, and a `$lib` you passed was sent with the SDK's `$lib_version`. -The SDK doesn't check the rest before sending. PostHog drops the event, and the SDK removes it from the queue. -With `debug` on, the SDK logs one line per batch with how many events PostHog dropped, how many duplicate copies it dropped and how many it asked to retry, with the reasons PostHog gave, never the event names or properties. -It no longer logs a line for each queued event. -Debug logs for capture requests name the event count and the response status, and no longer print the request and response bodies. -When a `beforeSend` hook throws, the debug log names the event and the exception type, not the exception message, which can hold the data the hook was removing. In 3.x it printed the exception. -When a property value can't be serialized, the debug log names the key and the value's type, not the value. In 3.x it printed the value. -Update any log-based checks that match the 3.x text. +### Check session IDs -- An event with an empty or whitespace-only distinct ID is dropped, for example one `beforeSend` sets to `""`. -- An event whose name is over 200 UTF-8 bytes is dropped. Legacy capture had no limit on event name length. -- An event whose distinct ID is over 200 UTF-8 bytes is dropped. Legacy capture shortened the ID to 200 characters and kept the event. +Capture v1 sends `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, not as properties. The SDK moves them out of `properties` for you, by the value's type: -In 3.x, an empty event name or distinct ID made legacy capture reject the whole batch it was in. +- **A string.** The SDK sends it unchanged, including an empty string. +- **`null`.** It counts as unset, and the SDK removes it without a log. +- **Any other value.** The SDK removes it and doesn't send it. With `debug` on, the SDK logs the key and the value's JSON type, never the value. -A `NaN` or infinite number in the properties is dropped from the event, and the event is sent without it. +In PostHog, the events still have `$session_id` and `$window_id`, so insights, filters, and session replay work as before. -A map key in the properties that isn't a string is converted to one when it's a number, a boolean or `null`. Any other key is dropped with its value, and the rest of the event is sent. With `debug` on, the SDK logs the key's type. In 3.x, a nested map with a non-string key lost the whole event. +### Review beforeSend hooks -A `null` element in a list or array in the properties is now sent as JSON `null` at its position, and so is an element that can't be serialized, such as `NaN`. In 3.x, both were removed, which moved the later elements to lower indexes. A property or map entry whose value is `null` is still left out. +Review your `beforeSend` hooks for the new event shape. Capture v1 reads processing settings from an `options` object sent next to `properties`, and `beforeSend` can read and change `PostHogEvent.options`. -The distinct ID can come from `identify()`, the `distinctId` argument of `capture` or `beforeSend`. -If you identify users with a long ID, such as a JWT or a long email address, shorten or hash it before you upgrade. Otherwise every event for that user is dropped. -`identify()` with an empty or whitespace-only distinct ID is still ignored, as in 3.x. +- **Person processing.** In 3.x.x, the SDK marked person processing with the `$process_person_profile` property. In 4.x.x, it's the `process_person_profile` option, and the property isn't set. To change person processing in `beforeSend`, edit `event.options`. +- **Properties a hook adds.** A `$process_person_profile` property the hook adds only fills an option that is still unset. It doesn't override the `false` the SDK set for an anonymous event. +- **New option maps.** A hook that assigns a new map to `event.options` without keeping that key loses the `false` the SDK set. That turns person processing on for anonymous users, overriding `personProfiles`. Editing `event.options` in place keeps it. +- **Copies.** `beforeSend` gets its own copy of the event's nested maps, lists, and arrays, in `properties` and `options`. Changes a hook makes no longer reach the objects you passed to `capture` or registered, and identity checks against them (`===`) no longer match. In 3.x.x, hooks edited the caller's objects. +- **Returned events.** `options` is a property of `PostHogEvent`, not a constructor parameter, so the constructor and `copy` are unchanged from 3.x.x. When `beforeSend` returns a different event whose `options` is `null`, such as one made with `event.copy(…)` or the constructor, it gets the options of the event the hook was given. To send an event with no options, set `options` to an empty map. +- **Event uuids.** The event `beforeSend` returns keeps the uuid of the capture it came from. A uuid you set in `beforeSend`, for example with `copy(uuid = …)`, is replaced. A hook that returns an event kept from an earlier call still sends one uuid per capture. +- **Timing.** `beforeSend` still runs when you capture the event, before it's queued, not when the batch is sent. -### Property precedence +### Check person processing -An event's properties are merged in this order, and later values win: +- **The SDK's value.** When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither the option nor the property, since PostHog processes person profiles by default. In 3.x.x, every event carried a `$process_person_profile` property. +- **One event.** To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. +- **Every event.** A registered `$process_person_profile` changes it for every event. In 3.x.x, the SDK's value replaced a registered `$process_person_profile`, so a registered `false` had no effect. +- **A registered `false`.** In 4.x.x it applies, also after `identify` and with `PersonProfiles.ALWAYS`. Those events don't change the person profile, and their `$set` is ignored. They are still linked to the person and billed as identified events. +- **`PersonProfiles.NEVER`.** A `process_person_profile` option or `$process_person_profile` property set to `true`, passed or registered, turns person processing on for that event. In 3.x.x, `NEVER` always won. If you rely on `NEVER` to keep events personless, make sure neither is set to `true`, or remove it in `beforeSend`. +- **`PersonProfiles.IDENTIFIED_ONLY`.** `identify`, `alias`, `group`, and `setPersonProperties` still turn on person processing for the user's later events, as in 3.x.x. +- **Duplicate checks.** A `$set` sent with `process_person_profile: false` doesn't update the person, so it no longer suppresses a later `setPersonProperties` or `identify` call with the same properties as a duplicate. -1. properties the SDK sets itself, such as `$os_name`, `$app_version`, `$screen_name`, `$is_identified`, `$session_id` and the session replay debug properties (`$recording_status`, `$sdk_debug_*`) -2. registered super properties (`register`) -3. the properties you pass to `capture` or another event-sending method; `userProperties`, `userPropertiesSetOnce` and `groups` are placed as `$set`, `$set_once` and `$groups` here, and when you also pass that key in properties they win key by key; a `$groups` map in properties adds to the groups set with `group()` instead of replacing them -4. `beforeSend` +A registered `$process_person_profile` set to `false` also reaches the events `identify`, `alias`, `group`, and `setPersonProperties` send. -In 3.x, the SDK's own values won over super properties, and `$is_identified`, `$process_person_profile` and the session replay debug properties also won over the properties you pass. -In 4.0 a value you register or pass wins, for example `register("\$os_name", "custom")` sends every event with that value. -A registered `$session_id` now overrides the SDK's session ID, which can detach events from their session replay. -A caller `$screen_name` or `$session_id` still replaces the SDK's value even when it's blank, as in 3.x, so a blank `$session_id` is sent as an empty `session_id`. -In 3.x, a `$set`, `$set_once` or `$groups` map in properties replaced the per-call values and the groups set with `group()`. A `$set` or `$set_once` you pass, or `userProperties`, still replaces a registered one whole. +PostHog accepts `$identify`, `$create_alias`, and `$groupidentify` and then drops them with an ingestion warning, and the SDK doesn't report it. A `$set` event is kept, but the person isn't updated. -`$lib` and `$lib_version` name the library that produced the event, and the SDK fills them last, as a pair, only where nothing above named the library. -When neither is set, or only `$lib_version` is, the SDK sends its own `$lib` and `$lib_version`. -When `$lib` is the SDK's own name without a version, the SDK adds its version. -When `$lib` names another library, the SDK leaves both as they are and never adds its own version, so set both keys together. -In 3.x, a registered `$lib` or `$lib_version` was replaced by the SDK's, and a `$lib` you passed was sent with the SDK's `$lib_version`. +To keep identifying, pass the option on the call, or set it in `beforeSend`: -### Session and window IDs +```kotlin +PostHog.register("\$process_person_profile", false) -Capture v1 sends `$session_id` and `$window_id` as top-level `session_id` and `window_id` fields, not as properties. -The SDK moves them out of `properties` for you. -A string value, including an empty string, is sent unchanged. -Any other value is removed and not sent. With `debug` on, the SDK logs the key and the value's JSON type, never the value. -A null value counts as unset and is removed without a log. -In PostHog, the events still have `$session_id` and `$window_id`, so insights, filters and session replay work as before. +PostHog.identify( + distinctId = "user-123", + userProperties = mapOf("plan" to "pro"), + options = mapOf("process_person_profile" to true), +) +``` -### Timestamps and IDs +If you registered `false` to skip person profiles for anonymous users, remove it. `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, the default, already does that and still lets `identify` create the person. -The SDK sends every timestamp in UTC with 3 fractional digits, for example `2026-01-01T00:00:00.000Z`, as 3.x did. -It doesn't check for future timestamps. PostHog replaces a timestamp more than 23 hours ahead with the time it received the event. -Event uuids and anonymous distinct IDs are UUID v7, as in 3.x. An anonymous ID you change with `getAnonymousId` is sent as you return it. -Each capture request also sends a UUID v7 request ID in the `PostHog-Request-Id` header, which 3.x didn't send. +To create no person profiles at all, set `personProfiles = PersonProfiles.NEVER` instead. The SDK then skips these calls. -### Event options +### Check retries -Capture v1 reads processing settings from an `options` object sent next to `properties`. -`capture` takes a new `options` argument, and `beforeSend` can read and change `PostHogEvent.options`. -`screen`, `identify`, `setPersonProperties`, `alias`, `group` and `captureException` take the same argument, as their last parameter. -For `identify`, the options apply to the `$identify` or `$set` event the call sends. +These apply to analytics and AI event requests, unless a bullet names session replay or logs. Session replay and logs keep their 3.x.x status handling: they still retry 3xx and don't retry 404. + +- **Statuses retried.** The SDK retries network errors and 404, 408, 429, 500, 502, 503, and 504 responses. Other statuses drop the events, including 3xx. 3.x.x also retried 3xx responses, and didn't retry 404. +- **Billing limits and quotas.** A 402 (billing limit) drops the whole batch. A product quota, such as for exceptions or AI events, drops only those events inside a 200 response. +- **Partial retries.** When the response asks to retry only some events, the SDK keeps those events queued and removes the rest. +- **Resent requests.** A failed request is resent with the same events, request ID, and `created_at`, and the next attempt number, before newer events are sent. The request ID and attempt number reset after an app restart. OkHttp doesn't retry capture requests on its own. +- **The `Retry-After` cap.** A `Retry-After` header sets the minimum wait before the next send, up to 30 seconds. This also applies to session replay and logs. In 3.x.x there was no cap. +- **`Retry-After` formats.** `Retry-After` can be a number of seconds or an HTTP date. 3.x.x read only a number of seconds. +- **Backoff.** After a failed send, the wait before the next one doubles from 1 second up to 30 seconds, with up to 25% random jitter at millisecond precision. In 3.x.x it doubled without jitter and a `Retry-After` replaced it. This applies to events, session replay, and logs. +- **Retry limit.** Event, session replay, and log retries have no limit, as in 3.x.x. Queued records stay until they're delivered or a full queue evicts them (`maxQueueSize`, or `logs.maxBufferSize` for logs). +- **`maxRetries`.** `maxRetries` is renamed to `pushNotificationSubscriptionMaxRetries`, with no deprecated alias. It only limits push-notification subscription retries. +- **Request size.** A request carries at most `maxBatchSize` events and about 5 MiB. The SDK sends as soon as about 5 MiB of events is queued, even before `flushAt` is reached. In 3.x.x, batches were limited by event count only. +- **Event size.** There's no size limit for one analytics event in the SDK, as in 3.x.x. An event larger than about 5 MiB is sent in a request of its own. +- **413 responses.** A 413 still halves the batch until it fits, as in 3.x.x. An event that gets a 413 on its own is dropped. + +## Follow ups + +### Move to event options + +Capture v1 reads processing settings from an `options` object sent next to `properties`. `capture`, `screen`, `identify`, `setPersonProperties`, `alias`, `group`, and `captureException` take an `options` argument. For `identify`, the options apply to the `$identify` or `$set` event the call sends. + +Pass an option in `options` instead of its `$`-prefixed property: ```kotlin -// 3.x +// 3.x.x PostHog.capture("signed_up", properties = mapOf("\$cookieless_mode" to true)) -// 4.0 +// 4.x.x PostHog.capture("signed_up", options = mapOf("cookieless_mode" to true)) ``` -Kotlin callers that use named or positional arguments for the existing parameters keep compiling. -Java callers pass the new trailing `options` argument, or `null`. -Classes that implement `PostHogInterface` add the parameter. -`identify(distinctId, userProperties, userPropertiesSetOnce)` moved from `PostHogCoreInterface` to `PostHogStatelessInterface`; call it through `PostHogInterface` or `PostHogStatelessInterface`. - -The legacy option properties, the `$`-prefixed properties legacy capture reads as settings, still work. -When the event is sent, the SDK removes each one from `properties` and uses it for its option: +The legacy option properties still work. They're the `$`-prefixed properties legacy capture reads as settings. When the event is sent, the SDK removes each one from `properties` and uses it for its option: | Legacy option property | Option | | --- | --- | @@ -489,40 +696,20 @@ When the event is sent, the SDK removes each one from `properties` and uses it f | `$ignore_sent_at` | `disable_skew_correction` | | `$product_tour_id` | `product_tour_id` | -- An option you pass to any of these methods or set in `beforeSend` wins over its legacy property. An option set to `null` counts as unset, so the legacy property fills it. -- To change person processing in `beforeSend`, edit `event.options`. A `$process_person_profile` property the hook adds only fills an option that is still unset, so it doesn't override the `false` the SDK set for an anonymous event. -- When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither, because PostHog processes person profiles by default. In 3.x, every event carried a `$process_person_profile` property. To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. A registered `$process_person_profile` changes it for every event. In 3.x, the SDK's value replaced a registered `$process_person_profile`, so a registered `false` had no effect. In 4.0 it applies, also after `identify` and with `PersonProfiles.ALWAYS`: those events don't change the person profile, and their `$set` is ignored. They are still linked to the person and billed as identified events. -- This also applies with `personProfiles = PersonProfiles.NEVER`: a `process_person_profile` option or `$process_person_profile` property set to `true`, passed or registered, turns person processing on for that event. In 3.x, `NEVER` always won. If you rely on `NEVER` to keep events personless, make sure neither is set to `true`, or remove it in `beforeSend`. -- Review your `beforeSend` hooks for the new event shape. In 3.x, the SDK marked person processing with the `$process_person_profile` property. In 4.0, it's the `process_person_profile` option, and the property isn't set. A hook that assigns a new map to `event.options` without keeping that key loses the `false` the SDK set. That turns person processing on for anonymous users, overriding `personProfiles`. Editing `event.options` in place keeps it. -- `beforeSend` gets its own copy of the event's nested maps, lists and arrays, in `properties` and `options`. Changes a hook makes no longer reach the objects you passed to `capture` or registered, and identity checks against them (`===`) no longer match. In 3.x, hooks edited the caller's objects. -- `options` is a property of `PostHogEvent`, not a constructor parameter, so the constructor and `copy` are unchanged from 3.x. When `beforeSend` returns a different event whose `options` is `null`, such as one made with `event.copy(…)` or the constructor, it gets the options of the event the hook was given. To send an event with no options, set `options` to an empty map. -- A `$set` sent with `process_person_profile: false` doesn't update the person, so it no longer suppresses a later `setPersonProperties` or `identify` call with the same properties as a duplicate. -- The SDK sends option values as given. PostHog reads common forms of a value, such as `"false"` or `0` for a boolean, and drops an event whose option value it can't read. -- Other option keys are sent unchanged, and PostHog ignores keys it doesn't know. -- There are no global or context options. To set an option on every event, register its legacy property, for example `register("\$cookieless_mode", true)`. -- There's no setting for GeoIP lookup or `historical_migration` on events, as in 3.x. -- With `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, `identify`, `alias`, `group` and `setPersonProperties` still turn on person processing for the user's later events, as in 3.x. -- A registered `$process_person_profile` set to `false` also reaches the events `identify`, `alias`, `group` and `setPersonProperties` send. PostHog accepts `$identify`, `$create_alias` and `$groupidentify` and then drops them with an ingestion warning, and the SDK doesn't report it. A `$set` event is kept, but the person isn't updated. To keep identifying, pass the option on the call, or set it in `beforeSend`: - - ```kotlin - PostHog.register("\$process_person_profile", false) - - PostHog.identify( - distinctId = "user-123", - userProperties = mapOf("plan" to "pro"), - options = mapOf("process_person_profile" to true), - ) - ``` - - If you registered `false` to skip person profiles for anonymous users, remove it: `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, the default, already does that and still lets `identify` create the person. To create no person profiles at all, set `personProfiles = PersonProfiles.NEVER` instead. The SDK then skips these calls. -- An empty or whitespace-only `distinctId` argument to `capture` now uses the current distinct ID, like `null`. In 3.x, the event was dropped. -- The event `beforeSend` returns keeps the uuid of the capture it came from. A uuid you set in `beforeSend`, for example with `copy(uuid = …)`, is replaced, so a hook that returns an event kept from an earlier call still sends one uuid per capture. -- Events still queued on disk by 3.x are sent to capture v1 after the update, with their legacy properties moved to options. - -### AI events - -4.0 adds `captureAi`, which sends AI events, such as `$ai_generation`, to PostHog's AI endpoint (`/i/v1/ai/events`) instead of the analytics endpoint. -It takes the same arguments as `capture`, and the events go through the same `beforeSend` hooks. +An option you pass to any of these methods or set in `beforeSend` wins over its legacy property. An option set to `null` counts as unset, so the legacy property fills it. + +- **Other keys.** Other option keys are sent unchanged, and PostHog ignores keys it doesn't know. +- **Every event.** There are no global or context options. To set an option on every event, register its legacy property, for example `register("\$cookieless_mode", true)`. +- **GeoIP and migrations.** To turn off GeoIP lookup, set `disableGeoIp`. It sends `$geoip_disable` as an event property, not an option. There's no setting for `historical_migration` on events, as in 3.x.x. +- **Queued events.** Events still queued on disk by 3.x.x are sent to capture v1 after the update, with their legacy properties moved to options. + +### Send AI events with captureAi + +`captureAi` sends AI events, such as `$ai_generation`, to PostHog's AI endpoint (`/i/v1/ai/events`) instead of the analytics endpoint. `capture` never sends events to the AI endpoint, even ones named `$ai_*`. + +`$ai_*` events you keep sending with `capture` still reach PostHog through the analytics endpoint, as in 3.x.x. Moving them to `captureAi` gets you the AI endpoint's much larger event size limit, and a queue of their own, so large AI events don't hold up your other events. + +`captureAi` takes the same arguments as `capture`, and the events go through the same `beforeSend` hooks: ```kotlin PostHog.captureAi( @@ -531,63 +718,14 @@ PostHog.captureAi( ) ``` -- `captureAi` returns the event's uuid, or `null` when the event isn't queued: the SDK is disabled or opted out, the event name is empty, `beforeSend` dropped it, or it's over the size limit. Once 100 AI events (`captureAiMaxQueueSize`) or 50 MiB are queued, including events still waiting to be written to disk during a slow upload, the oldest are dropped. -- An AI event's properties can be up to 8 MiB. The SDK drops a serialized event over 8 MiB + 64 KiB, measured before `encryption`. With `debug` on, it logs the event name and the limit, never the content. Set `captureAiMaxEventBytes` to lower that limit; a larger value uses 8 MiB + 64 KiB, and with `debug` on the SDK logs that it did. -- PostHog drops an event sent with `captureAi` whose name doesn't start with `$ai_`. `capture` never sends events to the AI endpoint, even ones named `$ai_*`. -- AI requests time out after 60 seconds without network activity, or `captureAiTimeout`. Other requests keep OkHttp's 10-second defaults. -- On Android, AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. -- `flush()` and `close()` also send the AI queue. On Android, AI events left on disk are sent at the next launch. -- AI requests are gzipped unless you set `captureAiCompression` to `PostHogCompression.NONE`. `compression` doesn't apply. -- AI events use `flushAt`, `maxBatchSize` and `flushIntervalSeconds`, like other events. A request carries up to about 5 MiB, as for analytics events (see [Retries](#retries)). -- The SDK sends AI events unchanged. It doesn't redact or truncate prompts, outputs or media, so use `beforeSend` to remove anything you don't want to send. - -### Retries - -These apply to analytics and AI event requests, unless a bullet names session replay or logs. Session replay and logs keep their 3.x status handling: they still retry 3xx and don't retry 404. - -- The SDK retries network errors and 404, 408, 429, 500, 502, 503 and 504 responses. Other statuses drop the events, including 3xx, and a 402 (billing limit) drops the whole batch. A product quota, such as for exceptions or AI events, drops only those events inside a 200 response. 3.x also retried 3xx responses, and didn't retry 404. -- When the response asks to retry only some events, the SDK keeps those events queued and removes the rest. -- A failed request is resent with the same events, request ID and `created_at`, and the next attempt number, before newer events are sent. The request ID and attempt number reset after an app restart. OkHttp doesn't retry capture requests on its own. -- A `Retry-After` header sets the minimum wait before the next send, up to 30 seconds. This also applies to session replay and logs. In 3.x there was no cap. -- `Retry-After` can be a number of seconds or an HTTP date. 3.x read only a number of seconds. -- After a failed send, the wait before the next one doubles from 1 second up to 30 seconds, with up to 25% random jitter at millisecond precision. In 3.x it doubled without jitter and a `Retry-After` replaced it. This applies to events, session replay and logs. -- Event, session replay and log retries have no limit, as in 3.x: queued records stay until they're delivered or a full queue evicts them (`maxQueueSize`, or `logs.maxBufferSize` for logs). -- `maxRetries` is renamed to `pushNotificationSubscriptionMaxRetries`, with no deprecated alias. It only limits push-notification subscription retries. -- A request carries at most `maxBatchSize` events and about 5 MiB, and the SDK sends as soon as about 5 MiB of events is queued, even before `flushAt` is reached. In 3.x, batches were limited by event count only. -- There's no size limit for one analytics event in the SDK, as in 3.x. An event larger than about 5 MiB is sent in a request of its own. -- A 413 still halves the batch until it fits, as in 3.x. An event that gets a 413 on its own is dropped. -- `beforeSend` still runs when you capture the event, before it's queued, not when the batch is sent. - -### New: `onFeatureFlags()` - -`onFeatureFlags()` is now the way to listen for flag loads, for example from a screen or a library. You can remove the listener later: - -```kotlin -val subscription = PostHog.onFeatureFlags { loaded -> - if (loaded.variants["new-checkout"] == "test") { - showTestVariant() - } -} - -// later -subscription.unsubscribe() -``` - -On Android, listeners run on the main thread. If flags have already loaded, a new listener also gets the current values shortly after it registers. You can register before `setup()`, and listeners stay registered across `close()` and `setup()`. - -### `posthog-server` - -`posthog-server` isn't having a major release, and its API is unchanged: it keeps its own `apiKey`, `getFeatureFlagPayload` and `remoteConfig`, and `com.posthog.PostHogOnFeatureFlags` now ships in `posthog-server` itself. None of the API changes above apply to it. `PostHogEvent`, which `beforeSend` gets, keeps its 3.x constructor and `copy`, and gains an `options` property; `posthog-server` still sends to `/batch`, which doesn't use it, so a value set in `beforeSend` is sent but has no effect. - -It still sends events to `/batch`, not to capture v1, so the endpoint, proxy, retry and event option changes above don't apply to it either. - -Using core `posthog` on its own through `PostHogStateless.with` isn't a supported entry point in core 7.0. Without its own queue it gets Android's capture v1 behavior, including the persisted-queue retries, which isn't a server-side contract. Use `posthog-server` for server-side JVM apps. A class that extends `PostHogStateless` also needs updating: the protected `buildEvent()` gained `options` and `uuid` parameters, and `captureFeatureFlagCalledEvent()` is no longer protected. - -A personal API key (`phx_...`) in `projectToken` now disables the client at setup, as an empty token does, and both print why even when `debug` is off. - -Events with an empty name are dropped before sending. `userProperties`, `userPropertiesSetOnce` and `groups` now merge key by key over a `$set`, `$set_once` or `$groups` map in `properties`. A `null` element in a list or array in the properties is sent as JSON `null` at its position instead of being removed. `beforeSend` gets its own copy of the event's nested maps, lists and arrays, so its changes no longer reach the objects you passed to `capture`. - -`posthog-server` 2.25.0 depends on core 7.0, so upgrade it and `posthog-android` together: - -- If your project uses `posthog-android` 4.0 or core 7.0, use `posthog-server` 2.25.0 or later. Older `posthog-server` versions aren't compatible with core 7.0 at runtime. -- If your project still uses `posthog-android` 3.x, stay on `posthog-server` 2.24.x. `posthog-server` 2.25 brings in core 7.0, and Gradle then upgrades `posthog-android` to 4.0. +- **Return value.** `captureAi` returns the event's uuid, or `null` when the event isn't queued. That happens when the SDK is disabled or opted out, the event name is empty, `beforeSend` dropped it, or it's over the size limit. +- **Queue limits.** Once 100 AI events (`captureAiMaxQueueSize`) or 50 MiB are queued, the oldest are dropped. The count includes events still waiting to be written to disk during a slow upload. +- **Event size.** An AI event's properties can be up to 8 MiB. The SDK drops a serialized event over 8 MiB + 64 KiB, measured before `encryption`. With `debug` on, it logs the event name and the limit, never the content. +- **A lower size limit.** Set `captureAiMaxEventBytes` to lower that limit. A larger value uses 8 MiB + 64 KiB, and with `debug` on the SDK logs that it did. +- **Event names.** PostHog drops an event sent with `captureAi` whose name doesn't start with `$ai_`. +- **Timeouts.** AI requests time out after 60 seconds without network activity, or `captureAiTimeout`. Other requests keep OkHttp's 10-second defaults. +- **Disk queue.** On Android, AI events are queued on disk separately from other events (`posthog-disk-ai-queue` in the app's cache directory). Up to 100 events (`captureAiMaxQueueSize`) and 50 MiB are kept, and the oldest are dropped first. `maxQueueSize` doesn't apply. +- **Flushing.** `flush()` and `close()` also send the AI queue. On Android, AI events left on disk are sent at the next launch. +- **Compression.** AI requests are gzipped unless you set `captureAiCompression` to `PostHogCompression.NONE`. `compression` doesn't apply. +- **Batching.** AI events use `flushAt`, `maxBatchSize`, and `flushIntervalSeconds`, like other events. A request carries up to about 5 MiB, as for analytics events (see [Check retries](#check-retries)). +- **Content.** The SDK sends AI events unchanged. It doesn't redact or truncate prompts, outputs, or media, so use `beforeSend` to remove anything you don't want to send. From 9217eecad76b4c43e729478be759f2f35efd539b Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Fri, 13 Nov 2026 15:04:36 -0500 Subject: [PATCH 46/49] fix: keep a registered personless setting off identity events (#979) * fix: keep a registered personless setting off identity events A registered `$process_person_profile: false`, or a `process_person_profile` option a wrapper registers, no longer applies to `$identify`, `$create_alias`, `$merge_dangerously`, `$groupidentify`, `$set` and `$set_once`. PostHog drops those events with person processing off. A value passed on the call or set in `beforeSend` still applies. * docs: note the identity-event exception on register * docs: keep the $set and $set_once distinction in the migration guide * test: cover $set_once, $merge_dangerously, a call property and beforeSend --- .changeset/android-v4-major.md | 1 + MIGRATION.md | 20 ++----- posthog/src/main/java/com/posthog/PostHog.kt | 29 ++++++---- .../main/java/com/posthog/PostHogInterface.kt | 6 +- .../com/posthog/PostHogWrapperEventTest.kt | 55 +++++++++++++++++-- 5 files changed, 79 insertions(+), 32 deletions(-) diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 43be95729..42755586a 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -14,6 +14,7 @@ - **Breaking:** set the `process_person_profile` option to `false` only when person processing is off, instead of adding a `$process_person_profile` property to every event - **Breaking:** let a `process_person_profile` option or `$process_person_profile` property set to `true` turn person processing on for an event even with `PersonProfiles.NEVER` - **Breaking:** let registered super properties override properties the SDK sets, such as `$os_name`, and let super and event properties override `$is_identified`, `$process_person_profile` and the session replay debug properties +- Ignore a registered `$process_person_profile` or `process_person_profile` option on `$identify`, `$create_alias`, `$merge_dangerously`, `$groupidentify`, `$set` and `$set_once`, so a registered `false` doesn't stop identifying users - **Breaking:** fill `$lib` and `$lib_version` last and as a pair, only when the event doesn't name its library. A `$lib` you register or pass is sent as it is, without the SDK's version - **Breaking:** let `userProperties`, `userPropertiesSetOnce` and `groups` win key by key over `$set`, `$set_once` and `$groups` maps in the same call's properties, and merge a `$groups` map in properties into the groups set with `group()` - **Breaking:** keep the event's own uuid when `beforeSend` returns an event with another uuid diff --git a/MIGRATION.md b/MIGRATION.md index 3bb90c8c3..d38b3878d 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -50,7 +50,7 @@ Read the checklist first, then the sections that apply to you. - [ ] You read `$session_id` or `$window_id` from the raw request body, for example in a proxy → [Check session IDs](#check-session-ids) - [ ] You assign a new map to `event.options` in `beforeSend` → [Review beforeSend hooks](#review-beforesend-hooks) - [ ] You set the event `uuid` in `beforeSend` → [Review beforeSend hooks](#review-beforesend-hooks) -- [ ] You register `$process_person_profile` as `false` and still call `identify`, `alias`, `group`, or `setPersonProperties` → [Check person processing](#check-person-processing) +- [ ] You register `$process_person_profile` as `false` and expect it to keep every event personless → [Check person processing](#check-person-processing) - [ ] You rely on a `Retry-After` longer than 30 seconds → [Check retries](#check-retries) - [ ] You set `maxRetries` on `PostHogConfig` or `PostHogAndroidConfig` → [Check retries](#check-retries) @@ -625,26 +625,14 @@ Review your `beforeSend` hooks for the new event shape. Capture v1 reads process - **The SDK's value.** When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither the option nor the property, since PostHog processes person profiles by default. In 3.x.x, every event carried a `$process_person_profile` property. - **One event.** To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. - **Every event.** A registered `$process_person_profile` changes it for every event. In 3.x.x, the SDK's value replaced a registered `$process_person_profile`, so a registered `false` had no effect. -- **A registered `false`.** In 4.x.x it applies, also after `identify` and with `PersonProfiles.ALWAYS`. Those events don't change the person profile, and their `$set` is ignored. They are still linked to the person and billed as identified events. +- **A registered `false`.** In 4.x.x it applies, also after `identify` and with `PersonProfiles.ALWAYS`. Those events don't change the person profile, and their `$set` is ignored. They are still linked to the person and billed as identified events. It doesn't apply to identity events (see below). - **`PersonProfiles.NEVER`.** A `process_person_profile` option or `$process_person_profile` property set to `true`, passed or registered, turns person processing on for that event. In 3.x.x, `NEVER` always won. If you rely on `NEVER` to keep events personless, make sure neither is set to `true`, or remove it in `beforeSend`. - **`PersonProfiles.IDENTIFIED_ONLY`.** `identify`, `alias`, `group`, and `setPersonProperties` still turn on person processing for the user's later events, as in 3.x.x. - **Duplicate checks.** A `$set` sent with `process_person_profile: false` doesn't update the person, so it no longer suppresses a later `setPersonProperties` or `identify` call with the same properties as a duplicate. -A registered `$process_person_profile` set to `false` also reaches the events `identify`, `alias`, `group`, and `setPersonProperties` send. +A registered `$process_person_profile`, or a `process_person_profile` option a wrapper SDK registers, doesn't apply to identity events: `$identify`, `$create_alias`, `$merge_dangerously`, `$groupidentify`, `$set`, and `$set_once`. -PostHog accepts `$identify`, `$create_alias`, and `$groupidentify` and then drops them with an ingestion warning, and the SDK doesn't report it. A `$set` event is kept, but the person isn't updated. - -To keep identifying, pass the option on the call, or set it in `beforeSend`: - -```kotlin -PostHog.register("\$process_person_profile", false) - -PostHog.identify( - distinctId = "user-123", - userProperties = mapOf("plan" to "pro"), - options = mapOf("process_person_profile" to true), -) -``` +With person processing off, PostHog drops `$identify`, `$create_alias`, `$merge_dangerously`, and `$groupidentify`, and keeps `$set` and `$set_once` but ignores their person update. So a registered `false` would stop `identify`, `alias`, `group`, and `setPersonProperties` from working. A value you pass on the call, or set in `beforeSend`, still applies. If you registered `false` to skip person profiles for anonymous users, remove it. `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, the default, already does that and still lets `identify` create the person. diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index 4430702f6..c0162e840 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -893,6 +893,7 @@ public class PostHog private constructor( appendSharedProps: Boolean = true, appendGroups: Boolean = true, timestamp: Date? = null, + isIdentityEvent: Boolean = false, claimReplayDebugBundle: () -> Boolean = { false }, readReplayDebugProperties: () -> Map = ::readReplayDebugProperties, ): MutableMap { @@ -970,6 +971,9 @@ public class PostHog private constructor( if (registeredPrefs.isNotEmpty()) { props.putAll(registeredPrefs) } + if (isIdentityEvent) { + props.remove("\$process_person_profile") + } // Per-call values win over registered ones. userProperties?.let { @@ -1124,14 +1128,16 @@ public class PostHog private constructor( * legacy `$process_person_profile` property in [properties] (per call or registered) already * says otherwise. Nothing is added otherwise: PostHog processes person profiles by default. * [personProcessingPending] counts a person processing change a wrapper build defers to its - * send. Returns a copy, so `beforeSend` edits never reach the caller's map. + * send. An [isIdentityEvent] skips the registered `process_person_profile`. Returns a copy, so + * `beforeSend` edits never reach the caller's map. */ private fun optionsForEvent( options: Map?, properties: Map, personProcessingPending: Boolean = false, + isIdentityEvent: Boolean = false, ): MutableMap? { - val registered = getRegisteredOptions() + val registered = getRegisteredOptions().let { if (isIdentityEvent) it - "process_person_profile" else it } val eventOptions = if (registered.isEmpty()) { options?.toMutableMap() @@ -1154,16 +1160,10 @@ public class PostHog private constructor( /** * Whether a `$set` sent with [options] surely updates the person: the setting is missing or a * Boolean `true`. Any other value, including a false one, might not, so it never records a hash. + * Registered values don't apply to identity events, so only [options] counts. */ private fun surelyProcessesPersonProfile(options: Map?): Boolean { - // An explicit null in [options] replaces the registered option, as in optionsForEvent. - val option = - if (options?.containsKey("process_person_profile") == true) { - options["process_person_profile"] - } else { - getRegisteredOptions()["process_person_profile"] - } - val value = option ?: getPreferences().getValue("\$process_person_profile") + val value = options?.get("process_person_profile") return value == null || value == true } @@ -1393,6 +1393,7 @@ public class PostHog private constructor( if (event == PostHogEventName.GROUP_IDENTIFY.event) { groupIdentify = true } + val isIdentityEvent = event in IDENTITY_EVENTS // Externally-built $exception events (e.g. the Flutter/RN bridge) carry only // serialized class names, so they are matched by name instead of isInstance. @@ -1432,6 +1433,7 @@ public class PostHog private constructor( // only append groups if not a group identify event and not a snapshot appendGroups = !groupIdentify, timestamp = timestamp, + isIdentityEvent = isIdentityEvent, claimReplayDebugBundle = { isReplayDebugEvent(event) && claimReplayDebugBundle() }, readReplayDebugProperties = readReplayDebugProperties, ) @@ -1443,7 +1445,7 @@ public class PostHog private constructor( if (isSnapshotEvent) { options?.toMutableMap() } else { - optionsForEvent(options, mergedProperties, deferPersonProcessing && requiresPersonProcessing) + optionsForEvent(options, mergedProperties, deferPersonProcessing && requiresPersonProcessing, isIdentityEvent) } // This capture's identity, kept through beforeSend. @@ -3420,6 +3422,11 @@ public class PostHog private constructor( private val projectTokens = mutableSetOf() + // Events that change a person or group. PostHog drops or ignores them when person + // processing is off, so a registered `process_person_profile` doesn't apply to them. + private val IDENTITY_EVENTS = + setOf("\$identify", "\$create_alias", "\$merge_dangerously", "\$groupidentify", "\$set", "\$set_once") + /** * Captures application log records into PostHog's logs product * (separate from product analytics events). Forwards to the shared diff --git a/posthog/src/main/java/com/posthog/PostHogInterface.kt b/posthog/src/main/java/com/posthog/PostHogInterface.kt index 27147494c..6cc779ee5 100644 --- a/posthog/src/main/java/com/posthog/PostHogInterface.kt +++ b/posthog/src/main/java/com/posthog/PostHogInterface.kt @@ -352,6 +352,9 @@ public interface PostHogInterface : PostHogCoreInterface { * [unregister] with the same key. The property persists across app restarts. * PostHogPreferences.ALL_INTERNAL_KEYS are not allowed since they are internal and used by * the SDK only. + * A registered `$process_person_profile` isn't sent with `$identify`, `$create_alias`, + * `$merge_dangerously`, `$groupidentify`, `$set` or `$set_once`, so it can't stop those events + * from updating persons and groups. A value passed on the call still applies. * @param key the Key * @param value the Value */ @@ -709,7 +712,8 @@ public interface PostHogInterface : PostHogCoreInterface { * * Registers capture options sent with every later event, under each event's own options. New * values overwrite existing ones for the same keys and persist across app restarts until removed - * with [unregisterOptionsForWrapper] or cleared by `reset()`. + * with [unregisterOptionsForWrapper] or cleared by `reset()`. A registered `process_person_profile` + * isn't sent with identity events, as described on [register]. * * @suppress */ diff --git a/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt b/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt index 07995d3a1..2b4f22d5b 100644 --- a/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogWrapperEventTest.kt @@ -528,22 +528,69 @@ internal class PostHogWrapperEventTest { } @Test - fun `an explicit null option over a registered one doesn't mark a personless $set as processed`() { + fun `a registered personless setting doesn't reach identity events`() { + val http = httpServers.mockHttp(total = 7) + val sut = getSut(http) + sut.registerOptionsForWrapper(mapOf("process_person_profile" to false)) + sut.register("\$process_person_profile", false) + + sut.identify("user") + sut.alias("other") + sut.group("company", "acme", mapOf("name" to "Acme")) + sut.setPersonProperties(mapOf("plan" to "pro")) + sut.capture("\$set_once", userPropertiesSetOnce = mapOf("first" to "web")) + sut.capture("\$merge_dangerously", properties = mapOf("alias" to "anon")) + sut.capture("plain") + queueExecutor.awaitExecution() + val sent = (1..7).flatMap { events(takeRequest(http)) }.associateBy { it["event"] } + + val identityEvents = listOf("\$identify", "\$create_alias", "\$groupidentify", "\$set", "\$set_once", "\$merge_dangerously") + for (event in identityEvents) { + val identity = assertNotNull(sent[event], event) + assertNull(identity.options()?.get("process_person_profile"), event) + assertFalse(identity.properties().containsKey("\$process_person_profile"), event) + } + assertEquals(false, assertNotNull(sent["plain"]).options()?.get("process_person_profile")) + } + + @Test + fun `a call's personless setting still applies to an identity event`() { val http = httpServers.mockHttp() val sut = getSut(http) sut.registerOptionsForWrapper(mapOf("process_person_profile" to true)) - sut.register("\$process_person_profile", false) - sut.setPersonProperties(mapOf("plan" to "pro"), null, mapOf("process_person_profile" to null)) + sut.setPersonProperties(mapOf("plan" to "pro"), null, mapOf("process_person_profile" to false)) queueExecutor.awaitExecution() val personless = events(takeRequest(http)).single() - sut.setPersonProperties(mapOf("plan" to "pro"), null, null) + sut.setPersonProperties(mapOf("plan" to "pro")) queueExecutor.awaitExecution() assertEquals(false, personless.options()?.get("process_person_profile")) assertEquals(2, http.requestCount) } + @Test + fun `a call property or beforeSend can still turn person processing off for an identity event`() { + val http = httpServers.mockHttp(total = 2) + val sut = + getSut(http) { + addBeforeSend { event -> + if (event.event == "\$identify") event.options = mutableMapOf("process_person_profile" to false) + event + } + } + sut.register("\$process_person_profile", true) + + sut.capture("\$set", properties = mapOf("\$process_person_profile" to false), userProperties = mapOf("plan" to "pro")) + sut.identify("user") + queueExecutor.awaitExecution() + val sent = (1..2).flatMap { events(takeRequest(http)) }.associateBy { it["event"] } + + for (event in listOf("\$set", "\$identify")) { + assertEquals(false, assertNotNull(sent[event], event).options()?.get("process_person_profile"), event) + } + } + @Test fun `unregister and reset remove registered options`() { val http = httpServers.mockHttp() From 7bd8b1950bdf7ecfa346d7b2f3808cfb2460a912 Mon Sep 17 00:00:00 2001 From: Anna Garcia Date: Fri, 13 Nov 2026 15:17:25 -0500 Subject: [PATCH 47/49] docs: regenerate the migration page from MIGRATION.md after #979 The generated page still told users that a registered $process_person_profile reaches identify, alias, group and setPersonProperties, which #979 changed. Co-Authored-By: Claude Opus 5.5 --- references/posthog-android-migration.md | 20 ++++---------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/references/posthog-android-migration.md b/references/posthog-android-migration.md index fdb5d10e6..0305c98ac 100644 --- a/references/posthog-android-migration.md +++ b/references/posthog-android-migration.md @@ -54,7 +54,7 @@ Read the checklist first, then the sections that apply to you. - [ ] You read `$session_id` or `$window_id` from the raw request body, for example in a proxy → [Check session IDs](#check-session-ids) - [ ] You assign a new map to `event.options` in `beforeSend` → [Review beforeSend hooks](#review-beforesend-hooks) - [ ] You set the event `uuid` in `beforeSend` → [Review beforeSend hooks](#review-beforesend-hooks) -- [ ] You register `$process_person_profile` as `false` and still call `identify`, `alias`, `group`, or `setPersonProperties` → [Check person processing](#check-person-processing) +- [ ] You register `$process_person_profile` as `false` and expect it to keep every event personless → [Check person processing](#check-person-processing) - [ ] You rely on a `Retry-After` longer than 30 seconds → [Check retries](#check-retries) - [ ] You set `maxRetries` on `PostHogConfig` or `PostHogAndroidConfig` → [Check retries](#check-retries) @@ -629,26 +629,14 @@ Review your `beforeSend` hooks for the new event shape. Capture v1 reads process - **The SDK's value.** When `personProfiles` turns person processing off, the SDK sets the `process_person_profile` option to `false`. Otherwise it sends neither the option nor the property, since PostHog processes person profiles by default. In 3.x.x, every event carried a `$process_person_profile` property. - **One event.** To change person processing for one event, pass the `process_person_profile` option or the `$process_person_profile` property. - **Every event.** A registered `$process_person_profile` changes it for every event. In 3.x.x, the SDK's value replaced a registered `$process_person_profile`, so a registered `false` had no effect. -- **A registered `false`.** In 4.x.x it applies, also after `identify` and with `PersonProfiles.ALWAYS`. Those events don't change the person profile, and their `$set` is ignored. They are still linked to the person and billed as identified events. +- **A registered `false`.** In 4.x.x it applies, also after `identify` and with `PersonProfiles.ALWAYS`. Those events don't change the person profile, and their `$set` is ignored. They are still linked to the person and billed as identified events. It doesn't apply to identity events (see below). - **`PersonProfiles.NEVER`.** A `process_person_profile` option or `$process_person_profile` property set to `true`, passed or registered, turns person processing on for that event. In 3.x.x, `NEVER` always won. If you rely on `NEVER` to keep events personless, make sure neither is set to `true`, or remove it in `beforeSend`. - **`PersonProfiles.IDENTIFIED_ONLY`.** `identify`, `alias`, `group`, and `setPersonProperties` still turn on person processing for the user's later events, as in 3.x.x. - **Duplicate checks.** A `$set` sent with `process_person_profile: false` doesn't update the person, so it no longer suppresses a later `setPersonProperties` or `identify` call with the same properties as a duplicate. -A registered `$process_person_profile` set to `false` also reaches the events `identify`, `alias`, `group`, and `setPersonProperties` send. +A registered `$process_person_profile`, or a `process_person_profile` option a wrapper SDK registers, doesn't apply to identity events: `$identify`, `$create_alias`, `$merge_dangerously`, `$groupidentify`, `$set`, and `$set_once`. -PostHog accepts `$identify`, `$create_alias`, and `$groupidentify` and then drops them with an ingestion warning, and the SDK doesn't report it. A `$set` event is kept, but the person isn't updated. - -To keep identifying, pass the option on the call, or set it in `beforeSend`: - -```kotlin -PostHog.register("\$process_person_profile", false) - -PostHog.identify( - distinctId = "user-123", - userProperties = mapOf("plan" to "pro"), - options = mapOf("process_person_profile" to true), -) -``` +With person processing off, PostHog drops `$identify`, `$create_alias`, `$merge_dangerously`, and `$groupidentify`, and keeps `$set` and `$set_once` but ignores their person update. So a registered `false` would stop `identify`, `alias`, `group`, and `setPersonProperties` from working. A value you pass on the call, or set in `beforeSend`, still applies. If you registered `false` to skip person profiles for anonymous users, remove it. `personProfiles = PersonProfiles.IDENTIFIED_ONLY`, the default, already does that and still lets `identify` create the person. From 3433e90e5b87fe751613977d2a502d33f526b262 Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 16 Nov 2026 09:51:12 -0500 Subject: [PATCH 48/49] fix: close replay masking and legacy retry gaps from 4.0 review (#980) * fix: close replay masking and legacy retry gaps from 4.0 review - Mask Compose text that a negative TextIndent paints left of its layout box (or right of it, for right-to-left text). - Read cleared text semantics from SemanticsModifier elements on Compose 1.0-1.2, which have no getTail, instead of discarding every frame. - Re-queue one copy per uuid when capture asks to retry legacy events, since it drops a uuid's later copies in a batch for good. Co-Authored-By: Claude Opus 5.5 * fix: measure only rendered text and keep node runtimes fail-closed - Skip clearAndSetSemantics { text = ... } replacements when looking for the text to measure: only semantics with GetTextLayoutResult count. - A missing getTail is only expected on pre-1.3 layout wrappers. On a NodeCoordinator it throws again, so the frame is discarded. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- posthog-android/consumer-rules.pro | 1 + .../replay/PostHogReplayIntegration.kt | 42 ++++++++++++--- .../PostHogReplayComposeMaskScopeTest.kt | 51 +++++++++++++++++++ .../PostHogSendCachedEventsIntegration.kt | 7 ++- ...ogSendCachedLegacyEventsIntegrationTest.kt | 18 +++++++ 5 files changed, 112 insertions(+), 7 deletions(-) diff --git a/posthog-android/consumer-rules.pro b/posthog-android/consumer-rules.pro index deaab4cfe..fa0bbb539 100644 --- a/posthog-android/consumer-rules.pro +++ b/posthog-android/consumer-rules.pro @@ -124,6 +124,7 @@ public void applySemantics(androidx.compose.ui.semantics.SemanticsPropertyReceiver); } -keepnames class androidx.compose.ui.node.DelegatingNode +-keepnames class androidx.compose.ui.node.NodeCoordinator # Session replay walks the Compose layout tree to mask images that have no semantics. -keepclassmembers class androidx.compose.ui.node.LayoutNode { diff --git a/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt b/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt index d3c3a29a2..71b9fa9b2 100644 --- a/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt +++ b/posthog-android/src/main/java/com/posthog/android/replay/PostHogReplayIntegration.kt @@ -48,6 +48,7 @@ import androidx.compose.ui.layout.LayoutInfo import androidx.compose.ui.node.RootForTest import androidx.compose.ui.semantics.SemanticsActions import androidx.compose.ui.semantics.SemanticsConfiguration +import androidx.compose.ui.semantics.SemanticsModifier import androidx.compose.ui.semantics.SemanticsNode import androidx.compose.ui.semantics.SemanticsProperties import androidx.compose.ui.semantics.SemanticsPropertyKey @@ -1956,26 +1957,44 @@ public class PostHogReplayIntegration( return config } for (info in layoutInfo.getModifierInfo()) { + // Compose before 1.3 has no modifier nodes: text semantics are a SemanticsModifier element. + (info.modifier as? SemanticsModifier)?.semanticsConfiguration?.let { + if (it.isRenderedText()) { + return it + } + } val coordinates = info.coordinates - val node = coordinates.javaClass.getMethod("getTail").invoke(coordinates) ?: continue + val getTail = + try { + coordinates.javaClass.getMethod("getTail") + } catch (e: NoSuchMethodException) { + check(!coordinates.isA(NODE_COORDINATOR)) { "Can't read the modifier nodes of $coordinates" } + continue + } + val node = getTail.invoke(coordinates) ?: continue val applySemantics = try { node.javaClass.getMethod("applySemantics", SemanticsPropertyReceiver::class.java) } catch (e: NoSuchMethodException) { - check(!node.isDelegatingNode()) { "Can't read the semantics delegated by $node" } + check(!node.isA(DELEGATING_NODE)) { "Can't read the semantics delegated by $node" } continue } val semantics = SemanticsConfiguration() applySemantics.invoke(node, semantics) - if (semantics.contains(SemanticsProperties.Text)) { + if (semantics.isRenderedText()) { return semantics } } return config } - private fun Any.isDelegatingNode(): Boolean { - return generateSequence>(javaClass) { it.superclass }.any { it.name == "androidx.compose.ui.node.DelegatingNode" } + // The text's own semantics, not a clearAndSetSemantics { text = ... } replacement, which can't be measured. + private fun SemanticsConfiguration.isRenderedText(): Boolean { + return contains(SemanticsProperties.Text) && contains(SemanticsActions.GetTextLayoutResult) + } + + private fun Any.isA(className: String): Boolean { + return generateSequence>(javaClass) { it.superclass }.any { it.name == className } } // Text(String) rebuilds its paragraph on every GetTextLayoutResult call, so a capture's walks @@ -2012,7 +2031,14 @@ public class PostHogReplayIntegration( val paragraph = layout.multiParagraph // This result is re-wrapped to the box, but softWrap = false draws one unwrapped line. val width = if (input.softWrap) paragraph.width else max(paragraph.width, paragraph.intrinsics.maxIntrinsicWidth) - glyphs = glyphs.copy(right = max(glyphs.right, width), bottom = max(glyphs.bottom, paragraph.height)) + // A negative TextIndent starts a line left of the box, or right of it for right-to-left text. + val lineStarts = (0 until paragraph.lineCount).map { paragraph.getHorizontalPosition(paragraph.getLineStart(it), true) } + glyphs = + glyphs.copy( + left = min(glyphs.left, lineStarts.minOrNull() ?: 0f), + right = maxOf(glyphs.right, width, lineStarts.maxOrNull() ?: 0f), + bottom = max(glyphs.bottom, paragraph.height), + ) overdraws = true } val strokes = listOfNotNull(input.style.textStroke()) + input.text.spanStyles.mapNotNull { it.item.textStroke() } @@ -3493,6 +3519,10 @@ public class PostHogReplayIntegration( // discards this tick and retries at the next scheduled snapshot. private const val MAX_BASELINE_ARM_ATTEMPTS: Int = 3 + // Compose internals, matched by name in textSemantics(). Kept by consumer-rules.pro. + private const val NODE_COORDINATOR: String = "androidx.compose.ui.node.NodeCoordinator" + private const val DELEGATING_NODE: String = "androidx.compose.ui.node.DelegatingNode" + private val integrationInstalled = AtomicBoolean(false) } } diff --git a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayComposeMaskScopeTest.kt b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayComposeMaskScopeTest.kt index 533f210d6..ad3339b69 100644 --- a/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayComposeMaskScopeTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/replay/PostHogReplayComposeMaskScopeTest.kt @@ -38,9 +38,11 @@ import androidx.compose.ui.text.SpanStyle import androidx.compose.ui.text.TextStyle import androidx.compose.ui.text.buildAnnotatedString import androidx.compose.ui.text.input.PasswordVisualTransformation +import androidx.compose.ui.text.style.TextIndent import androidx.compose.ui.text.style.TextOverflow import androidx.compose.ui.text.withStyle import androidx.compose.ui.unit.dp +import androidx.compose.ui.unit.sp import com.posthog.android.PROJECT_TOKEN import com.posthog.android.PostHogAndroidConfig import com.posthog.android.internal.InteractionActivity @@ -139,6 +141,40 @@ internal class PostHogReplayComposeMaskScopeTest { assertTrue(mask.right > bounds.right, "expected $mask to extend past $bounds") } + @Test + fun `visible overflow left of the layout box from a negative indent is covered by its mask`() { + compose.activity.setContent { + BasicText( + "secret", + Modifier.padding(start = 100.dp).then(textModifier).testTag("text"), + style = TextStyle(textIndent = TextIndent(firstLine = (-40).sp)), + overflow = TextOverflow.Visible, + ) + } + + val bounds = boundsOf("text") + val mask = maskRects().single() + assertTrue(mask.contains(bounds)) + assertTrue(mask.left < bounds.left, "expected $mask to extend left of $bounds") + } + + @Test + fun `visible overflow right of the layout box from a negative right-to-left indent is covered by its mask`() { + compose.activity.setContent { + BasicText( + "\u05e1\u05d5\u05d3", + Modifier.padding(start = 100.dp).then(textModifier).testTag("text"), + style = TextStyle(textIndent = TextIndent(firstLine = (-40).sp)), + overflow = TextOverflow.Visible, + ) + } + + val bounds = boundsOf("text") + val mask = maskRects().single() + assertTrue(mask.contains(bounds)) + assertTrue(mask.right > bounds.right, "expected $mask to extend right of $bounds") + } + @Test fun `postHogMask covers the visible overflow of text`() { compose.activity.setContent { @@ -382,6 +418,21 @@ internal class PostHogReplayComposeMaskScopeTest { assertTrue(mask.right > boundsOf("text").right, "expected $mask to extend past the layout box") } + @Test + fun `visible overflow of text with replacement text semantics is covered by its mask`() { + compose.activity.setContent { + BasicText( + "a secret far wider than its layout box", + Modifier.testTag("text").clearAndSetSemantics { text = AnnotatedString("label") }.then(textModifier), + softWrap = false, + overflow = TextOverflow.Visible, + ) + } + + val mask = maskRects().single() + assertTrue(mask.right > boundsOf("text").right, "expected $mask to extend past the layout box") + } + @Test fun `postHogMask covers the visible overflow of text with cleared semantics`() { compose.activity.setContent { diff --git a/posthog/src/main/java/com/posthog/internal/PostHogSendCachedEventsIntegration.kt b/posthog/src/main/java/com/posthog/internal/PostHogSendCachedEventsIntegration.kt index 8f353c30e..af450a581 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogSendCachedEventsIntegration.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogSendCachedEventsIntegration.kt @@ -115,7 +115,12 @@ internal class PostHogSendCachedEventsIntegration( try { val retryUuids = api.captureV1(events).retryIds if (retryUuids.isNotEmpty()) { - retryBytes = eventsBytes.filterIndexed { index, _ -> events[index].uuid?.toString() in retryUuids } + // One copy per uuid: capture drops a uuid's later copies in a batch for good. + retryBytes = + eventsBytes.indices + .filter { events[it].uuid?.toString() in retryUuids } + .distinctBy { events[it].uuid } + .map { eventsBytes[it] } } } catch (e: PostHogApiError) { if (isCaptureV1RetriableStatusCode(e.statusCode)) { diff --git a/posthog/src/test/java/com/posthog/internal/PostHogSendCachedLegacyEventsIntegrationTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogSendCachedLegacyEventsIntegrationTest.kt index 78b239036..e82185fbe 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogSendCachedLegacyEventsIntegrationTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogSendCachedLegacyEventsIntegrationTest.kt @@ -160,6 +160,24 @@ internal class PostHogSendCachedLegacyEventsIntegrationTest { assertEquals(listOf(retried), retained(prefix)) } + @Test + fun `re-queues one copy of a retried event that the queue holds twice`() { + val retried = event.replace("8837f4d8-01e3-4bb8-b3f3-16b8fa8173e5", "11111111-0b10-42e2-b3d4-8f35af1b11f6") + val prefix = writeLegacyFile(listOf(retried, retried, event)) + val http = + servers.mockHttp( + response = + MockResponse().setBody( + "{\"results\":{\"11111111-0b10-42e2-b3d4-8f35af1b11f6\":{\"result\":\"retry\",\"duplicates_dropped\":1}," + + "\"8837f4d8-01e3-4bb8-b3f3-16b8fa8173e5\":{\"result\":\"ok\"}}}", + ), + ) + getSut(prefix, http.url("/").toString()).install(mock()) + executor.shutdownAndAwaitTermination() + assertEquals(1, http.requestCount) + assertEquals(listOf(retried), retained(prefix)) + } + @Test fun `sends events from the legacy queue in batches`() { val prefix = writeLegacyFile(listOf(event, event)) From 36253029f81faf0fc7399b5155f1f12a680072ec Mon Sep 17 00:00:00 2001 From: Anna Garcia <11654201+turnipdabeets@users.noreply.github.com> Date: Mon, 16 Nov 2026 13:36:30 -0500 Subject: [PATCH 49/49] feat!: enable surveys by default (#984) * feat!: enable surveys by default Match the iOS, Flutter, React Native, web and KMP SDKs. Surveys still display only with posthog-android-surveys-compose or a custom surveysDelegate. * fix: skip survey matching without a survey UI Without posthog-android-surveys-compose or a custom surveysDelegate, the default delegate only logs, so matching evaluated linked flags (capturing $feature_flag_called) and property-filter regexes for surveys nobody could see. * chore: fold the surveys default changeset into the 4.0 changeset Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .changeset/android-v4-major.md | 1 + MIGRATION.md | 16 ++++++ .../surveys/PostHogSurveysIntegration.kt | 11 +++- .../PostHogSurveysEventPropertyFilterTest.kt | 2 + .../surveys/PostHogSurveysNoRendererTest.kt | 51 +++++++++++++++++++ .../java/com/posthog/android/sample/MyApp.kt | 3 -- .../main/java/com/posthog/PostHogConfig.kt | 16 ++++-- .../java/com/posthog/PostHogConfigTest.kt | 5 ++ 8 files changed, 96 insertions(+), 9 deletions(-) create mode 100644 posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysNoRendererTest.kt diff --git a/.changeset/android-v4-major.md b/.changeset/android-v4-major.md index 42755586a..1358c7cdf 100644 --- a/.changeset/android-v4-major.md +++ b/.changeset/android-v4-major.md @@ -26,6 +26,7 @@ - **Breaking:** remove the deprecated `propertiesSanitizer` option and `PostHogPropertiesSanitizer`. Use `addBeforeSend` - **Breaking:** remove the deprecated `evaluationEnvironments` option. Use `evaluationContexts` - **Breaking:** remove the deprecated `remoteConfig` option. The SDK always loads remote config at setup +- **Breaking:** enable `surveys` by default. Surveys display when the app depends on `posthog-android-surveys-compose` or sets `surveysConfig.surveysDelegate`; set `surveys = false` to keep them off - **Breaking:** remove the deprecated `getFeatureFlagPayload()`. Use `getFeatureFlagResult(key, sendFeatureFlagEvent = false)?.payload` - **Breaking:** remove the `defaultValue` parameter from `getFeatureFlag()`, which returns `null` for a missing flag or a disabled SDK. A positional `Boolean` second argument now sets `sendFeatureFlagEvent`, and `$feature_flag_called` no longer reports a fallback as the flag's value - **Breaking:** leave `$feature_flag_response` out of `$feature_flag_called` for a missing flag instead of sending an empty string diff --git a/MIGRATION.md b/MIGRATION.md index d38b3878d..69f3bcda1 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -42,6 +42,7 @@ Read the checklist first, then the sections that apply to you. - [ ] You break down by `$locale` for the language your app shows (use `$app_language`, and call `setAppLanguage()` if you need it on Android 6 to 12) → [Check locale properties](#check-locale-properties) - [ ] You use session replay → [Check session replay](#check-session-replay) - [ ] You read `$`-prefixed query parameters from `Deep Link Opened` events → [Check deep links](#check-deep-links) +- [ ] You depend on `posthog-android-surveys-compose` or set `surveysConfig.surveysDelegate`, and don't set `surveys` → [Check surveys](#check-surveys) - [ ] You capture events with an empty event name, or with an event name over 200 bytes → [Check dropped events](#check-dropped-events) - [ ] You set an empty distinct ID in `beforeSend` → [Check dropped events](#check-dropped-events) - [ ] You set `$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at`, or `$product_tour_id` to a value PostHog can't read, such as `"maybe"` → [Check dropped events](#check-dropped-events) @@ -538,6 +539,21 @@ The `Deep Link Opened` event leaves out query parameters whose name starts with Other parameters and the `url` property are sent as in 3.x.x. +### Check surveys + +`surveys` defaults to `true`, as in the iOS, Flutter, React Native and web SDKs. In 3.x.x it defaulted to `false`. + +Surveys still display only when your app depends on `posthog-android-surveys-compose` or sets `surveysConfig.surveysDelegate`. Without either, nothing changes. + +If you have one of them but don't want surveys to show, turn them off: + +```kotlin +// 4.x.x +config.surveys = false +``` + +If you already set `surveys = true`, you can remove the line. + ### Check dropped events Capture v1 checks each event on its own and drops only the invalid ones, so the rest of the batch is delivered. In 3.x.x, an empty event name or distinct ID made legacy capture reject the whole batch it was in. diff --git a/posthog-android/src/main/java/com/posthog/android/surveys/PostHogSurveysIntegration.kt b/posthog-android/src/main/java/com/posthog/android/surveys/PostHogSurveysIntegration.kt index 8670ac5eb..84dd378f2 100644 --- a/posthog-android/src/main/java/com/posthog/android/surveys/PostHogSurveysIntegration.kt +++ b/posthog-android/src/main/java/com/posthog/android/surveys/PostHogSurveysIntegration.kt @@ -199,6 +199,13 @@ public class PostHogSurveysIntegration( } } + /** + * Whether a delegate that can display surveys is available. The default delegate only logs, + * so without the Compose module or a custom delegate, skip matching: it evaluates linked + * flags (capturing `$feature_flag_called`) and property filters for surveys nobody can see. + */ + private fun canRenderSurveys(): Boolean = getSurveysDelegate() !is PostHogSurveysDefaultDelegate + private fun defaultMatchType(matchType: SurveyMatchType?): SurveyMatchType { return matchType ?: SurveyMatchType.I_CONTAINS } @@ -877,7 +884,7 @@ public class PostHogSurveysIntegration( * 4. Tracks the active survey state */ internal fun showNextSurvey() { - if (!canShowNextSurvey()) { + if (!canRenderSurveys() || !canShowNextSurvey()) { return } @@ -1251,6 +1258,8 @@ public class PostHogSurveysIntegration( event: String, properties: Map?, ) { + if (!canRenderSurveys()) return + val candidates = synchronized(eventActivationLock) { // Copy to avoid concurrent modification issues diff --git a/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysEventPropertyFilterTest.kt b/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysEventPropertyFilterTest.kt index 56bf2a1f0..838f364a1 100644 --- a/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysEventPropertyFilterTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysEventPropertyFilterTest.kt @@ -4,6 +4,7 @@ import androidx.test.core.app.ApplicationProvider import androidx.test.ext.junit.runners.AndroidJUnit4 import com.posthog.PostHogConfig import com.posthog.PostHogInterface +import com.posthog.surveys.PostHogSurveysDelegate import com.posthog.surveys.Survey import com.posthog.surveys.SurveyConditions import com.posthog.surveys.SurveyEventCondition @@ -26,6 +27,7 @@ internal class PostHogSurveysEventPropertyFilterTest { val config = PostHogConfig("test-api-key").apply { surveys = true + surveysConfig.surveysDelegate = mock() } val integration = PostHogSurveysIntegration(context, config) val fake = mock() diff --git a/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysNoRendererTest.kt b/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysNoRendererTest.kt new file mode 100644 index 000000000..6a06df839 --- /dev/null +++ b/posthog-android/src/test/java/com/posthog/android/surveys/PostHogSurveysNoRendererTest.kt @@ -0,0 +1,51 @@ +package com.posthog.android.surveys + +import android.content.Context +import androidx.test.core.app.ApplicationProvider +import androidx.test.ext.junit.runners.AndroidJUnit4 +import com.posthog.PostHogConfig +import com.posthog.PostHogInterface +import com.posthog.surveys.Survey +import org.junit.runner.RunWith +import org.mockito.kotlin.any +import org.mockito.kotlin.anyOrNull +import org.mockito.kotlin.mock +import org.mockito.kotlin.never +import org.mockito.kotlin.verify +import java.io.StringReader +import kotlin.test.Test + +@RunWith(AndroidJUnit4::class) +internal class PostHogSurveysNoRendererTest { + @Test + fun `default delegate does not evaluate survey flags on load or event`() { + val config = PostHogConfig("test-api-key") + val postHog = mock() + val survey = + config.serializer.deserialize( + StringReader( + """ + { + "id": "survey", "name": "Survey", "type": "popover", "questions": [], + "start_date": "2024-07-23T09:18:18.376Z", + "linked_flag_key": "linked-flag", + "conditions": { + "events": { "values": [{ "name": "purchase" }] } + } + } + """.trimIndent(), + ), + ) + val integration = PostHogSurveysIntegration(ApplicationProvider.getApplicationContext(), config) + integration.install(postHog) + try { + integration.onSurveysLoaded(listOf(survey)) + integration.onEvent("purchase", emptyMap()) + } finally { + integration.uninstall() + } + + verify(postHog, never()).isFeatureEnabled(any(), any(), anyOrNull()) + verify(postHog, never()).getFeatureFlag(any(), anyOrNull()) + } +} diff --git a/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt b/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt index 27826ef05..b79f98850 100644 --- a/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt +++ b/posthog-samples/posthog-android-sample/src/main/java/com/posthog/android/sample/MyApp.kt @@ -48,9 +48,6 @@ class MyApp : Application() { sessionReplayConfig.maskAllTextInputs = false sessionReplayConfig.maskAllImages = false sessionReplayConfig.captureLogcat = true - // Surveys are opt-in. With :posthog-android-surveys-compose on the classpath the - // core SDK auto-discovers the Compose UI delegate — no surveysConfig wiring needed. - surveys = true // Enabled so the ErrorTrackingActivity "Crash app (fatal)" button is captured // as an $exception with $exception_steps. Requires exception autocapture // enabled for the project in PostHog too. diff --git a/posthog/src/main/java/com/posthog/PostHogConfig.kt b/posthog/src/main/java/com/posthog/PostHogConfig.kt index c3531d0f7..a05bb56ae 100644 --- a/posthog/src/main/java/com/posthog/PostHogConfig.kt +++ b/posthog/src/main/java/com/posthog/PostHogConfig.kt @@ -197,14 +197,20 @@ public open class PostHogConfig( */ public var personProfiles: PersonProfiles = PersonProfiles.IDENTIFIED_ONLY, /** - * Enable Surveys for Android (Intended for internal use only) + * Whether the SDK loads surveys and shows the ones that match. * - * Note: Not fully supported or documented yet. Primarily used by hybrid SDKs to attach a custom display logic. + * Defaults to `true`. Surveys display only when the app depends on + * `com.posthog:posthog-android-surveys-compose` or sets `surveysConfig.surveysDelegate`; + * without either, the SDK doesn't match or show surveys. Surveys must also be enabled in + * the PostHog project settings. Set to `false` to stop loading and showing surveys. * - * Requires Surveys to be enabled in the PostHog Project Settings - * Defaults to false + * ```kotlin + * val config = PostHogAndroidConfig(projectToken = "phc_...").apply { + * surveys = false + * } + * ``` */ - public var surveys: Boolean = false, + public var surveys: Boolean = true, /** * Configures an optional HTTP proxy for the PostHog API client. * diff --git a/posthog/src/test/java/com/posthog/PostHogConfigTest.kt b/posthog/src/test/java/com/posthog/PostHogConfigTest.kt index 9a68d7deb..a0703bf47 100644 --- a/posthog/src/test/java/com/posthog/PostHogConfigTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogConfigTest.kt @@ -50,6 +50,11 @@ internal class PostHogConfigTest { assertTrue(config.beforeSendList.isEmpty()) } + @Test + fun `surveys is enabled by default`() { + assertTrue(config.surveys) + } + @Test fun `sendFeatureFlagEvent is enabled by default`() { assertTrue(config.sendFeatureFlagEvent)