}>
{githubName}
{packageRepos.map(repo => }>
{repo.name}
)}
{examples.map(({url, name}) => }>
{name}
)}
}>
Get help on Slack
;
};
This SDK supports both Java and Kotlin Android apps using Android SDK 21 and above.
**Server/Backend Development?**
If you're building JVM backend applications (servers, CLIs, workers), see the [Kotlin (JVM)](/lib/kotlin-jvm) documentation instead, which provides JVM-optimized guidance without Android-specific dependencies.
## Installation
```kotlin Gradle (Kotlin DSL) theme={null}
repositories {
mavenCentral()
}
dependencies {
implementation("io.growthbook.sdk:GrowthBook:7.1.0")
// Choose ONE network dispatcher:
implementation("io.growthbook.sdk:NetworkDispatcherKtor:1.0.12")
// OR
implementation("io.growthbook.sdk:NetworkDispatcherOkHttp:1.0.7")
// Optional: JSON serialization helpers
implementation("io.growthbook.sdk:GrowthBookKotlinxSerialization:1.0.0")
}
```
```groovy Gradle (Groovy DSL) theme={null}
repositories {
mavenCentral()
}
dependencies {
implementation 'io.growthbook.sdk:GrowthBook:7.1.0'
// Choose ONE network dispatcher:
implementation 'io.growthbook.sdk:NetworkDispatcherKtor:1.0.12'
// OR
implementation 'io.growthbook.sdk:NetworkDispatcherOkHttp:1.0.7'
// Optional: JSON serialization helpers
implementation 'io.growthbook.sdk:GrowthBookKotlinxSerialization:1.0.0'
}
```
### Network Dispatchers
The SDK requires a network dispatcher for fetching feature definitions:
* **`GBNetworkDispatcherKtor`** - Ktor-based implementation (Android-friendly default)
* **`GBNetworkDispatcherOkHttp`** - OkHttp-based implementation (recommended for most Android apps)
## Quick Start
To create a GrowthBook SDK instance, use `GBSDKBuilder`. The SDK uses coroutines, so initialize it from a coroutine scope.
```kotlin theme={null}
import com.sdk.growthbook.GBSDKBuilder
import com.sdk.growthbook.GrowthBookSDK
import com.sdk.growthbook.model.toGbBoolean
import com.sdk.growthbook.model.toGbString
import com.sdk.growthbook.network.GBNetworkDispatcherKtor
import kotlinx.coroutines.launch
class MainActivity : AppCompatActivity() {
private lateinit var growthBook: GrowthBookSDK
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// User attributes for targeting and assigning users to experiment variations
val attributes = mapOf(
"id" to "user-123".toGbString(),
"deviceType" to "Android".toGbString(),
"appVersion" to "1.2.0".toGbString(),
"isPremium" to true.toGbBoolean()
)
lifecycleScope.launch {
growthBook = GBSDKBuilder(
// Fetch and cache feature definitions from GrowthBook API
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = attributes,
trackingCallback = { experiment, result ->
// Track experiment views in your analytics system
analytics.track("experiment_viewed", mapOf(
"experiment_id" to experiment.key,
"variation_id" to result.variationId
))
},
networkDispatcher = GBNetworkDispatcherKtor(),
// Optional: encryption key if using encrypted features
encryptionKey = "your_encryption_key_here"
).initialize()
}
}
}
```
### Configuration Options
The `GBSDKBuilder` accepts several configuration options:
* **apiKey** (`String`, required) - Your GrowthBook API key
* **apiHost** (`String`, required) - API host URL (typically `https://cdn.growthbook.io/`)
* **streamingHost** (`String`, optional) - Streaming host URL for SSE updates
* **attributes** (`Map`) - User attributes for targeting
* **trackingCallback** (`(GBExperiment, GBExperimentResult) -> Unit`) - Analytics tracking callback
* **networkDispatcher** (`NetworkDispatcher`, required) - Network implementation
* **encryptionKey** (`String`, optional) - Decryption key for encrypted features
* **cachingEnabled** (`Boolean`, default: true) - Enable/disable local feature caching
* **remoteEval** (`Boolean`, default: false) - Enable remote feature evaluation
* **enableLogging** (`Boolean`, default: false) - Print debug logs to stdout
The following options are set via builder methods rather than constructor parameters:
* `.setEnabled(Boolean)` - Enable/disable all experiments (default: true)
* `.setQAMode(Boolean)` - Disable randomization for QA testing (default: false)
* `.setForcedVariations(Map)` - Force specific variations for QA
* `.setRefreshHandler(GBCacheRefreshHandler)` - Callback fired when features are refreshed
* `.setStickyBucketService(GBStickyBucketService)` - Enable sticky bucketing
* `.setFeatureUsageCallback(GBFeatureUsageCallback)` - Callback fired on every feature evaluation
### Updating User Attributes
You can update user attributes at any time using `setAttributes()`. This completely replaces the attributes object:
```kotlin theme={null}
// Update attributes when user logs in
growthBook.setAttributes(mapOf(
"id" to userId.toGbString(),
"isPremium" to true.toGbBoolean(),
"country" to "US".toGbString(),
))
```
**Attribute Changes**
Be aware that changing attributes may change the assigned feature values, which can be disorienting to users if not handled carefully.
### Feature Refresh Handler
To access features as soon as they're loaded from the backend, use `setRefreshHandler()`:
```kotlin theme={null}
class MainActivity : AppCompatActivity() {
private var growthBookSDK: GrowthBookSDK? = null
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
lifecycleScope.launch {
val builder = GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = mapOf("id" to userId.toGbString()),
networkDispatcher = GBNetworkDispatcherKtor(),
trackingCallback = { _, _ -> }
)
builder.setRefreshHandler { isRefreshed, error ->
if (isRefreshed) {
// Features are now loaded and ready to use
val feature = growthBookSDK?.feature("new-checkout-flow")
if (feature?.on == true) {
// Show new checkout flow
}
} else {
Log.e("GrowthBook", "Failed to refresh features", error)
}
}
growthBookSDK = builder.initialize()
}
}
}
```
## Evaluating Features
### Feature Result
The `feature()` method takes a feature key and returns a `GBFeatureResult` object with the following properties:
* **gbValue** (`GBValue`) - The assigned value of the feature (typed wrapper)
* **on** (`Boolean`) - The value cast to a boolean
* **off** (`Boolean`) - The value cast to a boolean and then negated
* **source** (`GBFeatureSource`) - Why the value was assigned: `unknownFeature`, `defaultValue`, `force`, `experiment`, `prerequisite`, `cyclicPrerequisite`, or `override`
When the source is `experiment`, there are additional properties:
* **experiment** (`GBExperiment`) - The experiment configuration
* **experimentResult** (`GBExperimentResult`) - The experiment evaluation result
### Basic Usage
```kotlin theme={null}
// Boolean feature flag
val newCheckoutEnabled = growthBook.feature("new-checkout-flow").on
if (newCheckoutEnabled) {
showNewCheckout()
} else {
showLegacyCheckout()
}
// String feature
val buttonColor = growthBook.feature("button-color").gbValue as? GBString
// Numeric feature
val maxRetries = growthBook.feature("max-retries").gbValue as? GBNumber
// Complex JSON feature
val config = growthBook.feature("service-config").gbValue as? GBJson
```
### Working with GBValue
Starting with version 2.0.0, feature values use the `GBValue` type for better type safety:
```kotlin theme={null}
val featureResult = growthBook.feature("my-feature")
// Access the typed value
when (val gbValue = featureResult.gbValue) {
is GBBoolean -> {
val boolValue = gbValue.value
println("Boolean: $boolValue")
}
is GBString -> {
val stringValue = gbValue.value
println("String: $stringValue")
}
is GBNumber -> {
val numberValue = gbValue.value // Double
println("Number: $numberValue")
}
is GBArray -> {
println("GbArray: $gbValue")
}
is GBJson -> {
println("JSON: $gbValue")
}
is GBNull -> {
println("Null value")
}
is GBValue.Unknown -> {
println("GBValue.Unknown")
}
}
```
### Typed Feature Access
For convenience, you can directly get a typed feature value using `featureValue()` (available in version 7.1.0+):
```kotlin theme={null}
// Get feature value with inferred type
val maxRetries: Int? = growthBook.featureValue("max-retries")
val buttonColor: String? = growthBook.featureValue("button-color")
val isEnabled: Boolean? = growthBook.featureValue("new-feature-enabled")
// Use with default values
val timeout = growthBook.featureValue("api-timeout") ?: 5000L
```
### Feature Source and Experiments
Check why a feature value was assigned and access experiment details:
```kotlin theme={null}
val feature = growthBook.feature("premium-feature")
println("Feature value: ${feature.gbValue}")
println("Is on: ${feature.on}")
println("Source: ${feature.source}")
// If the feature value came from an experiment
if (feature.source == GBFeatureSource.experiment) {
val experiment = feature.experiment
val result = feature.experimentResult
println("Experiment key: ${experiment?.key}")
println("Variation ID: ${result?.variationId}")
println("In experiment: ${result?.inExperiment}")
}
```
## Running Inline Experiments
You can run experiments directly without defining them in the GrowthBook API. This is useful for programmatic experiments:
```kotlin theme={null}
val experiment = GBExperiment(
key = "button-color-test"
variations = listOf(
"blue", "red", "green"
).map { it.toGbString() },
weights = listOf(0.5f, 0.3f, 0.2f),
)
val result = growthBook.run(experiment)
// Get the assigned variation
val color = result.value as GBString // "blue", "red", or "green"
println("Assigned color: $color")
if (result.inExperiment) {
// User is in the experiment
applyButtonColor(color)
}
```
### Experiment Configuration
The `GBExperiment` class accepts the following properties:
**Required:**
* **key** (`String`) - The unique identifier for this experiment
* **variations** (`Array`) - Array of variations to choose between
**Optional:**
* **weights** (`FloatArray`) - Traffic distribution across variations (must sum to 1.0)
* **active** (`Boolean`, default: true) - If false, always return control (first variation)
* **coverage** (`Float`, default: 1.0) - Percentage of users to include (0.0 to 1.0)
* **condition** (`GBCondition`) - Targeting conditions for the experiment
* **namespace** (`GBNamespace`) - Namespace for experiment isolation
* **force** (`Int`) - Force all users to a specific variation index (for QA)
* **hashAttribute** (`String`, default: "id") - User attribute for variation assignment
### Experiment Result
The `GBExperimentResult` object contains:
* **inExperiment** (`Boolean`) - Whether the user is in the experiment
* **variationId** (`Int`) - The index of the assigned variation
* **value** (`Any`) - The value of the assigned variation
* **hashAttribute** (`String`) - The attribute used for hashing
* **hashValue** (`String`) - The value of the hash attribute
* **key** (`String`) - The experiment key
* **bucket** (`Float`) - The hash bucket value (0.0 to 1.0)
* **stickyBucketUsed** (`Boolean`) - Whether sticky bucketing was used
### Advanced Experiment Example
```kotlin theme={null}
// Complex experiment with targeting and custom weights
val pricingExperiment = GBExperiment(
key = "pricing-test",
variations = listOf(9.99, 14.99, 19.99)
.map { it.toGbNumber() },
hashAttribute = "userId" // Use custom attribute for hashing
).apply {
weights = listOf(0.5f, 0.3f, 0.2f)
coverage = 0.8f // Only 80% of users
// Only target premium users in the US
condition = JsonObject(mapOf(
"country" to JsonPrimitive("US"),
"plan" to JsonPrimitive("premium"),
))
}
val result = growthBook.run(pricingExperiment)
if (result.inExperiment) {
val price = result.value as GBNumber
displayPrice(price)
// Track the experiment view
analytics.track("pricing_experiment_viewed", mapOf(
"price" to price,
"variation_id" to result.variationId
))
}
```
## Sticky Bucketing
Sticky Bucketing ensures users see consistent experiment variations even when targeting conditions or user attributes change. This prevents jarring user experiences from switching variations mid-experiment.
### How It Works
When sticky bucketing is enabled, the SDK persists experiment assignments in local storage. The next time the user is evaluated for that experiment, they'll get the same variation they saw before.
### Implementation
Implement the `GBStickyBucketService` interface to enable sticky bucketing:
```kotlin theme={null}
import com.sdk.growthbook.stickybucket.GBStickyBucketService
import com.sdk.growthbook.utils.GBStickyAssignmentsDocument
import android.content.SharedPreferences
import kotlinx.coroutines.CoroutineScope
import kotlinx.serialization.json.Json
import kotlinx.serialization.encodeToString
import kotlinx.serialization.decodeFromString
class StickyBucketServiceImpl(
override val coroutineScope: CoroutineScope,
private val preferences: SharedPreferences,
private val prefix: String = "gb_sticky_"
) : GBStickyBucketService {
override suspend fun getAssignments(
attributeName: String,
attributeValue: String
): GBStickyAssignmentsDocument? {
val key = "$prefix${attributeName}||$attributeValue"
val json = preferences.getString(key, null) ?: return null
return try {
Json.decodeFromString(json)
} catch (e: Exception) {
null
}
}
override suspend fun saveAssignments(doc: GBStickyAssignmentsDocument) {
val key = "$prefix${doc.attributeName}||${doc.attributeValue}"
val json = Json.encodeToString(doc)
preferences.edit()
.putString(key, json)
.apply()
}
override suspend fun getAllAssignments(
attributes: Map
): Map {
val docs = mutableMapOf()
attributes.forEach { (attrName, attrValue) ->
getAssignments(attrName, attrValue)?.let { doc ->
val docKey = "${doc.attributeName}||${doc.attributeValue}"
docs[docKey] = doc
}
}
return docs
}
}
```
### Using Sticky Bucketing
Pass your sticky bucket service implementation when building the SDK:
```kotlin theme={null}
val preferences = context.getSharedPreferences("growthbook_prefs", Context.MODE_PRIVATE)
val stickyBucketService = StickyBucketServiceImpl(
coroutineScope = lifecycleScope,
preferences = preferences
)
val growthBook = GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = mapOf("id" to userId.toGbString()),
networkDispatcher = GBNetworkDispatcherKtor(),
trackingCallback = { _, _ -> }
)
.setStickyBucketService(stickyBucketService)
.initialize()
```
**Sticky Bucket Documents**
Each sticky bucket document contains:
* `attributeName` - The attribute used to identify the user (e.g., "id", "deviceId")
* `attributeValue` - The value of that attribute (e.g., "user-123")
* `assignments` - A map of experiment assignments (e.g., `{"exp1__0": "control"}`)
{null}
## Automatic Features Refresh
The GrowthBook SDK supports automatic feature refresh through multiple mechanisms to ensure your app always has the latest feature definitions.
### Server-Sent Events (SSE)
Server-Sent Events provide real-time feature updates without polling. When enabled, the SDK maintains a persistent connection to receive live updates whenever features change.
```kotlin theme={null}
val growthBook = gbSdkBuilder.initialize()
val flow = growthBook.startAutoRefreshFeatures()
flow.launchIn(lifecycleScope)
```
### Manual Refresh
You can manually trigger feature refresh at any time:
```kotlin theme={null}
lifecycleScope.launch {
growthBook.refreshCache()
Log.d("GrowthBook", "Feature refresh requested")
}
```
### Cache Configuration
By default, caching is enabled. You can disable it via the `cachingEnabled` constructor parameter:
```kotlin theme={null}
val growthBook = GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = attributes,
networkDispatcher = GBNetworkDispatcherKtor(),
trackingCallback = { _, _ -> },
cachingEnabled = false // disable local cache
).initialize()
```
To be notified when features are refreshed from the server, use `setRefreshHandler()` on the builder:
```kotlin theme={null}
val builder = GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = attributes,
networkDispatcher = GBNetworkDispatcherKtor(),
trackingCallback = { _, _ -> }
)
builder.setRefreshHandler { isRefreshed, error ->
if (isRefreshed) {
Log.d("GrowthBook", "Features refreshed successfully")
} else {
Log.w("GrowthBook", "Feature refresh failed: ${error?.errorMessage}")
}
}
val growthBook = builder.initialize()
```
## Experiment Tracking and Feature Usage Callbacks
The SDK provides comprehensive tracking capabilities for experiments and feature usage.
### Experiment Tracking Callback
The tracking callback is called whenever a user is included in an experiment. This is essential for analytics and experiment analysis.
```kotlin theme={null}
val growthBook = GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = mapOf("id" to userId.toGbString()),
networkDispatcher = GBNetworkDispatcherKtor(),
// Experiment tracking callback
trackingCallback = { experiment, result ->
// Send to your analytics system
analytics.track("experiment_viewed", mapOf(
"experiment_id" to experiment.key,
"variation_id" to result.variationId,
"variation_value" to result.value,
"user_id" to userId,
"in_experiment" to result.inExperiment,
"hash_used" to result.hashUsed
))
// Optional: Track in your own analytics
firebaseAnalytics.logEvent("experiment_viewed") {
param("experiment_id", experiment.key)
param("variation_id", result.variationId.toString())
}
}
).initialize()
```
**Tracking Timing**
The tracking callback is only called when the user is actually included in the experiment. If they're not in the experiment, this callback won't be triggered.
### Feature Usage Callback
The feature usage callback is called every time a feature is evaluated, regardless of whether it's part of an experiment or not.
```kotlin theme={null}
val growthBook = GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = mapOf("id" to userId.toGbString()),
networkDispatcher = GBNetworkDispatcherKtor(),
trackingCallback = { _, _ -> }
)
.setFeatureUsageCallback { featureKey, result ->
// Track feature usage for monitoring and debugging
Log.d("GrowthBook", "Feature evaluated: $featureKey = ${result.gbValue}")
// Send to monitoring systems
monitoring.trackFeatureUsage(featureKey, result.gbValue)
// Optional: Track in analytics
analytics.track("feature_used", mapOf(
"feature_key" to featureKey,
"feature_value" to result.gbValue.toString(),
"source" to result.source.name,
"user_id" to userId
))
}
.initialize()
```
### Advanced Tracking Example
Combine both callbacks for comprehensive tracking:
```kotlin theme={null}
class GrowthBookManager {
private val analytics: AnalyticsService
private val monitoring: MonitoringService
fun initializeGrowthBook(userId: String): GrowthBookSDK {
return GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = mapOf("id" to userId.toGbString()),
networkDispatcher = GBNetworkDispatcherKtor(),
trackingCallback = { experiment, result ->
trackExperiment(experiment, result, userId)
}
)
.setFeatureUsageCallback { featureKey, result ->
trackFeatureUsage(featureKey, result, userId)
}
.initialize()
}
private fun trackExperiment(experiment: GBExperiment, result: GBExperimentResult, userId: String) {
// Send to multiple analytics platforms
analytics.track("experiment_viewed", mapOf(
"experiment_id" to experiment.key,
"variation_id" to result.variationId,
"user_id" to userId
))
// Track in monitoring for alerting
monitoring.recordExperimentView(experiment.key, result.variationId)
}
private fun trackFeatureUsage(featureKey: String, result: GBFeatureResult, userId: String) {
// Monitor feature usage patterns
monitoring.recordFeatureUsage(featureKey, result.gbValue)
// Track feature performance
if (result.source == GBFeatureSource.experiment) {
analytics.track("feature_experiment_used", mapOf(
"feature_key" to featureKey,
"experiment_id" to result.experiment?.key,
"user_id" to userId
))
}
}
}
```
## Encrypted Features and Secure Attributes
GrowthBook supports encryption for sensitive feature definitions and secure attribute hashing for privacy protection.
### Encrypted Features
Encrypted features ensure that sensitive feature configurations never reach the client in plain text.
#### Setup Encrypted Features
1. **Enable encryption in GrowthBook**: Go to your SDK Connection settings and enable "Encrypt SDK Payload"
2. **Get your encryption key**: Copy the encryption key from the SDK Connection settings
3. **Configure the SDK**:
```kotlin theme={null}
val growthBook = GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = mapOf("id" to userId.toGbString()),
networkDispatcher = GBNetworkDispatcherKtor(),
trackingCallback = { _, _ -> },
// Provide your encryption key
encryptionKey = "your_encryption_key_here"
).initialize()
```
#### Working with Encrypted Features
```kotlin theme={null}
// The SDK automatically decrypts features when evaluating
val encryptedFeature = growthBook.feature("sensitive-feature")
val value = encryptedFeature.gbValue
// You can check if encryption is working by looking at the source
if (encryptedFeature.source == GBFeatureSource.defaultValue) {
Log.d("GrowthBook", "Feature decrypted successfully")
}
```
**Security Best Practices**
* Store encryption keys securely (use Android Keystore or environment variables)
* Never commit encryption keys to version control
* Rotate encryption keys regularly
* Use different keys for different environments
{null}
### Secure Attributes
Secure attributes allow you to target users based on sensitive information without exposing that information to the client.
#### Setup Secure Attributes
1. **Enable secure attribute hashing** in your SDK Connection settings
2. **Hash sensitive attributes** before passing them to the SDK:
```kotlin theme={null}
import java.security.MessageDigest
import java.nio.charset.StandardCharsets
class SecureAttributeManager {
private val salt = "your_organization_salt" // From Organization Settings
fun hashSecureAttribute(value: String): String {
val input = value + salt
val digest = MessageDigest.getInstance("SHA-256")
val hash = digest.digest(input.toByteArray(StandardCharsets.UTF_8))
return hash.joinToString("") { "%02x".format(it) }
}
fun createSecureAttributes(user: User): Map {
return mapOf(
"id" to user.id.toGbString(),
"email" to hashSecureAttribute(user.email).toGbString(), // Hash sensitive email
"phone" to hashSecureAttribute(user.phone).toGbString(), // Hash sensitive phone
"country" to user.country.toGbString(), // Non-sensitive attributes remain plain
"plan" to user.plan.toGbString()
)
}
}
```
#### Using Secure Attributes
```kotlin theme={null}
val secureManager = SecureAttributeManager()
// Hash sensitive attributes before setting them
val secureAttributes = secureManager.createSecureAttributes(currentUser)
val growthBook = GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = secureAttributes,
networkDispatcher = GBNetworkDispatcherKtor(),
trackingCallback = { _, _ -> }
).initialize()
// The SDK will use hashed attributes for targeting
val targetedFeature = growthBook.feature("premium-feature")
```
#### Advanced Secure Attribute Example
```kotlin theme={null}
class UserAttributeManager {
private val salt = BuildConfig.GROWTHBOOK_SECURE_ATTRIBUTE_SALT
private fun sha256(input: String): String {
val digest = MessageDigest.getInstance("SHA-256")
val hash = digest.digest(input.toByteArray(StandardCharsets.UTF_8))
return hash.joinToString("") { "%02x".format(it) }
}
fun buildUserAttributes(user: User): Map {
val attributes = mutableMapOf()
// Non-sensitive attributes
attributes["id"] = user.id.toGbString()
attributes["country"] = user.country.toGbString()
attributes["plan"] = user.plan.toGbString()
attributes["signupDate"] = user.signupDate.toGbString()
// Hash sensitive attributes
if (user.email.isNotEmpty()) {
attributes["email"] = sha256(user.email + salt).toGbString()
}
if (user.phone.isNotEmpty()) {
attributes["phone"] = sha256(user.phone + salt).toGbString()
}
// Hash PII for targeting
attributes["userSegment"] = sha256("${user.id}_${user.plan}" + salt).toGbString()
return attributes
}
}
// Usage in your app
val attributeManager = UserAttributeManager()
val attributes = attributeManager.buildUserAttributes(currentUser)
growthBook.setAttributes(attributes)
```
### Custom Attributes
You can define custom attributes for advanced targeting scenarios:
```kotlin theme={null}
import com.sdk.growthbook.model.GBArray
val customAttributes = mapOf(
// Standard attributes
"id" to userId.toGbString(),
"country" to "US".toGbString(),
// Custom business attributes
"lifetimeValue" to userLifetimeValue.toGbNumber(),
"lastPurchaseDate" to lastPurchaseTimestamp.toGbString(),
"preferredCategory" to userPreferences.category.toGbString(),
"deviceModel" to Build.MODEL.toGbString(),
"appVersion" to BuildConfig.VERSION_NAME.toGbString(),
// Computed attributes
"isHighValueCustomer" to (userLifetimeValue > 1000).toGbBoolean(),
"daysSinceLastPurchase" to daysSinceLastPurchase.toGbNumber(),
// Array attributes for complex targeting
"purchasedCategories" to GBArray(listOf("electronics", "books", "clothing").map { it.toGbString() }),
"subscriptionFeatures" to GBArray(userSubscriptions.features.map { it.toGbString() })
)
val growthBook = GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = customAttributes,
networkDispatcher = GBNetworkDispatcherKtor(),
trackingCallback = { _, _ -> }
).initialize()
```
## Remote Evaluation
See the [Remote Evaluation overview](/self-host/remote-evaluation) for more information about what Remote Evaluation is, how it works, and deployment options.
Remote Evaluation evaluates feature flags on a secure server instead of the client, ensuring sensitive targeting rules and unused variations never reach the client.
### When to Use
Use Remote Evaluation when you need to:
* Keep targeting rules private
* Hide unused feature variations
* Prevent users from seeing all possible values
* Add an extra layer of security
**Backend Required**
Remote Evaluation requires either:
* GrowthBook Cloud with Remote Evaluation enabled
* A self-hosted GrowthBook Proxy Server
* A custom remote evaluation backend
{null}
### Setup
Enable Remote Evaluation in your SDK Connection settings in GrowthBook, then configure the SDK:
```kotlin theme={null}
val growthBook = GBSDKBuilder(
apiKey = "sdk_abc123",
apiHost = "https://cdn.growthbook.io/",
attributes = mapOf("id" to userId.toGbString()),
networkDispatcher = GBNetworkDispatcherKtor(),
trackingCallback = { _, _ -> },
remoteEval = true // Enable remote evaluation
).initialize()
```
When Remote Evaluation is enabled, the SDK will make an API call to evaluate features whenever user attributes change.
**Sticky Bucketing with Remote Evaluation**
If using Sticky Bucketing with Remote Evaluation, configure sticky bucketing on your remote evaluation backend. You don't need to provide a `StickyBucketService` to the client SDK.
## Serialization Support
The optional `GrowthBookKotlinxSerialization` module provides helpers for working with complex feature values using kotlinx.serialization.
### Installation
```kotlin theme={null}
dependencies {
implementation("io.growthbook.sdk:GrowthBookKotlinxSerialization:1.0.0")
}
```
### Usage
Define your data classes and use the serialization helpers:
```kotlin theme={null}
import kotlinx.serialization.Serializable
import com.sdk.growthbook.serialization.*
@Serializable
data class AppConfig(
val apiTimeout: Long,
val maxRetries: Int,
val enabledFeatures: List,
val themeColors: Map
)
// Get a complex feature value as a typed object
val configFeature = growthBook.feature("app-config")
val config: AppConfig? = configFeature.gbValue.decodeAs()
config?.let {
println("API Timeout: ${it.apiTimeout}")
println("Max Retries: ${it.maxRetries}")
println("Enabled Features: ${it.enabledFeatures.joinToString()}")
// Use the configuration in your app
setupApiClient(timeout = it.apiTimeout, retries = it.maxRetries)
}
```
**When to Use**
You only need the serialization module if you work with complex JSON feature values and want type-safe deserialization. For simple boolean, string, and number features, you can skip this dependency.
## ProGuard Configuration (Android)
If you use ProGuard or R8 for code shrinking and obfuscation, add these rules to your `proguard-rules.pro`:
```proguard theme={null}
# Core GrowthBook SDK
-keep class com.sdk.growthbook.** { *; }
# Kotlinx Serialization
-keep class kotlinx.serialization.json.** { *; }
-keepattributes *Annotation*, InnerClasses
-dontnote kotlinx.serialization.SerializationKt
# Keep serializers
-keep,includedescriptorclasses class com.sdk.growthbook.**$$serializer { *; }
# Keep companion objects
-keepclassmembers class com.sdk.growthbook.** {
*** Companion;
}
# Keep classes with KSerializer
-keepclasseswithmembers class com.sdk.growthbook.** {
kotlinx.serialization.KSerializer serializer(...);
}
```
**Important**
These are baseline rules. Depending on your app's configuration and the features you use, you may need additional rules. Test thoroughly with ProGuard enabled.
## Version History and Breaking Changes
The Kotlin SDK has undergone several major version updates with breaking changes:
### Recent Versions
* **v1.1.63** (2024-11-26) - Changed `value` field type to `kotlinx.serialization.json.JsonElement`
* **v2.0.0** (2025-01-10) - Renamed `value` to `gbValue` with `GBValue` type; added typed `feature()` method
* **v3.0.0** (2025-01-27) - Changed user attributes to use `GBValue` types
* **v4.0.0** (2025-03-03) - Changed `initialize()` to suspend method
* **v5.0.0** (2025-05-22) - Moved GBValue to Core module
* **v6.0.0** (2025-05-22) - Renamed `hostURL` to `apiHost`, added `streamingHost`
* **v6.1.0** (2025-08-15) - Changed `GBStickyBucketService` methods to suspend, added `coroutineScope`
* **v7.1.0** (2026-04-07) - Added `featureValue()` and hid reified typed APIs from Objective-C
### Migration Guidance
When upgrading between major versions, review the changelog on the [GitHub repository](https://github.com/growthbook/growthbook-kotlin) for detailed migration instructions.
## Further Reading
The GitHub repository contains comprehensive documentation including:
* Detailed API reference
* Advanced usage examples
* Integration guides
* Contributing guidelines
**GitHub Repository:** [https://github.com/growthbook/growthbook-kotlin](https://github.com/growthbook/growthbook-kotlin)
## Supported Features