Skip to main content

Java SDK

This supports Java applications using Java version 1.8 and higher.

New

The GrowthBook Java SDK is a brand new feature. If you experience any issues, let us know either on Slack or create an issue.

Installation​

Gradle​

To install in a Gradle project, add Jitpack to your repositories, and then add the dependency with the latest version to your project's dependencies.

build.gradle
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

dependencies {
    implementation 'com.github.growthbook:growthbook-sdk-java:0.5.0'
}

Maven​

To install in a Maven project, add Jitpack to your repositories:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

Next, add the dependency with the latest version to your project's dependencies:

<dependency>
    <groupId>com.github.growthbook</groupId>
    <artifactId>growthbook-sdk-java</artifactId>
    <version>0.5.0</version>
</dependency>

Usage​

There are 2 steps to initializing the GrowthBook SDK:

  1. Create a GrowthBook context GBContext with the features JSON and the user attributes
  2. Create the GrowthBook SDK class with the context

GrowthBook context​

The GrowthBook context GBContext can be created either by implementing the builder class, available at GBContext.builder(), or by using the GBContext constructor.

Field nameTypeDescription
attributesJsonStringThe user attributes JSON. See Attributes.
featuresJsonStringThe features JSON served by the GrowthBook API (or equivalent). See Features.
enabledBooleanWhether to enable the functionality of the SDK (default: true)
isQaModeBooleanWhether the SDK is in QA mode. Not for production use. If true, random assignment is disabled and only explicitly forced variations are used (default: false)
urlStringThe URL of the current page. Useful when evaluating features and experiments based on the page URL.
forcedVariationsMapMap<String, Integer>Force specific experiments to always assign a specific variation (used for QA)
trackingCallbackTrackingCallbackA callback that will be invoked with every experiment evaluation where the user is included in the experiment. See TrackingCallback. To subscribe to all evaluated events regardless of whether the user is in the experiment, see Subscribing to experiment runs.
featureUsageCallbackFeatureUsageCallbackA callback that will be invoked every time a feature is viewed. See FeatureUsageCallback

Using the GBContext builder​

The builder is the easiest to use way to construct a GBContext, allowing you to provide as many or few arguments as you'd like. All fields mentioned above are available via the builder.

// Fetch feature definitions from the GrowthBook API
// We recommend adding a caching layer in production
// Get your endpoint in the Environments tab -> SDK Endpoints: https://app.growthbook.io/environments
URI featuresEndpoint = new URI("https://cdn.growthbook.io/api/features/<environment_key>");
HttpRequest request = HttpRequest.newBuilder().uri(featuresEndpoint).GET().build();
HttpResponse<String> response = HttpClient.newBuilder().build()
    .send(request, HttpResponse.BodyHandlers.ofString());
String featuresJson = new JSONObject(response.body()).get("features").toString();

// JSON serializable user attributes
String userAttributesJson = user.toJson();

// Initialize the GrowthBook SDK with the GBContext
GBContext context = GBContext
    .builder()
    .featuresJson(featuresJson)
    .attributesJson(userAttributesJson)
    .build();

GrowthBook growthBook = new GrowthBook(context);
Note

The above example uses java.net.http.HttpClient which, depending on your web framework, may not be the best option, in which case it is recommended to use a networking library more suitable for your implementation.

Using the GBContext constructor​

You can also use GBContext constructor if you prefer, which will require you to pass all arguments explicitly.

// Fetch feature definitions from the GrowthBook API
// We recommend adding a caching layer in production
// Get your endpoint in the Environments tab -> SDK Endpoints: https://app.growthbook.io/environments
URI featuresEndpoint = new URI("https://cdn.growthbook.io/api/features/<environment_key>");
HttpRequest request = HttpRequest.newBuilder().uri(featuresEndpoint).GET().build();
HttpResponse<String> response = HttpClient.newBuilder().build()
    .send(request, HttpResponse.BodyHandlers.ofString());
String featuresJson = new JSONObject(response.body()).get("features").toString();

// JSON serializable user attributes
String userAttributesJson = user.toJson();

