Objective-C API

9 minute readReference

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

CloudBees Feature Management is an advanced feature flagging solution that lets development teams quickly build and deploy applications without compromising on security.

Features

  • Mobile-first: CloudBees Feature Management is the first feature flagging system built from the ground up to run directly inside phones, tablets, and wearables.

  • Simple: CloudBees Feature Management allows developers to focus on their business logic instead of complex configurations.

  • Modern: Using static types, the compiler and IDE are responsible for preventing collisions, allowing easy flag discovery by developers (through autocomplete).

  • Support Optimizations: CloudBees Feature Management supports your needs for a fully capable experimentation system, including A/B/N testing, optimizations, and customizations.

Classes

Classes Description

ROXBaseContainer

Contains configurations and flags.

ROXCore

Acts as a facade interface.

ROXExperiment

Contains session data about an Experiment.

ROXFlag

Feature flag containing BOOL values.

ROXString

Feature flag containing NSString values.

ROXInt

Feature flag containing int values.

ROXDouble

Feature flag containing double values.

ROXOptions

Contains the configuration that is used when running +[ROXCore setupWithKey:options:].

ROXReportingValue

Contains data about values of an Experiment.

ROXTargetGroup

Contains session data about a Target Group.

ROXBaseContainer

@interface ROXBaseContainer : NSObject

A container class for configurations and flags.

Any class that inherits from this base class can be used as an entry point for flags and configurations that are controlled by CloudBees Feature Management. To use an instance of this class, you need to register the instance using the [ROXCore register:]` method and retrieve the instance using `[ROXCore get:] method.

Methods Description Declaration

-namespace

Override this property to override the default namespace of a class.

(NSString *)namespace;

ROXCore

ROXCore class is a static objc class that acts as a facade interface.

You use this flag for the following:

  • Initialize CloudBees Feature Management SDK using +setupWithKey:

  • Register container instances using +register:

  • Retrieve container instances using +getContainer:

  • Load custom properties with setCustomPropertyKey:value: methods

  • Present the flags view controller with +flagsViewController

Methods Description Declaration Parameter

setupWithKey:

Loads the SDK, usually called as part of -[AppDelegate application:didFinishLaunchingWithOptions:]

(void)setupWithKey:(NSString *)roxKey;

roxKey The app key (taken from ROX dashboard)

setupWithKey:options:

Loads the SDK, usually called as part of -[AppDelegate application:didFinishLaunchingWithOptions:]

(void)setupWithKey:(NSString *)roxKey options:(ROXOptions *)options;

roxKey The app key (taken from CloudBees Feature Management dashboard)

options setup options

shutdown

This method allows for the graceful shutdown of the ROXCore object, and will close and clean all background tasks and threads. It can only be used when ROXCore is successfully setup.

Calling shutdown when it’s not possible, will result a log warning.

You can call setup again after shutdown; right after shutdown, all register and setCustomProperty will use a new ROXCore, and will register the objects to the Dashboard on the next setup call.

+(void)shutdown;

register

Register a container instance to CloudBees Feature Management system.

@params container The instance to register, this instance values are set at +setupWithKey:, or if the app goes into foreground. NOTE: This method should be called only once for a given class.

+ (void) register:(ROXBaseContainer *)container;

+(void) register:(NSString *)namespace container:(ROXBaseContainer *)container;

container - container to register.

namespace - optional flag namespace prefix for the container. A namespace can only be registered once; trying to use the same namespace twice will throw an exception.

unfreeze

unfreezeNamespace

Unfreeze the state of all flags in code.

When a flag is used in code, its value gets frozen in the app until the next app foreground event. Calling this function will unfreeze all flags, and using a flag will return it’s most updated value.

If namespace version is used, it will only unfreeze flags within the given namespace.

+ (void)unfreeze;

+(void) unfreezeNamespace:(NSString*)ns;

flagsViewController

A view to control feature flags values locally on a mobile device or simulator.

CloudBees Feature Management ViewController allows developers, QA, or internal employees (depending on policy) to view, disable, enable and reset the state of their flags locally on the device. The functions return a view controller that can be loaded to the view hierarchy for test devices upon shake, or by triggering an existing debug view in the app.

