Java Server SDK - Statsig Documentation

Java Core on Github

Migrating from the Legacy Java SDK? See our Migration Guide.

Setup the SDK

Install the SDK

Requirements

Java 8 or higher (Java 8 support added in version 0.4.3)
Compatible with all platforms listed in the Supported OS and Architecture Combinations section, including:
- macOS (x86_64, arm64)
- Windows (x86_64)
- Amazon Linux 2 and 2023 (x86_64, arm64)

Overview

The Statsig Java SDK can be installed in two ways:Recommended: Single JAR installation (since version 0.4.0)

Use the “uber” JAR which contains both the core library and popular platform-specific native libraries in a single package
Simplifies dependency management and deployment across different environments

Advanced: Two-part installation

The platform-independent core library
An OS/architecture-specific native library for your specific platform

Installation Steps

Recommended: Using the Uber JAR (All-in-One)

Since version 0.4.0, Statsig provides an “uber” JAR that contains both the core library and native libraries for popular supported platforms in a single package. This is the recommended approach for most users.

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.statsig:javacore:X.X.X:uber' // Uber JAR with all native libraries
}

<dependencies>
    <dependency>
        <groupId>com.statsig</groupId>
        <artifactId>javacore</artifactId>
        <version>X.X.X</version>
        <classifier>uber</classifier>
    </dependency>
</dependencies>

You can find the latest version on Maven Central.The uber JAR includes native libraries for:

Linux (x86_64, arm64)
macOS (x86_64, arm64)
Windows (x86_64)

This approach eliminates the need to specify the exact platform and simplifies deployment across different environments.

Advanced: Platform-Specific Installation

If you need more control over dependencies or want to minimize the JAR size for a specific platform, you can use the platform-specific installation approach.

Install Core Library

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.statsig:javacore:X.X.X'  // Replace X.X.X with the latest version
}

<dependencies>
    <dependency>
        <groupId>com.statsig</groupId>
        <artifactId>javacore</artifactId>
        <version>X.X.X</version>  <!-- Replace X.X.X with the latest version -->
    </dependency>
</dependencies>

You can find the latest version on Maven Central.

Install Platform-Specific Library

You need to add the appropriate OS/architecture-specific dependency. Choose one of the following methods:Method 1: Automatic DetectionRun the following code to detect your system and get the appropriate dependency:

import com.statsig.*;

// All StatsigOptions are optional, feel free to adjust them as needed
StatsigOptions options = new StatsigOptions.Builder().build();

Statsig statsig = new Statsig("your-secret-key", options);

You’ll receive output similar to:

For Linux with arm64 architecture, add the following to build.gradle:
  implementation 'com.statsig:javacore:<version>:aarch64-unknown-linux-gnu'

For Linux with x86_64 architecture, add the following to build.gradle:
  implementation 'com.statsig:javacore:<version>:x86_64-unknown-linux-gnu'

Method 2: Manual Configuration

dependencies {
    implementation 'com.statsig:javacore:X.X.X'  // Core SDK (from Step 1)
    implementation 'com.statsig:javacore:X.X.X:YOUR-OS-ARCHITECTURE' // OS/architecture-specific dependency
}

<dependencies>
    <dependency>
        <groupId>com.statsig</groupId>
        <artifactId>javacore</artifactId>
        <version>X.X.X</version>
    </dependency>
    <dependency>
        <groupId>com.statsig</groupId>
        <artifactId>javacore</artifactId>
        <version>X.X.X</version>
        <classifier>YOUR-OS-ARCHITECTURE</classifier>
    </dependency>
</dependencies>

Replace YOUR-OS-ARCHITECTURE with one of the supported combinations from the Supported OS and Architecture Combinations section.

Docker Considerations for Alpine LinuxWhen using Alpine Linux or other musl-based Docker containers, you need to install additional compatibility packages for the native libraries to work properly. Add the following to your Dockerfile:

RUN apk add --no-cache libgcc gcompat

The Statsig Java Core SDK automatically detects musl-based systems and will use the appropriate musl-compatible native libraries (e.g., x86_64-unknown-linux-musl, aarch64-unknown-linux-musl).

Tested Platforms

Docker base images where the Java Core SDK has been tested and verified:

Docker Base Image	Description
amazoncorretto:21	Amazon Corretto 21 JDK
amazoncorretto:21-alpine-jdk	Amazon Corretto 21 JDK on Alpine Linux
amazonlinux:2	Amazon Linux 2
public.ecr.aws/amazonlinux/amazonlinux:2023	Amazon Linux 2023
azul/zulu-openjdk-alpine:21	Azul Zulu OpenJDK 21 on Alpine Linux
azul/zulu-openjdk:21	Azul Zulu OpenJDK 21
eclipse-temurin:21-jdk	Eclipse Temurin 21 JDK
eclipse-temurin:21-jdk-alpine	Eclipse Temurin 21 JDK on Alpine Linux

Initialize the SDK

After installation, you will need to initialize the SDK using a Server Secret Key from the Statsig console.

