Swift API

6 minute readReference

The following information is for the latest version of the Swift SDK. If you are running an older version, please check the CloudBees Feature Management - iOS changelog for any differences.

CloudBees Feature Management is an advanced feature flagging solution that lets development teams quickly build and deploy applications without compromising on security.

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 complex configurations.

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

  • Support Optimizations: CloudBees Feature Management supports your needs for a fully capable flag system, including A/B/N testing, optimizations, and customizations.

ROX

public class ROX

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

  1. Initializing CloudBees Feature Management 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 Feature Management server and calculates configurations and target groups. public static func setup(withKey key: String)

    key

    The app key from the CloudBees Feature Management UI.

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 Feature Management server and calculates configurations and target groups. public static func setup(withKey key: String, options: ROXOptions)

    key

    a unique identifier from type String generated from CloudBees Feature Management

    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.

  • Call shutdown only if ROX is successfully set up, otherwise a log warning results.

  • You can call setup again after shutdown. Afterwards, register and setCustomProperty use a new ROX, and register the objects to the CloudBees Feature Management UI on the next setup call. public static func shutdown()

register(_:)

Register a container instance to CloudBees Feature Management.

This method should be called only once for a given class. public static func register(_ container: RoxContainer)
container

The instance to register. 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 is frozen until the next app foreground event. Calling this function unfreezes 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 shows 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 semantic versioning (semver)

value

The value of the custom property

setCustomProperty(key:value:)

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

  • Use this method to supply a code block that is evaluated on a foreground event, or when either ROX.sync() or 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.

Refer to public static func dynamicAPI() → ROXDynamicAPI.

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 CloudBees Feature Management. 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.

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

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 that are controlled by the CloudBees Feature Management server.

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

RoxFlag

This class is the API for boolean flags that are controlled by the 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 the CloudBees Feature Management server.

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 that are controlled by the CloudBees Feature Management server.

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