+ (id)flagsViewController; Return Value ViewController which shows the local feature flags and provides an interface to turn them on or off.

setCustomStringProperty:forKey:

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

+ (void)setCustomStringProperty:(NSString *)value forKey:(NSString *)key;

key The name of the custom property

value The value of the custom property

setCustomComputedStringProperty:forKey:

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

+ (void)setCustomComputedStringProperty:(NSString * (^)())block forKey:(NSString *)key;

key The name of the custom property

block. This block will get invoked when trying to evaluate the value of the property.

setCustomBooleanProperty:forKey:

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

+ (void)setCustomBooleanProperty:(BOOL)value forKey:(NSString *)key;

key The name of the custom property

value The value of the custom property

setCustomComputedBooleanProperty:forKey:

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

+ (void)setCustomComputedBooleanProperty:(BOOL (^)())block forKey:(NSString *)key;

key The name of the custom property

block this block will get invoked when trying to evaluate the value of the property

setCustomIntProperty:forKey:

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

+ (void)setCustomIntProperty:(int)value forKey:(NSString *)key;

key The name of the custom property

value The value of the custom property

setCustomComputedIntProperty:forKey:

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

+ (void)setCustomComputedIntProperty:(int (^)())block forKey:(NSString *)key;

key The name of the custom property

block this block will get invoked when trying to evaluate the value of the property

setCustomDoubleProperty:forKey:

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

+ (void)setCustomDoubleProperty:(double)value forKey:(NSString *)key;

key The name of the custom property

value The value of the custom property

setCustomComputedDoubleProperty:forKey:

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

+ (void)setCustomComputedDoubleProperty:(double (^)())block forKey:(NSString *)key;

key The name of the custom property

block this block will get invoked when trying to evaluate the value of the property

setCustomSemverProperty:forKey:

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

+ (void)setCustomSemverProperty:(NSString *)value forKey:(NSString *)key;

key The name of the custom property

value The value of the custom property

setCustomComputedSemverProperty:forKey:

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

+ (void)setCustomComputedSemverProperty:(NSString * (^)())block forKey:(NSString *)key;

key The name of the custom property

block. This block will get invoked when trying to evaluate the value of the property

setGlobalDynamicPropertyContext

Set a global context. This context will be available to all flags evaluations (in addition to the specific call context).

+(void) setGlobalDynamicPropertyContext:(ROXDynamicPropertyContext)context;

context - function that retrieves custom property value from the key given. See the type definitions section below.

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 wrap all user methods with try-catch in order to handle it while in the relevant context, and not afterwards.

+(void)setUserspaceUnhandledErrorHandler:(ROXUserspaceUnhandledErrorHandler)handler;

handler - a function that will handle all exceptions raised within user-defined functions.

See also User space error handler.

overrides

ROXFlagsOverrides is used to override a flag value locally, it is used by developers working on a feature in dev mode and shouldn’t be used in production builds.

+(ROXFlagsOverrides*)overrides;

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.

See also Dynamic api.

+(ROXDynamicAPI*)dynamicAPI;

ROXString

@interface ROXString : NSObject

ROXString is a feature flag object that can have string values. ROXString accepts a list of possible string values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for an override via the dashboard.

Methods Description Declaration Parameters

value

Returns the ROXString’s value considering the given context.

-(NSString*)value;

-(NSString*)value:(ROXDynamicPropertyContext)context;

context - context object used to calculate custom dynamic property values during the flag evaluation.

defaultValue

Returns the ROXString’s default value.

-(NSString*)defaultValue;

name

Returns the feature flag name.

@property (readonly, nonatomic) NSString* name;

variations

Returns the feature flag variations.

@property (readonly, nonatomic) NSArray<NSString*>* variations;

unfreeze

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

-(void)unfreeze;

peek

Returns the current flag value. Will not trigger freeze or impression. If the flag is frozen, the frozen value will be returned.

-(NSString*)peek;

ROXFlag

@interface ROXFlag : ROXString

This class is the API for BOOL feature flags that are controlled by CloudBees Feature Management server.

