Android API

15 minute readReference

The following information is for the latest version of the Android SDK. If you are running an older version, please check the CloudBees Feature Management - Android changelog for any differences.

Class Rox

package io.rollout.android;

class Rox
▼

The Rox class provides your application its primary interface with feature flags in the CloudBees Feature Management system. This is the central repository for your application’s flags, it handles communications with the server to obtain the latest values. It provides a mechanism through which you can use the feature flags to control your application’s behavior. It works with a RoxContainer-derived object, which holds your application’s feature flags. The values contained in the provided RoxContainer will be marked as feature flags and will appear in the dashboard for your application once the application is run.

This class also allows you to manage custom properties. These can be static settings of type string, boolean, integer, or double, or you can use a generator class to provide a custom property that is dependent upon code state. These generated properties must derive from CustomPropertyGenerator, which is a template class.

You can also use a RoxOptions object to configure some aspects of this class. You can set the verbosity level, custom platform, global freeze level, impression handler, fetch handler.

setup

static void setup(Application app)
static void setup(Application app, String rolloutKey)
static void setup(Application app, RoxOptions options)
static void setup(Application application, String rolloutKey, RoxOptions sdkOptions)
▼

Configures the Rox object to work with the provided Android application. Using this method will result in a default verbosity level of VERBOSE_LEVEL_SILENT. If provided, apply the provided RoxOptions object, which can be used to set an increased level of logging verbosity and a callback for the completion of each sync with the server.

Parameters

Parameter Modifier and Type Description

app

Application

An Android application object representing the feature-controlled app to be managed.

options

RoxOptions

A RoxOptions instance with the desired configuration for this application.

rolloutKey

String

An application key that will override the one specified in the manifest.

register

static void register(RoxContainer container)
static void register(String namespace, RoxContainer container)
▼

Registers a feature flag container with the Rox client. The public member variables of this container will become a flag in your CloudBees Feature Management dashboard and will be named with the object name.

Parameters

Parameter Modifier and Type Description

namespace

String

The prefix namespace for all flags in this container. If no namespace is provided, the namespace will default to be an empty string.

container

RoxContainer

An object derived from RoxContainer that contains your application’s feature flags.

For example, assuming we have the following container:

package com.example.pacman;

public class MyContainer implements RoxContainer {
  public RoxString welcomeMessageText = new RoxString("Hello User");
  public RoxFlag enableLogin = new RoxFlag();
}
▼

and we register the container with the following code:

RoxContainer conf = new MyContainer();
Rox.register("Login", conf);
Rox.setup(this.getApplication());
▼

The flag in the dashboard will have the names Login.welcomeMessageText and Login.enableLogin. This is very handy if you want to have groups of flags.

If you don’t need a namespace, you can set the namespace to an empty string.

fetch

static void fetch()
▼

Creates a network request for the latest configuration.

setGlobalContext

static void setGlobalContext(Context context)
▼

Sets the global evaluation context. This context is merged with local one when evaluating flag conditions. Values from local context have precedence over globally set values.

setUserspaceUnhandledErrorHandler

static void setUserspaceUnhandledErrorHandler(UserSpaceExceptionHandler handler)
▼

Sets the global handler for exceptions triggered by user-defined functions like configuration fetched handler, impression handler, dynamic property rule handler, or custom property generator.

void handleUserSpaceException(ExceptionTrigger source, Throwable exception);
▼

Note: exceptions triggered within the exception handler itself aren’t propagated, but just logged.

unfreeze

static void unfreeze()
static void unfreeze(String namespace)
▼

Unfreezes all flags within the given namespace.

Parameter Modifier and Type Description

namespace

String

The flag namespace prefix. If no namespace is provided, the namespace will default to be an empty string.

getOverrides

static FlagOverrides getOverrides()
▼

Returns the current flag overrides.

setCustomComputedBooleanProperty

static void setCustomComputedBooleanProperty(String name, io.rollout.properties.CustomPropertyGenerator<Boolean> generator)
static void setCustomComputedBooleanProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Boolean> generator)
▼

