C++ Client SDK

Set Up the SDK

1. Install the SDK

   Downloaded From GitHubFetchContent

   cpp

   Copy

   add_subdirectory(path/to/downloaded/statsig_sdk)
   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.

   cpp

   Copy

   #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 uses cache (if available) and returns immediately. Data for subsequent sessions is then fetched in the background.

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

   For convenience, there is also a singleton instance accessible through StatsigClient::Shared().

   cpp

   Copy

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

   To adjust how the SDK works, pass a StatsigOptions struct during initialization.

   cpp

   Copy

   StatsigOptions options;
   options.environment = StatsigEnvironment{"staging"};
   
   client.InitializeSync(..., options);
   
   // or
   
   client.InitializeAsync(..., options);
   

Use the SDK

Checking a Feature Flag/Gate

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 work well for simple on/off switches with optional advanced user targeting. To send a different set of values (strings, numbers, and so on) to clients based on specific user attributes such as country, use Dynamic Configs. The API is similar to Feature Gates, but returns an entire JSON object you configure on the server, from which you can fetch typed parameters. 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;

Getting a Layer/Experiment

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

Logging an Event

After setting up a Feature Gate or an Experiment, you can track custom events to see how your new features or different experiment groups affect those events. Call the Log Event API for the event, and optionally provide a value and metadata object to be logged 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 or get your configurations. Pass as much information as possible to take advantage of advanced gate and config conditions.

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

StatsigUser user;
user.user_id = "a-user";
user.email = "developer@statsig.com";
user.custom_ids = {
    {"employeeID", "an-employee"}
};

Private attributes

To prevent sensitive user PII from being logged, use the privateAttributes field on the StatsigUser object. Any attribute set in privateAttributes is used only for evaluation and targeting, and Statsig removes it from logs before sending them to the server.

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

Updating users

When user data changes, call an UpdateUser function to make Statsig aware of the new user.

client.UpdateUserSync(user);

// or, use the shared instance

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

To ensure you have the latest values during an update (for example, when transitioning from logged out to logged in), 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 options parameter to customize the StatsigClient. Current options are listed below:

Shutting Statsig Down

To save data and battery usage and prevent logged events from being dropped, the SDK keeps event logs in client cache and flushes them periodically. Because of this, some events may not have been sent when your app shuts down.

To ensure all logged events are flushed or saved locally, call 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?