JavaScript (browser) SDK reference

8 minute readReference

The following information is for the latest SDK version (6.x). The CloudBees platform requires that your installed SDK version be at least 6.x. Please install the latest SDK by following the instructions in the platform UI or in the SDK installation documentation.

Any updates to version 6.x are noted in the platform changelog.

The Rox object is the main class to be used when registering your application’s feature flags in the platform. Define a set of Rox.Flag(), Rox.RoxNumber(), or Rox.RoxString() objects, and supply these to Rox.register() to connect them with your application. Then provide your app key from the platform UI and configured options, and your feature flags are ready to use.

To use the Rox object, you must specify a feature flag container. This defines a set of Rox.Flag, Rox.RoxNumber, and Rox.RoxString objects that can be used to control the features of your application. Once the flags have been defined, call the setup with the correct API key and options set.

Register a container

Use as in the following example:

// demoContainer.js
   module.exports = {
     sayHello: new Rox.Flag(),
     flagA: new Rox.Flag(),
     colorsVariant: new Rox.RoxString('red', ['green', 'blue']),
     sizeVariant: new Rox.RoxNumber(14, [24, 40])
   }

// Main application file
   import DemoContainer from './demoContainer';
   Rox.register('ApplicationFeatures', DemoContainer);
▼

Set up the object

Configures the CloudBees platform to work with the application.

const options = {
    version: '1.0.0',
};
Rox.setup(APP_KEY, options);
▼
Parameter Modifier and type Description

APP_KEY

string

The environment-specific SDK key provided by the platform UI.

options

options

The desired configuration for this application.

Rox.Flag

Creates a new Rox.Flag (default: false).

To use the Rox.Flag object, declare it within a flag container as follows:

export default {
   displayWelcome: new Rox.Flag(),
   requireCaptcha: new Rox.Flag(),
}
▼

Constructor

Return value is none.

new Flag(defaultValue)
▼
Parameter Type Description

defaultValue

boolean:= false

Initial state of the flag

options

Object

Additional options: Adjust the freeze level with { freeze: 'none'/'untilLaunch' }. The default is 'none'.

name

Returns the name of this flag.

isEnabled()

Returns true when the flag is enabled.

unfreeze()

Unfreezes all flags, and using a flag returns its most updated value.

Rox.RoxString

Rox.RoxString is a feature flag object that accepts a list of possible string values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI.

The following code constructs some simple Rox.RoxString objects, which can be used to have a flag with string values.

export default {
     colorsVariant: new Rox.RoxString('red', ['green', 'blue', 'red']),
     languageVariant: new Rox.RoxString('english', ['english', 'spanish', 'german'])
}
▼

Constructor

new RoxString(defaultValue, variations)
▼

Sets the default value and variations for this RoxString instance.

Parameter Type Description

defaultValue

String

The default value for this feature flag

variations

Array<String>

The domain of possible values for this flag

options

Object

Additional options: Adjust the freeze level with { freeze: 'none'/'untilLaunch' }. The default is 'none'.

The return value is none.

name

Returns the name of this flag (the name is set only after register, or a dynamicApi call).

getValue()

Returns the current value of the RoxString, accounting for value overrides.

unfreeze()

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

Rox.RoxNumber

Rox.RoxNumber is a feature flag object that accepts a list of possible number values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI.

The following code constructs some simple Rox.RoxNumber objects:

export default {
     sizeVariant: new Rox.RoxNumber(12, [24, 40, 84]),
     thresholdVariant: new Rox.RoxNumber(10, [100, 10000])
}
▼

Constructor

new RoxNumber(defaultValue, variations, options)
▼

Sets the default value and variations for this RoxNumber instance.

Parameter Type Description

defaultValue

Number

The default value for this feature flag

variations

Array<Number>

The domain of possible values for this flag

options

Object

Additional options: Adjust the freeze level with { freeze: 'none'/'untilLaunch' }. The default is 'none'.

The return value is none.

name

Returns the name of this flag (the name is set only after register, or a dynamicApi call).

getValue()

Returns the current number value of the RoxNumber object, accounting for value overrides.

unfreeze()

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

Rox.overrides

Rox.overrides overrides a flag value on localhost. It must be used in dev mode, not in production builds.

The base API is used to show the flag update flow. It is usually not required to invoke this API directly on platforms that do not support the flag view (rox-react-native).

When you override an existing flag value using the Rox.overrides.setOverride method, the SDK disregards the existing configuration coming from the UI and serializes the override on disk. This value is loaded and overrides the flag directly after you call Rox.setup. Call the Rox.overrides.clearOverride method to clear the override from the cache.