Server Secret Keys should always be kept private. If you expose one, you can disable and recreate it in the Statsig console.

There is also an optional parameter named options that allows you to pass in a StatsigOptions to customize the SDK.

import com.statsig.*;

// All StatsigOptions are optional, feel free to adjust them as needed
StatsigOptions options = new StatsigOptions.Builder()
                    .setSpecsSyncIntervalMs(10000)
                    .setEventLoggingFlushIntervalMs(10000)
                    .setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
                    .build();

Statsig myStatsigServer = new Statsig(SECRET_KEY, options);
myStatsigServer.initialize().get();

import com.statsig.*

// All StatsigOptions are optional, feel free to adjust them as needed
val options = StatsigOptions.Builder()
    .setSpecsSyncIntervalMs(10000)
    .setEventLoggingFlushIntervalMs(10000)
    .setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
    .build()

val myStatsigServer = Statsig(SECRET_KEY, options)
myStatsigServer.initialize().get()

initialize will perform a network request. After initialize completes, virtually all SDK operations will be synchronous (See Evaluating Feature Gates in the Statsig SDK). The SDK will fetch updates from Statsig in the background, independently of your API calls.

Getting Started

Quick Start Example

Create a new Java project

Create a new Gradle or Maven project with the following structure:

my-statsig-app/
├── build.gradle (or pom.xml)
└── src/main/java/ExampleApp.java

Add Statsig dependency

plugins {
    id 'java'
    id 'application'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.statsig:javacore:X.X.X:uber'
}

application {
    mainClass = 'ExampleApp'
}

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>my-statsig-app</artifactId>
    <version>1.0-SNAPSHOT</version>
    
    <dependencies>
        <dependency>
            <groupId>com.statsig</groupId>
            <artifactId>javacore</artifactId>
            <version>X.X.X</version>
            <classifier>uber</classifier>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.0.0</version>
                <configuration>
                    <mainClass>ExampleApp</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Replace X.X.X with the latest version from Maven Central.

Write your application code

import com.statsig.*;

public class ExampleApp {
    public static void main(String[] args) throws Exception {
        // Initialize Statsig
        StatsigOptions options = new StatsigOptions.Builder().build();
        Statsig statsig = new Statsig("YOUR_SERVER_SECRET_KEY", options);
        statsig.initialize().get();
        
        try {
            // Check a feature gate
            boolean isEnabled = statsig.checkGate("user123", "my_feature_gate");
            System.out.println("Feature gate is " + (isEnabled ? "enabled" : "disabled"));
            
            // Get a config
            DynamicConfig config = statsig.getConfig("user123", "my_config");
            System.out.println("Config value: " + config.getString("some_parameter", "default_value"));
        } finally {
            // Always shutdown Statsig when done
            statsig.shutdown();
        }
    }
}

import com.statsig.*

fun main() {
    // Initialize Statsig
    val options = StatsigOptions.Builder().build()
    val statsig = Statsig("YOUR_SERVER_SECRET_KEY", options)
    statsig.initialize().get()
    
    try {
        // Check a feature gate
        val isEnabled = statsig.checkGate("user123", "my_feature_gate")
        println("Feature gate is ${if (isEnabled) "enabled" else "disabled"}")
        
        // Get a config
        val config = statsig.getConfig("user123", "my_config")
        println("Config value: ${config.getString("some_parameter", "default_value")}")
    } finally {
        // Always shutdown Statsig when done
        statsig.shutdown().get()
    }
}

Replace YOUR_SERVER_SECRET_KEY with your actual server secret key from the Statsig Console.

Run the application

./gradlew run

mvn compile exec:java

If everything is set up correctly, you should see output related to your feature gate and configuration.

Working with the SDK

Checking a Feature Flag/Gate

Now that your SDK is initialized, let’s fetch a Feature Gate. Feature Gates can be used to create logic branches in code that can be rolled out to different users from the Statsig Console. Gates are always CLOSED or OFF (think return false;) by default. From this point on, all APIs will require you to specify the user (see Statsig user) associated with the request. For example, check a gate for a certain user like this:

String userID = "user_id";
boolean result = statsig.checkGate(userID, "my_feature_gate");

// with StatsigUser
StatsigUser user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build();
boolean gateResult = statsig.checkGate(user, "my_feature_gate");

val userID = "user_id"
val result = statsig.checkGate(userID, "my_feature_gate")

// with StatsigUser
val user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build()
val gateResult = statsig.checkGate(user, "my_feature_gate")

Reading a Dynamic Config

Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, Dynamic Configs can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:

String userID = "user_id";
DynamicConfig config = statsig.getConfig(userID, "my_config");

String name = config.getString("name", "");
int size = config.getInt("size", 10);

// with StatsigUser
StatsigUser user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build();
DynamicConfig dynamicConfig = statsig.getConfig(user, "my_config");

val userID = "user_id"
val config = statsig.getConfig(userID, "my_config")

