Stickiness in feature toggles is not working as expected in Unleash for our Android app. Users are not consistently receiving the same variant despite setting userId in the Unleash context.

[Sonu1024]

Describe the bug

Unleash Android SDK Version = "1.2.1"

URL - https://unleash-stage.penpencil.co/projects

Code

package com.penpencil.core.unleash

import android.content.Context
import android.os.Looper
import android.util.Log
import androidx.annotation.WorkerThread
import com.penpencil.core.BuildConfig
import com.penpencil.core.logging.PwLog
import io.getunleash.android.DefaultUnleash
import io.getunleash.android.UnleashConfig
import io.getunleash.android.data.Toggle
import io.getunleash.android.data.UnleashContext
import io.getunleash.android.data.Variant
import io.getunleash.android.events.UnleashReadyListener
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.cancel
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock
import kotlinx.coroutines.withContext
import kotlinx.coroutines.withTimeoutOrNull
import java.lang.ref.WeakReference

/**

• @Property config Configuration object containing Unleash setup parameters
  */
  class UnleashFeatureManager private constructor() {

  private var applicationContext: WeakReference? = null
  private var unleash: DefaultUnleash? = null
  private val coroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
  private val contextUpdateMutex = Mutex()
  companion object {
  @volatile
  private var instance: UnleashFeatureManager? = null

   fun getInstance(): UnleashFeatureManager {
       return instance ?: synchronized(this) {
           instance ?: UnleashFeatureManager().also { instance = it }
       }
   }
  

  }

  /**

  • Initializes the Unleash SDK with the provided configuration.

  • Should be called from Application class or a dependency injection module.

  • @param context Application context

  • @param config Configuration data for Unleash initialization
    */
    fun initialize(
    context: Context, config: FeatureConfig
    ) {
    if (unleash != null) return

    applicationContext = WeakReference(context.applicationContext)

    val unleashConfig =
    UnleashConfig.newBuilder(appName = config.appName)
    .proxyUrl(config.proxyUrl)
    .clientKey(config.clientKey).apply {
    pollingStrategy.interval(config.pollingInterval)
    metricsStrategy.interval(config.metricsInterval)
    }.build()

    val initialContext =
    UnleashContext.newBuilder().userId(config.userId).build()

    applicationContext?.get()?.let { appContext ->
    unleash = DefaultUnleash(
    androidContext = appContext, unleashConfig = unleashConfig
    ).apply {
    setContext(initialContext)
    }
    }
    }

  /**

  • Starts the Unleash client with optional bootstrap data.
  • Uses coroutines for async initialization and timeout handling.
  • @param bootstrapToggles Optional list of initial toggle states
  • @param maxWaitTimeMs Maximum time to wait for initialization in milliseconds
  • @return Boolean indicating whether initialization was successful
    */
    suspend fun start(
    bootstrapToggles: List? = null, onReady: (() -> Unit)
    ) = withContext(Dispatchers.Main) {
    try {
    Log.e("TAG", "start: ${System.currentTimeMillis()}")
    // Use Dispatchers.Main for main thread
    unleash?.let { client ->
    // Start Unleash on the main thread
    bootstrapToggles?.let { toggles ->
    client.start(bootstrap = toggles)
    } ?: client.start(
    eventListeners = listOf(object : UnleashReadyListener {
    override fun onReady() {
    // Handle readiness if needed
    onReady?.invoke()
    }
    })
    )
    }
    } catch (e: Exception) {
    Log.e("UnleashFeatureManager", "Failed to start Unleash client", e)
    }
    }

  /**

  • Checks if a feature flag is enabled asynchronously.
  • @param flagName Name of the feature flag
  • @param defaultValue Default value if the flag is not found or Unleash is not ready
  • @return Boolean indicating if the feature is enabled
    */
    suspend fun isFeatureEnabledAsync(
    flagName: String, defaultValue: Boolean = false
    ): Boolean = executeWhenReady {
    unleash?.isEnabled(flagName) ?: defaultValue
    } ?: defaultValue

  /**

  • Checks if a feature flag is enabled with timeout protection.

  • Should be called from a background thread or coroutine.
    */
    suspend fun isFeatureEnabled(
    flagName: String,
    defaultValue: Boolean = false,
    maxWaitTimeMs: Long = 1000
    ): Boolean = withContext(Dispatchers.IO) {
    if (unleash == null) {
    Log.w("UnleashFeatureManager", "Unleash client is not initialized.")
    return@withContext defaultValue
    }

    try {
    // Use coroutine timeout instead of blocking wait
    withTimeoutOrNull(maxWaitTimeMs) {
    while (!isReady()) {
    delay(100) // Non-blocking delay
    }
    unleash?.isEnabled(flagName) ?: defaultValue
    } ?: run {
    Log.w("UnleashFeatureManager", "Unleash client is not ready within the timeout.")
    defaultValue
    }
    } catch (e: Exception) {
    Log.e("UnleashFeatureManager", "Error checking feature flag: ${e.message}")
    defaultValue
    }
    }

// If you absolutely need a sync version (not recommended), make it explicit:
/**
* WARNING: This method blocks the calling thread and should NOT be called from the main thread.
*/
@workerthread
fun isFeatureEnabledBlocking(
flagName: String,
defaultValue: Boolean = false,
maxWaitTimeMs: Long = 1000
): Boolean {
if (Looper.getMainLooper().isCurrentThread) {
if (BuildConfig.DEBUG) {
throw IllegalStateException("isFeatureEnabledBlocking called on main thread!")
} else {
Log.e("UnleashFeatureManager", "isFeatureEnabledBlocking called on main thread!")
return defaultValue
}
}

    return runBlocking {
        isFeatureEnabled(flagName, defaultValue, maxWaitTimeMs)
    }
}


/**
 * Gets the variant for a feature flag asynchronously.
 *
 * @param flagName Name of the feature flag
 * @return Variant object containing the feature variant information
 */
suspend fun getFeatureVariantAsync(flagName: String): Variant? = executeWhenReady {
    unleash?.getVariant(flagName)
}


/**
 * Gets the variant for a feature flag with timeout protection.
 * Uses coroutines for non-blocking operations.
 *
 * @param flagName Name of the feature flag
 * @param maxWaitTimeMs Maximum time to wait for readiness in milliseconds
 * @return Variant object containing the feature variant information
 */
suspend fun getFeatureVariant(
    flagName: String,
    maxWaitTimeMs: Long = 1000
): Variant? = withContext(Dispatchers.IO) {
    if (unleash == null) {
        Log.w("UnleashFeatureManager", "Unleash client is not initialized.")
        return@withContext null
    }

    try {
        // Use coroutine timeout instead of blocking wait
        withTimeoutOrNull(maxWaitTimeMs) {
            while (!isReady()) {
                delay(100) // Non-blocking delay
            }
            unleash?.getVariant(flagName)
        } ?: run {
            Log.w("UnleashFeatureManager", "Unleash client is not ready within the timeout.")
            null
        }
    } catch (e: Exception) {
        Log.e("UnleashFeatureManager", "Error getting feature variant: ${e.message}")
        null
    }
}

/**
 * WARNING: This method blocks the calling thread and should NOT be called from the main thread.
 * Consider using getFeatureVariant() with coroutines instead.
 */
@WorkerThread
fun getFeatureVariantBlocking(
    flagName: String,
    maxWaitTimeMs: Long = 1000
): Variant? {
    if (Looper.getMainLooper().isCurrentThread) {
        if (BuildConfig.DEBUG) {
            throw IllegalStateException("isFeatureEnabledBlocking called on main thread!")
        } else {
            Log.e("UnleashFeatureManager", "isFeatureEnabledBlocking called on main thread!")
            return null
        }
    }

    return runBlocking {
        getFeatureVariant(flagName, maxWaitTimeMs)
    }
}

/**
 * Updates the Unleash context with new user information.
 * Executes on IO dispatcher to avoid blocking the main thread.
 *
 * @param userId User identifier
 * @param sessionId Session identifier
 * @param properties Additional context properties
 */
suspend fun updateContext(
    userId: String, properties: Map<String, String> = emptyMap()
) = withContext(Dispatchers.IO) {
    // Use the Mutex to ensure thread-safe updates
    contextUpdateMutex.withLock {
        try {
            val context = UnleashContext.newBuilder().userId(userId).apply {
                properties.forEach { (key, value) ->
                    addProperty(key, value)
                }
            }.build()
            unleash?.setContext(context)
        } catch (e: Exception) {
            PwLog.e("Error updating context: ${e.message}")
        }
    }
}

fun isReady(): Boolean {
    return unleash?.isReady() ?: false
}

/**
 * Updates the Unleash context asynchronously using coroutines.
 * Executes on IO dispatcher and waits for client readiness.
 *
 * @param userId User identifier
 * @param properties Additional context properties
 * @return Boolean indicating if the update was successful
 */
suspend fun updateContextAsync(
    userId: String,
    properties: Map<String, String> = emptyMap(),
    maxWaitTimeMs: Long = 1000
): Boolean = withContext(Dispatchers.IO) {
    if (unleash == null) {
        Log.w("UnleashFeatureManager", "Unleash client is not initialized.")
        return@withContext false
    }

    executeWhenReady(maxWaitTimeMs) {
        try {
            val context = UnleashContext.newBuilder()
                .userId(userId)
                .apply {
                    properties.forEach { (key, value) ->
                        addProperty(key, value)
                    }
                }
                .build()

            unleash?.setContext(context)
            true
        } catch (e: Exception) {
            Log.e("UnleashFeatureManager", "Error updating context: ${e.message}")
            false
        }
    } ?: false
}

/**
 * Waits until the Unleash client is ready and then executes the provided block.
 *
 * @param maxWaitTimeMs Maximum time to wait for readiness in milliseconds
 * @param block The block of code to execute once Unleash is ready
 * @return The result of the block or null if Unleash is not ready within the timeout
 */
suspend fun <T> executeWhenReady(maxWaitTimeMs: Long = 1000, block: suspend () -> T): T? {
    return withContext(Dispatchers.Main) {
        if (withTimeoutOrNull(maxWaitTimeMs) {
                while (unleash?.isReady() == false) {
                    delay(100)
                }
                unleash?.isReady() == true
            } == true) {
            block()
        } else {
            Log.w("UnleashFeatureManager", "Unleash client is not ready within the timeout.")
            null
        }
    }
}


/**
 * Stops the Unleash client and releases resources.
 */
fun stop() {
    unleash?.close()
    unleash = null
}

/**
 * Cleans up resources when the feature manager is no longer needed.
 */
fun cleanup() {
    stop()
    coroutineScope.cancel()
    applicationContext = null
    instance = null

Steps to reproduce the bug

1. Initialize Unleash with the configuration:
   val unleashConfig = UnleashConfig.newBuilder(appName = config.appName)
   .proxyUrl(config.proxyUrl)
   .clientKey(config.clientKey)
   .build()

2.Set Unleash context with a userId:

3. Fetch a feature variant:
   val variant = unleash?.getVariant("my_feature")
   Log.d("UnleashDebug", "Feature Variant: ${variant?.name}")

4. Restart the app and observe that the variant is changing instead of remaining consistent for the same userId.

Expected behavior

For a given userId, the variant should remain the same across app launches.

Logs, error output, etc.

The variant changes across app launches even when the userId remains the same.

Screenshots

No response

Additional context

When i am increasing target group, userId from control group is moving to target group.

Unleash version

1.2.1

Subscription type

Open source

Hosting type

Hosted by Unleash

SDK information (language and version)

1.2.1

[Sonu1024]

@thomasheartman

[gastonfournier]

Hi, I used our sample application

unleash-android/app/src/main/java/io/getunleash/unleashandroid/MainActivity.kt

Line 39 in c7c8a1d

class MainActivity : ComponentActivity() {

to validate this and I couldn't reproduce. There's this video showing that the behavior is consistent also with our playground: https://www.loom.com/share/f5c5d4c49bf04b679763ec70e72c8534?sid=5a0f8b16-597d-4800-9f78-3c2c3e8a02a0

I'm using the latest code but I also couldn't find anything indicating a potential bug in 1.2.1. My only guess is that either this is a configuration issue in your feature flag configuration or a problem with the code wrapping Unleash.

[Sonu1024]

Thanks for checking this! I appreciate your help.

However, I noticed that when I increase the target group size, users who were originally assigned to the control group are moving to the target group. From my understanding, once a user is assigned to a group (control or target), they should stick to that assignment, and increasing the target group size shouldn’t reassign existing users.

Is this the expected behavior? It seems like stickiness is not being maintained as expected. Let me know if I’m missing something or if there’s a configuration issue I should check.

Thanks!

[Sonu1024]

@gastonfournier

[Sonu1024]

[Sonu1024]

Initial Setup:

Control Group → cta_disabled

Target Group → cta_enabled

Testing with 0% Target Group Allocation:

I tested with 10 users when the target group was set to 0%.

All users received cta_disabled as expected.

Increasing the Target Group to 99%:

I increased the target group allocation from 0% to 99%.

The same 10 users, who were originally in the control group (cta_disabled), started receiving cta_enabled instead.

Expected Behavior:
Users should stick to their original assignment (either control or target) once they receive a variation.

Increasing the target group allocation should only affect new users, not reassign existing ones.

Issue:
Users who were in the control group initially (cta_disabled) should not move to the target group (cta_enabled) when the target group percentage increases.

It seems like stickiness is not being maintained as expected.

[gastonfournier]

Hi @Sonu1024 unfortunately there's a wrong expectation here. Stickiness is consistent, not persistent. So if you change the allocation, the stickiness may change unless you store that information somewhere.

Imagine you have 25% exposure in control group (C = control group, T target group) and you only have 4 users (for simplicity).

	User 1	User 2	User 3	User 4
Variant	Control	Target	Target	Target

If you increase the exposure to 50%, Unleash guarantees that the User 1 will still be receiving the Control group, but User 2 will change from Target to Control

	User 1	User 2	User 3	User 4
Variant	Control	Control	Target	Target

If you go back to 25% then User 1 will still be with the Control group but User 2 will go back to Target.

If you persist the allocation, there might be a number of issues. What happens if you need to rollback the target group? You'd need a way to "invalidate the storage/cache". How do you guarantee that all evaluations return the same variant? All would have to talk to the same centralized storage.

Unleash for privacy reasons does not store individualized data of the users, and therefore it's not something we have in our roadmap but it's something you can add if you have to as a wrapper of the Unleash library (pseudo-code):

if (myStorage.get(context) != null) {
    return myStorage.get(context);
}
val variant = unleash.getVariant('feature', context);
myStorage.set(context, variant);
return variant;