Rox.overrides.setOverride

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, which is recalled the next time the SDK is loaded to production.

Parameter Type Description

flagName

String

Full flag name including namespace, for example, default.flagName.

value

String

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

Rox.overrides.clearOverride

Clears the override value from the flag (and the disk). After calling the setOverride function, the override value is serialized on the disk. This function is used to clear the override value.

Parameter Type Description

flagName

String

Full flag name including namespace, for example, default.flagName.

Rox.overrides.hasOverride

Returns type Boolean true if a flag has an override.

Parameter Type Description

flagName

String

Full flag name including namespace, for example, default.flagName.

Rox methods

A list of Rox methods follows.

setup

Initiate connection for the application identified by the environment-specific SDK key from the platform UI. The registered containers are synced and the platform gets the appropriate values.

(static) setup(appKey, options [optional])
▼

Use as in the following example:

Rox.register('', container);
const configurationFetchedHandler = fetcherResults => {
  console.log(fetcherResults);
};

const impressionHandler = (reportingValue, context) => {
  console.log('flag impression', reportingValue, context);
};

const options = {
  version: '2.0.0',
  debugLevel: 'verbose',
  configurationFetchedHandler: configurationFetchedHandler,
  impressionHandler: impressionHandler,
  freeze: 'none',
  dynamicPropertyRuleHandler: dynamicPropertyRuleHandler
};

Rox.setup(APP_KEY, options);
▼
Parameter Type Description

appKey

String

environment-specific SDK key (from UI)

options

Object

configuration object (optional)

options

Parameter Type Description

version

String

JavaScript client version

configurationFetchedHandler

Function

Function that is called after data is synced from the platform.

debugLevel

String

SDK verbosity level, accept verbose level

impressionHandler

Function

Function that is called every time a flag value is computed and evaluated on the client. If a flag has an override or is already frozen, no impression handler is triggered.

platform

String

Custom platform, used when you want to override the default platform. (Browser, for platforms like Tizen, Chromecast, etc.)

freeze

String ('untilLaunch' | 'none')

The default freeze level to set a flag, unless it is overridden on the flag constructor. The default is 'none'.

logger

A custom logger object

Overrides the default logger. For example, to override the default log.error behavior, add the following code: options.logger = { error: (m) → console.log(m) }

dynamicPropertyRuleHandler

Function

Function that is called every time a condition with a property is evaluated, and is not previously configured with any setCustomProperty functions.

Proxy

Object

All SDK network calls go to a proxy, which calls the platform servers. No default, indicating that all network calls go to the server endpoints.

Proxy Object structure: {
  protocol: <protocol - string ex:"http"/"https">,
  host: <host - url>,
  port: <port - valid port number>,
  auth: {
    username: <username - string>,
    password: <password - string>
  }
}
▼

The return value is the promise that is executed once the configuration is retrieved from the platform.

register

Register a container of Rox entities by specifying a namespace.

(static) register(namespace, container)
▼

Register a container of Rox entities and set the namespace to an empty string.

(static) register(container)
▼
Parameter Type Description

namespace

String

Container namespace. Default is ''.

container

Object

Object literal whose properties are Rox entities.

setCustomBooleanProperty

Sets a custom property value for use when creating target groups.

(static) setCustomBooleanProperty(key, value)
▼
Parameter Type Description

key

String

The name of the custom property.

value

Boolean

The value of the custom property, or a function that retrieves a value.

 
// Check if a user has the tester role via a function
Rox.setCustomBooleanProperty("tester", function(){
   return user.getInstance().isTester();
});
▼

setCustomNumberProperty

Sets a custom property value for use when creating target groups.

(static) setCustomNumberProperty(key, value)
▼
Parameter Type Description

key

String

The name of the custom property.

value

Number or a function

The value of the custom property, or a function that retrieves a value.

 
// Calculates the user's age via a function
Rox.setCustomNumberProperty("age", function(){
   return user.getInstance().getAge();
});
▼

setCustomStringProperty

Sets a custom property value for use when creating target groups.

(static) setCustomNumberProperty(key, value)
▼
Parameter Type Description

key

String

The name of the custom property.

value

String or function

The value of the custom property, or a function that retrieves a value.

 
// Retriving user email via a function
Rox.setCustomStringProperty("email", function(){
   return user.getInstance().email();
});
▼

fetch

Fetch() pulls the latest configuration and flag values down from the platform.

(static) fetch()
▼