val name = config.getString("name", "")
val size = config.getInt("size", 10)

// with StatsigUser
val user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build()
val dynamicConfig = statsig.getConfig(user, "my_config")

Getting a Layer/Experiment

Then we have Layers/Experiments, which you can use to run A/B/n experiments. We offer two APIs, but often recommend the use of layers, which make parameters reusable and let you run mutually exclusive experiments.

String userID = "user_id";

// Getting an Experiment
Experiment experiment = statsig.getExperiment(userID, "my_experiment");
String expName = experiment.getString("experiment_param", "");

// Getting a Layer
Layer layer = statsig.getLayer(userID, "my_layer");
String layerValue = layer.getString("layer_param", "default");

// with StatsigUser
StatsigUser user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build();
    
Experiment experimentWithUser = statsig.getExperiment(user, "my_experiment");
Layer layerWithUser = statsig.getLayer(user, "my_layer");

val userID = "user_id"

// Getting an Experiment
val experiment = statsig.getExperiment(userID, "my_experiment")
val expName = experiment.getString("experiment_param", "")

// Getting a Layer
val layer = statsig.getLayer(userID, "my_layer")
val layerValue = layer.getString("layer_param", "default")

// with StatsigUser
val user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build()
    
val experimentWithUser = statsig.getExperiment(user, "my_experiment")
val layerWithUser = statsig.getLayer(user, "my_layer")

Retrieving Feature Gate Metadata

In certain scenarios, you may need more information about a gate evaluation than just a boolean value. For additional metadata about the evaluation, use the Get Feature Gate API, which returns a FeatureGate object:

String userID = "user_id";
FeatureGate gate = statsig.getFeatureGate(userID, "my_feature_gate");

System.out.println("Gate name: " + gate.name);
System.out.println("Gate value: " + gate.value);
System.out.println("Rule ID: " + gate.ruleID);

// with StatsigUser
StatsigUser user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build();
FeatureGate gateWithUser = statsig.getFeatureGate(user, "my_feature_gate");

val userID = "user_id"
val gate = statsig.getFeatureGate(userID, "my_feature_gate")

println("Gate name: ${gate.name}")
println("Gate value: ${gate.value}")
println("Rule ID: ${gate.ruleID}")

// with StatsigUser
val user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build()
val gateWithUser = statsig.getFeatureGate(user, "my_feature_gate")

Parameter Stores

Sometimes you don’t know whether you want a value to be a Feature Gate, Experiment, or Dynamic Config yet. If you want on-the-fly control of that outside of your deployment cycle, you can use Parameter Stores to define a parameter that can be changed into at any point in the Statsig console. Parameter Stores are optional, but parameterizing your application can prove very useful for future flexibility and can even allow non-technical Statsig users to turn parameters into experiments.

String userID = "user_id";
ParameterStore store = statsig.getParameterStore(userID, "my_param_store");

String stringValue = store.getString("string_param", "default");
int intValue = store.getInt("int_param", 0);
boolean boolValue = store.getBoolean("bool_param", false);
double doubleValue = store.getDouble("double_param", 0.0);

// with StatsigUser
StatsigUser user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build();
ParameterStore storeWithUser = statsig.getParameterStore(user, "my_param_store");

val userID = "user_id"
val store = statsig.getParameterStore(userID, "my_param_store")

val stringValue = store.getString("string_param", "default")
val intValue = store.getInt("int_param", 0)
val boolValue = store.getBoolean("bool_param", false)
val doubleValue = store.getDouble("double_param", 0.0)

// with StatsigUser
val user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build()
val storeWithUser = statsig.getParameterStore(user, "my_param_store")

Logging an Event

Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig—simply call the Log Event API and specify the user and event name to log; you additionally provide some value and/or an object of metadata to be logged together with the event:

import java.util.HashMap;
import java.util.Map;

String userID = "user_id";
String eventName = "my_custom_event";

// Simple event
statsig.logEvent(userID, eventName);

// Event with value
statsig.logEvent(userID, eventName, 10.5);

// Event with metadata
Map<String, String> metadata = new HashMap<>();
metadata.put("key1", "value1");
metadata.put("key2", "value2");
statsig.logEvent(userID, eventName, metadata);

// Event with value and metadata
statsig.logEvent(userID, eventName, 10.5, metadata);

// with StatsigUser
StatsigUser user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build();
statsig.logEvent(user, eventName, 10.5, metadata);

val userID = "user_id"
val eventName = "my_custom_event"

// Simple event
statsig.logEvent(userID, eventName)

// Event with value
statsig.logEvent(userID, eventName, 10.5)

// Event with metadata
val metadata = mapOf(
    "key1" to "value1",
    "key2" to "value2"
)
statsig.logEvent(userID, eventName, metadata)

// Event with value and metadata
statsig.logEvent(userID, eventName, 10.5, metadata)

// with StatsigUser
val user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build()
statsig.logEvent(user, eventName, 10.5, metadata)

Sending Events to Log Explorer

