Rollout.io - Documentation

ReactNative

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

// demoContainer.js
   module.exports = {
     sayHello: new Rox.Flag(),
     flagA: new Rox.Flag(),
     colorsVariant: new Rox.Variant('red', ['green', 'blue']),
     textColor: new Rox.Configuration('black')
   }

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

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

unfreeze()

Unlock the Flag value from changes from the last time it was freezed

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

export default {
     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()

Returns the current value of the Variant, accounting for value overrides

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

unfreeze()

Unlock the Flag value from changes from the last time it was freezed

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

export default {
     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()

Returns the current value of the Config, accounting for value overrides

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

unfreeze()

Unlock the Configuration value from changes from the last time it was freezed

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 Flags View. 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, so it is "remembered" for the next the SDK is loaded to production.

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

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

Retruns 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, experiment, context) => {
  console.log('flag impression', reportingValue, experiment, context); 
};

const options = {
  version: '2.0.0',
  debugLevel: 'verbose',
  configurationFetchedHandler: configurationFetchedHandler,
  impressionHandler: impressionHandler,
  freeze: Rox.FreezeOptions.freezeOptionNone
};

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

freeze

Rox.FreezeOptions

the default freeze level to set to flag unless it was overridden on flag constructor, default is Rox.FreezeOptions.freezeOptionUntilForeground

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

AsyncStorage

AsyncStorage object implementation

Implementation of AsyncStorage to override the default one.

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

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 retrieve a value

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

Parameters

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.

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 retrieve a value

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

setDynamicCustomPropertyRule

(static) setDynamicCustomPropertyRule(handler)
The Dynamic Custom Property Generator is called when an explicit Custom property definition does not exists on the client side.

If you do not set the setDynamicCustomPropertyRule it will then activate the default function which tries to extract the prop value from the context by it's name
(propName, context) => context ? context[propName] : undefined

Parameters

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

Example

// when looking for a property, look for it on the logged in user properties
Rox.setDynamicCustomPropertyRule((propName, context) => getLoggeIndUser().properties[propName]); 

fetch

(static) fetch()
Fetch() pulls the latest configuration and flag values down from the Rollout servers

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 it’s most updated value

Parameters

Parameter
Type
Description

namespace

String

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

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

  • "APPLIED_FROM_EMBEDDED" - data source is embedded inside the html see Embedded Experiments

  • "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 Rollout servers

hasChanges

Boolean

True if this data is no already available on the client

errorDetails

String

Error string in case of an error

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 Rox.setup
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 });

Updated 4 months ago

ReactNative


Suggested Edits are limited on API Reference Pages

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