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);
Constructor
new Flag(defaultValue)
Parameter | Type | Description |
---|---|---|
|
| Initial state of the flag |
|
| additional options - adjust the freeze level with: { freeze: 'none'/'untilLaunch' } default is 'none' |
Return Value
none
Rox.RoxString
Rox.RoxString is used to create and manage CloudBees Feature Management that determine different predefined string values.
Constructor
new RoxString(defaultValue, variations)
Sets the default value, and variations for this RoxString instance.
Parameter | Type | Description |
---|---|---|
|
| The default value for this feature flag |
|
| The domain of possible values for this flag |
|
| 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 |
---|---|---|
|
| 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.
Constructor
new RoxNumber(defaultValue, variations, options)
Sets the default value and variations for this RoxNumber
instance.
Parameter | Type | Description |
---|---|---|
|
| The default value for this feature flag |
|
| The domain of possible values for this flag |
|
| 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
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 |
---|---|---|
|
| 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 the a flag value gets computed and evaluated on the client (if flag has override, or already frozen, no impression handler will be triggered) |
|
| custom platform, for cases you want to override
the default platform ( |
|
| configure the interval of fetch configuration call. The default value is 60s and the minimum is 30s |
|
| Function that is called every time a condition with property is evaluated and was not configured with any of the setCustomProperty functions |
|
| 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) |
|
| 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)
Register a container of Rox entities by specifying a namespace.
alternatively: register(container) - this will set the namespace to an empty string.
Parameter | Type | Description |
---|---|---|
|
| Container name, default: '' |
|
| 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 |
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 |
| `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 |
---|---|---|
|
| 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 |
| `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:
|
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) {}
See also Impression handler.
-
First parameter is an object with:
-
name - flag’s name
-
value - flag’s value
-
targeting - flag’s targeting: true/false
-
-
The second parameter is the context which the call used (global context merged with the calls' context, might 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 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 |
---|---|---|
|
| 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 |