C++ API

7 minute readReference

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

ROX C++ header

#import <roxx/server.h>

Rox Namespace

The Rox namespace provides an interface for CloudBees Feature Management to manage feature flags that control the behavior of your application. This is the central repository for your application’s flags. This namespace handles communications with the server to obtain the latest flag values, implement flag settings, and set up flag configurations. The values in the namespace are marked as feature flags and display in the CloudBees Feature Management UI once the application is run.

These classes and interfaces also allow you to manage custom properties. These can be static settings of type string, boolean, integer, or double, or you can use a generator class to provide a custom property that is dependent upon code state. These generated properties must derive from CustomPropertyGeneratorInterface.

You can also use an Options object to configure some aspects of feature flag management in CloudBees Feature Management. You can set the custom platform, impression handler, dynamic properties rule, and configuration fetched handler.

Setup

StateCode Setup(const char *api_key, Options *options = nullptr)

Configures the Rox object to work with the provided application.

Parameter Modifier and Type Description

apiKey

const char *

The environment key provided by the dashboard

options

Options*

A Options instance with the desired configuration for this application.

Return value

typedef enum RoxStateCode { RoxUninitialized = 0, RoxSettingUp = 1, RoxInitialized = 2, RoxShuttingDown = 3, RoxErrorEmptyApiKey = -1, RoxErrorInvalidApiKey = -2, RoxErrorGenericSetupFailure = -1000 } RoxStateCode;

In case of a successful call, Setup will return RoxInitialized code. Otherwise, the application logs should be analyzed for errors and warnings. If Setup returned failure code, it may be called again after fixing the errors from the logs.

Shutdown

void Shutdown()

Frees all Rox Internal Objects. Should be used on application exit.

Setup may be called again after Shutdown.

Example

// application start Rox::Setup(DEFAULT_API_KEY) // application end Rox::Shutdown();

SetContext

void SetContext(Context *context)

Set a global context. This context will be available to all flags evaluations (in addition to the specific call context).

Fetch

void Fetch()

Create a network request for the latest configuration.

Custom Properties

The role of Custom Properties is to segment the audience.

The custom properties can be these types:

  • bool

  • int

  • double

  • semver

  • string

There are simple (direct) Custom Properties and calculated ones, using RoxContext to be more dynamic.

Simple (direct) Custom Properties

SetCustomProperty

template<typename T> void SetCustomProperty(const char *name, T value)

Sets a custom property representing a T value.

Parameter Modifier and Type Description

name

const char *

The name of the property to create

value

T

The value for the custom property depends on the type

SetCustomSemverProperty

voidSetCustomSemverProperty(const char *name, const char *value)

Sets a custom property representing a semver value.

Parameter Modifier and Type Description

name

const char *

The name of the property to create

value

const char *

The semver value for the custom property

Computed Custom properties (using RoxContext)

SetCustomComputedProperty

template<typename T> void SetCustomComputedProperty(const char *name, CustomPropertyGeneratorInterface *generator)

Sets a computed T Custom Property on the Rox client. This is a computable T, with an object that generates the value for the property. The generator should be a delegate of type CustomPropertyGeneratorInterface.

Parameter Modifier and Type Description

name

const char *

The name of the property to create

generator

CustomPropertyGeneratorInterface *

A CustomPropertyGeneratorInterface class

SetCustomComputedSemverProperty

void SetCustomComputedSemverProperty(const char *name, CustomPropertyGeneratorInterface *generator)

Sets a computed semver Custom Property on the Rox client. This is a computable semver, with an object that generates the value for the property. The generator should be a delegate of type CustomPropertyGeneratorInterface.

Parameter Modifier and Type Description

name

string

The name of the property to create

generator

CustomPropertyGeneratorInterface *

A CustomPropertyGeneratorInterface class

Class Options

RoxOptions covers configuration options for the Rox client. This includes settings like configuration fetch interval, impression handler and more.

Instances of this class should be created using OptionsBuilder.

Here is an example of setting up a new Options object. This options object sets the version, provides an impression handler, and calls the fetch handler.