Methods Description Declaration Parameters

isEnabled

a property to indicate if the flag is enabled or disabled

@property (readonly, nonatomic) BOOL isEnabled;

enabled

Runs block is flag is enabled

- (void)enabled:(void (^)(void))codeBlock;

codeBlock will get invoked (synchronously) if flag is enabled

disabled

Runs block is flag is disabled

- (void)disabled:(void (^)(void))codeBlock;

codeBlock will get invoked (synchronously) if flag is disabled

enabled:disabled:

Runs one of the given block based on flag status

- (void)enabled:(void (^)(void))enabledCodeBlock disabled:(void (^)(void))disabledCodeBlock;

enabledCodeBlock will get invoked (synchronously) if flag is enabled

disabledCodeBlock will get invoked (synchronously) if flag is disabled

forceValue

Force a value on the flag. This will override any other value (Experiment, Flags View Controller, etc..), and can only be overridden with another call to forceValue:

- (void)forceValue:(BOOL)value;

value to force the SDK with

initWithDefault

Initialize a flag with a default boolean value

- (instancetype)initWithDefault:(BOOL)defaultValue;

defaultValue a default value for this flag

ROXInt

@interface ROXInt : ROXString

ROXInt is a feature flag object that can have int values. ROXInt accepts a list of possible int values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for an override via the dashboard.

Methods Description Declaration Parameters

value

Returns the ROXInt’s value considering the given context.

-(int)value;

-(int)value:(ROXDynamicPropertyContext)context;

context - context object used to calculate custom dynamic property values during the flag evaluation.

initWithDefault

Initializes new ROXInt with default value, variations and possible freeze level.

-(instancetype)initWithDefault:(int)defaultValue;

-(instancetype)initWithDefault:(int)defaultValue variations:(NSArray<NSNumber*> *)variations;

- (instancetype)initWithDefault:(int)defaultValue variations:(nonnull NSArray<NSNumber *> *)variations freeze:(ROXFreeze)freeze;

ROXDouble

@interface ROXDouble : ROXString

ROXDouble is a feature flag object that can have double values. ROXDouble accepts a list of possible double values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for an override via the dashboard.

Methods Description Declaration Parameters

value

Returns the ROXDouble’s value considering the given context.

-(double)value;

-(double)value:(ROXDynamicPropertyContext)context;

context - context object used to calculate custom dynamic property values during the flag evaluation.

initWithDefault

Initializes new ROXDouble with default value, variations and possible freeze level.

-(instancetype)initWithDefault:(double)defaultValue;

-(instancetype)initWithDefault:(double)defaultValue variations:(NSArray<NSNumber*> *)variations;

-(instancetype)initWithDefault:(double)defaultValue variations:(NSArray<NSNumber *> *)variations freeze:(ROXFreeze)freeze;

ROXOptions

@interface ROXOptions : NSObject

This is the configuration class that is used when running +[ROXCore setupWithKey:options:].

Methods Description Declaration Parameters

syncCompletionHandler

The completion handler that is called when the SDK has synced and applied the configuration.

@property (readwrite, copy, nonatomic, nullable) ROXSyncCompletionHandler syncCompletionHandler;

verbose

Set SDK verbosity level for debugging

@property (assign, readwrite, nonatomic) ROXOptionsVerboseLevel verbose;

disableCrashReporting

Setting this option to YES will prevent the SDK from handling and reporting crashed sessions.

@property (assign, readwrite, nonatomic) BOOL disableCrashReporting;

dynamicPropertiesRule

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 dynamicPropertiesRule, it will then activate the default function which tries to extract the property value from context.

@property (nonatomic, copy, nullable) ROXDynamicPropertiesRule dynamicPropertiesRule;

ROXDynamicAPI

@interface ROXDynamicAPI : NSObject

An alternative to 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.

See also Dynamic api.

Methods Description Declaration Parameter

isEnabled

Evaluate a boolean flag.

-(BOOL)isEnabled:(NSString*)name withDefault:(BOOL)defaultValue;

-(BOOL)isEnabled:(NSString*)name withDefault:(BOOL)defaultValue context:(ROXDynamicPropertyContext)context;