You can forward logs to Logs Explorer for convenient analysis using the Forward Log Line Event API. This lets you include custom metadata and event values with each log.

import java.util.HashMap;
import java.util.Map;

String userID = "user_id";

Map<String, Object> payload = new HashMap<>();
payload.put("log_level", "error");
payload.put("message", "Something went wrong");
payload.put("timestamp", System.currentTimeMillis());

statsig.forwardLogLineEvent(userID, payload);

// with StatsigUser
StatsigUser user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build();
statsig.forwardLogLineEvent(user, payload);

val userID = "user_id"

val payload = mapOf(
    "log_level" to "error",
    "message" to "Something went wrong",
    "timestamp" to System.currentTimeMillis()
)

statsig.forwardLogLineEvent(userID, payload)

// with StatsigUser
val user = StatsigUser.builder()
    .userID("user_id")
    .email("my_user@example.com")
    .build()
statsig.forwardLogLineEvent(user, payload)

Using Shared Instance

In some applications, you may want to create a single Statsig instance that can be accessed globally throughout your codebase. The shared instance functionality provides a singleton pattern for this purpose: The Java SDK supports using a shared instance for convenience:

import com.statsig.*;

// Initialize the shared instance
StatsigOptions options = new StatsigOptions.Builder().build();
Statsig.initializeGlobalSingleton("secret-key", options);
Statsig.getGlobalSingleton().initialize().get();

// Use the shared instance
boolean result = Statsig.getGlobalSingleton().checkGate("user_id", "my_feature_gate");

// Shutdown the shared instance when done
Statsig.getGlobalSingleton().shutdown();

import com.statsig.*

// Initialize the shared instance
val options = StatsigOptions.Builder().build()
Statsig.initializeGlobalSingleton("secret-key", options)
Statsig.getGlobalSingleton().initialize().get()

// Use the shared instance
val result = Statsig.getGlobalSingleton().checkGate("user_id", "my_feature_gate")

// Shutdown the shared instance when done
Statsig.getGlobalSingleton().shutdown()

Manual Exposures

By default, the SDK will automatically log an exposure event when you check a gate, get a config, get an experiment, or call get() on a parameter in a layer. However, there are times when you may want to log an exposure event manually. For example, if you’re using a gate to control access to a feature, but you don’t want to log an exposure until the user actually uses the feature, you can use manual exposures. Manual exposures allow you to control when exposure events are logged. This is useful when you want to delay exposure logging until certain conditions are met.

String userID = "user_id";

// Check gate without logging exposure
boolean result = statsig.checkGateWithExposureLoggingDisabled(userID, "my_feature_gate");

// Manually log the exposure when ready
statsig.manuallyLogGateExposure(userID, "my_feature_gate");

// Works with configs too
DynamicConfig config = statsig.getConfigWithExposureLoggingDisabled(userID, "my_config");
statsig.manuallyLogConfigExposure(userID, "my_config");

// And with experiments/layers
Experiment experiment = statsig.getExperimentWithExposureLoggingDisabled(userID, "my_experiment");
statsig.manuallyLogExperimentExposure(userID, "my_experiment");

Layer layer = statsig.getLayerWithExposureLoggingDisabled(userID, "my_layer");
statsig.manuallyLogLayerParameterExposure(userID, "my_layer", "parameter_name");

val userID = "user_id"

// Check gate without logging exposure
val result = statsig.checkGateWithExposureLoggingDisabled(userID, "my_feature_gate")

// Manually log the exposure when ready
statsig.manuallyLogGateExposure(userID, "my_feature_gate")

// Works with configs too
val config = statsig.getConfigWithExposureLoggingDisabled(userID, "my_config")
statsig.manuallyLogConfigExposure(userID, "my_config")

// And with experiments/layers
val experiment = statsig.getExperimentWithExposureLoggingDisabled(userID, "my_experiment")
statsig.manuallyLogExperimentExposure(userID, "my_experiment")

val layer = statsig.getLayerWithExposureLoggingDisabled(userID, "my_layer")
statsig.manuallyLogLayerParameterExposure(userID, "my_layer", "parameter_name")

Statsig User

The StatsigUser object represents a user in Statsig. You must provide a userID or at least one of the customIDs to identify the user. When calling APIs that require a user, you should pass as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks), and correctly measure impact of your experiments on your metrics/events. At least one ID (userID or customID) is required because it’s needed to provide a consistent experience for a given user (click here) Besides userID, we also have email, ip, userAgent, country, locale and appVersion as top-level fields on StatsigUser. In addition, you can pass any key-value pairs in an object/dictionary to the custom field and be able to create targeting based on them.

Private Attributes

Private attributes are user attributes that are used for evaluation but are not forwarded to any integrations. They are useful for PII or sensitive data that you don’t want to send to third-party services. The StatsigUser object represents a user in your application and contains fields used for feature evaluation.

import com.statsig.*;
import java.util.HashMap;
import java.util.Map;

// Build a user with various fields
Map<String, Object> customFields = new HashMap<>();
customFields.put("plan", "premium");
customFields.put("age", 25);

