React Native API

9 minute readReference

The following information is for the latest version of the React Native SDK. If you are running an older version, please check the CloudBees Feature Management - JavaScript changelog for any differences.

The Rox object is the main class to be used when registering your application’s feature flags with CloudBees Feature Management. 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 CloudBees Feature Management UI) 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

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

Setting up the object

const options = {
    version: '1.0.0',
};
Rox.setup(APP_KEY, options);
▼

Rox.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:

export default {
   displayWelcome: new Rox.Flag(),
   requireCaptcha: new Rox.Flag(),
}
▼

Constructor

new Flag(defaultValue)
▼
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'

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

unfreeze()

Unlock the Flag value from changes from the last time it was frozen.

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.

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

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

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

Return Value

Type: string - the current value of this RoxString object

unfreeze()

Unlock the Flag value from changes from the last time it was frozen.

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.

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

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

unfreeze()

Unlock the flag value from changes from the last time it was frozen.

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. 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 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 (full flag name including namespace) and desired value (from type String).

This function also saves the override value on the local device disk; thus, it is "remembered" for the next time the SDK is loaded.

Parameter Type Description

flagName

String

full flag name including namespace, eg. default.flagName

value

String

The value of a flag, if this is a boolean flag the value should be "true"

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. default.flagName

Rox.overrides.hasOverride

Returns true if a flag has an override.

Parameter Type Description

flagName

String

full flag name including namespace, eg. default.flagName

Return Value

Type : boolean - true if flag has an override in place

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

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 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. Used for cases you want to override the default platform (Browser) (e.g. tizen, chromecast, etc.).

freeze

Rox.FreezeOptions

the default freeze level to set a flag unless it was overridden on flag constructor. The default is 'none'

logger

a custom logger object

override default logger for example, to override the default log.error behavior add the following code

options.logger = { error: (m) → console.log(m) }

dynamicPropertyRuleHandler

Function

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

AsyncStorage

AsyncStorage object implementation

Implementation of AsyncStorage to override the default one.

Proxy

Object

All SDK network calls go to a proxy, which calls CloudBees Feature Management servers. No default, indicating that all network calls go to CloudBees Feature Management server endpoints.

Proxy Object structure: {
  protocol: <protocol - string ex:"http"/"https">,
  host: <host - url>,
  port: <port - valid port number>,
  auth: {
    username: <username - string>,
    password: <password - string>
  }
}
▼

To use with a proxy server, refer to Using a 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

namespace

String

Container name, default: ''

container

Object

Object literal whose properties are Rox entities

setCustomStringProperty

(static) setCustomStringProperty(key, value)
▼

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

Parameter Type Description

key

String

The name of the custom property

value

`String

Function`

 
// retrieving user email via a function
Rox.setCustomStringProperty("email", function(){
   return user.getInstance().email();
});
▼

setCustomBooleanProperty

(static) setCustomBooleanProperty(key, value)
▼

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

Parameter Type Description

key

String

The name of the custom property

value

Boolean

The value of the custom property, or a function that retrieve a value

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

setCustomNumberProperty

(static) setCustomNumberProperty(key, value)
▼

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

Parameter Type Description

key

String

The name of the custom property

value

Number or Function

The value of the Custom Property, or a function that retrieve a value

 
// Calculating the age of the user via a function
Rox.setCustomNumberProperty("age", function(){
   return user.getInstance().getAge();
});
▼

fetch

(static) fetch()
▼

Fetch() pulls the latest configuration and flag values down from the CloudBees Feature Management server.

unfreeze

(static) unfreeze(namespace)
▼

Unfreeze the state of all flags in code.

Calling this function will unfreeze all flags, and using a flag will return its most updated value.

Parameter Type Description

namespace

String

namespace to unfreeze flags and configuration from. If none is supplied, the function will affect all namespaces

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

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)

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 that data that was applied One of the following values:

  • "APPLIED_FROM_EMBEDDED" - data source is embedded inside the html

  • "APPLIED_FROM_CACHE"- data source is from local storage cache

  • "APPLIED_FROM_NETWORK" - data source is network

  • "ERROR_FETCH_FAILED" - data wasn’t received correctly

creationDate

Date

the time this data was created and signed on the CloudBees Feature Management server

hasChanges

Boolean

True if this data is not already available on the client

errorDetails

String

Error string in 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 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

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

Rox.FreezeOptions

freezeOptionUntilLaunch

Will freeze the flag/configuration until the next launch.

freezeOptionUntilForeground

Will freeze the flag/configuration until the next app foreground event.

freezeOptionNone

Will not freeze the flag/configuration.

AsyncStorage

AsyncStorage implementation can be passed to on 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.

Here is an example of how it can be used in order to replace the default implementation (AsyncStorage from react-native) with react-native-community/async-storage.

import AsyncStorage from '@react-native-community/async-storage';

await Rox.setup(envKey, { AsyncStorage: AsyncStorage });
▼
Python API
Ruby API