iOS/tvOS SDK installation

Control feature rollout for certain user segments of your application with feature flags. To start using feature management in CloudBees Unify, follow the instructions below to install the SDK and deploy a feature flag.

Install the SDK

Follow these steps to install the SDK:

Select Feature management Installation.
Select an Environment from the options, or create an environment by completing the following:
1. Select Create environment.
2. Enter an Environment name.
3. (Optional) Enter a Description.
4. (Optional) Select Approvers if you want to have a manual approval required before deployment.
5. (Optional) Enter any Properties you want to associate with the environment. For more information, refer to properties configuration and properties in an environment.
6. Select Submit.
Select iOS or tvOS, as appropriate, from the language options.
Select a type of platform from the options.
Follow the instructions specific for your chosen platform to add the ROX package to your application:
Add the ROX package with Carthage
To add the ROX package with Carthage:
Add the following to the cartfile:

github "rollout/rox-spm"
▼

Run the following command in the terminal to install the Carthage dependencies:

carthage update --use-xcframeworks
▼

Add the appropriate binaries from the Carthage/Bin directory to your project.

For Objective-C: ROXCore.xcframework

For Swift: ROXCore.xcframework and ROX.xcframework
Add the ROX package with CocoaPods
To add the ROX package with CocoaPods:
Add the following to the podfile:

pod 'ROX'
▼

Run the following command in the terminal to install the CocoaPods dependencies:

pod install
▼
Add the ROX package with Swift Package Manager
To add the ROX package with Swift Package Manager, use the appropriate repositories for your project:
For Objective-C: https://github.com/rollout/rox-core-spm

For Swift: https://github.com/rollout/rox-spm
Add the ROX package with XCFramework (manual installation)
To add the ROX package with XCFramework (manual installation):
Download the latest version ROX.xcframework ZIP archive from https://github.com/rollout/rox-spm/releases.

Extract the archive into a directory within your application.

Add files in Xcode by adding the appropriate binaries for your project:

For Objective-C: ROXCore.xcframework

For Swift: ROXCore.xcframework and ROX.xcframework

Add the following code, as appropriate for your project, to import the SDK and create flags in your application:

#import <ROXCore/ROXCore.h>
@interface flags : ROXBaseContainer
@property (nonatomic) ROXFlag* enableTutorial;
@property (nonatomic) ROXString* titleColors;
@end

#import "MyContainer.h"
@implementation flags

- (instancetype)init {
  self = [super init];
  if (self) {
    self.enableTutorial = [[ROXFlag alloc] init];
    self.titleColors = [[ROXString alloc] initWithDefault:@"White" variations:@[@"Blue", @"Green", @"Yellow"]];
  }
  }
  return self;
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

        // Register the flag
    [ROX register:[[flags alloc] init]];

    // Setup the environment key
    [ROX setupWithKey:@"<YOUR-SDK-KEY>"]; (1)

    return YES;
}

[flags.enableTutorial enabled:^{
  // start the tutorial
} disabled:^{
  // skip the tutorial
}];

if ([flags.titleColors.value isEqualToString:@"Blue"]) {
    NSLog(@"Title color is Blue");
}
else if ([flags.titleColors.value isEqualToString:@"White"]) {
    NSLog(@"Title color is White");
}
else if ([flags.titleColors.value isEqualToString:@"Green"]) {
    NSLog(@"Title color is Green");
}
else if ([flags.titleColors.value isEqualToString:@"Yellow"]) {
    NSLog(@"Title color is Yellow");
}

@end▼

import ROX
import ROXCore

public class flags : RoxContainer {
let enableTutorial = RoxFlag()
let titleColors = RoxString(withDefault: "White", variations: ["White", "Blue", "Green", "Yellow"])
static let INSTANCE = flags()
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

  //Register the flags instance
  ROX.register(container: flags.INSTANCE)

  // Setup the environment key
  ROX.setup(withKey: "<YOUR-SDK-KEY>") (1)

  return true
}

flags.INSTANCE.enableTutorial.enabled {
}

switch flags.titleColors!.value()! {
case "White":
print("Title color is White")
case "Blue":
print("Title color is Blue")
case "Green":
print("Title color is Green")
case "Yellow":
print("Title color is Yellow")
default:
print("Title color is default - White")
}▼

1	CloudBees Unify provides the unique SDK key for your environment at the `<YOUR-SDK-KEY>` location within the `Rox.setup` call.

Run your application and then select Test integration to confirm a successful connection.

After running the application, flags added in the code are automatically added to your feature flag list.

You have installed an SDK and created flags in your application.

App Groups support for app extensions

If your iOS app includes extensions such as widgets, keyboards, or share extensions, enable App Groups to ensure that your main app and all extensions share the same user identity and feature flag values. Without App Groups, the SDK counts each extension as a separate user, which inflates user counts and causes inconsistent flag evaluations across your app.

Why use App Groups?

When you properly configure App Groups:

The main app and all extensions share a single user identity
User count metrics are accurate
All app components receive consistent feature flag values
Analytics accurately reflect actual user behavior

When you do not configure App Groups:

The SDK treats each extension (for example, widgets, keyboards, and share extensions) as a separate user
This inflates user count metrics, making it appear as more users than actually exist
Each extension may receive different feature flag values
Analytics data becomes inaccurate

Who needs to configure App Groups?

If your app has no extensions: No action is required; the SDK works without App Groups configuration.
If your app has extensions: Follow the setup steps below.

Set up App Groups in Xcode

Before using the SDK’s appGroupIdentifier option, you must enable the App Groups capability in Xcode for both your main app and each extension target.

Open your project in Xcode.
Select your main app target.
Select the Signing & Capabilities tab.
Select + Capability and add App Groups.
Select + to create a new App Group container, or select an existing one.
1. Use a reverse-DNS format identifier such as group.com.yourcompany.yourapp.
Repeat these steps for each extension target (for example, widgets, keyboards, and share extensions), using the same App Group identifier.

Use the exact same App Group identifier across all targets to share data.

Configure the SDK to use App Groups

After enabling App Groups in Xcode, configure the SDK to use the App Group identifier when initializing.

let options = ROXOptions()
options.appGroupIdentifier = "group.com.yourcompany.yourapp"
ROX.setup(withKey: "your-sdk-key", options: options)▼

ROXOptions *options = [[ROXOptions alloc] init];
options.appGroupIdentifier = @"group.com.yourcompany.yourapp";
[ROX setupWithKey:@"your-sdk-key" options:options];▼

Replace "group.com.yourcompany.yourapp" with the App Group identifier you created in Xcode.

After configuration, the SDK persists user identity in the shared App Group container. The SDK counts your main app and all extensions as a single user and delivers identical feature flag values.