Node.js API

The Rox object is the main class to be used when registering your application’s feature flags with CloudBees Feature Management. Simply define a set of Rox.Flag(), Rox.RoxNumber(), and Rox.RoxString() objects, and supply these to Rox.register() to connect them with your application. Once this is done, provide your app key (from the CloudBees Feature Management dashboard) and configured options, and your feature flags are ready to use!

Example

To use the Rox object, you’ll first need to 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, simply call setup with the correct API key and options set.

Registering a container

// 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 {PRODUCT} knows about the flags and they can be configured in the dashboard
Rox.register('DemoApp', DemoContainer);

Classes

Flag

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

Example

To use the Rox.Flag object, simply declare it within a flag container as you would any other member:

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

Constructor

new Flag(defaultValue)

Parameter Type Description

Parameter	Type	Description
`defaultValue`	`boolean:= false`	Initial state of the flag
`options`	`Object`	additional options - adjust the freeze level with: { freeze: 'none'/'untilLaunch' } default is 'none'

defaultValue

boolean:= false

Initial state of the flag

options

Object

additional options - adjust the freeze level with: { freeze: 'none'/'untilLaunch' } default is 'none'

Return Value

none

name

Return Value

Type :string - returns the name of this flag

isEnabled()

Return Value

Type :boolean - returns true when the flag is enabled

isEnabled(context):boolean

Parameter Type Description

Parameter	Type	Description
`context`	`Object`	object to be merged with the global context, the context is used when calculating the custom properties

context

Object

object to be merged with the global context, the context is used when calculating the custom properties

Return Value

Type :boolean - Returns true when the flag is enabled

Rox.RoxString

Rox.RoxString is used to create and manage CloudBees Feature Management that determine different predefined string values.

Example

The following code constructs some simple Rox.RoxString objects, which can be used to have a flag 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

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' } default is 'none'

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' } default is 'none'

Return Value

none

name

Return Value

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

getValue(context):string

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

Parameter Type Description

Parameter	Type	Description
`context`	`Object`	object to be merged with the global context, the context is used when calculating the custom

context

Object

object to be merged with the global context, the context is used when calculating the custom

Return Value

Type: string - the current value of this RoxString object

Rox.RoxNumber

Rox.RoxNumber is used to create and manage CloudBees Feature Management that determine different predefined number values.

Example

The following code constructs some simple Rox.RoxNumber objects, which can be used to have a flag with string 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

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' } default is 'none'

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' } default is 'none'

Return Value

none

name

Return Value