name - flag name including optional namespace.

defaultValue - flag’s default value.

context - context object used to calculate custom dynamic property values during the flag evaluation.

getValue

Evaluate a string flag.

-(NSString*)getValue:(NSString*)name withDefault:(NSString*)defaultValue;

-(NSString*)getValue:(NSString*)name withDefault:(NSString*)defaultValue variations:(NSArray<NSString*>*)variations;

-(NSString*)getValue:(NSString*)name withDefault:(NSString*)defaultValue variations:(NSArray<NSString*>*)variations context:(ROXDynamicPropertyContext)context;

name - flag name including optional namespace.

defaultValue - flag’s default value.

variations - all alternative values to use on the dashboard (can be changed on the dashboard side).

context - context object used to calculate custom dynamic property values during the flag evaluation.

getInt

Evaluate an integer flag.

-(int)getInt:(NSString*)name withDefault:(int)defaultValue;

-(int)getInt:(NSString*)name withDefault:(int)defaultValue variations:(NSArray<NSNumber*>*)variations;

-(int)getInt:(NSString*)name withDefault:(int)defaultValue variations:(NSArray<NSNumber*>*)variations context:(ROXDynamicPropertyContext)context;

name - flag name including optional namespace.

defaultValue - flag’s default value.

variations - all alternative values to use on the dashboard (can be changed on the dashboard side).

context - context object used to calculate custom dynamic property values during the flag evaluation.

getDouble

Evaluate a double flag.

-(double)getDouble:(NSString*)name withDefault:(double)defaultValue;

-(double)getDouble:(NSString*)name withDefault:(double)defaultValue variations:(NSArray<NSNumber*>*)variations;

-(double)getDouble:(NSString*)name withDefault:(double)defaultValue variations:(NSArray<NSNumber*>*)variations context:(ROXDynamicPropertyContext _Nullable)context;

name - flag name including optional namespace.

defaultValue - flag’s default value.

variations - all alternative values to use on the dashboard (can be changed on the dashboard side).

context - context object used to calculate custom dynamic property values during the flag evaluation.

ROXReportingValue

@interface ROXReportingValue : NSObject

This class contains data about values of an experiment.

Methods Description Declaration Parameter

name

Name of the reporting

@property (readonly, nonatomic) NSString *name;

value

Value of the reporting

@property (readonly, nonatomic) NSString *value;

ROXTargetGroup

@interface ROXTargetGroup : NSObject

This class contains session data about a Target Group.

Methods Description Declaration

Name

The target group name.

@property (readonly, nonatomic) NSString *name;

isEnabled

Is device part of this target group

@property (readonly, nonatomic) BOOL isEnabled;

ROXOptionsVerboseLevel

enum ROXOptionsVerboseLevel {}

The enum to define SDK verbosity level.

Methods Description Declaration

ROXOptionsVerboseLevelSilent

Silent Log

ROXOptionsVerboseLevelSilent

ROXOptionsVerboseLevelDebug

Verbose Log

ROXOptionsVerboseLevelDebug

Type Definitions

The following type definitions are available globally.

Methods Description Declaration

ROXDynamicPropertyContext

A function that retrieves custom property value by the given key.

typedef NSObject* (^ROXDynamicPropertyContext)(NSString* propName);

ROXDynamicPropertiesRule

A function that applies custom logic to the custom property evaluation.

typedef NSObject* (^ROXDynamicPropertiesRule)(NSString* propName, ROXDynamicPropertyContext context);

ROXUserspaceUnhandledErrorHandler

A function that handles exception raised within other user-defined handlers.

typedef void (^ROXUserspaceUnhandledErrorHandler)(ROXExceptionTrigger trigger, NSException *exception);

ROXExceptionTrigger

An indicator of the exception source.

typedef NS_ENUM (NSUInteger, ROXExceptionTrigger){ ROXExceptionTriggerDynamicPropertiesRule, ROXExceptionTriggerConfigurationFetchedHandler, ROXExceptionTriggerImpressionHandler, ROXExceptionTriggerCustomPropertyGenerator };
Node.js API
PHP API