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
Flag()
, Configuration()
, and Variant()
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 Flag
, Configuration
, and Variant
objects that can be used to control the features of your application.
Once the flags have been defined, simply call the setup with the correct API
key and options set.
Registering a container
import {Configuration, Flag, Variant, Rox} from 'rox-ssr';
// create a flags and configuration container should usualy be in a different module|file
const DemoContainer = {
sayHello: new Flag(),
flagA: new Flag(),
colorsVariant: new Variant('red', ['green', 'blue']),
textColor: new Configuration('black')
};
// register the container, this lets {PRODUCT} knows about the flags and they can be configured in the dashboard
Rox.register('DemoApp', DemoContainer);
Classes
Constructor
new Flag(defaultValue)
Parameter | Type | Description |
---|---|---|
|
|
Initial state of the flag |
Return Value
none
Variant
Variant is used to create and manage feature flags that determine different predefined values.
Constructor
new Variant(defaultValue, options, name)
Sets the name, default value, and options for this variant instance.
Parameter | Type | Description |
---|---|---|
|
|
The default value for this feature flag |
|
|
The domain of possible values for this flag |
|
|
The name of this flag |
Return Value
none
getValue(context):string
Returns the current value of the Variant, accounting for value overrides.
Parameter | Type | Description |
---|---|---|
|
|
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
Constructor
new Configuration(defaultValue)
Parameter | Type | Description |
---|---|---|
|
`string |
boolean |
getValue(context):string | boolean | number
Parameter | Type | Description |
---|---|---|
|
|
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.overrides
Rox.overrides is used to override a flag value on localhost, it is used by developers working on a feature in dev mode and shouldn’t be used in production builds.
It is the base API that is used to show the Flag update flow.
When you override an existing flag value using the
Rox.overrides.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 Rox.overrides.clearOverride
method.
Rox.overrides.setOverride
Sets an override value on a specific flag, this function accepts two parameters flag name (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 when the next SDK is loaded to production.
Parameter | Type | Description |
---|---|---|
flagName |
String |
full flag name including namespace, eg.
|
value |
String |
The value of a flag, if this is a boolean flag the value
should be |
Rox.overrides.clearOverride
Clears the override value from the flag (and the disk).
After calling setOverride
function the override value is serialized on
the disk, this function is used to clear this override value.
Parameter | Type | Description |
---|---|---|
flagName |
String |
full flag name including namespace, eg.
|
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
import {Rox} from 'rox-ssr';
Rox.register('', container);
const options = {
version: '2.0.0'
};
Rox.setup('76aea5dd656a254d125c2a19',options);
Parameter | Type | Description |
---|---|---|
|
|
application key as appears in Rox dashboard |
|
|
configuration object (optional) |
Options
Parameter | Type | Description |
---|---|---|
|
|
javascript client version |
|
|
function that is called after data was synced from the CloudBees Feature Management backend |
|
|
SDK verbosity level, accept 'verbose' level |
|
|
function that is called every time a flag value gets computed and evaluated on the client |
|
|
custom platform; for cases where you want to override
the default platform ( |
|
|
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 the CloudBees Feature Management backend servers.
register
(static) register(name, container)
Register a container of Rox entities by specifying a namespace.
Parameter | Type | Description |
---|---|---|
|
|
Container name |
|
|
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 |
---|---|---|
|
|
The context object |
import {Rox} from 'rox-ssr';
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 |
---|---|---|
|
|
The name of the custom property |
|
|
The value of the custom property, or a function that accepts context and retrieve a value (see example) |
import {Rox} from 'rox-ssr';
// 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.
Parameter | Type | Description |
---|---|---|
|
|
The name of the custom property |
|
|
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 |
---|---|---|
|
|
The name of the custom property |
|
|
The value of the custom property, or a function that accepts context and retrieve a value (see example) |
import {Rox} from 'rox-ssr';
// 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 CloudBees Feature Management 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.
Parameter | Type | Description |
---|---|---|
|
|
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)
configurationFetchedHandler
function configurationFetchedHandler(fetcherResult){}
configurationFetchedHandler
function is called with one argument from
type FetcherResults
.
The FetcherResults
instance has the following properties:
name | type | description |
---|---|---|
fetcherStatus |
string |
Indicates the source of the data that was applied Possible values include:
|
creationDate |
Date |
The time the data was created and signed on CloudBees Feature Management servers |
hasChanges |
Boolean |
True if this data is not already available on the client |
errorDetails |
String |
Any error information that is available should one occur |