boolean isEnabled = true;
boolean isQaMode = false;
String url = null;
Map<String, Integer> forcedVariations = new HashMap<>();
TrackingCallback trackingCallback = new TrackingCallback() {
    @Override
    public <ValueType> void onTrack(Experiment<ValueType> experiment, ExperimentResult<ValueType> experimentResult) {
        // TODO: Something after it's been tracked
    }
};

// Initialize the GrowthBook SDK with the GBContext
GBContext context = new GBContext(
    userAttributesJson,
    featuresJson,
    isEnabled,
    isQaMode,
    url,
    forcedVariations,
    trackingCallback
);

GrowthBook growthBook = new GrowthBook(context);

For complete examples, see the Examples section below.

Features​

The features JSON is equivalent to the features property that is returned from the SDK Endpoint for the specified environment. You can find your endpoint on the Environments → SDK Endpoints page .

Attributes​

Attributes are a JSON string. You can specify attributes about the current user and request. Here's an example:

String userAttributes = "{\"country\": \"canada\", \"id\": \"user-abc123\"}";

If you need to set or update attributes asynchronously, you can do so with Context#attributesJson or GrowthBook#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.

Tracking Callback​

Any time an experiment is run to determine the value of a feature, we may call this callback so you can record the assigned value in your event tracking or analytics system of choice.

The tracking callback is only called when the user is in the experiment. If they are not in the experiment, this will not be called. If you'd like to subscribe to all evaluations, regardless of experiment result, see Subscribing to experiment runs.

TrackingCallback trackingCallback = new TrackingCallback() {
    @Override
    public <ValueType> void onTrack(
        Experiment<ValueType> experiment,
        ExperimentResult<ValueType> experimentResult
    ) {
        // TODO: Something after it's been tracked
    }
};

GBContext context = GBContext
    .builder()
    .featuresJson(featuresJson)
    .attributesJson(userAttributesJson)
    .trackingCallback(trackingCallback)
    .build();

Feature usage callback​

Any time a feature is viewed, this callback is called with the feature key and result.

String featuresJson = featuresRepository.getFeaturesJson();
String userAttributesJson = user.toJson();

FeatureUsageCallback featureUsageCallback = new FeatureUsageCallback() {
    @Override
    public <ValueType> void onFeatureUsage(String featureKey, FeatureResult<ValueType> result) {
        // TODO: Something with the feature result
    }
};

GBContext context = GBContext
    .builder()
    .featuresJson(featuresJson)
    .featureUsageCallback(featureUsageCallback)
    .attributesJson(userAttributesJson)
    .build();

GrowthBook growthBook = new GrowthBook(context);

Using Features​

Every feature has a "value" which is assigned to a user. This value can be any JSON data type. If a feature doesn't exist, the value will be null.

There are 4 main methods for evaluating features.

MethodReturn typeDescription
isOn(String)BooleanReturns true if the value is a truthy value
isOff(String)BooleanReturns true if the value is a falsy value
getFeatureValue(String)generic T (nullable)Returns the value cast to the generic type. Type is inferred based on the defaultValue argument provided.
evalFeature(String)FeatureResult<T>Returns a feature result with a value of generic type T. The value type needs to be specified in the generic parameter.
if (growthBook.isOn("dark_mode")) {
    // value is truthy
}

if (growthBook.isOff("dark_mode")) {
    // value is falsy
}

Float featureValue = growthBook.getFeatureValue("donut_price", 5.0f);
FeatureResult<Float> featureResult = growthBook.<Float>evalFeature("donut_price");

isOn() / isOff()​

These methods return a boolean for truthy and falsy values.

Only the following values are considered to be "falsy":

  • null
  • false
  • ""
  • 0

Everything else is considered "truthy", including empty arrays and objects.

If the value is "truthy", then isOn() will return true and isOff() will return false. If the value is "falsy", then the opposite values will be returned.

getFeatureValue(featureKey, defaultValue)​

This method has a variety of overloads to help with casting values to primitive and complex types.

In short, the type of the defaultValue argument will determine the return type of the function.

