Swift SDK reference

5 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.

ROX

public class ROX

ROX class is a static Swift class that acts as a facade interface. Use for:

  1. Initializing the CloudBees platform SDK using ROX.setup(withKey:).

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

  3. Loading custom properties with ROX.setCustomProperty(key:value:).

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

setup(withKey:)

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

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

  • Executes an async network call to fetch the flag container from the CloudBees platform using the environment-specific SDK key, and calculates configurations and target groups with public static func setup(withKey key: String).

setup(withKey:options:)

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

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

  • Executes an async network call to fetch the flag container from the CloudBees platform using the environment-specific SDK key, and calculates configurations and target groups with public static func setup(withKey key: String).

shutdown()

public static func shutdown()
▼

  • This method allows for the graceful shutdown of the ROX object, and closes and cleans all background tasks and threads.

  • Call shutdown only if ROX is successfully set up. Calling shutdown when it is not possible results in a log warning.

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

register(_:)

Register a container instance to the CloudBees platform. Values are set at ROX.sync(), ROX.setup(withKey:), or if the app goes into the foreground.

Call this method only once for a given class. 
public static func register(_ container: RoxContainer)
▼

unfreeze()

  • Unfreezes the state of all flags in the code.

  • When a flag is used in code, its value is frozen until the next app foreground event. Call this function to unfreeze all flags.

  • After unfreezing, using a flag returns its most updated value.

public static func unfreeze()
▼

flagsViewController()

  • A view to control feature flag 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
▼

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)
▼
Parameter Description

key

The name of the custom property.

asSemver

Whether the string is computed and treated as a semver. Refer to the Semantic Versioning documentation for more information.

value

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 a foreground event or when either ROX.sync() or ROX.setup(withKey:) is called.

static func setCustomProperty(key: String, asSemver: Bool, value: @escaping () -> String)
▼
Parameter Description

key

The name of the custom property.

asSemver

Whether the string is computed and treated as a semver. Refer to the Semantic Versioning documentation for more information.

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.

Use as in the following examples:

public static func setCustomProperty(key: String, value: Bool)
▼
public static func setCustomProperty(key: String, value: Int32)
▼
public static func setCustomProperty(key: String, value: String)
▼
Parameter Description

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 want to supply a block of code for evaluation on a foreground event, or when either ROX.sync() or ROX.setup(withKey:) is called.

Use as in the following examples:

public static func setCustomProperty(key: String, value: @escaping () -> Bool)
▼
public static func setCustomProperty(key: String, value: @escaping () -> Int32)
▼
public static func setCustomProperty(key: String, value: @escaping () -> String)
▼
Parameter Description

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.

Use as in the following examples:

public static func setCustomProperty(key: String, value: @escaping() -> Double)
▼
public static func setCustomProperty(key: String, value: Double)
▼
Parameter Description

key

The name of the custom property

value

A code block to return the value of the custom property

setGlobalContext(context:)

Sets a global context, a function that retrieves a custom property value from the given key. This context is available to all flag evaluations in addition to the specific call context.

public static func setGlobalContext(context: @escaping (String) -> NSObject?)
▼

dynamicAPI()

This enables you to evaluate flags without having a static container. dynamicAPI() creates flags as if they were registered, including sending them to the UI. An alternative to using RoxContainer with register(_:).

Refer to public static func dynamicAPI() → ROXDynamicAPI.

RoxContainer

RoxContainer is 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 platform. To use an instance of this class, you must register the instance using the ROX.register(_:) method and retrieve the instance using the ROX.get(_:) method.

The following is an example of a class using both 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)'")
▼
Methods Description Declaration

namespace

Override this property to override the default namespace of a class

var namespace: String?

RoxString

This class is the API for string flags controlled by the platform.

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

RoxFlag

This class is the API for Boolean flags controlled by the platform.

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 controlled by the platform.

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

RoxDouble

This class is the API for floating-point type flags controlled by the platform.

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