Sets a custom Computed Boolean property on the Rox client. This is a computable boolean, with an object that generates the value for the property. The generator should be derived from the CustomPropertyGenerator template class in rox-java-core.

Parameters

Parameter Modifier and Type Description

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the Boolean property’s generator class.

setCustomComputedDoubleProperty

static void setCustomComputedDoubleProperty(String name, io.rollout.properties.CustomPropertyGenerator<Double> generator)
static void setCustomComputedDoubleProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Boolean> generator)
▼

Sets a custom Computed Double property on the Rox client. This is a computable double, with an object that generates the value for the property. The generator should be derived from the CustomPropertyGenerator template class in rox-java-core.

Parameters

Parameter Modifier and Type Description

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the Double property’s generator class.

setCustomComputedIntegerProperty

static void setCustomComputedIntegerProperty(String name, io.rollout.properties.CustomPropertyGenerator<Integer> generator)
static void setCustomComputedIntegerProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Boolean> generator)
▼

Sets a custom Computed Integer property on the Rox client. This is a computable integer, with an object that generates the value for the property. The generator should be derived from the CustomPropertyGenerator template class in rox-java-core.

Parameters

Parameter Modifier and Type Description

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the Integer property’s generator class.

setCustomComputedSemverProperty

static void setCustomComputedSemverProperty(String name, io.rollout.properties.CustomPropertyGenerator<String> generator)
static void setCustomComputedSemverProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Boolean> generator)
▼

Sets a custom Computed Semantic-versioned String property on the Rox client. This is a computable semantically-versioned string, with an object that generates the value for the property. The generator should be derived from the CustomPropertyGenerator template class in rox-java-core.

Parameters

Parameter Modifier and Type Description

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the string property’s generator class.

setCustomComputedStringProperty

static void setCustomComputedStringProperty(String name, io.rollout.properties.CustomPropertyGenerator<String> generator)
static void setCustomComputedStringProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Boolean> generator)
▼

Sets a custom computed String property on the Rox client. This is a computable string, with an object that generates the value for the property. The generator should be derived from the CustomPropertyGenerator template class in rox-java-core.

Parameters

Parameter Modifier and Type Description

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the string property’s generator class.

setCustomBooleanProperty

static void setCustomBooleanProperty(String name, boolean value)
▼

Sets a custom property representing a boolean value

Parameters

Parameter Modifier and Type Description

name

String

The name of the custom property.

value

boolean

The value for the custom property, as a boolean true or false.

setCustomDoubleProperty

static void setCustomDoubleProperty(String name, double value)
▼

Sets a custom property that can store a specified double value.

Parameters

Parameter Modifier and Type Description

name

String

The property name.

value

double

The value of the property.

setCustomIntegerProperty

static void setCustomIntegerProperty(String name,int value)
▼

Sets a custom property that can store a specified integer value.

Parameters

Parameter Modifier and Type Description

name

String

The property name.

value

int

The value of the property.

setCustomSemverProperty

static void setCustomSemverProperty(String name,String value)
▼

Sets a custom property that uses a Semantic Version as its value. See https://semver.org for more information on Semantic Versioning.

Parameters

Parameter Modifier and Type Description

name

String

The name of the property to create

value

String

The property value, formatted using the rules defined at https://semver.org.

setCustomStringProperty

static void setCustomStringProperty(String name,String value)
▼

Sets a custom string property for the Rox client, which is a string property you can fetch by name.

Parameters

Parameter Modifier and Type Description

name

String

The name of the property to create.

value

String

The property’s value.

shutdown

void shutdown()
▼

This function unregisters all flags and custom properties that were registered before the call to shutdown.

dynamicAPI

static DynamicAPI dynamicAPI()
▼

Retrieve a dynamic API instance that can be used to get flags values (and create flags) from flag names (string)

Interface DynamicAPI

package io.rollout.client;

interface DynamicAPI
▼

DynamicAPI is a facade for a dynamic API that enables creating and getting flag values by their name. The instance is retrieved by calling dynamicAPI function on Rox.

Example