Return typeMethodAdditional Info
BooleangetFeatureValue(String featureKey, Boolean defaultValue)
DoublegetFeatureValue(String featureKey, Double defaultValue)
FloatgetFeatureValue(String featureKey, Float defaultValue)
IntegergetFeatureValue(String featureKey, Integer defaultValue)
StringgetFeatureValue(String featureKey, String defaultValue)
<ValueType> ValueTypegetFeatureValue(String featureKey, ValueType defaultValue, Class<ValueType> gsonDeserializableClass)Internally, the SDK uses Gson. You can pass any class that does not require a custom deserializer.
ObjectgetFeatureValue(String featureKey, Object defaultValue)Use this method if you need to cast a complex object that uses a custom deserializer, or if you use a different JSON serialization library than Gson, and cast the type yourself.

See the Java Docs for more information.

See the unit tests for example implementations including type casting for all above-mentioned methods.

evalFeature(String)​

The evalFeature method returns a FeatureResult<T> object with more info about why the feature was assigned to the user. The T type corresponds to the value type of the feature. In the above example, T is Float.

FeatureResult<T> It has the following getters.

MethodReturn typeDescription
getValue()generic T (nullable)The evaluated value of the feature
getSource()enum FeatureResultSource (nullable)The reason/source for the evaluated feature value.
getRuleId()String (nullable)ID of the rule that was used to assign the value to the user.
getExperiment()Experiment<T> (nullable)The experiment details, available only if the feature evaluates due to an experiment.
getExperimentResult()ExperimentResult<T> (nullable)The experiment result details, available only if the feature evaluates due to an experiment.

As expected in Kotlin, you can access these getters using property accessors.

Inline Experiments​

Instead of declaring all features up-front in the context and referencing them by IDs in your code, you can also just run an experiment directly. This is done with the growthbook.run(Experiment<T>) method.

Experiment<Float> donutPriceExperiment = Experiment
    .<Float>builder()
    .conditionJson("{\"employee\": true}")
    .build();
ExperimentResult<Float> donutPriceExperimentResult = growthBook.run(donutPriceExperiment);

Float donutPrice = donutPriceExperimentResult.getValue();

Inline experiment return value ExperimentResult​

An ExperimentResult<T> is returned where T is the generic value type for the experiment.

There's also a number of methods available.

MethodReturn typeDescription
getValue()generic T (nullable)The evaluated value of the feature
getVariationId()Integer (nullable)Index of the variation used, if applicable
getInExperiment()BooleanIf the user was in the experiment. This will be false if the user was excluded from being part of the experiment for any reason (e.g. failed targeting conditions).
getHashAttribute()StringUser attribute used for hashing, defaulting to id if not set.
getHashValue()String (nullable)The hash value used for evaluating the experiment, if applicable.
getFeatureId()StringThe feature key/ID
getHashUsed()BooleanIf a hash was used to evaluate the experiment. This flag will only be true if the user was randomly assigned a variation. If the user was forced into a specific variation instead, this flag will be false.

As expected in Kotlin, you can access these getters using property accessors.

Tracking feature usage and experiment impressions​

Subscribing to experiment runs with the ExperimentRunCallback​

You can subscribe to experiment run evaluations using the ExperimentRunCallback.

String featuresJson = featuresRepository.getFeaturesJson();
String userAttributesJson = user.toJson();

ExperimentRunCallback experimentRunCallback = new ExperimentRunCallback() {
    @Override
    public void onRun(ExperimentResult experimentResult) {
        // TODO: something with the experiment result
    }
};

GBContext context = GBContext
    .builder()
    .featuresJson(featuresJson)
    .attributesJson(userAttributesJson)
    .build();

GrowthBook growthBook = new GrowthBook(context);

growthBook.subscribe(experimentRunCallback);

Every time an experiment is evaluated when calling growthBook.run(Experiment), the callbacks will be called.

You can subscribe with as many callbacks as you like:

GrowthBook growthBook = new GrowthBook(context);

growthBook.subscribe(experimentRunCallback1);
growthBook.subscribe(experimentRunCallback2);
growthBook.subscribe(experimentRunCallback3);