Map<String, String> privateAttributes = new HashMap<>();
privateAttributes.put("internal_id", "123456");

StatsigUser user = StatsigUser.builder()
    .userID("user_123")
    .email("user@example.com")
    .ip("192.168.1.1")
    .userAgent("Mozilla/5.0...")
    .country("US")
    .locale("en_US")
    .appVersion("1.2.3")
    .custom(customFields)
    .privateAttributes(privateAttributes)
    .build();

// Use the user for evaluation
boolean result = statsig.checkGate(user, "my_feature_gate");

import com.statsig.*

// Build a user with various fields
val customFields = mapOf(
    "plan" to "premium",
    "age" to 25
)

val privateAttributes = mapOf(
    "internal_id" to "123456"
)

val user = StatsigUser.builder()
    .userID("user_123")
    .email("user@example.com")
    .ip("192.168.1.1")
    .userAgent("Mozilla/5.0...")
    .country("US")
    .locale("en_US")
    .appVersion("1.2.3")
    .custom(customFields)
    .privateAttributes(privateAttributes)
    .build()

// Use the user for evaluation
val result = statsig.checkGate(user, "my_feature_gate")

Private Attributes

Private attributes are fields that will be used for evaluation but will not be logged in events sent to Statsig servers.

Map<String, String> privateAttributes = new HashMap<>();
privateAttributes.put("sensitive_field", "sensitive_value");

StatsigUser user = StatsigUser.builder()
    .userID("user_123")
    .privateAttributes(privateAttributes)
    .build();

val privateAttributes = mapOf(
    "sensitive_field" to "sensitive_value"
)

val user = StatsigUser.builder()
    .userID("user_123")
    .privateAttributes(privateAttributes)
    .build()

Statsig Options

You can pass in an optional parameter options in addition to sdkKey during initialization to customize the Statsig client. Here are the available options that you can configure.

StatsigOptions

string

Environment parameter for evaluation.

string

Custom URL for fetching feature specifications.

long

How often the SDK updates specifications from Statsig servers (in milliseconds).

boolean

default:"false"

Turn this on if you are proxying download_config_specs / get_id_lists and want to fall back to the default Statsig endpoint to increase reliability.

string

Custom URL for logging events.

boolean

default:"false"

If true, the SDK will not collect any logging within the session, including custom events and config check exposure events.

boolean

default:"false"

Required to be true when using segments with more than 1000 IDs.

boolean

default:"false"

If true, the SDK will not parse User-Agent strings into browserName, browserVersion, systemName, systemVersion, and appVersion when needed for evaluation.

boolean

default:"false"

If true, the SDK will not parse IP addresses (from user.ip) into country codes when needed for evaluation.

long

How often events are flushed to Statsig servers (in milliseconds).

int

Maximum number of events to queue before forcing a flush.

DataStore

An adapter with custom storage behavior for config specs. Can also continuously fetch updates in place of the Statsig network.

PersistentStorage

Interface to use persistent storage within the SDK.

OutputLogger.LogLevel

Set the logging level for the SDK. Options: NONE, ERROR, WARN, INFO, DEBUG.

ObservabilityClient

Interface to integrate observability metrics exposed by the SDK.

// Example usage
StatsigOptions options = new StatsigOptions.Builder()
    .setEnvironment("staging")
    .setSpecsSyncIntervalMs(10000)
    .setEventLoggingFlushIntervalMs(5000)
    .setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
    .build();

Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();

// Example usage
val options = StatsigOptions.Builder()
    .setEnvironment("staging")
    .setSpecsSyncIntervalMs(10000)
    .setEventLoggingFlushIntervalMs(5000)
    .setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
    .build()

val statsig = Statsig("secret-key", options)
statsig.initialize().get()

Shutting Statsig Down

Because we batch and periodically flush events, some events may not have been sent when your app/server shuts down. To make sure all logged events are properly flushed, you should call shutdown() before your app/server shuts down:

// Shutdown flushes all pending events and stops background tasks
statsig.shutdown();

// Or with a timeout (blocks until shutdown completes or timeout)
statsig.shutdown().get(5, TimeUnit.SECONDS);

// Shutdown flushes all pending events and stops background tasks
statsig.shutdown()

// Or with a timeout (blocks until shutdown completes or timeout)
statsig.shutdown().get(5, TimeUnit.SECONDS)

Local Overrides

Local Overrides are a way to override the values of gates, configs, experiments, and layers for testing purposes. This is useful for local development or testing scenarios where you want to force a specific value without having to change the configuration in the Statsig console. Local overrides allow you to override feature gate and config values for testing purposes.

import java.util.HashMap;
import java.util.Map;

// Override a gate
statsig.overrideGate("my_feature_gate", true);

// Override a config
Map<String, Object> configOverride = new HashMap<>();
configOverride.put("key", "value");
configOverride.put("number", 42);
statsig.overrideConfig("my_config", configOverride);

