Objective-C SDK reference

8 minute readReference

The following information is for the latest SDK version (6.x). The CloudBees platform requires that your installed SDK version be at least 6.x. Please install the latest SDK by following the instructions in the platform UI or in the SDK installation documentation.

Any updates to version 6.x are noted in the platform changelog.

The following classes are available:

ROXBaseContainer

@interface ROXBaseContainer : NSObject

A container class for flag configurations.

Use any class that inherits from this base class as an entry point for flags and configurations that are controlled by the CloudBees platform. To use an instance of this class, register the instance using the [ROXCore register:]` method and retrieve the instance using the `[ROXCore get:] method.

Method Description Declaration

-namespace

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

(NSString *)namespace;

ROXCore

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

Use this flag to:

  • Initialize the CloudBees platform 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.

Method Description Declaration Parameters

setupWithKey:

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

(void)setupWithKey:(NSString *)roxKey;

roxKey The platform environment-specific SDK key

setupWithKey:options:

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

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

  • roxKey The platform environment-specific SDK key

  • options Setup options

shutdown

Allows for the graceful shutdown of the ROXCore object, and closes and cleans all background tasks and threads. Use only when ROXCore is successfully set up; otherwise it results in a log warning.

You can call setup again after shutdown. In that case, register and setCustomProperty use a new ROXCore, and register the objects to the UI on the next setup call.

+(void)shutdown;

register

Registers a container instance to the CloudBees platform.

@params container The instance to register. Values are set at +setupWithKey:, or if the app goes into foreground. Call this method only once for a given class.

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

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

  • container is the container to register.

  • namespace is the optional flag namespace prefix for the container. You must only register a namespace once; otherwise throws an exception.

  • unfreeze

  • unfreezeNamespace

Unfreezes the state of all coded flags.

Because the value of a flag is frozen until the next foreground event, you can call this function to unfreeze all flags. After unfreezing, using a flag returns its most updated value.

If a namespace version is used, flags are only unfrozen within the given namespace.

+ (void)unfreeze;

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

flagsViewController

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

ViewController allows developers or others (depending on policy) to view, enable, disable, and reset the state of their flags locally on the device. The function returns 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;

setCustomStringProperty:forKey:

Sets a custom property value for use when creating target groups.

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

  • key is the custom property name.

  • value is the custom property value.

setCustomComputedStringProperty:forKey:

Sets a custom property value for use when creating target groups.

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

  • key is the custom property name.

  • block is invoked during property evaluation.

setCustomBooleanProperty:forKey:

Sets a custom property value for use when creating target groups.

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

  • key is the custom property name.

  • value is the custom property value.

setCustomComputedBooleanProperty:forKey:

Sets a custom property value for use when creating target groups.

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

  • key is the custom property name.

  • block is invoked during property evaluation.

setCustomIntProperty:forKey:

Sets a custom property value for use when creating target groups.

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

  • key is the custom property name.

  • value is the custom property value.

setCustomComputedIntProperty:forKey:

Sets a custom property value for use when creating target groups.

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

  • key is the custom property name.

  • block is invoked during property evaluation.

setCustomDoubleProperty:forKey:

Sets a custom property value for use when creating target groups.

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

  • key is the custom property name.

  • value is the custom property value.

setCustomComputedDoubleProperty:forKey:

Sets a custom property value for use when creating target groups.

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

  • key is the custom property name.

  • block is invoked during property evaluation.

setCustomSemverProperty:forKey:

Sets a custom property value for use when creating target groups.

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

  • key is the custom property name.

  • value is the custom property value.

setCustomComputedSemverProperty:forKey:

Sets a custom property value for use when creating target groups.

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

  • key is the custom property name.

  • block is invoked during property evaluation.

setGlobalDynamicPropertyContext

Sets a global context that is available to all flag evaluations (in addition to the specific call context).

+(void) setGlobalDynamicPropertyContext:(ROXDynamicPropertyContext)context;

context is the function that retrieves the custom property value from the key given (refer to the appropriate type definition).

setUserspaceUnhandledErrorHandler

A handler for all user function errors, to assist in debugging. If this function is not set, errors are logged to the logger.

CloudBees recommends that you wrap all user methods with try-catch to handle errors while in the relevant context, and not after.

+(void)setUserspaceUnhandledErrorHandler:(ROXUserspaceUnhandledErrorHandler)handler;

handler is a function to handle all exceptions raised within user-defined functions.

overrides

Use ROXFlagsOverrides to override a flag value locally. Use only in dev mode, not in production builds.

+(ROXFlagsOverrides*)overrides;

dynamicAPI

An alternative to using container with register. 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.

+(ROXDynamicAPI*)dynamicAPI;

ROXFlag

@interface ROXFlag : ROXString

