Swift API docs (4.9)

6 minute read

CloudBees Feature Management 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 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 the complex configurations on the dashboard.

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

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

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

ROX

public class ROX

ROX class is a static swift class that acts as a facade interface.

You can use this flag for the following:

  1. Initialize CloudBees Feature Management SDK using ROX.setup(withKey:).

  2. Register container instances using ROX.register(_:).

  3. Retrieve container instances using ROX.getContainer(_:).

  4. Load custom properties with ROX.setCustomProperty(key:value:).

  5. Present the flags view controller with ROX.flagsViewController().

Methods Description Declaration Parameter

setup(withKey:)

  • Loads the SDK, usually called as part of AppDelegate.application:didFinishLaunchingWithOptions:

  • Checks if a cached experimentation container exists, and loads a container.

  • Executes an async network call to fetch the experiment container from the CloudBees Feature Management server and calculates experiments and target groups.

public static func setup(withKey key: String)

key

The app key (taken from ROX dashboard)

setup(withKey:options:)

  • Loads the SDK, usually called as part of AppDelegate.application:didFinishLaunchingWithOptions:

  • Checks if a cached experimentation container exists, and loads a container.

  • Executes an async network call to fetch the experiment container from the ROX server and calculates experiments and target groups.

public static func setup(withKey key: String, options: ROXOptions)

key

a unique identifier from type String generated from ROX dashboard

options

setup options

register(_:)

Register a container instance to CloudBees Feature Management system, the same instance can be retrieved by using ROX.getContainer(_:) function

This method should be called only once for a given class.

public static func register(_ container: RoxContainer)

container

The instance to register, this instance values are set at ROX.sync(), ROX.setup(withKey:), or if the app goes into foreground

getContainer(_:)

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

public static func getContainer<T:RoxContainer>(_ clazz: T.Type) → T?

clazz

The type of instance you want to retrieve

Return Value The instance that was registered

sync()

Recalculate the rules of experiments allocation based on new data. See Also ROX,unfreeze()

Usually called after the user has logged in to refresh ROX custom properties
If a flag has already been used (had impression), it’s frozen and the calculation will not change the flag state. To change the flag state unfreeze the flag right after the sync call.

public static func sync()

unfreeze()

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 its most updated value.

public static func unfreeze()

flagsViewController()

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

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

public static func flagsViewController() → UIViewController

Return Value ViewController which shows the local feature flags and provides an interface to turn them on or off.

setCustomProperty(key:value:)

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

public static func setCustomProperty(key: String, value: String)

key

The name of the custom property

value

The value of the custom property

setCustomProperty(key:asSemver:value:)

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

public static func setCustomProperty(key: String, asSemver: Bool, value: String)

key

The name of the custom property

asSemver

Should the string be computed and treated as a semver (What is Semantic Versioning)

value

The value of the custom property

setCustomProperty(key:value:)

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

  • This method is used when you wish to supply a block of code that will be evaluated on a foreground event or when either ROX.sync() , ROX.setup(withKey:) is called.

public static func setCustomProperty(key: String, value: @escaping () → String)

key

The name of the custom property

value

a code block to return the value of the custom property

setCustomProperty(key:asSemver:value:)

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

  • This method is used when you wish to supply a block of code that will be evaluated on foreground event or when either ROX.sync() or ROX.setup(withKey:) is called.

static func setCustomProperty(key: String, asSemver: Bool, value: @escaping () → String)

asSemver

Should the string be computed and treated as a semver (What is Semantic Versioning)

value

A code block to return the value of the custom property

setCustomProperty(key:value:)

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

public static func setCustomProperty(key: String, value: Bool)

key

The name of the custom property

value

The value of the custom property

setCustomProperty(key:value:)

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

  • This method is used when you wish to supply a block of code that will be evaluated on foreground event or when either ROX.sync() or ROX.setup(withKey:) is called.

public static func setCustomProperty(key: String, value: @escaping () → Bool)

key

The name of the custom property

value::a code block to return the value of the custom property

setCustomProperty(key:value:)

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

public static func setCustomProperty(key: String, value: Int32)

key

The name of the custom property

value

The value of the custom property

setCustomProperty(key:value:)

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

  • This method is used when you wish to supply a block of code that will be evaluated on foreground event or when either ROX.sync() or ROX.setup(withKey:) is called.

public static func setCustomProperty(key: String, value: @escaping () → Int32)

key

The name of the custom property

value::a code block to return the value of the custom property

setCustomProperty(key:value:)

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

public static func setCustomProperty(key: String, value: Double)

key

The name of the custom property

value

a code block to return the value of the custom property

setCustomProperty(key:value:)

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

public static func setCustomProperty(key: String, value: @escaping() → Double)

key

The name of the custom property

value

a code block to return the value of the custom property

roxDisabled()

Check if ROX is disabled.

public static func roxDisabled() → Bool

Return Value

True if ROX is disabled (disabled from the server side).

Protocols

Protocols Description

RoxContainer

A container class for configurations and flags.

Any Swift class that adopts this protocol can be used as an entry point for flags and containers that are controlled by the CloudBees Feature Management system. To use an instance of this class you need to register the instance using the ROX.register(:) method and retrieve the instance using ROX.get(:) method.

Here is an example of a class using flags and containers together
public class MyContainer : RoxContainer { //group support feature flag let groupSupport = RoxFlag() // String configuration defaulted to "Hello World" let message = RoxConfigurationString(defaultValue: "Hello World") // Bool configuration default to true let shouldShowBadge = RoxConfigurationBool(defaultValue: true) // Int configuration default to 100 let popupTimeout = RoxConfigurationInt(defaultValue: 100) // Double configuration default to let ratio = RoxConfigurationDouble(defaultValue: 0.55) } // Register MyContainer class ROX.register(MyContainer()) // Access MyContainer from any let conf = ROX.get(MyContainer.self)! // Use the Flag conf.groupSupport.enabled { print("group support enable code goes here") } print("Welcome message is '\(conf.message.value)'")

RoxContainer

Methods Description Declaration

namespace

Override this property to override the default namespace of a class

var namespace: String?

RoxFlag

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

open class ROXFlag : ROXVariant { open var isEnabled: Bool { get } open func enabled(_ codeBlock: (() -> Swift.Void)!) open func disabled(_ codeBlock: (() -> Swift.Void)!) open func enabled(_ enabledCodeBlock: (() -> Swift.Void)!, disabled disabledCodeBlock: (() -> Swift.Void)!) open var name: String! { get } } public typealias RoxFlag = ROXFlag