C++ Server SDK

Set up the SDK

1. Install the SDK

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

   cmake

   Copy

   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

   Copy

   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

2. 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

   Copy

   #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 you initialize the SDK, 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:

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.

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.

// 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:

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 in the server SDK user ID requirements, Statsig requires at least one identifier (userID or customID) 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.

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:

Shutdown

To gracefully shut down the SDK and flush all events:

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.

// 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

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

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){};
};