The experiment run callback is called for every experiment run, regardless of experiment result. If you would like to subscribe only to evaluations where the user falls into an experiment, see TrackingCallback.

Subscribing to feature usage events with the FeatureUsageCallback​

You can subscribe to feature usage events by providing an implementation of the FeatureUsageCallback interface to the GBContext.

String featuresJson = featuresRepository.getFeaturesJson();
String userAttributesJson = user.toJson();

FeatureUsageCallback featureUsageCallback = new FeatureUsageCallback() {
    @Override
    public <ValueType> void onFeatureUsage(String featureKey, FeatureResult<ValueType> result) {
        // TODO: Something with the feature result
    }
};

GBContext context = GBContext
    .builder()
    .featuresJson(featuresJson)
    .featureUsageCallback(featureUsageCallback)
    .attributesJson(userAttributesJson)
    .build();

GrowthBook growthBook = new GrowthBook(context);

Working with Encrypted features​

As of version 0.3.0, the Java SDK supports decrypting encrypted features. You can learn more about SDK Connection Endpoint Encryption.

The main difference is you create a GBContext by passing an encryption key (.encryptionKey() when using the builder) and using the encrypted payload as the features JSON (.featuresJson() for the builder).

// Fetch feature definitions from the GrowthBook API
// We recommend adding a caching layer in production
// Get your endpoint in the Environments tab -> SDK Endpoints: https://app.growthbook.io/environments
URI featuresEndpoint = new URI("https://cdn.growthbook.io/api/features/<environment_key>");
HttpRequest request = HttpRequest.newBuilder().uri(featuresEndpoint).GET().build();
HttpResponse<String> response = HttpClient.newBuilder().build()
    .send(request, HttpResponse.BodyHandlers.ofString());
String encryptedFeaturesJson = new JSONObject(response.body()).get("encryptedFeatures").toString();

// JSON serializable user attributes
String userAttributesJson = user.toJson();

// You can store your encryption key as an environment variable rather than hardcoding in plain text in your codebase
String encryptionKey = "<key-for-decrypting>";

// Initialize the GrowthBook SDK with the GBContext and the encryption key
GBContext context = GBContext
    .builder()
    .featuresJson(encryptedFeaturesJson)
    .encryptionKey(encryptionKey)
    .attributesJson(userAttributesJson)
    .build();

GrowthBook growthBook = new GrowthBook(context);

Fetching, Cacheing, and Refreshing features with GBFeaturesRepository​

As of version 0.4.0, the Java SDK provides an optional GBFeaturesRepository class which will manage networking for you in the following ways:

  • Fetching features from the SDK endpoint when initialize() is called
  • Decrypting encrypted features when provided with the client key, e.g. .builder().encryptionKey(clientKey)
  • Cacheing features (in-memory)
  • Refreshing features

If you wish to manage fetching, refreshing, and cacheing features on your own, you can choose to not implement this class.

Recommendation

This class should be implemented as a singleton class as it includes caching and refreshing functionality.

If you have more than one SDK endpoint you'd like to implement, you can extend the GBFeaturesRepository class with your own class to make it easier to work with dependency injection frameworks. Each of these instances should be singletons.

Fetching the features​

You will need to create a singleton instance of the GBFeaturesRepository class either by implementing its .builder() or by using its constructor.

Then, you would call myGbFeaturesRepositoryInstance.initialize() in order to make the initial (blocking) request to fetch the features. Then, you would call myGbFeaturesRepositoryInstance.getFeaturesJson() and provided that to the GBContext initialization.

GBFeaturesRepository featuresRepository = GBFeaturesRepository
    .builder()
    .apiHost("https://cdn.growthbook.io")
    .clientKey("<environment_key>") // replace with your client key
    .encryptionKey("<client-key-for-decrypting>") // optional, nullable
    .refreshStrategy(FeatureRefreshStrategy.SERVER_SENT_EVENTS) // optional; options: STALE_WHILE_REVALIDATE, SERVER_SENT_EVENTS (default: STALE_WHILE_REVALIDATE)
    .build();

