Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .changeset/android-v4-major.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,13 @@
- **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
- **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
36 changes: 31 additions & 5 deletions docs/migration-3.x-to-4.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,10 @@ 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 |
| `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.
Expand Down Expand Up @@ -94,6 +96,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
Expand Down Expand Up @@ -123,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
Expand All @@ -135,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());
Expand All @@ -155,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

Expand Down Expand Up @@ -216,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 ->
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ internal class PostHogSurveysLinkedFlagVariantTest(
val value = flagValues[it.getArgument<String>(0)]
value == true || value is String
}
whenever(postHog.getFeatureFlag(any(), anyOrNull(), anyOrNull())).thenAnswer {
whenever(postHog.getFeatureFlag(any(), anyOrNull())).thenAnswer {
flagValues[it.getArgument<String>(0)]
}
val survey =
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ internal class PostHogSurveysSelectionTest {
val value = flags[it.getArgument<String>(0)]
value == true || value is String
}
whenever(postHog.getFeatureFlag(any(), anyOrNull(), anyOrNull())).thenAnswer { flags[it.getArgument<String>(0)] }
whenever(postHog.getFeatureFlag(any(), anyOrNull())).thenAnswer { flags[it.getArgument<String>(0)] }
val integration = PostHogSurveysIntegration(context, config)
integration.install(postHog)
try {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,6 @@ internal class PostHogConfigTest {
assertEquals(30, coreConfig.maxBatchSize)
assertEquals(45, coreConfig.flushIntervalSeconds)
assertEquals(mockEncryption, coreConfig.encryption)
assertNull(coreConfig.onFeatureFlags)
}

@Test
Expand Down
16 changes: 7 additions & 9 deletions posthog/api/posthog.api
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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 <init> (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 <init> (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 <init> (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 <init> (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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -403,8 +401,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;
Expand Down Expand Up @@ -449,7 +447,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
Expand Down
Loading
Loading