The following information is for the latest SDK version. If you are running an older version, please check the CloudBees platform changelog for any differences. |
The Rox object is the main class to be used when registering your application’s feature flags in the platform.
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 platform UI and configured options, and your feature flags are ready to use.
To use the Rox object, you must 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 the setup with the correct API key and options set.
Register a container
// demoContainer.js module.exports = { sayHello: new Rox.Flag(), flagA: new Rox.Flag(), colorsVariant: new Rox.RoxString('red', ['green', 'blue']), sizeVariant: new Rox.RoxNumber(14, [24, 40]) } // Main application file import DemoContainer from './demoContainer'; Rox.register('ApplicationFeatures', DemoContainer);
Rox.Flag
Creates a new Rox.Flag
(default: false).
To use the Rox.Flag
object, simply declare it within a flag container
as you would any other member:
export default { displayWelcome: new Rox.Flag(), requireCaptcha: new Rox.Flag(), }
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 is none
.
Rox.RoxString
Use Rox.RoxString
to create and manage flags that
determine different predefined string values.
Use as in the following 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
.
export default { 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 |
---|---|---|
|
|
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 is none
.
name
Type: string
returns the flag name. The name is set only after registering, or a dynamicAPI call.
getValue()
Returns Type: string
, the current value of the RoxString object, accounting for value overrides.
Rox.RoxNumber
Rox.RoxNumber is used to create and manage feature flags that determine different predefined number values.
Use as in the following example:
The following code constructs some simple Rox.RoxNumber objects, which can be used to have a flag with string values.
export default { 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 |
---|---|---|
|
|
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' |
The return value is none
.
name
Returns the type String name of this flag (the name is set only after register, or a dynamicApi call).
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 must not be used in production builds.
It is the base API that is used to show the flag update flow.
It is usually not required to invoke this API directly beside on platforms that do not have support for the flag view (rox-react-native
).
When you override an existing flag value using the Rox.overrides.setOverride
method, the SDK disregards existing configuration coming from the UI and serializes the override
on disk.
This value is 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 (full flag name including namespace) and desired value (from type String).
This function also saves the override value on the local device disk, "remembering" the flag value for the next time the SDK is loaded.
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.overrides.hasOverride
Returns type boolean true
if a flag has an override.
Parameter | Type | Description |
---|---|---|
flagName |
String |
full flag name including namespace, eg.
|
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.
Use as in the following example:
Rox.register('', container); const configurationFetchedHandler = fetcherResults => { console.log(fetcherResults); }; const impressionHandler = (reportingValue, context) => { console.log('flag impression', reportingValue, context); }; const options = { version: '2.0.0', debugLevel: 'verbose', configurationFetchedHandler: configurationFetchedHandler, impressionHandler: impressionHandler, freeze: 'none', dynamicPropertyRuleHandler: dynamicPropertyRuleHandler };
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 is synced from the platform. |
|
|
SDK verbosity level, accept |
|
|
Function that is called every time a flag value is computed and evaluated on the client. If a flag has an override, or is already frozen, then no impression handler is triggered. |
|
|
Custom platform, used when you want to override the default platform.
( |
|
|
The default freeze level to set a flag, unless it is overridden on the flag constructor. The default is |
|
A custom logger object |
Overrides the default logger.
For example, to override the default |
|
|
Function that is called every time a condition with a property is evaluated, and not previously configured with any |
|
|
All SDK network calls go to a proxy, which calls the platform servers. No default, indicating that all network calls go to the server endpoints.
|
The return value is the promise that is executed once the configuration is retrieved from the platform.
register
(static) register(namespace, container)
Register a container of Rox entities by specifying a namespace.
(static) register(container)
Register a container of Rox entities and set the namespace to an empty string.
Parameter | Type | Description |
---|---|---|
|
String |
Container namespace. Default is ''. |
|
Object |
Object literal whose properties are Rox entities. |
setCustomBooleanProperty
(static) setCustomBooleanProperty(key, value)
Sets a custom property value for use when creating target groups.
Parameter | Type | Description |
---|---|---|
|
String |
The name of the custom property. |
|
Boolean |
The value of the custom property, or a function that retrieves a value. |
// Check if a user has the tester role via a function Rox.setCustomBooleanProperty("tester", function(){ return user.getInstance().isTester(); });
setCustomNumberProperty
(static) setCustomNumberProperty(key, value)
Sets a custom property value for use when creating target groups.
Parameter | Type | Description |
---|---|---|
|
String |
The name of the custom property. |
|
Number or a function |
The value of the custom property, or a function that retrieves a value. |
// Calculates the user's age via a function Rox.setCustomNumberProperty("age", function(){ return user.getInstance().getAge(); });
setCustomStringProperty
(static) setCustomNumberProperty(key, value)
Sets a custom property value for use when creating target groups.
Parameter | Type | Description |
---|---|---|
|
String |
The name of the custom property. |
|
String or function |
The value of the custom property, or a function that retrieves a value. |
// Retriving user email via a function Rox.setCustomStringProperty("email", function(){ return user.getInstance().email(); });
fetch
(static) fetch()
Fetch() pulls the latest configuration and flag values down from the platform.
unfreeze
(static) unfreeze(namespace)
Unfreezes the state of all flags in code.
Calling this function unfreezes all flags, and using a flag returns its most updated value.
Parameter | Type | Description |
---|---|---|
|
|
Namespace from which to unfreeze flags and configuration. If none specified, the function affects all namespaces. |
setUserspaceUnhandledErrorHandler
Use this handler for all user function errors, to help debug and understand unexpected flag values. If this function is not set, errors are logged to the logger.
CloudBees recommends that you use try -catch on user functions, in order to handle them in the relevant context, and not afterward.
|
function setUserspaceUnhandledErrorHandler(exceptionTrigger, error)
Name | Type | Description |
---|---|---|
|
String |
Indicates which user function raised the error. Must be one of the following values:
|
|
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) {}
-
reporting
is an object describing:-
Flag
name
-
Flag
value
-
Flag targeting, and whether evaluation is result of configuration in the UI or is default.
-
-
context
is the context passed to the flag evaluation function. Undefined if no context used.
configurationFetchedHandler
function configurationFetchedHandler(fetcherResult){}
configurationFetchedHandler
function is called with one argument from
type FetcherResults
.
The FetcherResults
instance has the following properties:
Name | Type | Description |
---|---|---|
|
String |
Indicates the source of the applied data, and is one of the following values:
|
|
Date |
The time this data was created and signed in the CloudBees platform. |
|
Boolean |
True if this data is not already available on the client. |
|
String |
Error string in the case of an error. |
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 its name.
(propName, context) => context ? context[propName] : undefined
Parameter | Type | Description |
---|---|---|
|
|
The function to be called when the SDK searches for a property not explicitly set by the setCustom`Type`Property functions. |
Rox.dynamicApi
An alternative to using a container and registering. This allows you to evaluate flags without having a static container. DynamicApi creates flags as if they were registered, including sending them to the UI.
isEnabled
Evaluate a boolean flag.
(static) isEnabled(name, defaultValue, context)
Name | Type | Description |
---|---|---|
|
String |
The flag name. Returns an error if not a string. |
|
Boolean |
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 boolean. |
|
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 |
---|---|---|
|
String |
The flag name. Returns an error if not a string. |
|
String |
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. |
|
Array<string> |
All alternative values, can be used in and updated in the UI. |
|
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 |
---|---|---|
|
String |
The flag name. Returns an error if not a string. |
|
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 number. |
|
Array<number> |
All alternative values, can be used in and updated in the UI. |
|
Object |
A context to evaluate the flag with. It is merged with the global context. |
AsyncStorage
An implementation of AsyncStorage can be passed to the options to be used for storing/getting keys on/from the device caching mechanism.
The default behavior, when not supplying AsyncStorage implementation, is
AsyncStorage from react-native
.
It can be used to replace the default
implementation (AsyncStorage from react-native
) with
react-native-community/async-storage, as follows:
import AsyncStorage from '@react-native-community/async-storage'; await Rox.setup(envKey, { AsyncStorage: AsyncStorage });