// Optional callback for getting updates when features are refreshed
featuresRepository.onFeaturesRefresh(new FeatureRefreshCallback() {
    @Override
    public void onRefresh(String featuresJson) {
        System.out.println("Features have been refreshed");
        System.out.println(featuresJson);
    }
});

try {
    featuresRepository.initialize();
} catch (FeatureFetchException e) {
    // TODO: handle the exception
    e.printStackTrace();
}

// Initialize the GrowthBook SDK with the GBContext and features
GBContext context = GBContext
    .builder()
    .featuresJson(featuresRepository.getFeaturesJson())
    .attributesJson(userAttributesJson)
    .build();

GrowthBook growthBook = new GrowthBook(context);

For more references, see the Examples below.

Cacheing and refreshing behaviour​

As of version 0.9.0, there are 2 refresh strategies available.

Stale While Revalidate​

This is the default strategy but can be explicitly stated by passing FeatureRefreshStrategy.STALE_WHILE_REVALIDATE as the refresh strategy option to the GBFeaturesRepository builder or constructor.

The GBFeaturesRepository will automatically refresh the features when the features become stale. Features are considered stale every 60 seconds. This amount is configurable with the ttlSeconds option.

When you fetch features and they are considered stale, the stale features are returned from the getFeaturesJson() method and a network call to refresh the features is enqueued asynchronously. When that request succeeds, the features are updated with the newest features, and the next call to getFeaturesJson() will return the refreshed features.

Server-Sent Events​

This is a new strategy that can be enabled by passing FeatureRefreshStrategy.SERVER_SENT_EVENTS as the refresh strategy option to the GBFeaturesRepository builder or constructor.

If you're using GrowthBook Cloud , this is ready for you to use. If you are self-hosting, you will need to set up the GrowthBook Proxy to enable it.

Overriding Feature Values​

The Java SDK allows you to override feature values and experiments using the URL.

Force Experiment Variations​

You can force an experiment variation by passing the experiment key and variation index as query parameters in the URL you set on the GBContext. For example, if you add ?my-experiment-id=2 to the URL, users will be forced into the variation at index 2 in the variations list when evaluating the experiment with key my-experiment-id.

Force Feature Values via the URL​

You can force a value for a feature by passing the key, prefixed by gb~, and the URI-encoded value in the URL's query parameters. You must also set allowUrlOverrides to true when building your GBContext in order to enable this feature as it is not enabled by default.

GBContext context = GBContext
    .builder()
    .url("http://localhost:8080/url-feature-force?gb~dark_mode=true&gb~donut_price=3.33&gb~banner_text=Hello%2C%20everyone!%20I%20hope%20you%20are%20all%20doing%20well!")
    .allowUrlOverrides(true)
    .build();

The above code sample sets the following:

  • dark_mode: true
  • banner_text: "Hello, everyone! I hope you are all doing well!"
  • donut_price: 3.33

Supported types​

TypeValue
StringA URI-encoded string value
FloatA float value, e.g. 3.33
DoubleA double value, e.g. 3.33
IntegerAn integer value, e.g. 1337
BooleanA boolean value, e.g. true or false. You can also represent boolean values with on/off state as on or off or binary values 1 or 0.
JSON as Gson-deserializableA class that can be deserialized using Gson and that does not have any dependencies on custom type adapters.
JSON as StringA URI-encoded string value that should be a valid JSON string that you can deserialize with your own JSON deserialization implementation.

The value passed in the URL is cast at runtime based on the generic type argument passed in when evaluating the feature. This means that when you call <ValueType>getFeatureValue(), what you pass into the URL must successfully cast as ValueType otherwise the value in the URL will be ignored.

All keys must be prefixed with gb~.

Using with Proguard and R8​

Many Android projects use code-shrinking and obfuscation tools like Proguard and R8 in production.

If you are experiencing unexpected feature evaluation results with your release Android builds that do not occur in your debug builds, it's most likely related to this.

You will need to add the following to your proguard-rules.pro file to ensure that all of the GrowthBook SDK classes are kept so that your features are evaluated properly in projects that use Proguard and R8:

# Growthbook Java SDK classes
-keep class growthbook.sdk.java.** { *; }

Code Examples​

Further Reading​