Install client-side SDKs

Install and configure client-side SDKs to enable feature flag evaluation directly on user devices such as web browsers, mobile apps, desktop applications, and OTT platforms. Client-side SDKs provide fast flag evaluation with minimal latency since processing occurs locally on the user’s device.

For conceptual information about feature management architecture, refer to Understanding feature management.

CloudBees Unify requires SDK version 6.x or later. Ensure you have access to your application’s source code and dependency management system before beginning installation.

Choose your client-side platform

Identify the appropriate SDK based on your application platform and verify platform-specific requirements.

Client-side SDKs are designed for applications that run in user environments where flag evaluation must be fast and responsive:

Web applications: JavaScript/TypeScript running in browsers
Mobile applications: Android, iOS, and tvOS native apps
Cross-platform mobile: React Native applications
OTT platforms: Android TV, Fire TV, Chromecast, and Tizen applications

To select your platform:

Determine your application type from the supported client-side platforms.
Verify you have the appropriate development environment and package manager installed.
Confirm your target platform supports SDK version 6.x or later.

Install the SDK package

Add the CloudBees Unify SDK to your application using platform-specific package managers and installation procedures.

You must have an existing feature management application and environment set up in CloudBees Unify before installing the SDK.

To install the SDK package:

Access the installation instructions in CloudBees Unify:
1. Navigate to Feature management Flags.
2. Select the installation instructions icon to open the guided setup.
3. Select your target environment or create a new environment if needed.
Choose your platform and package manager:
1. Select your platform from the language options (JavaScript, Android, iOS, React Native).
2. Choose the appropriate package manager for your project.
Install the SDK using platform-specific commands:

For JavaScript/browser applications:

# npm
npm install rox-browser --save

# yarn
yarn add rox-browser

# TypeScript projects also need:
npm install @types/rox-browser --save▼

For Android applications: Add to your build.gradle dependencies:

implementation 'io.rollout.rox:rox-android:6.0.0'▼

For iOS/tvOS applications: Add to your Podfile:

pod 'Rox'▼

For React Native applications:

# npm
npm install rox-react-native --save

# yarn
yarn add rox-react-native▼

After installation, the SDK package appears in your project dependencies and is ready for configuration.

Configure SDK initialization

Set up the SDK in your application entry point and configure any platform-specific requirements.

Add required permissions (mobile platforms)

For Android applications, add internet permissions to AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />▼

Place the uses-permission tags outside the application tag to enable internet access.

Initialize the SDK

Add SDK initialization code to your application’s main entry point:

For JavaScript applications:

import Rox from 'rox-browser';

// Initialize SDK (setup call comes after flag registration)▼

For Android applications: Add to the onCreate() method of your Application class:

import android.app.Application;
import io.rollout.android.Rox;

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // SDK setup occurs after flag registration
    }
}▼

For iOS applications: Add to your AppDelegate:

import Rox

// Setup occurs in application didFinishLaunchingWithOptions▼

For React Native applications:

import Rox from 'rox-react-native';

// Initialize in your main App component▼

Set up feature flags

Define flag containers with typed flags and register them with the SDK before initialization.

Create flag definitions

Define your feature flags using strongly-typed flag objects that specify default values and available variations:

JavaScript example:

const flags = {
  enableTutorial: new Rox.Flag(),
  titleColors: new Rox.RoxString('White', ['White', 'Blue', 'Green', 'Yellow']),
  titleSize: new Rox.RoxNumber(12, [14, 18, 24])
};▼

Android example:

import io.rollout.configuration.RoxContainer;
import io.rollout.flags.RoxFlag;
import io.rollout.flags.RoxString;

public class Flags implements RoxContainer {
    public RoxFlag enableTutorial;
    public RoxString titleColors;

    public Flags() {
        this.enableTutorial = new RoxFlag(false);
        this.titleColors = new RoxString("White",
            new String[]{"White", "Blue", "Green", "Yellow"});
    }
}▼

Register flags and initialize SDK

JavaScript complete setup:

import Rox from 'rox-browser';

const flags = {
  enableTutorial: new Rox.Flag(),
  titleColors: new Rox.RoxString('White', ['White', 'Blue', 'Green', 'Yellow'])
};

async function initializeFeatureFlags() {
  Rox.register('default', flags);
  await Rox.setup('YOUR-SDK-KEY');

  // Use flags after setup completes
  if (flags.enableTutorial.isEnabled()) {
    // Feature code here
  }
}

initializeFeatureFlags();▼

Android complete setup:

public class App extends Application {
    private Flags flags;

    @Override
    public void onCreate() {
        super.onCreate();

        flags = new Flags();
        Rox.register(flags);
        Rox.setup(this); // SDK key configured in AndroidManifest.xml

        // Use flags after setup
        if (flags.enableTutorial.isEnabled()) {
            // Feature code here
        }
    }
}▼

Configure SDK key

Retrieve and configure your environment-specific SDK key from CloudBees Unify:

Navigate to Feature management Flags and select your application.
Copy the SDK key displayed for your target environment.
Configure the key in your application:

For JavaScript/React Native: Pass the key directly to the Rox.setup() call.

For Android: Add the key to AndroidManifest.xml inside the application tag:

<meta-data
  android:name="rox.apiKey"
  android:value="YOUR-SDK-KEY" />▼

For iOS: Configure the key in your setup call or Info.plist.

Keep SDK keys secure and avoid committing them directly to source control. Use environment variables or secure configuration management.

Configure iOS app extensions with App Groups

If your iOS app includes extensions such as widgets, keyboards, or share extensions, configure App Groups so 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.

If your iOS app has no extensions, skip this section.

Enable App Groups in Xcode

Before configuring the SDK, enable the App Groups capability for both your main app target 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. Use a reverse-DNS format identifier, for example group.com.yourcompany.yourapp.
Repeat these steps for each extension target (widgets, keyboards, share extensions), using the same App Group identifier.

Initialize the SDK with the App Group identifier

After enabling App Groups in Xcode, pass the App Group identifier when initializing the SDK. Use the same identifier across all targets.

Swift:

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

Objective-C:

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

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

Test integration

Verify the SDK installation and connection to CloudBees Unify using the built-in integration testing features.

To test your integration:

Run your application with the SDK initialization code.
Return to the CloudBees Unify installation interface and select Test Integration.
Confirm the connection status shows as successful.

If the test integration succeeds, you see a confirmation message and your flags automatically appear in the CloudBees Unify feature flag list.

Common integration issues:

Problem: Test integration fails or times out

Solution: Verify your SDK key is correct and your application has internet connectivity. Check that flag registration occurs before the Rox.setup() call.

Problem: Flags don’t appear in the CloudBees Unify interface

Solution: Ensure your application runs completely through the SDK initialization process. Flags only sync to CloudBees Unify after successful SDK setup.

Problem: Network connectivity errors

Solution: Verify your application has appropriate internet permissions and can access CloudBees servers. Check firewall and proxy configurations.