C++ Client SDK

Statsig’s SDK for Experimentation and Feature Flags in C++ applications.

Source code: statsig-io/cpp-client-sdk

Set Up the SDK

This page explains set up the sdk.

1. Install the SDK

   Downloaded From GitHub

   add_subdirectory(path/to/downloaded/statsig_sdk)
   target_link_libraries(${PROJECT_NAME} StatsigClientSDK)
   ```text
   </Tab>
   
   <Tab title="FetchContent">
   ```cpp
   include(FetchContent)
   
   FetchContent_Declare(statsig
     GIT_REPOSITORY    https://github.com/statsig-io/cpp-client-sdk.git
     GIT_TAG           main
   )
   FetchContent_MakeAvailable(statsig)
   
   target_link_libraries(${PROJECT_NAME} StatsigClientSDK)
   

2. Initialize the SDK

   Next, initialize the SDK with a client SDK key from the “API Keys” tab on the Statsig console. These keys are safe to embed in a client application.

   Along with the key, pass in a User Object with the attributes you’d like to target later on in a gate or experiment.

   #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
   );
   ```text
   
   **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()`.
   
   ```cpp
   // 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
   );
   ```text
   
   **Optional** - Configuration via StatsigOptions
   
   It is possible to adjust certain aspects of how the SDK works via a [StatsigOptions](#statsig-options) struct.
   Just pass in a StatsigOptions struct during initialization.
   
   ```cpp
   StatsigOptions options;
   options.environment = StatsigEnvironment{"staging"};
   
   client.InitializeSync(..., options);
   
   // or
   
   client.InitializeAsync(..., options);
   

Use 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;

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

Getting a 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>();

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();

Statsig User

You need to provide a StatsigUser object to check/get your configurations. You should pass as much information as possible in order to take advantage of advanced gate and config conditions.

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

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 = "[e-mail]";
user.custom_ids = {
    {"employeeID", "an-employee"}
};
```python

### 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: "[e-mail]" }` 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.

```cpp
client.UpdateUserSync(user);

// or, use the shared instance

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

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.

```cpp
{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

This page explains 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.

Lifecycle & Advanced Usage

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();

How do I run experiments for logged out users?​

This page explains how do i run experiments for logged out users?​.

See the guide on device level experiments