C++ Server SDK

Statsig's Server SDK for C++ applications

View the C++ SDK source code and releases

Set up the SDK

Install the SDK

If you are using CMake, add the following to a .cmake file:

cmake

FetchContent_Declare(statsig
        GIT_REPOSITORY    https://github.com/statsig-io/cpp-server-sdk.git
        GIT_TAG           v0.1.0
)

FetchContent_MakeAvailable(statsig)

And include the following in your CMakeLists.txt file:

cmake

cmake_minimum_required(VERSION 3.11)

include(FetchContent)
include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/statsig.cmake)

Check out the latest versions on https://github.com/statsig-io/cpp-server-sdk/releases/latest

Initialize the SDK
After installation, initialize the SDK using a Server Secret Key from the Statsig console.
Don't embed your Server Secret Key in client-side applications or expose it in any external-facing documents. If you accidentally expose it, you can create a new one in the Statsig console.
cpp
#include <statsig.h> statsig::initialize('server-secret-key'); // Or, if you want to initialize with certain options statsig::Options options; options.localMode = true statsig::initialize('server-secret-key', options)
initialize performs a network request. After initialize completes, virtually all SDK operations are synchronous (refer to Evaluating Feature Gates in the Statsig SDK). The SDK fetches updates from Statsig in the background independently of API calls.

Working with the SDK

Checking a Feature Flag/Gate

After the SDK is initialized, you can fetch a Feature Gate. Feature Gates create logic branches in code that you can roll out to different users from the Statsig Console. Gates are always CLOSED or OFF (equivalent to return false;) by default.All APIs require you to specify the user (refer to Statsig user) associated with the request. For example:

cpp

statsig::User user;
user.userID = "some_user_id"
if (statsig::checkGate(user, 'use_new_feature'))
{
  // Gate is on, enable new feature
}
else {
  // Gate is off
}

Reading a Dynamic Config

Feature Gates are useful for simple on/off switches with optional user targeting. To send a different set of values (strings, numbers, and similar types) to clients based on user attributes such as country, use Dynamic Configs. The API is similar to Feature Gates, but returns a full JSON object configurable on the server from which you can fetch typed parameters.

cpp

statsig::DynamicConfig config = statsig::get_config(user, 'awesome_product_details')

auto item_name = config.value['product_name'];
auto price = config.value['price'];
auto shouldDiscount = config.value['discount'];

Getting a Layer/Experiment

Use Layers/Experiments to run A/B/n experiments. Two APIs are available. Statsig recommends Layers because they enable quicker iterations with parameter reuse.

cpp

// Values via getLayer

statsig::Layer layer = statsig::getLayer(user, "user_promo_experiments")
auto title = layer.get("title", "Welcome to Statsig!")
auto discount = layer.get("discount")

// or, via getExperiment

statsig::DynamicConfig title_exp = statsig::getExperiment(user, "new_user_promo_title")
statsig::DynamicConfig price_exp = statsig::getExperiment(user, "new_user_promo_price")

title = title_exp.value["title"]
discount = price_exp.value["discount"]

...

price = msrp * (1 - discount)

Logging an Event

To track custom events, call the Log Event API. Specify the user, event name, and an optional value or metadata object:

cpp

statsig::logEvent(user, 'add_to_cart')

Learn more about identifying users, group analytics, and best practices for logging events in the logging events guide.

Statsig User

When calling APIs that require a user, pass as much information as possible to take advantage of advanced gate and config conditions (like country or OS/browser level checks) and to correctly measure the impact of experiments on metrics and events. As explained here, at least one identifier (userID or customID) is required to provide a consistent experience for a given user.

In addition to userID, the top-level fields on StatsigUser are: email, ip, userAgent, country, locale, and appVersion. You can also pass any key-value pairs in an object or dictionary to the custom field and create targeting based on them.

While typing is lenient on the StatsigUser object, evaluation operators only work on primitive types (mostly strings and numbers). The SDK attempts to cast custom field types to match the operator, but evaluation results for non-primitive types are not guaranteed. For example, an array set as a custom field is compared only as a string.

Private Attributes

The StatsigUser object also has a privateAttributes field, which is a dictionary for setting private user attributes. The SDK uses attributes in privateAttributes only for evaluation and targeting, and removes them from logs before sending them to the Statsig server.

For example, if a feature gate should pass only for users with emails ending in "@statsig.com" but you don't want to log email addresses to Statsig, add the key-value pair { email: "my_user@statsig.com" } to privateAttributes.

Statsig Options

initialize() takes an optional options parameter in addition to the secret key to customize the Statsig client. Available options include:

api string, default "https://statsigapi.net/v1"
- The base url to use for network requests from the SDK
rulesetsSyncIntervalMs: int, default 10000
- The interval to poll for changes to your gate and config definition changes
loggingIntervalMs: int, default 60000
- The default interval to flush logs to Statsig servers
loggingMaxBufferSize: int, default 1000, can be set lower but anything over 1000 will be dropped on the server
- The maximum number of events to batch before flushing logs to the server
localMode: bool, default false
- Restricts the SDK to not issue any network requests and only respond with default values (or local overrides)

ID Lists are not supported in the C++ server SDK

Shutdown

To gracefully shut down the SDK and ensure all events are flushed:

cpp

statsig::shutdown()

Local overrides

You can override the values the SDK returns for testing. This is useful for local development when you want to test specific scenarios.

cpp

// Adding gate overrides
statsig::overrideGate("a_gate_name", true)

// Adding config overrides
std::unordered_map<std::string, JSON::any> overrideValue = {
    {"overridden key", "overridden field"},
};
statsig::overrideConfig("a_config_name", overrideValue)

FAQ

How do I run experiments for logged out users?

Refer to the guide on device level experiments.

Reference

User

cpp

struct User
{
  std::string userID;
  std::string email;
  std::string ipAddress;
  std::string userAgent;
  std::string country;
  std::string locale;
  std::string appVersion;
  std::unordered_map<std::string, JSON::any> custom;
  std::unordered_map<std::string, JSON::any> privateAttribute;
  std::unordered_map<std::string, std::string> statsigEnvironment;
  std::unordered_map<std::string, std::string> customIDs;
};
inline bool operator==(User const &a, User const &b)
{
  return a.userID == b.userID &&
          a.email == b.email &&
          a.ipAddress == b.ipAddress &&
          a.userAgent == b.userAgent &&
          a.country == b.country &&
          a.locale == b.locale &&
          a.appVersion == b.appVersion &&
          a.custom == b.custom &&
          a.privateAttribute == b.privateAttribute &&
          a.statsigEnvironment == b.statsigEnvironment &&
          a.customIDs == b.customIDs;
};

Options

cpp

struct Options
{
  std::string api;
  bool localMode;
  int rulesetsSyncIntervalMs;
  int loggingIntervalMs;
  int loggingMaxBufferSize;
  Options() : api("https://statsigapi.net"),
              localMode(false),
              rulesetsSyncIntervalMs(10 * 1000),
              loggingIntervalMs(60 * 1000),
              loggingMaxBufferSize(1000){};
};

Was this helpful?