Type :string - returns the name of this flag (the name will be set only after register, 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

ROX Methods

setup

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

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

Example

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

Parameter Type Description

Parameter	Type	Description
`appKey`	`String`	application key as appears in Rox dashboard
`options`	`Object`	configuration object (optional)

appKey

String

application key as appears in Rox dashboard

options

Object

configuration object (optional)

Options

Parameter Type Description

Parameter	Type	Description
`version`	`String`	javascript client version
`configurationFetchedHandler`	`Function`	function that is called after data was synced from the CloudBees Feature Management backend
`debugLevel`	`String`	SDK verbosity level, accept 'verbose' level
`impressionHandler`	`Function`	function that is called every time the a flag value gets computed and evaluated on the client (if flag has override, or already frozen, no impression handler will be triggered)
`platform`	`String`	custom platform, for cases you want to override the default platform (`Browser`), for platforms like tizen, chromecast, etc..
`fetchIntervalInSec`	`Number`	configure the interval of fetch configuration call. The default value is 60s and the minimum is 30s
`dynamicPropertyRuleHandler`	`Function`	Function that is called every time a condition with property is evaluated and was not configured with any of the setCustomProperty functions
`hosting`	`String`	Customizes the region of your data No default, indicating the US (Dashboard at app.rollout.io) Possible value: eu (Dashboard at eu-app.rollout.io)
`Proxy`	`Object`	All SDK network calls go to a proxy, which will then call CloudBees Feature Management servers. No default, indicating that all network calls go to CloudBees Feature Management server endpoints. Object structure: { protocol: <protocol>, host: <host>, port: <port>, auth: { username: <username>, password: <password>}}. The authorization is Basic Http authentication. You will need to use a proxy. Refer to https://hub.docker.com/r/picoded/http-simple-proxy for more information.

version

String

javascript client version

configurationFetchedHandler

Function

function that is called after data was synced from the CloudBees Feature Management backend

debugLevel

String

SDK verbosity level, accept 'verbose' level

impressionHandler

Function

function that is called every time the a flag value gets computed and evaluated on the client (if flag has override, or already frozen, no impression handler will be triggered)

platform

String

custom platform, for cases you want to override the default platform (Browser), for platforms like tizen, chromecast, etc..

fetchIntervalInSec

Number

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

dynamicPropertyRuleHandler

Function

Function that is called every time a condition with property is evaluated and was not configured with any of the setCustomProperty functions

hosting

String

Customizes the region of your data No default, indicating the US (Dashboard at app.rollout.io) Possible value: eu (Dashboard at eu-app.rollout.io)

Proxy

Object

All SDK network calls go to a proxy, which will then call CloudBees Feature Management servers. No default, indicating that all network calls go to CloudBees Feature Management server endpoints. Object structure: { protocol: <protocol>, host: <host>, port: <port>, auth: { username: <username>, password: <password>}}. The authorization is Basic Http authentication. You will need to use a proxy. Refer to https://hub.docker.com/r/picoded/http-simple-proxy for more information.

Return Value

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

register

(static) register(namespace, container)

alternatively: register(container) - this will set the namespace to an empty string.

Parameter Type Description

Parameter	Type	Description
`namespace`	`String`	Container name, default: ''
`container`	`Object`	Object literal whose properties are Rox entities

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 will include static identifiers that do not change in the lifetime of the app.

Parameter Type Description

Parameter	Type	Description
`context`	`Object`	The context object

context

Object

The context object

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

setCustomStringProperty

(static) setCustomStringProperty(key, value)

Sets a custom property value that can be used when creating target groups.

Parameter Type Description

Parameter	Type	Description
`key`	`String`	The name of the custom property
`value`	`String	Function`

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 that can be used when creating target groups.

Parameter Type Description

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 retrieve a value (see example)

key

String

The name of the custom property

value

Boolean

The value of the custom property, or a function that accepts context and retrieve a value (see example)

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

setCustomNumberProperty

(static) setCustomNumberProperty(key, value)

Sets a custom property value that can be used when creating target groups.

Parameter Type Description

Parameter	Type	Description
`key`	`String`	The name of the custom property
`value`	`Number	Function`

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 might help you debug and understand unexpected flag values. In case this function is not set, errors will be logged to the logger. Note: it is recommended to use try-catch on user functions in order to handle it while in the relevant context, and 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 generator

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

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 will then activate the default function which tries to extract the property value from the context by its name.

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

Parameter Type Description

Parameter	Type	Description
`handler`	`(propName, context) ⇒ value`	The function to be called when the SDK is looking for a property that was not explicitly set by the setCustom`Type`Property functions

handler

(propName, context) ⇒ value

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

Rox.dynamicApi

An alternative of using container with register. This allows you to evaluate flags without having a static container. DynamicApi will create flags as if they were registered, including sending them to the dashboard.

Refer to Dynamic api for more details.

isEnabled

Evaluate a boolean flag

(static) isEnabled(name, defaultValue, context)

name

type

description

name

string

the flag’s name - throws an error if not a string

defaultValue

boolean

the default value to use if no dashboard configurations or value was set to default on dashboard; throws an error if not a boolean

context

Object

a context to evalute the flag with, will be merged with the global context

value

Evaluate a string flag

(static) value(name, defaultValue, variations, context)

name

type

description

name

string

the flag’s name - throws an error if not a string

defaultValue

number

the default value to use if there is no dashboard configurations or if the value was set to default on dashboard; throws an error if not a string

variations

Array<string>

all alternative values to use on the dashboard (can be changed on the dashboard side)

context

Object

a context to evalute the flag with, will be merged with the global context

getNumber

Evaluate a number flag

(static) getNumber(name, defaultValue, variations, context)

name	type	description
name	string	the flag’s name - throws an error if not a string
defaultValue	number	the default value to use if there is no dashboard configurations or if the value was set to default on dashboard; throws an error if not a number
variations	Array<number>	all alternative values to use on the dashboard (can be changed on the dashboard side)
context	Object	a context to evalute the flag with, will be merged with the global context

name

type

description

name

string

the flag’s name - throws an error if not a string

defaultValue

number

the default value to use if there is no dashboard configurations or if the value was set to default on dashboard; throws an error if not a number

variations

Array<number>

all alternative values to use on the dashboard (can be changed on the dashboard side)

context

Object

a context to evalute the flag with, will be merged with the global context