In this example, DynamicAPI is used to get the flag value by passing in context and defaultValue.

Context context = new RoxContext.Builder().from(
  ImmutableMap.of("someKey", "someValue")
);
DynamicAPI dynamic = Rox.dynamicAPI();
boolean flagAEnabled = dynamic.isEnabled("flagA", context, false);
▼

isEnabled (dynamic api)

boolean isEnabled(String flagName, boolean defaultValue)
boolean isEnabled(String flagName, Context context, boolean defaultValue)
▼

Returns true if the flagName is enabled for context, else return defaultValue.

Parameter Modifier and Type Description

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

boolean

If experiment is not set for this flag, return the default value.

value (dynamic api)

String value(String name, String defaultValue)
String value(String name, String defaultValue, Context context)
String value(String name, String defaultValue, String[] variations)
String value(String name, String defaultValue, String[] variations, Context context)
▼

Returns string flag value for the flag flagName.

Parameter Modifier and Type Description

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

String

If experiment is not set for this flag, return the default value.

variations

String[]

Flag values that will be available for selection in the dashboard once the flag is created.

getInt (dynamic api)

int getInt(String name, int defaultValue)
int getInt(String name, int defaultValue, Context context)
int getInt(String name, int defaultValue, int[] variations)
int getInt(String name, int defaultValue, int[] variations, Context context)
▼

Returns integer flag value for the flag flagName.

Parameter Modifier and Type Description

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

int

If experiment is not set for this flag, return the default value.

variations

int[]

Flag values that will be available for selection in the dashboard once the flag is created.

getDouble (dynamic api)

double getDouble(String name, double defaultValue)
double getDouble(String name, double defaultValue, Context context)
double getDouble(String name, double defaultValue, double[] variations)
double getDouble(String name, double defaultValue, double[] variations, Context context)
▼

Returns double flag value for the flag flagName.

Parameter Modifier and Type Description

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

double

If experiment is not set for this flag, return the default value.

variations

double[]

Flag values that will be available for selection in the dashboard once the flag is created.

Class RoxOptions

package io.rollout.client;

class RoxOptions
▼

RoxOptions covers configuration options for the Rox client, including settings such as the verbosity of the logging. Instances of this class should be created using RoxOptions.Builder.

An example of setting up a new RoxOptions object is below. It sets the verbosity level to "Debug", provides an impression handler, a fetch handler, and more.

To use with a proxy server, refer to Using a proxy for more information.

 RoxOptions options = new RoxOptions.Builder()
    .withVerboseLevel(RoxOptions.VerboseLevel.VERBOSE_LEVEL_DEBUG)
    .withPlatform("FireTv")
    .withLogger(logger)
    .withConfigurationFetchedHandler(fetchHandler)
    .withImpressionHandler(impressionHandler)
    .withDynamicPropertyRule(dynamicPropertyRule)
    .withFreeze(Freeze.UntilLaunch)
    .withHosting("eu")
    .withProxy(new ProxyConfig("http://proxy.example.com", "sdkuser", "sdkpassword"))
    .build();
Rox.setup(this, options);
▼

Class RoxOptions.Builder

package io.rollout.android.client;

static class RoxOptions.Builder
▼

This Builder class is used to create a new RoxOptions instance.

build

RoxOptions build()
▼

Builds the RoxOptions object, with the configured options

Returns

a RoxOptions object containing the specified option values

withVerboseLevel

RoxOptions.Builder withVerboseLevel(RoxOptions.VerboseLevel verboseLevel)
▼

Configures the RoxOptions Builder object with the specified VerboseLevel set

Parameters

Parameter Modifier and Type Description

verboseLevel

RoxOptions.VerboseLevel

the verbosity level.

Returns The builder instance

withConfigurationFetchedHandler

RoxOptions.Builder withConfigurationFetchedHandler(ConfigurationFetchedHandler configurationFetchedHandler)
▼

Configures the RoxOptions Builder object with the specified Functor that is called every time the configuration is applied on the client, the configuration can be retrieved from cache, embedded experiments or Network.