// Override an experiment
Map<String, Object> experimentOverride = new HashMap<>();
experimentOverride.put("variant", "test");
statsig.overrideExperiment("my_experiment", experimentOverride);

// Override a layer
Map<String, Object> layerOverride = new HashMap<>();
layerOverride.put("layer_param", "override_value");
statsig.overrideLayer("my_layer", layerOverride);

// Clear all overrides
statsig.clearAllOverrides();

// Clear specific override
statsig.clearGateOverride("my_feature_gate");
statsig.clearConfigOverride("my_config");

// Override a gate
statsig.overrideGate("my_feature_gate", true)

// Override a config
val configOverride = mapOf(
    "key" to "value",
    "number" to 42
)
statsig.overrideConfig("my_config", configOverride)

// Override an experiment
val experimentOverride = mapOf(
    "variant" to "test"
)
statsig.overrideExperiment("my_experiment", experimentOverride)

// Override a layer
val layerOverride = mapOf(
    "layer_param" to "override_value"
)
statsig.overrideLayer("my_layer", layerOverride)

// Clear all overrides
statsig.clearAllOverrides()

// Clear specific override
statsig.clearGateOverride("my_feature_gate")
statsig.clearConfigOverride("my_config")

Persistent Storage

The Persistent Storage interface allows you to implement custom storage for user-specific configurations. This enables you to persist user assignments across sessions, ensuring consistent experiment groups even when the user returns later. This is particularly useful for client-side A/B testing where you want to ensure users always see the same variant. Persistent storage allows the SDK to cache feature specifications locally, enabling faster initialization and offline operation.

import com.statsig.*;

class MyPersistentStorage implements PersistentStorage {
    @Override
    public void save(String key, String data) {
        // Save data to your persistent storage (e.g., file, database)
        // Example: Files.write(Paths.get(key), data.getBytes());
    }

    @Override
    public String load(String key) {
        // Load data from your persistent storage
        // Example: return new String(Files.readAllBytes(Paths.get(key)));
        return null;
    }

    @Override
    public void delete(String key) {
        // Delete data from your persistent storage
        // Example: Files.deleteIfExists(Paths.get(key));
    }
}

// Use persistent storage
StatsigOptions options = new StatsigOptions.Builder()
    .setPersistentStorage(new MyPersistentStorage())
    .build();

Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();

import com.statsig.*

class MyPersistentStorage : PersistentStorage {
    override fun save(key: String, data: String) {
        // Save data to your persistent storage (e.g., file, database)
        // Example: File(key).writeText(data)
    }

    override fun load(key: String): String? {
        // Load data from your persistent storage
        // Example: return File(key).readText()
        return null
    }

    override fun delete(key: String) {
        // Delete data from your persistent storage
        // Example: File(key).delete()
    }
}

// Use persistent storage
val options = StatsigOptions.Builder()
    .setPersistentStorage(MyPersistentStorage())
    .build()

val statsig = Statsig("secret-key", options)
statsig.initialize().get()

Data Store

The Data Store interface allows you to implement custom storage for Statsig configurations. This enables advanced caching strategies and integration with your preferred storage systems. Data stores allow you to customize how the SDK fetches and caches feature specifications, enabling advanced use cases like using Redis or other distributed caches.

import com.statsig.*;

class MyDataStore implements DataStore {
    @Override
    public String getDataSync(String key) {
        // Synchronously fetch data for the given key
        // This is called during SDK evaluation
        return null;
    }

    @Override
    public CompletableFuture<Void> setData(String key, String data) {
        // Store data for the given key
        // Called when SDK receives updates from Statsig
        return CompletableFuture.completedFuture(null);
    }

    @Override
    public CompletableFuture<Void> initialize() {
        // Perform any initialization needed for your data store
        return CompletableFuture.completedFuture(null);
    }

    @Override
    public void shutdown() {
        // Clean up resources
    }
}

// Use data store
StatsigOptions options = new StatsigOptions.Builder()
    .setDataStore(new MyDataStore())
    .build();

Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();

import com.statsig.*
import java.util.concurrent.CompletableFuture

class MyDataStore : DataStore {
    override fun getDataSync(key: String): String? {
        // Synchronously fetch data for the given key
        // This is called during SDK evaluation
        return null
    }

    override fun setData(key: String, data: String): CompletableFuture<Void> {
        // Store data for the given key
        // Called when SDK receives updates from Statsig
        return CompletableFuture.completedFuture(null)
    }

    override fun initialize(): CompletableFuture<Void> {
        // Perform any initialization needed for your data store
        return CompletableFuture.completedFuture(null)
    }

    override fun shutdown() {
        // Clean up resources
    }
}

// Use data store
val options = StatsigOptions.Builder()
    .setDataStore(MyDataStore())
    .build()

val statsig = Statsig("secret-key", options)
statsig.initialize().get()

Custom Output Logger

The Output Logger interface allows you to customize how the SDK logs messages. This enables integration with your own logging system and control over log verbosity. Custom output logger allows you to redirect SDK logs to your own logging system.

