Kotlin (Android)

This SDK supports both Java and Kotlin Android apps using Android SDK 21 and above.

Installation

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.growthbook.sdk:GrowthBook:1.1.60'
    implementation 'io.growthbook.sdk:NetworkDispatcherKtor:1.0.2'
}

NetworkDispatcherKtor artifact provides NetworkDispatcher implementation based on ktor network client. If you want to use implementation based on OkHttp network client you can use NetworkDispatcherOkHttp artifact.

Quick Usage

To create a GrowthBook SDK instance, use GBSDKBuilder. Then, you can evaluate feature flags or run experiments.

// User attributes for targeting and assigning users to experiment variations
val attrs = HashMap<String, Any>()
attrs.put("id", "123")
attrs.put("env", "dev")
attrs.put("betaUser", true)

val gb = GBSDKBuilder(
  // Fetch and cache feature definitions from GrowthBook API
  // If self-hosting, we recommend using a CDN in production
  apiKey = "key_123abc",
  hostURL = "https://cdn.growthbook.io/",
  attributes = attrs,
  trackingCallback = { gbExperiment, gbExperimentResult ->
    // TODO: track in your analytics system
    print("Viewed Experiment")
    print("Experiment Id: " + gbExperiment.key)
    print("Variation Id: " + gbExperimentResult.variationId)
  },
  networkDispatcher = GBNetworkDispatcherKtor(),
  encryptionKey = "insert_your_encription_key_if_you_are_using_encryption",
).initialize()

If you need to set or update attributes asynchronously, you can do so with setAttributes(). This will completely overwrite the attributes object with whatever you pass in. Also, be aware that changing attributes may change the assigned feature values. This can be disorienting to users if not handled carefully.

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. Code snippet:

class ForExampleMainActivity {
    var growthBookSDK: GrowthBookSDK? = null

    fun someInitMethodForExampleOnStart() {
        val gbSdkBuilder = GBSDKBuilder(
            ....
        )

        gbSdkBuilder.setRefreshHandler { isRefreshed, gbError ->
            // access your features
            growthBookSDK?.feature("your_feature_key").on
        }

        growthBookSDK = gbSdkBuilder.initialize()
    }
}

Using Features

The feature method takes a String feature name and returns a FeatureResult object with a few useful properties:

• value (Any) - The assigned value of the feature
• on (Boolean) - The value cast to a boolean
• off (Boolean) - The value cast to a boolean and then negated
• source (String) - Why the value was assigned to the user. One of "unknownFeature", "defaultValue", "force", or "experiment"

When the source is "experiment", there are 2 additional properties that tell you which experiment was used and more details about the result of the experiment:

• experiment (GBExperiment)
• experimentResult (GBExperimentResult)

Here are some examples:

val feature = gb.feature("my-feature")

// Do something if feature is truthy
if (feature.on) { }

// Do something if feature is falsy
if (feature.off) { }

// Print the actual value of the feature
// (depending on the feature, might be a string, number, boolean, etc.)
println(feature.value)

// Print the experiment id used to assign the feature value
if (feature.source == "experiment") {
  println(feature.experiment.key)
}

Running Inline Experiments

Instead of just using features defined in the GrowthBook API, you can also just run an experiment directly. This is done with the run method which takes a GBExperiment object as an argument and returns a GBExperimentResult object:

cal exp = GBExperiment()
exp.key = "my-experiment"
exp.variations = arrayOf("control", "variation")

val result = gb.run(exp)

// Either "control" or "variation"
println(result.value)

The GBExperiment class has two required properties - key and variations. There are also a number of optional properties:

• key (String) - The unique identifier for this experiment
• variations (Any[]) - Array of variations to decide between
• weights (Float[]) - How to weight traffic between variations. Must add to 1.
• active (Boolean) - If set to false, always return the control (first variation)
• coverage (Float) - What percent of users should be included in the experiment (between 0 and 1, inclusive)
• condition (GBCondition) - Optional targeting condition
• namespace ([String, Int, Int]) - Adds the experiment to a namespace
• force (Int) - All users included in the experiment will be forced into the specific variation index
• hashAttribute (String) - What user attribute should be used to assign variations (defaults to id)

The GBExperimentResult object returns the following properties:

• inExperiment (Boolean)
• variationId (Int) - The array index of the assigned variation
• value (Any) - The value of the assigned variation
• hashAttribute (String) - The user attribute used to assign a variation
• hashValue (String) - The value of the attribute used to assign a variation

More Documentation

The GitHub repo for this SDK has more detailed class and method documentation - https://github.com/growthbook/growthbook-kotlin