Streamlines A/B testing and feature flag management, enabling dynamic variation adjustments and targeting without code redeployments. Supports existing event tracking and includes features like sticky bucketing and remote evaluation for enhanced security and user consistency.
Lightweight and fast
Kotlin Multiplatform (Android, iOS, JVM, JS, Wasm)
Use your existing event tracking (GA, Segment, Mixpanel, custom)
Adjust variation weights and targeting without deploying new code
See CHANGELOG.md for version history.
App level build.gradle (Groovy DSL):
repositories {
mavenCentral()
}
dependencies {
// Add GrowthBook module:
implementation 'io.growthbook.sdk:GrowthBook:7.2.0'
// Add Network Dispatcher you prefer:
// 1) NetworkDispatcherKtor — supports Android, iOS, JVM, JS, Wasm
implementation 'io.growthbook.sdk:NetworkDispatcherKtor:1.0.12'
// 2) NetworkDispatcherOkHttp — supports Android and JVM only
implementation 'io.growthbook.sdk:NetworkDispatcherOkHttp:1.0.7'
}
If you are not sure which dispatcher to choose we recommend to use network dispatcher based on Ktor.
The main class of NetworkDispatcherKtor artifact is GBNetworkDispatcherKtor while the main class of NetworkDispatcherOkHttp artifact is GBNetworkDispatcherOkHttp.
If you are using other network client for example android-lite-http and don't want to have any other network client in your application,
you can provide your own implementation of NetworkDispatcher based on your network client.
Add Internet Permission to your AndroidManifest.xml, if not already added
<uses-permission android:name="android.permission.INTERNET" />
Integration is super easy:
Now you can start/stop tests, adjust coverage and variation weights, and apply a winning variation to 100% of traffic, all within the Growth Book App without deploying code changes to your site.
initialize() method should be called in order to obtain SDK instance:
var sdkInstance: GrowthBookSDK = GBSDKBuilder(
apiKey = <API_KEY>,
hostURL = <GrowthBook_URL>,
attributes = < Hashmap >,
trackingCallback = { gbExperiment, gbExperimentResult -> },
encryptionKey = <String?>,
networkDispatcher = <NetworkDispatcher>, // you can use GBNetworkDispatcherKtor() or GBNetworkDispatcherOkHttp()
).initialize()
If you are accessing features the first time there will be no features right after initialize() method call because features are not got from Backend yet. If you need to access features as soon as possible, you need to use GBCacheRefreshHandler. You can pass your implementation of GBCacheRefreshHandler through setRefreshHandler() method.
.setEnabled(true) // Enable / Disable experiments
.setQAMode(true) // Enable / Disable QA Mode
.setForcedVariations(<HashMap>) // Pass Forced Variations
.setInitialFeatures(<GBFeatures>) // Seed bundled fallback features (see below)
.initialize()
setInitialFeatures)For a robust offline-first setup, you can bundle a known-good features payload (snapshotted from the API at build time) and seed the SDK with it at init. This gives flags a valid value from the first millisecond — on first installs, offline launches, and empty/corrupt cache — instead of falling back to hardcoded code defaults.
val bundledFeatures: GBFeatures = mapOf(
"dark-mode" to GBFeature(defaultValue = GBBoolean(false)),
"new-checkout" to GBFeature(defaultValue = GBBoolean(true)),
)
var sdkInstance: GrowthBookSDK = GBSDKBuilder(
apiKey = <API_KEY>,
hostURL = <GrowthBook_URL>,
attributes = hashMapOf(),
trackingCallback = { _, _ -> },
networkDispatcher = GBNetworkDispatcherKtor(),
)
.setInitialFeatures(bundledFeatures)
.initialize()
The seeded features are applied immediately. The normal cache/network refresh still runs on top and overwrites the seed as fresher data arrives. Effective precedence: network > disk cache > seed > code defaults.
Upgrading from 6.x (Android): Persistent caching is only implemented on Android; other platforms do not cache features to disk, so this upgrade note does not apply to them. On Android the cache file is automatically migrated from
FeatureCache.txtto the new scopedFeatureCache_<clientKey>.txton first launch. Single-instance apps migrate transparently with no cold start. Apps that use multiple SDK instances with differentclientKeys may see one cold start without cache on the first launch after upgrade — features self-correct after the first successful fetch.
This SDK operates with such models as GBContext, GBFeature, GBFeatureRule, GBFeatureSource, GBFeatureResult, GBExperiment, GBExperimentResult, etc.
These models can be found in model package. Some entities were put in utils/Constants.kt file. In JS SDK there is only one entity "Result" while in this SDK GBFeatureResult, GBExperimentResult are present.
You can specify attributes about the current user and request. These are used for two things:
Attributes can be any JSON data type - boolean, integer, float, string, list, or dict.
If you're using ProGuard, you may need to add rules to your configuration file to make it compatible with Obfuscation & Shriniking tools. These rules are guidelines only and some projects require more to work. You can modify those rules and adapt them to your project, but be aware that we do not support custom rules.
-keep { *; }
-keep { *; }
-keepattributes *Annotation*, InnerClasses
-dontnote kotlinx.serialization.SerializationKt
-keep,includedescriptorclasses { *; }
-keepclassmembers {
*** Companion;
}
-keepclasseswithmembers {
kotlinx.serialization.KSerializer serializer(...);
}
This mode brings the security benefits of a backend SDK to the front end by evaluating feature flags exclusively on a private server. Using Remote Evaluation ensures that any sensitive information within targeting rules or unused feature variations are never seen by the client. Note that Remote Evaluation should not be used in a backend context.
You must enable Remote Evaluation in your SDK Connection settings. Cloud customers are also required to self-host a GrowthBook Proxy Server or custom remote evaluation backend.
To use Remote Evaluation, set the remoteEval = true property to your SDK instance. A new evaluation API call will be
made any time a user attribute or other dependency changes.
If you would like to implement Sticky Bucketing while using Remote Evaluation, you must configure your remote evaluation backend to support Sticky Bucketing. You will not need to provide a StickyBucketService instance to the client side SDK.
By default, GrowthBook does not persist assigned experiment variations for a user. We rely on deterministic hashing to ensure that the same user attributes always map to the same experiment variation. However, there are cases where this isn't good enough. For example, if you change targeting conditions in the middle of an experiment, users may stop being shown a variation even if they were previously bucketed into it. Sticky Bucketing is a solution to these issues. You can provide a Sticky Bucket Service to the GrowthBook instance to persist previously seen variations and ensure that the user experience remains consistent for your users.
Sticky bucketing ensures that users see the same experiment variant, even when user session, user login status, or
experiment parameters change. See the Sticky Bucketing docs for more
information. If your organization and experiment supports sticky bucketing, you can implement an instance of
the StickyBucketService to use Sticky Bucketing. For simple bucket persistence using the CachingLayer.
Sticky Bucket documents contain three fields:
The attributeName/attributeValue combo is the primary key.
Here's an example implementation using a theoretical db object:
This project uses the MIT license. The core GrowthBook app will always remain open and free, although we may add some commercial enterprise add-ons in the future.
Initialization returns SDK instance - GrowthBookSDK
The feature method takes a single string argument, which is the unique identifier for the feature and returns a FeatureResult object.
fun feature(id: String) : GBFeatureResult
The featureValue method takes a string argument, which is the unique identifier, and the type of the accessed feature. The supported types of accessed features are: Boolean, String, Number, Short, Int, Long, Float, Double], GBJson - and returns a feature value typed with specified type.
inline fun <reified V>featureValue(id: String): V?
If you changed, added or removed any features, you can call the refreshCache method to clear the cache and download the latest feature definitions.
fun refreshCache()
use setRefreshHandler to set a callback that will be called whenever the cache is refreshed.
fun setRefreshHandler(handler: () -> Unit)
method for set prefix of filename in cache directory GrowthBook-KMM.
fun setCacheDirectory(prefix: String = "gbStickyBuckets__"): GBSDKBuilder {}
The run method takes an Experiment object and returns an ExperimentResult
fun run(experiment: GBExperiment) : GBExperimentResult
Get Context
fun getGBContext() : GBContext
Get Features
fun getFeatures() : GBFeatures
The setEncryptedFeatures method takes an encrypted string with an encryption key and then decrypts it with the default method of decrypting or with a method of decrypting from the user
fun setEncryptedFeatures(encryptedString: String, encryptionKey: String, subtleCrypto: Crypto?){
start receiving Features automatically when updated SSE
fun startAutoRefreshFeatures(): Flow<Resource<GBFeatures?>>{}
stop receiving Features automatically during SSE connection
fun stopAutoRefreshFeatures(): Flow<Resource<GBFeatures?>>{}
Delegate that set to Context successfully fetched features
fun featuresFetchedSuccessfully(features: GBFeatures, isRemote: Boolean) {}
Delegate which inform that fetching features failed
fun featuresFetchFailed(error: GBError, isRemote: Boolean) {}
The isOn method takes a single string argument, which is the unique identifier for the feature and returns the feature state on/off
fun isOn(featureDd: String): Boolean {}
The setForcedFeatures method setup the Map of user's (forced) features
fun setForcedFeatures(forcedFeatures: Map<String, Any>) {}
The getForcedFeatures method for mapping model object for request's body type
fun getForcedFeatures(): List<List<Any>> {}
The setAttributes method replaces the Map of user attributes that are used to assign variations
fun setAttributes(attributes: Map<String, Any>) {}
NEW: The setAttributesSync method is a synchronous version that waits for sticky bucket assignments to load before returning. Use this for login, logout, and user switching to prevent race conditions.
suspend fun setAttributesSync(attributes: Map) {}
Example usage:
lifecycleScope.launch {
sdk.setAttributesSync(loginAttributes)
// Sticky buckets are guaranteed to be loaded here
val result = sdk.feature("my-experiment")
}
The setAttributeOverrides method replaces the Map of user overrides attribute that are used for Sticky Bucketing
fun setAttributeOverrides(overrides: Map<String, Any>) {}
NEW: The setAttributeOverridesSync method is a synchronous version that waits for sticky bucket assignments to load
suspend fun setAttributeOverridesSync(overrides: Map) {}
The setForcedVariations method setup the Map of user's (forced) variations to assign a specific variation (used for QA)
fun setForcedVariations(forcedVariations: Map<String, Any>) {}
Delegate that call refresh Sticky Bucket Service after success fetched features
fun featuresAPIModelSuccessfully(model: FeaturesDataModel) {}
class GBStickyBucketServiceImp(
override val coroutineScope: CoroutineScope,
private val prefix: String = "gbStickyBuckets__",
private val localStorage: CachingLayer? = null
) : GBStickyBucketService {
override suspend fun getAssignments(
attributeName: String,
attributeValue: String
): GBStickyAssignmentsDocument? {
val key = "$attributeName||$attributeValue"
localStorage?.let { localStorage ->
localStorage.getContent("$prefix$key")?.let { data ->
return try {
Json.decodeFromJsonElement<GBStickyAssignmentsDocument>(data)
} catch (e: Exception) {
null
}
}
}
return null
}
override suspend fun saveAssignments(doc: GBStickyAssignmentsDocument) {
val key = "${doc.attributeName}||${doc.attributeValue}"
localStorage?.let { localStorage ->
try {
val docDataString = Json.encodeToString(doc)
val jsonElement: JsonElement = Json.parseToJsonElement(docDataString)
localStorage.saveContent("$prefix$key", jsonElement)
} catch (e: Exception) {
// Handle JSON serialization error
}
}
}
override suspend fun getAllAssignments(attributes: Map<String, String>): Map<String, GBStickyAssignmentsDocument> {
val docs = mutableMapOf<String, GBStickyAssignmentsDocument>()
attributes.forEach { (key, value) ->
getAssignments(key, value)?.let { doc ->
val docKey = "${doc.attributeName}||${doc.attributeValue}"
docs[docKey] = doc
}
}
return docs
}
}
Surfaced from shared tags and platforms — no rankings paid for.