Rollout.io - Documentation

Nodejs API

The Rox object is the main class to be used when registering your application's feature flags with Rollout. Simply define a set of Rox.Flag(), Rox.Configuration(), and Rox.Variant() objects, and supply these to Rox.register() to connect them with your application. Once this is done, provide your app key (from the Rollout 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.Configuration, and Rox.Variant 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 usualy be in a different module|file
const DemoContainer = {
 sayHello: new Rox.Flag(),
 flagA: new Rox.Flag(),
 colorsVariant: new Rox.Variant('red', ['green', 'blue']),
 textColor: new Rox.Configuration('black')
};

// register the container, this lets Rollout 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)

Parameters

Parameter
Type
Description

defaultValue

boolean:= false

Initial state of the flag

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

Parameters

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 :boolean - Returns true when the flag is enabled

Variant

Rox.Variant is used to create and manage Rollout feature flags that determine different predefined values

Example:

The following code constructs some simple Rox.Variant objects, which can be used to have a flag with values more complex than Rox.Flag

colorsVariant: new Rox.Variant('red', ['green', 'blue', 'red']);
languageVariant: new Rox.Variant('english', ['english', 'spanish', 'german']);

Constructor

new Variant(defaultValue, options, name)
Sets the name, default value, and options for this variant instance
Parameters

Parameter
Type
Description

defaultValue

String

The default value for this feature flag

options

Array<String>

The domain of possible values for this flag

name

String

The Name of this flag

Return Value
none

name

Return Value
Type :string - returns the name of this flag

getValue(context):string

Returns the current value of the Variant, 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

Return Value
Type: string - the current value of this Variant object

Configuration

Rox.Configuration manages a remote configuration setting with a value of type string, boolean, or number. The constructor sets the default value for the remote configuration setting

Example:

The following code constructs a simple Rox.Configuration object.

welcomeMessageConfig: new Rox.Configuration('Welcome to my application');

Constructor

new Configuration(defaultValue)

Parameter
Type
Description

defaultValue

string | boolean | number

The default configuration value

name

Return Value
Type :string - returns the name of this flag

getValue(context):string | boolean | number

Parameter
Type
Description

context

Object

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

Return Value
Type : string | boolean | number - the remote configuration settings value

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);

Parameters

Parameter
Type
Description

appKey

String

application key as appears in Rox dashboard

options

Object

configuration object (optional)

Options

Parameter
Type
Description

version

String

javascript client version

configurationFetchedHandler

Function

function that is called after data was synced from Rollout backend

debugLevel

String

SDK verbosity level, accept 'verbose' level

impressionHandler

Function

funciton that is called every time the a flag value gets computed and evaluated on the client

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

Return Value
Promise that gets executed once the configuration was retrieved from Rollout backend servers

register

(static) register(name, container)
Register a container of Rox entities by specifying a namespace.

Parameters

Parameter
Type
Description

name

String

Container name

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

Parameters

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

Parameters

Parameter
Type
Description

key

String

The name of the custom property

value

String | Function

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

// retriving 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.

Parameters

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)

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

Parameters

Parameter
Type
Description

key

String

The name of the custom property

value

Number | Function

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

// Calulating 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 Rollout servers

showOverrides

(static) showOverrides(position [optional])
Rox.showOverrides Opens the flag override view, providing a debug UI for the application's set of feature flags.

Parameters

Parameter
Type
Description

position

String

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

Using the impressionHandler option

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

Example

function impressionHandler(reporting, experiment, context) {}

see also Impression Handler

  • First parameter is an object with:

    • name - flag's name
    • value - flag's value
  • Second parameter is an object with the experiment info:

    • identifier - experiment id
    • name - experiment name
    • isArchived - whether the experiment is archived
    • labels - experiment's labels. assigned from dashboard
  • The last parameter is the context which the call used (global context merged with the calls' context)

Nodejs API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.