Parameters

Parameter Modifier and Type Description

configurationFetchedHandler

ConfigurationFetchedHandler

a Functor instance to be evaluated when configuration is fetched.

Returns The builder instance.

withLogger

RoxOptions.Builder withLogger(Logger logger)
▼

Configures the RoxOptions Builder object with a custom Logger, overrides the default logger logcat.

Parameters

Parameter Modifier and Type Description

logger

Logger

a custom logger instance.

Returns The builder instance.

withFreeze

RoxOptions.Builder withFreeze(Freeze freeze)
▼

Configures the RoxOptions Builder object with the default freeze behavior.

Parameters

Parameter Modifier and Type Description

freeze

Freeze

the default flag freeze level to set unless it was overridden on flag constructor.

Returns The builder instance.

withImpressionHandler

RoxOptions.Builder withImpressionHandler(ImpressionHandler impressionHandler)
▼

Configures the RoxOptions Builder object with the specified Functor that is called every time a flag value gets computed and evaluated on the client.

Parameters

Parameter Modifier and Type Description

impressionHandler

ImpressionHandler

A functor instance to be evaluated when flag is first evaluated.

Returns The builder instance.

withPlatform

RoxOptions.Builder withPlatform(String platform)
▼

Configures the RoxOptions Builder object with a custom platform, any String is applicable here. In practice, custom platform is used to allow easier separation of values to be sent to the client. (e.g. Android Tv, Android Tablet, Tizen).

Parameters

Parameter Modifier and Type Description

platform

String

A custom platform, any String is applicable here. (e.g. Android Tv, Android Tablet, Tizen).

Returns The builder instance.

withDynamicPropertyRule

RoxOptions.Builder withDynamicPropertyRule(DynamicPropertyRule dynamicPropertyRule)
▼

Configures the RoxOptions Builder object with the function that is called every time a condition with property is evaluated and was not configured with any of the setCustomProperty functions

Parameter

Modifier and Type

Description

dynamicPropertyRule

DynamicPropertyRule

A function instance to be invoked when a condition with unknown property is being evaluated.

Returns

The builder instance.

withHosting

RoxOptions.Builder withHosting(String region)
▼

Configures the RoxOptions Builder object with a region of your choice

Parameter

Modifier and Type

Description

region

String

The region to use, supported option: "eu" (any other value will result default, which is us hosting)

Returns

The builder instance.

Interface RoxContainer

package io.rollout.configuration;

interface RoxContainer
▼

The RoxContainer is an abstract class describing a feature flag container for a CloudBees Feature Management-enabled application. The RoxContainer child class for your application will contain all of the feature flags for the features in your application. These static feature flags are converted into CloudBees Feature Management flags when the container is registered with Rox using Rox.register(). Feature flag names will be derived from the provided flag variable names.

Example

Here’s a quick example of how to use this container class:

// File MyContainer.java
class MyContainer implements RoxContainer {
 // This will become a feature flag named "welcomeMessageText"
 public RoxString welcomeMessageText = new RoxString("DefaultValue");
}

// Include this code as early as possible in your program's initialization code
RoxContainer conf = new MyContainer();
// Registers the container, creating relevant flags
Rox.register(conf)
// Performs final setup of the Rox application.
Rox.setup(this.getApplication());
▼

Class RoxEnumFlag

package io.rollout.flags;

class RoxEnumFlag<T extends Enum<T>> implements ClientFlag

public RoxEnumFlag(T defaultValue)
public RoxEnumFlag(T defaultValue, Freeze freeze)
▼

Type Parameters

T - the enumeration to use as the basis for this feature flag.

RoxEnumFlag allows you to define feature flags with multiple options, as opposed to standard RoxFlag objects which can only represent a boolean value. These values are provided in an enumerable way, which allows you to easily use the RoxEnumFlag object in switch statements and other control-flow mechanisms. The Rox Dashboard will also display these enumerable values, providing a user-friendly way to debug your application’s settings. Provide the enumerable object as the template parameter, and the default value as the constructor parameter.

Example