import com.statsig.*;

class MyOutputLogger implements OutputLogger {
    @Override
    public void log(LogLevel level, String message) {
        // Route SDK logs to your logging system
        switch (level) {
            case ERROR:
                System.err.println("[ERROR] " + message);
                break;
            case WARN:
                System.out.println("[WARN] " + message);
                break;
            case INFO:
                System.out.println("[INFO] " + message);
                break;
            case DEBUG:
                System.out.println("[DEBUG] " + message);
                break;
        }
    }
}

// Use custom output logger
StatsigOptions options = new StatsigOptions.Builder()
    .setOutputLogger(new MyOutputLogger())
    .setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
    .build();

Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();

import com.statsig.*

class MyOutputLogger : OutputLogger {
    override fun log(level: OutputLogger.LogLevel, message: String) {
        // Route SDK logs to your logging system
        when (level) {
            OutputLogger.LogLevel.ERROR -> println("[ERROR] $message")
            OutputLogger.LogLevel.WARN -> println("[WARN] $message")
            OutputLogger.LogLevel.INFO -> println("[INFO] $message")
            OutputLogger.LogLevel.DEBUG -> println("[DEBUG] $message")
            else -> {}
        }
    }
}

// Use custom output logger
val options = StatsigOptions.Builder()
    .setOutputLogger(MyOutputLogger())
    .setOutputLoggerLevel(OutputLogger.LogLevel.INFO)
    .build()

val statsig = Statsig("secret-key", options)
statsig.initialize().get()

Observability Client

The Observability Client interface allows you to monitor the health of the SDK by integrating with your own observability systems. This enables tracking metrics, errors, and performance data. For more information on the metrics emitted by Statsig SDKs, see the Monitoring documentation. Observability client allows you to monitor SDK performance and emit custom metrics.

import com.statsig.*;

class MyObservabilityClient implements ObservabilityClient {
    @Override
    public void emitMetric(String metricName, double value, Map<String, String> tags) {
        // Send metric to your monitoring system
        System.out.println("Metric: " + metricName + " = " + value + ", tags: " + tags);
    }

    @Override
    public void startTimer(String operationName) {
        // Start timing an operation
    }

    @Override
    public void endTimer(String operationName, Map<String, String> tags) {
        // End timing and emit duration metric
    }
}

// Use observability client
StatsigOptions options = new StatsigOptions.Builder()
    .setObservabilityClient(new MyObservabilityClient())
    .build();

Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();

import com.statsig.*

class MyObservabilityClient : ObservabilityClient {
    override fun emitMetric(metricName: String, value: Double, tags: Map<String, String>) {
        // Send metric to your monitoring system
        println("Metric: $metricName = $value, tags: $tags")
    }

    override fun startTimer(operationName: String) {
        // Start timing an operation
    }

    override fun endTimer(operationName: String, tags: Map<String, String>) {
        // End timing and emit duration metric
    }
}

// Use observability client
val options = StatsigOptions.Builder()
    .setObservabilityClient(MyObservabilityClient())
    .build()

val statsig = Statsig("secret-key", options)
statsig.initialize().get()

FAQ

What Java versions are supported?

The Java Core SDK supports Java 8 and higher. Java 8 support was added in version 0.4.3.

Which platforms are supported?

The SDK supports:

Linux (x86_64, arm64, musl variants)
macOS (x86_64, arm64)
Windows (x86_64)

See the Tested Platforms section for verified Docker images.

Should I use the uber JAR or platform-specific JARs?

The uber JAR is recommended for most use cases as it includes native libraries for all popular platforms and simplifies deployment. Use platform-specific JARs only if you need to minimize JAR size or have specific dependency requirements.

How do I use this with Alpine Linux?

For Alpine Linux (musl-based systems), install compatibility packages:

RUN apk add --no-cache libgcc gcompat

The SDK will automatically use musl-compatible native libraries.

How do I handle initialization in production?

The SDK initialization is asynchronous. Use .get() on the CompletableFuture to wait for initialization:

Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get(); // Blocks until initialized

Always call shutdown() when your application terminates to flush pending events.

Can I use multiple Statsig instances?

Yes, you can create multiple Statsig instances with different configurations. You can also use the global singleton with Statsig.getGlobalSingleton() for convenience.

How do I debug SDK issues?

Set the output logger level to DEBUG to see detailed logs:

StatsigOptions options = new StatsigOptions.Builder()
    .setOutputLoggerLevel(OutputLogger.LogLevel.DEBUG)
    .build();

Reference

FeatureGate Class

class FeatureGate {
    String name;                      // Gate name
    boolean value;                    // Evaluation boolean result
    String ruleID;                    // Rule ID for this gate
    EvaluationDetails evaluationDetails; // Evaluation details
    String rawJson;                   // Raw JSON string representation
}

Experiment Class

