Skip to main content

C++ Client SDK

Installation​

To include the Statsig C++ SDK in your project. You can download it from GitHub or use CMake's FetchContent.

Then in your CMakeLists.txt file, do the following:

add_subdirectory(path/to/downloaded/statsig_sdk)
target_link_libraries(${PROJECT_NAME} StatsigClientSDK)

Initialize the SDK​

After installation, you will need to initialize the SDK using a Client SDK key from the "API Keys" tab on the Statsig console.

These Client SDK Keys are intended to be embedded in client side applications. If need be, you can invalidate or create new SDK Keys for other applications/SDK integrations.

info

Do NOT embed your Server Secret Key in client-side applications, or expose it in any external-facing documents. However, if you accidentally expose it, you can create a new one in the Statsig console.

In addition to the SDK key, you should also pass in a StatsigUser for feature gate targeting and experimentation grouping purposes.

The 3rd parameter is optional and allows you to pass in a [StatsigOptions](#statsig-options) to customize the SDK.
#include <statsig/statsig.h>

using namespace statsig;

StatsigUser user;
user.user_id = "a-user";
user.custom_ids = {
    {"employeeID", "an-employee"}
};

// Create your own instance
StatsigClient client;

// Initialize synchronously using cached values from the previous session
client.InitializeSync("client-{YOUR_CLIENT_SDK_KEY}", user);

// or, Initialize asynchronously from network
client.InitializeAsync(
    "client-{YOUR_CLIENT_SDK_KEY}", 
    [](StatsigResultCode result) {
        // completion callback
    }, 
    user
);

Synchronous initialization will leverage cache (if available), returning immediately. Data for subsequent sessions will then be fetched in the background.

Asynchronous initialization, on the other hand provides a callback, allowing you to wait for the most current data to be fetched.

For convenience, there is also a singleton instance that can be accessed via StatsigClient::Shared().

// Initialize synchronously using cached values from the previous session
StatsigClient::Shared().InitializeSync("client-{YOUR_CLIENT_SDK_KEY}", user);

// or, Initialize asynchronously from network
StatsigClient::Shared().InitializeAsync(
    "client-{YOUR_CLIENT_SDK_KEY}", 
    [](StatsigResultCode result) {
        // completion callback
    }, 
    user
);

Optional - Configuration via StatsigOptions

It is possible to adjust certain aspects of how the SDK works via a StatsigOptions struct. Just pass in a StatsigOptions struct during initialization.

StatsigOptions options;
options.environment = StatsigEnvironment{"staging"};

client.InitializeSync(..., options);

// or

client.InitializeAsync(..., options);

Working with the SDK​

Checking a Feature Flag/Gate​

Now that your SDK is initialized, let's check a Feature Gate. Feature Gates can be used to create logic branches in code that can be rolled out to different users from the Statsig Console. Gates are always CLOSED or OFF (think return false;) by default.

if (client.CheckGate("a_gate")) {
  // show new feature
}

// or, use the shared instance

if (StatsigClient::Shared().CheckGate("a_gate")) {
  // show new feature
}

Reading a Dynamic Config​

Feature Gates can be very useful for simple on/off switches, with optional but advanced user targeting. However, if you want to be able send a different set of values (strings, numbers, and etc.) to your clients based on specific user attributes, e.g. country, Dynamic Configs can help you with that. The API is very similar to Feature Gates, but you get an entire json object you can configure on the server and you can fetch typed parameters from it. For example:

DynamicConfig config = client.GetDynamicConfig("a_config");

// or, use the shared instance

DynamicConfig config = StatsigClient::Shared().GetDynamicConfig("a_config");

// then access the params
std::cout << config.GetValue()["a_string_param"] << std::endl;
info

DynamicConfig.GetValue returns JsonObj which is an unordered map of string to nlohmann/json. See https://github.com/nlohmann/json

Getting an Layer/Experiment​

Then we have Layers/Experiments, which you can use to run A/B/n experiments. We offer two APIs, but we recommend the use of layers to enable quicker iterations with parameter reuse.

// Values via getLayer

Layer layer = StatsigClient::Shared().GetLayer("name");
std::string promoTitle = layer.GetValue("title").get<std::string>();
double discount = layer.GetValue("discount").get<double>();

// or, via getExperiment

Experiment titleExperiment = StatsigClient::Shared().GetExperiment("new_user_promo_title");
Experiment priceExperiment = StatsigClient::Shared().GetExperiment("new_user_promo_price");

std::string promoTitle = titleExperiment.GetValue()["title"].get<std::string>();
double discount = priceExperiment.GetValue()["discount"].get<double>();
info

Layer.GetValue and Experiment.GetValue return JsonObj which are unordered maps of string to nlohmann/json. See https://github.com/nlohmann/json

Logging an Event​

Now that you have a Feature Gate or an Experiment set up, you may want to track some custom events and see how your new features or different experiment groups affect these events. This is super easy with Statsig - simply call the Log Event API for the event, and you can additionally provide some value and/or an object of metadata to be logged together with the event:

std::unordered_map<std::string, std::string> metadata{
    { "price", "9.99" },
    { "item_name", "some_great_product" }
};

StatsigEvent event("add_to_cart", "SKU_12345", metadata);
StatsigClient::Shared().LogEvent(event);

// Then, at some point later, you need to "flush" the events
StatsigClient::Shared().Flush();

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

Statsig User​

You should provide a StatsigUser object whenever possible when initializing the SDK, passing as much information as possible in order to take advantage of advanced gate and config conditions (like country or OS/browser level checks).

Most of the time, the userID field is needed in order to provide a consistent experience for a given user (see logged-out experiments to understand how to correctly run experiments for logged-out users).

If the user is logged out at the SDK init time, you can leave the `userID` out for now, and we will use a stable device ID that we create and store in the local storage for targeting purposes.

Besides userID, we also have email, ip, userAgent, country, locale and appVersion as top-level fields on StatsigUser. In addition, you can pass any key-value pairs in an object/dictionary to the custom field and be able to create targeting based on them.

Once the user logs in or has an update/changed, make sure to call `updateUser` with the updated `userID` and/or any other updated user attributes:
StatsigUser user;
user.user_id = "a-user";
user.email = "developer@statsig.com";
user.custom_ids = {
    {"employeeID", "an-employee"}
};

Private Attributes​

Have sensitive user PII data that should not be logged? No problem, we have a solution for it! On the StatsigUser object we also have a field called privateAttributes, which is a simple object/dictionary that you can use to set private user attributes. Any attribute set in privateAttributes will only be used for evaluation/targeting, and removed from any logs before they are sent to Statsig server.

For example, if you have feature gates that should only pass for users with emails ending in "@statsig.com", but do not want to log your users' email addresses to Statsig, you can simply add the key-value pair { email: "my_user@statsig.com" } to privateAttributes on the user and that's it!

Updating Users​

At some point, your user might need to change. To make Statsig aware of this new user, you will need to make a call to an UpdateUser function.

client.UpdateUserSync(user);

// or, use the shared instance

StatsigClient::Shared().UpdateUserSync(user);

If you want to ensure you have the latest values for an update (Say you are transition from logged out to logged in). You can use the Asynchronous update function.

{client or StatsigClient::Shared()}.UpdateUserAsync(
    user,
    [](StatsigResultCode result) {
        if (result == StatsigResultCode::Ok) {
          // do something now that the latest values have been fetched
        } else {
          // error state
        }
    }
);

Asynchronous vs Synchronous behaviors are the same as the Initialize functions.

Statsig Options​

StatsigClient::Initialize, in addition to sdk_key and user, takes an optional parameter options that you can provide to customize the StatsigClient. Here are the current options and we are always adding more to the list:

  • api: std::string, default https://statsigapi.net

    • The API to use for all SDK network requests. You should not need to override this unless you have another API that implements the Statsig API endpoints.

  • providers: EvaluationsDataProvider, default LocalFileCache then Network

    • Array of EvaluationsDataProvider, used to customize the initialization and update behavior.

Shutting Statsig Down​

In order to save users' data and battery usage, as well as prevent logged events from being dropped, we keep event logs in client cache and flush periodically. Because of this, some events may not have been sent when your app shuts down.

To make sure all logged events are properly flushed or saved locally, you should tell Statsig to shutdown when your app is closing:

client.Shutdown();

// or, use the shared instance

StatsigClient::Shared().Shutdown();

FAQ​

How do I run experiments for logged out users?​

See the guide on device level experiments