C++ Server SDK

Statsig's Server SDK for C++ applications

Set up the SDK

Install the SDK

If you're 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 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:

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

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 Statsig doesn't guarantee evaluation results for non-primitive types. For example, the SDK compares an array set as a custom field 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:

Option	Type	Default	Description
`api`	String	`"https://statsigapi.net/v1"`	Base URL for network requests from the SDK.
`rulesetsSyncIntervalMs`	Integer	`10000`	Interval to poll for changes to your gate and config definitions.
`loggingIntervalMs`	Integer	`60000`	Interval to flush logs to Statsig servers.
`loggingMaxBufferSize`	Integer	`1000`	Maximum number of events to batch before flushing logs to the server. You can set a lower value, but the server drops anything over 1000.
`localMode`	Boolean	`false`	Restricts the SDK from issuing network requests; the SDK responds only with default values or local overrides.

The C++ server SDK doesn't support ID Lists

Shutdown

To gracefully shut down the SDK and flush all events:

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?