class ImpressionHandler : public Rox::ImpressionHandlerInterface { public: explicit ImpressionHandler() {} public: void HandleImpression( RoxReportingValue *value, RoxExperiment *experiment, RoxContext *context) { // TODO: do something on impression } }; class ConfigurationFetchedHandler : public Rox::ConfigurationFetchedHandlerInterface { public: explicit ConfigurationFetchedHandler() { } public: void ConfigurationFetched(Rox::ConfigurationFetchedArgs *args) override { // TODO: do something on configuration fetched } }; class DynamicRulerHandler : public Rox::DynamicPropertiesRuleInterface { public: explicit DynamicRulerHandler() {} public: DynamicValue *Invoke(const char *propName, Context *context) { // TODO: return a DynanmicValue } }; int main(int argc, char **argv) { ImpressionHandler imp = ImpressionHandler(); ConfigurationFetchedHandler conf = ConfigurationFetchedHandler(); DynamicRulerHandler dynamicRule = DynamicRulerHandler(); Rox::Options *options = Rox::OptionsBuilder() .SetConfigurationFetchedHandler(&conf) .SetDevModeKey("your_dev_mode_secret") .SetDynamicPropertiesRule(&dynamicRule) .SetImpressionHandler(&imp) .SetRoxyUrl("http://localhost:4444") .SetVersion("2.1.0") .SetFetchInterval(100) .Build(); Rox::Setup("ROLLOUT_KEY", options); // do something... Rox::Shutdown(); }

Class OptionsBuilder

This Builder class is used to create a new Options instance.

SetVersion

OptionsBuilder &SetVersion(const char *version);

Set the version of the service running the CloudBees Feature Management SDK. This can be used on the dashboard for targeting filtering.

SetFetchInterval

OptionsBuilder &SetFetchInterval(int intervalInSeconds)

Set the polling interval for fetching configuration from the CloudBees Feature Management storage service.

SetConfigurationFetchedHandler

OptionsBuilder &SetConfigurationFetchedHandler(ConfigurationFetchedHandlerInterface *handler)

Set the configuration event handler to actions after configurations are fetched.

SetImpressionHandler

OptionsBuilder &SetImpressionHandler(ImpressionHandlerInterface *handler)

Set the impression event handler to add actions after an impression.

SetDynamicPropertiesRule

OptionsBuilder &SetDynamicPropertiesRule(DynamicPropertiesRuleInterface *rule)

The Dynamic Custom Property Generator is called when an explicit Custom property definition does not exists on the client side.

If you do not set the SetDynamicPropertiesRule, it will then activate the default function which tries to extract the prop value from the context by its name.

if (context != NULL) { return rox_context_get(context, prop_name); } return NULL;

Class DynamicPropertiesRuleInterface

Create a custom dynamic property rule, by overriding this class.

Invoke
virtual DynamicValue *Invoke(const char *propName, Context *context) = 0

See C API RoxDynamicValue for DynamicValue.

For an example, see Defining custom properties.

SetRoxyUrl

OptionsBuilder &SetRoxyUrl(const char *roxy_url)

SetDevModeKey

OptionsBuilder &SetDevModeKey(const char *devModeKey)

Set dev mode secret.

Build

Options *Build()

Creates the options object with all the property that were set.

Class Flag

GetName

const char *GetName()

Returns the flag’s name.

Create

static Flag *Create(const char *name, bool defaultValue = false)

Create a Flag with a default value.

IsEnabled

bool IsEnabled(Context *context = nullptr)

Returns the feature flag’s current value, or the default if no value was set.

Class String

String is a feature flag containing string values.

GetName

const char *GetName()

Returns the flag’s name.

GetValue

char *GetValue(Context *context = nullptr)

Returns the feature flag’s current value, or the default if no value was set.

Create

static Flag *Create(const char *name, bool defaultValue = false) static String *Create(const char *name, const char *defaultValue, const std::vector<std::string> &options);

Create a String with default value and options.

Class Int

Int is a feature flag containing integer values.

GetName

const char *GetName()

Returns the flag’s name.

GetValue

int GetValue(Context *context = nullptr)

Returns the feature flag’s current value, or the default if no value was set.

Create

static Int *Create(const char *name, int defaultValue) static Int *Create(const char *name, int defaultValue, const std::vector<int> &options);

Create a Int with default value and options.

Class Double

Double is a feature flag containing double precision values.

GetName

const char *GetName()

Returns the flag’s name.

GetValue

double GetValue(Context *context = nullptr)

Returns the feature flag’s current value, or the default if no value was set.

Create

static Double *Create(const char *name, double defaultValue) static Double *Create(const char *name, double defaultValue, const std::vector<double> &options);

Create a Double with default value and options.

Class Context

The context class is used to pass data to the feature flag evaluation. This object is used by the registered CustomProperties to evaluate the experiment expression and return the value.

You can create a context using the ContextBuilder.

Class ContextBuilder

ContextBuilder

ContextBuilder()

A simple constructor.

AddBoolValue

ContextBuilder &AddBoolValue(const char *name, bool value)

Adds a bool value to the name key in the context.

AddIntValue

ContextBuilder &AddIntValue(const char *name, int value)

Adds a int value to the name key in the context.

AddDoubleValue

ContextBuilder &AddDoubleValue(const char *name, double value)

Adds a double value to the name key in the context.

AddStringValue

ContextBuilder &AddStringValue(const char *name, const char *value)

Adds a string value to the name key in the context.

AddUndefined

ContextBuilder &AddUndefined(const char *name)

Adds an undefined value to the name key in the context.

AddNull

ContextBuilder &AddNull(const char *name)

Adds a NULL value to the name key in the context.

Build

Context *Build()

Builds the Context to use in the evaluation of Flag and Variant.

For an example, see Flag context.

Using ConfigurationFetchedHandler

As seen in OptionsBuilder, SetConfigurationFetchedHandler can be used to write a handler for after new configurations request. To do so, implement ConfigurationFetchedHandlerInterface.

Class ConfigurationFetchedHandlerInterface

ConfigurationFetched

virtual void ConfigurationFetched(ConfigurationFetchedArgs *args) = 0

For ConfigurationFetchedArgs, please see RoxConfigurationFetchedArgs C API.

For an example, see Configuration fetched handler.

Using ImpressionHandler

The impression handler delegate (as seen in OptionsBuilder SetImpressionHandler) has a couple of useful parameters which can help you decide on further actions.

To use the impressions handler implement the class ImpressionHandlerInterface.

Class ImpressionHandlerInterface

HandleImpression

virtual void HandleImpression(ReportingValue *value, Experiment *experiment, Context *context) = 0

See C API RoxReportingValue (for ReportingValue) and RoxExperiment (for Experiment).

For an example, see Impression handler.

Class DynamicApi

DynamicApi is a way to evaluate flags and variants by their name, on the fly, without creating a Flag or Variant object before (using their Create method).

Create

static DynamicApi *Create()

Create a DynamicApi, the proxy to all dynamic flags and variants evaluation.

IsEnabled

bool IsEnabled(const char *name, bool default_value = false, Context *context = nullptr)

Evaluate a flag by its name, and context.

If no experiment was set via the dashboard, the default_value will be returned.

GetString/GetInt/GetDouble - obtain flag value

char *GetString(const char *name, char *default_value = nullptr, Context *context = nullptr); char *GetString(const char *name, char *default_value, const std::vector<std::string> &options, Context *context); int GetInt(const char *name, int default_value, Context *context = nullptr) int GetInt(const char *name, int default_value, const std::vector<int> &options Context *context) double GetDouble(const char *name, double default_value, Context *context = nullptr); double GetDouble(const char *name, double default_value, const std::vector<double> &options, Context *context);

Evaluate a feature flag by its name, and context. Options will be sent to the dashboard to allow an easy pick in the experiment.

If no experiment was set via the dashboard, the default_value will be returned.

For an example, see Dynamic API.

Logging

Logging helps debug in case something behave unexpectedly.

If no logging was set, default will be used, this means print to stdout errors level logs.

There are 2 method to control logging:

SetLogLevel

static void SetLogLevel(LogLevel logLevel)

To use the default logging, with a different log level.

See RoxLogLevel in C API.

SetLogMessageHandler

static void SetLogMessageHandler(LogMessageHandlerInterface *handler)

To use a customized logger, this is done by providing a class that implements LogMessageHandlerInterface.

Class LogMessageHandlerInterface

HandleLogMessage

virtual void HandleLogMessage(LogMessage *message) = 0

The customized logging handler. See RoxLogMessage C API for LogMessage.

For an example, see Turning on verbose logging.

C++ is a C wrapper

Didn’t find what you were looking for? Please look in C Api, some structs have a matching struct without the Rox prefix (For Example C’s RoxDynamicValue ⇒ C++'s DynamicValue)

Still no luck? Please submit a product request directly to CloudBees Support.