// Define a color enumeration
enum Colors {
  Red, Blue, Green
}
// Create a color feature flag with a default value of Blue
public RoxEnumFlag<Colors> colorFeature = new RoxEnumFlag<>(Colors.Blue);
▼

getName

String getName()
▼

Returns

The feature flag’s name.

getRawFlag

RoxString getRawFlag()
▼

Returns the current RoxString object that represents the flag’s value

Returns

A RoxString object representing the current flag value.

getValue

T getValue()
▼

Returns the current value of this flag. If the value of the flag has been overwritten with a valid value, then the overwritten value is returned. Otherwise, the flag’s default value is returned. Note: a valid value is defined as a value that is a valid member of the enumeration type this flag is based on.

Returns

The current value of this flag.

unfreeze

void unfreeze(Freeze freeze);
▼

Unlock the flag value from changes from the last time it was frozen.

peekCurrentValue

String peekCurrentValue()
▼

Retrieves the current flag value without freeze, and without invoking impression. Used for development only. Avoid using in production environment.

peekCurrentValue

String peekOriginalValue()
▼

Retrieves the original value with no overrides, no freeze, and without invoking impression. Used for development only. Avoid using in production environment.

Class RoxFlag

package io.rollout.flags;

class RoxFlag implements BooleanFeatureFlag, ClientFlag

public RoxFlag()
public RoxFlag(boolean defaultValue)
public RoxFlag(boolean defaultValue, Freeze freeze)
▼

RoxFlag is a boolean feature flag. It can be either true or false.

Working with enabled() and disabled()

The .enabled() and .disabled() methods can be used to define behaviors for each of the possible states of a RoxFlag. For example, you can use the following code to create a RoxFlag with a disabled handler for showing onboarding flows.

roxContainer.myFlag.disabled(() -> {
    // run this code if the feature is disabled
});
▼

The above code defines Java lambda with an anonymous flaggable object with a single method - execute - that runs when the flag is false. This returns the instance of the flag, allowing for chaining the calls together:

roxContainer.myFlag.enabled(() -> {
    // run this code if the feature is enabled
}).disabled(() -> {
    // run this code if the feature is disabled
});
▼

enabled

RoxFlag enabled(io.rollout.flags.Flaggable enabledAction)
RoxFlag enabled(io.rollout.flags.Flaggable enabledAction, Context context)
▼

Executes the provided action if the flag is enabled (i.e. the flag value is true), and otherwise does nothing. Actions using this mechanism need to be derived from the flaggable interface.

enabledAction - A flaggable action to execute if the RoxFlag for the feature is enabled

Returns The relevant instance of RoxFlag (this), allowing for chaining of handlers

disabled

RoxFlag disabled(io.rollout.flags.Flaggable disabledAction)
RoxFlag disabled(io.rollout.flags.Flaggable disabledAction, Context context)
▼

Executes the provided action if the flag is disabled, otherwise does nothing. Actions using this mechanism need to be derived from the flaggable interface.

disabledAction - A flaggable action to execute if the RoxFlag for the feature is disabled.

Returns

The relevant instance of RoxFlag (this), allowing for chaining of handlers.

isEnabled

boolean isEnabled()
boolean isEnabled(Context context)
▼

Returns true if the flag is enabled for context, else return defaultValue.

Returns

boolean

getName

String getName()
▼

Returns

String name of this RoxFlag.

unfreeze

void unfreeze(Freeze freeze);
▼

Unlock the flag value from changes from the last time it was frozen.

peekCurrentValue

String peekCurrentValue()
▼

Retrieves the current flag value without freeze, and without invoking impression. Used for development only. Avoid using in production environment.

peekCurrentValue

String peekOriginalValue()
▼

Retrieves the original value with no overrides, no freeze, and without invoking impression. Used for development only. Avoid using in production environment.

Class RoxString

package io.rollout.flags;

class RoxString implements StringFeatureFlag, ClientFlag

public RoxString(String defaultValue)
public RoxString(String defaultValue, Freeze freeze)
public RoxString(String defaultValue, String[] options)
public RoxString(String defaultValue, String[] options, Freeze freeze)
▼

