Swift API docs

On this page

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