Skip to main content
This guide will help you migrate from the legacy Java/Kotlin Server SDK to the new Java Core SDK. The Java Core SDK offers significant performance improvements and new features, as it’s built on a shared Rust core library.

​
Why Migrate?

  • Performance: Java Core achieves faster evaluation times and lower CPU consumption, making it more efficient than the legacy SDK.
  • New Features: Access to Parameter Stores, CMAB (Contextual Multi-Armed Bandits), observabilityClient, and more
  • Future Support: All new features and improvements will only be available in Java Core
  • Maintenance: The legacy Java SDK is in maintenance mode and will only receive critical bug fixes

​
Installation Differences

​
Legacy Java/Kotlin SDK

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.statsig:serversdk:X.X.X'
}

​
Java Core SDK

Java Core requires both the core library and a platform-specific native library: 
repositories {
    mavenCentral()
}

dependencies {
    // Core library (required)
    implementation 'com.statsig:javacore:X.X.X'
    
    // Platform-specific library (required)
    implementation 'com.statsig:javacore:X.X.X:YOUR-OS-ARCHITECTURE'
}
To determine the correct platform-specific dependency, you can run this code: 
import com.statsig.*;

StatsigOptions options = new StatsigOptions.Builder().build();
Statsig statsig = new Statsig("your-secret-key", options);
This will output the appropriate dependency for your system.

​
API Differences

​
Key Package and Class Changes

FeatureLegacy Java SDKJava Core SDK
Packagecom.statsig.sdk.*com.statsig.*
Main ClassStatsig (static methods)Statsig (instance methods)
OptionsStatsigOptionsStatsigOptions.Builder()
UserStatsigUserStatsigUser.Builder()
Check GateStatsig.checkGateSync()statsig.checkGate()
Get ConfigStatsig.getConfigSync()statsig.getDynamicConfig()
Get ExperimentStatsig.getExperimentSync()statsig.getExperiment()
Get LayerStatsig.getLayerSync()statsig.getLayer()
Log EventStatsig.logEvent()statsig.logEvent()

​
Initialization

import com.statsig.sdk.Statsig;

StatsigOptions options = new StatsigOptions();
// Customize options as needed
// options.initTimeoutMs = 9999;
Future initFuture = Statsig.initializeAsync("server-secret-key", options);
initFuture.get();

​
Checking Gates

StatsigUser user = new StatsigUser("user_id");
Boolean isFeatureOn = Statsig.checkGateSync(user, "use_new_feature");

if (isFeatureOn) {
  // Gate is on, use new feature
} else {
  // Gate is off
}

​
Getting Configs

DynamicConfig config = Statsig.getConfigSync(user, "awesome_product_details");

String itemName = config.getString("product_name", "Awesome Product v1");
Double price = config.getDouble("price", 10.0);
Boolean shouldDiscount = config.getBoolean("discount", false);

​
Getting Experiments

DynamicConfig experiment = Statsig.getExperimentSync(user, "new_user_promo_title");

String promoTitle = experiment.getString("title", "Welcome to Statsig!");
Double discount = experiment.getDouble("discount", 0.1);

​
Getting Layers

Layer layer = Statsig.getLayerSync(user, "user_promo_experiments");

String promoTitle = layer.getString("title", "Welcome to Statsig!");
Double discount = layer.getDouble("discount", 0.1);

​
Logging Events

Statsig.logEvent(user, "purchase", 2.99, Map.of("item_name", "remove_ads"));

​
Configuration Options Differences

StatsigOptions options = new StatsigOptions();
options.setInitTimeoutMs(3000);
options.setTier("staging");
options.setLocalMode(false);
options.setApi("https://api.statsig.com/v1");
options.setRulesetsSyncIntervalMs(10 * 1000);
options.setIdListsSyncIntervalMs(60 * 1000);
options.setDisableAllLogging(false);

​
Migration Steps

  1. Update Dependencies
    • Replace com.statsig:serversdk with com.statsig:javacore
    • Add the platform-specific dependency
  2. Update Imports
    • Replace import com.statsig.sdk.* with import com.statsig.*
  3. Update Initialization
    • Change from static methods to instance methods
    • Use the builder pattern for options and StatsigUser
    • Replace new StatsigUser("user_id") with new StatsigUser.Builder().setUserID("user_id").build()
    • Initialize with new Statsig(key, options) and call initialize()
  4. Update User Creation
    • Use the builder pattern: new StatsigUser.Builder().setUserID("user_id").build()
  5. Update Method Calls
    • Replace static methods with instance methods
    • Remove Sync suffix from method names
    • Update method signatures as needed
  6. Test Thoroughly
    • Verify all feature gates, experiments, and configs work as expected
    • Check that event logging is functioning correctly
  1. Update Dependencies
    • Replace com.statsig:serversdk with com.statsig:javacore
    • Add the platform-specific dependency
  2. Update Imports
    • Replace import com.statsig.sdk.* with import com.statsig.*
  3. Update Initialization
    • Change from static methods to instance methods
    • Replace .apply {} blocks with the builder pattern
    • Replace val user = StatsigUser("user_id") with val user = StatsigUser.Builder().setUserID("user_id").build()
    • Initialize with val statsig = Statsig("key", options) and call initialize()
  4. Update User Creation
    • Use the builder pattern: val user = StatsigUser.Builder().setUserID("user_id").build()
  5. Update Method Calls
    • Replace static methods with instance methods
    • Remove Sync suffix from method names
    • Update method signatures as needed
    • Replace mapOf("key" to "value") with appropriate map creation methods
  6. Test Thoroughly
    • Verify all feature gates, experiments, and configs work as expected
    • Check that event logging is functioning correctly

​
New Features in Java Core

​
Parameter Stores

Java Core introduces Parameter Stores, which allow you to manage parameters across multiple feature gates, experiments, and dynamic configs: 
ParameterStore parameterStore = statsig.getParameterStore(user, "my_parameter_store");
String value = parameterStore.getString("parameter_name", "default_value");

​
Improved Performance

Java Core offers significantly better performance:
  • Faster evaluation times
  • More efficient network usage
  • Reduced CPU usage
  • Better memory management

​
Troubleshooting

​
Common Issues

  1. Missing Platform-Specific Dependency
    • Error: java.lang.UnsatisfiedLinkError: no statsig_jni in java.library.path
    • Solution: Add the correct platform-specific dependency
  2. Incompatible Method Calls
    • Error: java.lang.NoSuchMethodError
    • Solution: Update method calls to match the new API
  3. Configuration Differences
    • Issue: Features not evaluating as expected
    • Solution: Verify options are correctly configured in the new format

​
Need Help?

If you encounter any issues during migration, please reach out to us:
⌘I