Swift API

6 minute readReference

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.

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. Load custom properties with ROX.setCustomProperty(key:value:).

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

MethodsDescriptionDeclarationParameter

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

shutdown()

  • This method allows for the graceful shutdown of the ROX object, and will close and clean all background tasks and threads.

  • It can only be used when ROX 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 ROX, and will register the objects to the Dashboard on the next setup call.

public static func shutdown()

register(_:)

Register a container instance to CloudBees Feature Management system.

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

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

setGlobalContext(context:)

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

public static func setGlobalContext(context: @escaping (String) → NSObject?)

context

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

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.

public static func dynamicAPI() → ROXDynamicAPI

Protocols

ProtocolsDescription

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 flag defaulted to "Hello World"
    let message = RoxString(withDefault: "Hello World")

    // Bool flag default to true
    let shouldShowBadge = RoxFlag(withDefault: true)

    // Int configuration default to 100
    let popupTimeout = RoxInt(withDefault: 100)

    // Double configuration default to
    let ratio = RoxDouble(withDefault: 0.55)
}

let conf = MyContainer()

// Register MyContainer class
ROX.register(conf)

// Use the Flag
conf.groupSupport.enabled {
    print("group support enable code goes here")
}

print("Welcome message is '\(conf.message.value)'")

RoxContainer

MethodsDescriptionDeclaration

namespace

Override this property to override the default namespace of a class

var namespace: String?

RoxString

This class is the API for string feature flags that are controlled by ROX server.

open class RoxString {
    open var name: String! { get }
    open var value: String! { get }
}

RoxFlag

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

open class RoxFlag : RoxString {
   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 }
}

RoxInt

This class is the API for integer flags that are controlled by ROX server.

open class RoxInt : RoxString {
    open var name: String! { get }
    open var value: Int { get }
}

RoxDouble

This class is the API for a floating point type flags that are controlled by ROX server.

open class RoxDouble : RoxString {
    open var name: String! { get }
    open var value: Double { get }
}