ROXFlag is a feature flag object that accepts either a true or false value (a Boolean type).

Method Description Declaration Parameters

isEnabled

A property indicating if the flag is enabled or disabled.

@property (readonly, nonatomic) BOOL isEnabled;

enabled

Runs block if a flag is enabled.

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

codeBlock is invoked synchronously if the flag is enabled.

disabled

Runs block if flag is disabled.

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

codeBlock is invoked synchronously if the flag is disabled.

enabled:disabled:

Runs one of the given blocks based on flag status.

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

  • enabledCodeBlock is invoked synchronously if a flag is enabled.

  • disabledCodeBlock is invoked synchronously if a flag is disabled.

forceValue

Forces a value on the flag. This overrides any other value, and can only be overridden with another call to forceValue.

- (void)forceValue:(BOOL)value;

value is the forced value.

initWithDefault

Initializes a flag with a default Boolean value.

- (instancetype)initWithDefault:(BOOL)defaultValue;

defaultValue is the default flag value.

ROXString

@interface ROXString : NSObject

ROXString is a feature flag object that accepts a list of possible string values and a default value. Use this list when selecting new values for the feature, and you can override the value via the UI.

Method Description Declaration Parameters

value

Returns the ROXString value considering the given context.

-(NSString*)value;

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

context is a context object for calculating custom dynamic property values during the flag evaluation.

defaultValue

Returns the ROXString 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

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

-(void)unfreeze;

peek

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

-(NSString*)peek;

ROXInt

@interface ROXInt : ROXString

ROXInt is a feature flag object that accepts a list of possible integer values and a default value. Use this list when selecting new values for the feature, and you can override the value via the UI.

Method Description Declaration Parameters

value

Returns the ROXInt value considering the given context.

-(int)value;

-(int)value:(ROXDynamicPropertyContext)context;

context is a context object for calculating custom dynamic property values during the flag evaluation.

initWithDefault

Initializes a new ROXInt with a default value, variations and a 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 accepts a list of possible double values and a default value. Use this list when selecting new values for the feature, and you can override the value via the UI.

Method Description Declaration Parameters

value

Returns the ROXDouble value considering the given context.

-(double)value;

-(double)value:(ROXDynamicPropertyContext)context;

context is a context object for calculating custom dynamic property values during the flag evaluation.

initWithDefault

Initializes a new ROXDouble with a default value, variations and a 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

Use this configuration class when running +[ROXCore setupWithKey:options:].

Method 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

Sets the SDK verbosity level for debugging.

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

disableCrashReporting

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

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

dynamicPropertiesRule

Calls the dynamic custom property generator when an explicit custom property definition does not exist on the client side.

If you do not set the dynamicPropertiesRule, the default function is activated and attempts 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 creates flags as if they were registered, including sending them to the UI.

Method Description Declaration Parameters

isEnabled

Evaluate a a Boolean flag.

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

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

  • name is the flag name, including an optional namespace.

  • defaultValue is the flag default value.

  • context is a context object for calculating custom dynamic property values during the flag evaluation.

getValue

Evaluates 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 is the flag name, including an optional namespace.

  • defaultValue is the flag default value.

  • variations are all alternative values to use in the UI, and can be changed via the UI.

  • context is a context object for calculating custom dynamic property values during the flag evaluation.

getInt

Evaluates 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 is the flag name, including an optional namespace.

  • defaultValue is the flag default value.

  • variations are all alternative values to use in the UI, and can be changed via the UI.

  • context is a context object for calculating custom dynamic property values during the flag evaluation.

getDouble

Evaluates 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 is the flag name, including an optional namespace.

  • defaultValue is the flag default value.

  • variations are all alternative values to use in the UI, and can be changed via the UI.

  • context is a context object for calculating custom dynamic property values during the flag evaluation.

ROXReportingValue

@interface ROXReportingValue : NSObject

This class contains data about configured flag values.

Method Description Declaration Parameters

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.

Method Description Declaration

Name

The target group name.

@property (readonly, nonatomic) NSString *name;

isEnabled

Whether a device is part of this target group.

@property (readonly, nonatomic) BOOL isEnabled;

ROXOptionsVerboseLevel

enum ROXOptionsVerboseLevel {}

The enum to define the SDK verbosity level.

Method Description Declaration

ROXOptionsVerboseLevelSilent

Silent logging.

ROXOptionsVerboseLevelSilent

ROXOptionsVerboseLevelDebug

Verbose logging.

ROXOptionsVerboseLevelDebug

Type definitions

The following type definitions are available globally.

Method Description Declaration

ROXDynamicPropertyContext

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

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

ROXDynamicPropertiesRule

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

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

ROXUserspaceUnhandledErrorHandler

A function that handles an 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 };
.NET/C# client
React Native