class Experiment {
    String name;                      // Name of the experiment
    String ruleID;                    // ID of the rule used in the experiment
    Map<String, JsonElement> value;   // Configuration values specific to the experiment
    String groupName;                 // The group name the user falls into
    EvaluationDetails evaluationDetails; // Details about how the experiment was evaluated
    String rawJson;                   // Raw JSON representation of the experiment
}

Methods for Experiment:

public String getString(String key, String fallbackValue)
public boolean getBoolean(String key, Boolean fallbackValue)
public double getDouble(String key, double fallbackValue)
public int getInt(String key, int fallbackValue)
public long getLong(String key, long fallbackValue)
public Object[] getArray(String key, Object[] fallbackValue)
public Map<String, Object> getMap(String key, Map<String, Object> fallbackValue)

DynamicConfig Class

class DynamicConfig {
    String name;                      // Name of the config
    String ruleID;                    // ID of the rule used
    Map<String, JsonElement> value;   // Configuration values
    EvaluationDetails evaluationDetails; // Details about how the config was evaluated
    String rawJson;                   // Raw JSON representation
}

Methods for DynamicConfig:

public String getString(String key, String fallbackValue)
public boolean getBoolean(String key, Boolean fallbackValue)
public double getDouble(String key, double fallbackValue)
public int getInt(String key, int fallbackValue)
public long getLong(String key, long fallbackValue)
public Object[] getArray(String key, Object[] fallbackValue)
public Map<String, Object> getMap(String key, Map<String, Object> fallbackValue)

Layer Class

class Layer {
    String name;                      // Layer name
    String ruleID;                    // Rule ID for this layer
    String groupName;                 // Group name
    Map<String, JsonElement> value;   // Layer values
    String allocatedExperimentName;   // Allocated experiment name
    EvaluationDetails evaluationDetails; // Evaluation details
    String rawJson;                   // Raw JSON string representation
}

Methods for Layer:

public String getString(String key, String fallbackValue)
public boolean getBoolean(String key, Boolean fallbackValue)
public double getDouble(String key, double fallbackValue)
public int getInt(String key, int fallbackValue)
public long getLong(String key, long fallbackValue)
public Object[] getArray(String key, Object[] fallbackValue)
public Map<String, Object> getMap(String key, Map<String, Object> fallbackValue)

Fields Needed Methods (Enterprise Only)

This is available for Enterprise contracts. Please reach out to our support team, your sales contact, or via our slack channel if you want this enabled.

These methods allow you to retrieve a list of user fields that are used in the targeting rules for gates, configs, experiments, and layers.

// Get user fields needed for a gate evaluation
List<String> getFieldsNeededForGate(String gateName)

// Get user fields needed for a dynamic config evaluation
List<String> getFieldsNeededForDynamicConfig(String configName)

// Get user fields needed for an experiment evaluation
List<String> getFieldsNeededForExperiment(String experimentName)

// Get user fields needed for a layer evaluation
List<String> getFieldsNeededForLayer(String layerName)

Field Mapping The fields returned by these methods correspond to the following user properties:

// Field mapping between user properties and internal field names
userID -> "u"
email -> "e"
ip -> "i"
userAgent -> "ua"
country -> "c"
locale -> "l"
appVersion -> "a"
time -> "t"
stableID -> "s"
environment -> "en"
targetApp -> "ta"

// Custom fields are prefixed with "cf:"
// Example: "cf:plan", "cf:age"

​Setup the SDK

​Requirements

​Overview

​Installation Steps

​Recommended: Using the Uber JAR (All-in-One)

​Advanced: Platform-Specific Installation

​Getting Started

​Quick Start Example

​Working with the SDK

​Checking a Feature Flag/Gate

​Reading a Dynamic Config

​Getting a Layer/Experiment

​Retrieving Feature Gate Metadata

​Parameter Stores

​Logging an Event

​Sending Events to Log Explorer

​Using Shared Instance

​Manual Exposures

​Statsig User

​Private Attributes

​Private Attributes

​Statsig Options

​Shutting Statsig Down

​Local Overrides

​Persistent Storage

​Data Store

​Custom Output Logger

​Observability Client

​FAQ

​Reference

​FeatureGate Class

​Experiment Class

​DynamicConfig Class

​Layer Class

​Fields Needed Methods (Enterprise Only)

Setup the SDK

Requirements

Overview

Installation Steps

Recommended: Using the Uber JAR (All-in-One)

Advanced: Platform-Specific Installation

Getting Started

Quick Start Example

Working with the SDK

Checking a Feature Flag/Gate

Reading a Dynamic Config

Getting a Layer/Experiment

Retrieving Feature Gate Metadata

Parameter Stores

Logging an Event

Sending Events to Log Explorer

Using Shared Instance

Manual Exposures

Statsig User

Private Attributes

Private Attributes

Statsig Options

Shutting Statsig Down

Local Overrides

Persistent Storage

Data Store

Custom Output Logger

Observability Client

FAQ

Reference

FeatureGate Class

Experiment Class

DynamicConfig Class

Layer Class

Fields Needed Methods (Enterprise Only)