RoxString is a feature flag object with a value of string type. RoxString accepts a list of possible values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for override via the dashboard. This is similar to the capabilities offered by RoxEnumFlag, with a focus on string enumerations only.

Example

String[] titleColorsOptions = new String[] {"Black", "Blue", "Green"};
RoxString titleColorsVariant = new RoxString("Black", titleColorsOptions);
if (titleColorsVariant.getValue().equals("Black")) {
    // set title color to black
} else if (titleColorsVariant.getValue().equals("Green")) {
    // set title color to green
}
▼

getName

String getName()
▼

Returns

The feature flag’s name.

getValue

String getValue()
String getValue(Context context)
▼

Returns the current value of the feature flag as a String.

unfreeze

void unfreeze(Freeze freeze);
▼

Unlock the flag value from changes from the last time it was frozen.

peekCurrentValue

String peekCurrentValue()
▼

Retrieves the current flag value without freeze, and without invoking impression. Used for development only. Avoid using in production environment.

peekCurrentValue

String peekOriginalValue()
▼

Retrieves the original value with no overrides, no freeze, and without invoking impression. Used for development only. Avoid using in production environment.

Class RoxInt

package io.rollout.flags;

class RoxInt implements IntFeatureFlag, ClientFlag

public RoxInt(int defaultValue)
public RoxInt(int defaultValue, Freeze freeze)
public RoxInt(int defaultValue, int[] variations)
public RoxInt(int defaultValue, int[] variations, Freeze freeze)
▼

RoxInt is a feature flag object with a value of integer type.

Example

RoxInt ageVariant = new RoxInt(25, new int[]{ 20, 25, 30, 35, 40, 45, 55, 65 });
if (ageVariant.getValue() == 25) {
    // action...
}
▼

getName

String getName()
▼

Returns

The feature flag’s name.

getValue

int getValue()
int getValue(Context context)
▼

Returns the current value of the feature flag as an integer.

unfreeze

void unfreeze(Freeze freeze);
▼

Unlock the flag value from changes from the last time it was frozen.

peekCurrentValue

String peekCurrentValue()
▼

Retrieves the current flag value without freeze, and without invoking impression. Used for development only. Avoid using in production environment.

peekCurrentValue

String peekOriginalValue()
▼

Retrieves the original value with no overrides, no freeze, and without invoking impression. Used for development only. Avoid using in production environment.

Class RoxDouble

package io.rollout.flags;

class RoxDouble implements DoubleFeatureFlag, ClientFlag

public RoxDouble(double defaultValue)
public RoxDouble(double defaultValue, Freeze freeze)
public RoxDouble(double defaultValue, double[] variations)
public RoxDouble(double defaultValue, double[] variations, Freeze freeze)
▼

RoxDouble is a feature flag object with a value of double precision type.

Example

RoxDouble doubleVariant = new RoxDouble(1.1, new int[]{ 1.1, 2.2, 3.3 });
if (Double.compare(doubleVariant.getValue(), 2.0) >= 0) {
    // action...
}
▼

getName

String getName()
▼

Returns

The feature flag’s name.

getValue

double getValue()
double getValue(Context context)
▼

Returns the current value of the feature flag as an double.

unfreeze

void unfreeze(Freeze freeze);
▼

Unlock the flag value from changes from the last time it was frozen.

peekCurrentValue

String peekCurrentValue()
▼

Retrieves the current flag value without freeze, and without invoking impression. Used for development only. Avoid using in production environment.

peekCurrentValue

String peekOriginalValue()
▼

Retrieves the original value with no overrides, no freeze, and without invoking impression. Used for development only. Avoid using in production environment.

Class FlagOverrides

Class FlagOverrides is used to override a flag value locally, it is used by developers working on a feature in dev mode and shouldn’t be used in production builds.

When you override an existing flag value using the setOverride method, the SDK will disregard existing configuration coming from the dashboard and will serialize the override on disk this value will be loaded and override the flag right after you call Rox.setup. To clear the override from the cache you need to call the clearOverrides method.

