Objective-C API docs

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

Features

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

  • Simple: CloudBees Feature Flags allows developers to focus on their business logic and not working with the complex configurations on the dashboard.

  • Modern: Using static types, the compiler and IDE are responsible to prevent collisions to allow easy flags discovery by developers (by autocomplete).

  • Support Optimizations: CloudBees Feature Flags unique proposition is that is supports the company needs a full capable experimentation system, for A/B/N testing, optimizations, customizations and more.

  • Remote configuration included: CloudBees Feature Flags include a remote configuration module that allows developers to define a configuration that can be controlled from the server.

Classes

Classes Description

ROXBaseContainer

Contains configurations and flags.

ROXCore

Acts as a facade interface.

ROXExperiment

Contains session data about an Experiment.

ROXFlag

Contains the API for flags that are controlled by ROX Server. Flags are assigned to an experiment and their value is based on experiment container.

ROXMetadata

Contains the state of the current session.

ROXOptions

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

ROXRemoteVariable

Contains remote variables.

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 Flags. 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 Flags 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 Flags dashboard)

options setup options

register:

Register a container instance to CloudBees Feature Flags system, the same instance can be retrieved by using +getContainer: function

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

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

container

getContainer:

Retrieve an instance from type clazz that was registered with ROX.register(_:)

+ (NSObject *)getContainer:(Class)clazz;

clazz The type of instance you want to retrieve

Return Value The instance that was registered

sync

Recalculate the rules of experiments allocation base on new data [NOTE] Usually called after the user has logged in to refresh ROX custom properties

+ (void)sync;

unfreeze

Unfreeze the state of all flags in code

When a flag is used in code, his 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

+ (void)unfreeze;

flagsViewController

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

CloudBees Feature Flags 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

roxDisabled

Checks if device is a test device. Test device are managed by App Settings in the dashboard

+ (BOOL)roxDisabled; Return Value true if device is test device, false otherwise.

ROXExperiment

@interface ROXExperiment : NSObject

Methods Description Declaration

name

Experiment name

@property (readonly, nonatomic) NSString *name;

identifier

Experiment unique identifier

@property (readonly, nonatomic) NSString *identifier;

flags

Flags for this experiment

@property (readonly, nonatomic) NSArray<ROXReportingValue *> *flags;

ROXFlag

@interface ROXFlag : ROXVariant

This class is the API for flags that are controlled by CloudBees Feature Flags server. Flags are assigned to an experiment and their value is based on an experiment container.

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

ROXMetadata

@interface ROXMetadata : NSObject

This class contains the state of the current session.

Methods Description Declaration Parameters

experiments

An array of the available experiments in this session

@property (readonly, nonatomic) NSArray<ROXExperiment *> *experiments;

targetGroups

An array of the available targetGroups in this session

@property (readonly, nonatomic) NSArray<ROXTargetGroup *> *targetGroups;

remoteVariables

An array of the available remoteVariables in this session

@property (readonly, nonatomic) NSArray<ROXRemoteVariable *> *remoteVariables;

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;

ROXRemoteVariable

@interface ROXRemoteVariable : NSObject

Base class for remote variables.

Methods Description Declaration Parameter

name

The full name of the remote variable (including namespace).

@property (readonly, nonatomic) NSString *name;

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

ROXSyncCompletionHandler

The Callback definition for ROXOptions.syncCompletionHandler

typedef void(^ROXSyncCompletionHandler)(ROXMetadata *_Nonnull)