Node.js API

7 minute readReference

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

The Rox object is the main class to be used when registering your application’s feature flags with CloudBees Feature Management. 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 CloudBees Feature Management UI) and configured options, and your feature flags are ready to use.

To use the Rox object, 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 setup with the correct API key and options set.

Register a container as follows:

// create a flags and configuration container (should usually be in a different module|file)
const DemoContainer = {
 sayHello: new Rox.Flag(),
 flagA: new Rox.Flag(),
 colorsVariant: new Rox.RoxString('red', ['green', 'blue']),
 sizeVariant: new Rox.RoxNumber(14, [24, 40])
};

// register the container. This lets CloudBees Feature Management know about the flags so they can be configured in the UI.
Rox.register('DemoApp', DemoContainer);

Classes

A list of classes for the Node.js API follows.

Flag

The Flag class creates a new Rox.Flag (default: false).

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

displayWelcome: new Rox.Flag();
// requireCaptcha flag default value is set to true
requireCaptcha: new Rox.Flag(true);

Constructor

new Flag(defaultValue)
Parameter Type Description

defaultValue

boolean:= false

Initial state of the flag

options

Object

Additional options: you can adjust the freeze level with { freeze: 'none'/'untilLaunch' } (default is 'none').

Return value

none

name

Type :string - returns the name of this flag

isEnabled()

Type :boolean - returns true when the flag is enabled

isEnabled(context):boolean

Parameter Type Description

context

Object

Object to be merged with the global context. The context is used when calculating the custom properties.

Type :boolean - Returns true when the flag is enabled

Rox.RoxString

Rox.RoxString is used to determine different predefined string values in CloudBees Feature Management.

The following code constructs some simple Rox.RoxString objects, for flags with values more complex than Rox.Flag.

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: you can adjust the freeze level with { freeze: 'none'/'untilLaunch' } (default is 'none').

Return value

none

name

Type :string - returns the name of this flag (the name will be set only after registered, or a dynamicApi call).

getValue(context):string

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

Parameter Type Description

context

Object

Object to be merged with the global context. The context is used when calculating the custom properties.

Return value

Type: string - the current value of this RoxString object

Rox.RoxNumber

Rox.RoxNumber is used to determine different predefined number values in CloudBees Feature Management.

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

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: you can adjust the freeze level with { freeze: 'none'/'untilLaunch' } (default is 'none').

Return value

none

name

Type :string - returns the name of this flag (the name will be set only after registered, or a dynamicApi call).

getValue()

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

Return value

Type: number - the current value of this RoxNumber object

Methods

A list of ROX methods for the Node.js API follows.

setup

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

Initiate connection with Rox servers for the application identified by the application key. The registered containers are synced and Rox entities get the appropriate values.

Rox.register('', container);
const options = {
  version: '2.0.0'
};
Rox.setup('76aea5dd656a254d125c2a19',options);
Parameter Type Description

appKey

String

Application key as appears in the CloudBees Feature Management UI.

options

Object

Configuration object (optional).

Options

Parameter Type Description

version

String

javascript client version

configurationFetchedHandler

Function

Function called after data is synced from the CloudBees Feature Management backend.

debugLevel

String

SDK verbosity level, accept 'verbose' level.

impressionHandler

Function

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

platform

String

For overriding the default platform (Browser), such as for tizen or chromecast platforms.

fetchIntervalInSec

Number

Configures the interval of the fetch configuration call. The default value is 60s and the minimum is 30s.

dynamicPropertyRuleHandler

Function

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

hosting

String

Customizes the region of your data. No default, indicating the US (UI at app.rollout.io).

Proxy

Object

All SDK network calls go to a proxy, which calls CloudBees Feature Management servers. No default, indicating that all network calls go to CloudBees Feature Management 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>
  }
}

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

Return value

Promise that gets executed once the configuration is retrieved from the CloudBees Feature Management backend servers.

register

(static) register(namespace, container)

Register a container of Rox entities by specifying a namespace.

Alternatively: register(container) - this sets the namespace to an empty string.

Parameter Type Description

namespace

String

Container name, default: ''

container

Object

Object literal whose properties are Rox entities

setContext

(static) setContext(context)

Sets the global context of the SDK. The context is used when evaluating custom properties. A typical global context includes static identifiers that do not change in the lifetime of the app.

Parameter Type Description

context

Object

The context object

 
Rox.setContext({
  role: "api",
  hostname: "Hello Kiti"
})

setCustomStringProperty

(static) setCustomStringProperty(key, value)

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

Parameter Type Description

key

String

The name of the custom property

value

`String

Function`

 
// retrieving user email via a function and context
Rox.setCustomStringProperty("role", function(context){
   return context.role;
});

setCustomBooleanProperty

(static) setCustomBooleanProperty(key, value)

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

Parameter Type Description

key

String

The name of the custom property

value

Boolean

The value of the custom property, or a function that accepts context and retrieves a value (refer to the example below).

 
// Checking if the user is a tester via a function and context
Rox.setCustomBooleanProperty("tester", function(context){
   return context.user.isTester();
});

setCustomNumberProperty

(static) setCustomNumberProperty(key, value)

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

Parameter Type Description

key

String

The name of the custom property

value

`Number

Function`

 
// Calculating the age of the user via a function and context
Rox.setCustomNumberProperty("age", function(context){
   return context.user.getAge();
});

fetch

(static) fetch()

Fetch() pulls the latest configuration and flag values from CloudBees Feature Management servers.

setUserspaceUnhandledErrorHandler

A handler for all user function errors, which can help you debug and understand unexpected flag values. In case this function is not set, errors will be logged to the logger.

CloudBees Feature Management recommends using try-catch on a user function to handle it while in the relevant context, not afterward. 
function setUserspaceUnhandledErrorHandler(exceptionTrigger, error)
Name Type Description

exceptionTrigger

string

Indicates which user function raised the error.

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) {}

Refer to Impression handler for more information.

  • The first parameter is an object with:

    • name - flag name

    • value - flag value

    • targeting - flag targeting: true/false

  • The second parameter is the context of the call (global context merged with the calls' context, may be undefined if no context was used)

dynamicPropertyRuleHandler

function dynamicPropertyRuleHandler(propName, context){}

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 name.

(propName, context) => context ? context[propName] : undefined
Parameter Type Description

handler

(propName, context) ⇒ value

The function is called when the SDK is looking for a property not explicitly set by the setCustom`Type`Property functions.

Rox.dynamicApi

An alternative to using a container with register. You can evaluate flags without having a static container. DynamicApi creates flags as if they were registered, including sending them to the UI.

Refer to Dynamic api for more details.

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; it throws 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 - throws 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 string.

variations

Array<string>

All alternative values to use in the UI (can be changed 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 numeric value.

variations

Array<number>

All alternative values to use in the UI (can be changed in the UI).

context

Object

A context to evaluate the flag with. It is merged with the global context.
JavaScript SSR API
Objective-C API