showOverrides

(static) showOverrides(position [optional])
▼

Rox.showOverrides opens the flag override view, providing a debug UI for the application’s set of feature flags.

Parameter Type Description

position

String

Position for the debug menu. The possible values are 'top left', 'top right', 'bottom left', and 'bottom right'.

unfreeze

Unfreezes the state of all flags in code.

Calling this function unfreezes all flags, and using a flag returns its most updated value.

(static) unfreeze(namespace)
▼
Parameter Type Description

namespace

String

Namespace from which to unfreeze flags and configuration. If none specified, the function affects all namespaces.

setUserspaceUnhandledErrorHandler

Use this handler for all user function errors, to help debug and understand unexpected flag values. If this function is not set, errors are logged to the logger.

CloudBees recommends that you use try-catch on user functions, in order to handle them in the relevant context, and not afterward. 
function setUserspaceUnhandledErrorHandler(exceptionTrigger, error)
▼
Name Type Description

exceptionTrigger

String

Indicates which user function raised the error. Must be one of the following values:

  • "DYNAMIC_PROPERTIES_RULE": dynamicPropertyRuleHandler

  • "CONFIGURATION_FETCHED_HANDLER": configurationFetchedHandler

  • "IMPRESSION_HANDLER": impressionHandler

  • "CUSTOM_PROPERTY_GENERATOR": setCustomXXXProperty, any of the custom property generators.

error

Error

The original error from the user code.

Using the impressionHandler option

The impressionHandler function has two useful parameters which can help you decide on further actions.

function impressionHandler(reporting, context) {}
▼

  • reporting is an object describing:

    • Flag name

    • Flag value

    • Flag targeting, and whether evaluation is result of configuration in the UI or is default.

  • context is the context passed to the flag evaluation function. Undefined if no context used.

configurationFetchedHandler

configurationFetchedHandler function is called with one argument from type FetcherResults.

function configurationFetchedHandler(fetcherResult){}
▼

The FetcherResults instance has the following properties:

Name Type Description

fetcherStatus

String

Indicates the source of the applied data, and is one of the following values:

  • "APPLIED_FROM_EMBEDDED": Data source is embedded inside the HTML.

  • "APPLIED_FROM_CACHE": Data source is from local storage cache.

  • "APPLIED_FROM_NETWORK": Data source is network.

  • "ERROR_FETCH_FAILED": Data is not received correctly.

creationDate

Date

The time this data was created and signed in the CloudBees platform.

hasChanges

Boolean

True if this data is not already available on the client.

errorDetails

String

Error string in the case of an error.

dynamicPropertyRuleHandler

The dynamic custom property generator is called when an explicit custom property definition does not exist on the client side.

If you do not set the dynamicPropertyRuleHandler, it activates the default function, which tries to extract the property value from the context by its name.

function dynamicPropertyRuleHandler(propName, context){}
▼
(propName, context) => context ? context[propName] : undefined
▼
Parameter Type Description

handler

(propName, context) ⇒ value

The function to be called when the SDK searches for a property not explicitly set by the setCustom`Type`Property functions.

Rox.dynamicApi

An alternative to using a container and registering. This allows you to evaluate flags without having a static container. DynamicApi creates flags as if they were registered, including sending them to the UI.

isEnabled

Evaluate a Boolean flag.

(static) isEnabled(name, defaultValue, context)
▼
Name Type Description

name

String

The flag name. Returns an error if not a string.

defaultValue

Boolean

The default value to use if there are no UI configurations, or if the value is set to default in the UI. Returns an error if not a Boolean.

context

Object

A context to evaluate the flag with. It is merged with the global context.

value

Evaluate a string flag.

(static) value(name, defaultValue, variations, context)
▼
Name Type Description

name

String

The flag name. Returns an error if not a string.

defaultValue

String

The default value to use if there are no UI configurations, or if the value is set to default in the UI. Returns an error if not a string.

variations

Array<string>

All alternative values, can be used in and updated in the UI.

context

Object

A context to evaluate the flag with. It is merged with the global context.

getNumber

Evaluate a number flag.

(static) getNumber(name, defaultValue, variations, context)
▼
Name Type Description

name

String

The flag name. Returns an error if not a string.

defaultValue

Number

The default value to use if there are no UI configurations, or if the value is set to default in the UI. Returns an error if not a number.

variations

Array<number>

All alternative values, can be used in and updated in the UI.

context

Object

A context to evaluate the flag with. It is merged with the global context.
C++ Client
JavaScript SSR