hasOverride

boolean hasOverride(String flagName)
▼

Returns true if a flag has an override.

Parameter Modifier and Type Description

flagName

String

Full flag name including namespace, eg. default.flagName.

setOverride

void setOverride(String flagName, String value)
▼

Sets an override value on a specific flag, this function accepts two parameters flag name (full flag name including namespace) and desired value (from type String).

This function also saves the override value on the local device disk, so it is "remembered" for the next the SDK is loaded to production.

Parameter Modifier and Type Description

flagName

String

Full flag name including namespace, eg. default.flagName.

value

String

The value of a flag, if this is a boolean flag the value should be "true" or "false".

getOverride

String getOverride(String flagName)
▼

Retrieves the overriden value for the flag, if exists. Otherwise returns null.

Parameter Modifier and Type Description

flagName

String

Full flag name including namespace, eg. default.flagName.

clearOverride

void clearOverride(String flagName)
▼

Clears the override value from the flag and the storage.

Parameter Modifier and Type Description

flagName

String

Full flag name including namespace, eg. default.flagName.

clearOverrides

void clearOverrides()
▼

Clears all the override values and empties the overrides storage.

interface Context

package io.rollout.context;

interface Context
▼

The context interface is used to pass data to the flag when checking if the current flag is enabled or disabled. This object is used by the registered custom properties to evaluate the experiment expression and return the flag value.

You can create a context using the context’s Builder and sending a Map in the following format:

Context from(Map<String, Object> map)
▼

Example

Context context = new RoxContext.Builder().from(
  ImmutableMap.of("someKey", "someValue")
);
▼

get

Object get(String key)
▼

This get function is used to retrieve data from the context.

Interface ConfigurationFetchedHandler

package io.rollout.client;

interface ConfigurationFetchedHandler
▼
void onConfigurationFetched(FetcherResults results)
▼

where FetcherResults contains the following information:

Method Description 
FetcherStatus getFetcherStatus()
▼

Fetch status. Can be one of the following: AppliedFromEmbedded - embedded configuration applied; AppliedFromLocalStorage - cached configuration applied; AppliedFromNetwork - remote configuration applied; ErrorFetchedFailed - failed to apply remote configuration.

 
boolean hasChanges()
▼

Whether the configuration has changes compared to the previous fetch result.

 
Date getCreationDate()
▼

Configuration date.

 
FetcherError getErrorDetails()
▼

If status is ErrorFetchedFailed, this method will return error details. Otherwise it will return null.

For an example, see Configuration fetched handler.

Interface ImpressionHandler

package io.rollout.client;

interface ImpressionHandler
▼
void onImpression(io.rollout.flags.ImpressionEvent)
▼

where ImpressionEvent provides the flag name, value, and other impression information:

Method Description 
String getName()
▼

Impression’s flag name.

 
String getValue()
▼

Impression value.

 
boolean isTargeting()
▼

Indicates whether the flag is active or killed.

 
Context getContext()
▼

The context in which the impression was called. This is a merged context. containing the global context, and the call’s context)

For an example, see Impression handler.

DynamicPropertyRule

package io.rollout.properties;

interface DynamicPropertyRule
▼

The functional interface containing the following method:

Object invoke(String propName, Context context)
▼

This method is invoked every time when a condition with an unknown property is being evaluated.

Parameter Modifier and Type Description

propName

String

Property name being evaluated.

context

Context

Context being used for evaluation. Can be null.

Returns

Property evaluation result.

Example

DynamicPropertyRule rule = new DynamicPropertyRule() {
  @Override
  public Object invoke(String propName, Context context) {
    return ((Map<String, String>) context.get("user")).get(propName);
  }
};
▼

Default dynamic property rule

By default, a dynamic property rule is used that retrieves the property value from the evaluation context:

DynamicPropertyRule DEFAULT = new DynamicPropertyRule() {
  @Override
  public Object invoke(String propName, Context context) {
    return context != null ? context.get(propName) : null;
  }
};
▼
SDKs API reference
C API