Skip to main content

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.0.3'
}

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
  }
).initialize()

if (gb.feature("my-feature").on) {
  // Feature is enabled!
}

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.

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