C++ SDK reference (client-side)

Overview

This topic documents how to get started with the client-side C++ SDK, and links to reference information on all of the supported features.

Prerequisites and dependencies

To use the C++ SDK, you must have the following prerequisites installed on your build machine:

• Windows or a POSIX environment (Linux, OSX, BSD)
• cmake, version 3.19 or above
• boost, version 1.81 or above
• openssl, version 1.1 or above
• libpthread, if you are using a POSIX environment

To build the C++ SDK, you must have the following dependencies. These are automatically fetched by cmake during the build process:

• tl/expected
• djarek/certify

If you are planning to run the C++ SDK test suite, you will also need the following:

• nlohmann/json
• googletest

You do not need to run the test suite in order to use the SDK.

Get started

The following sections explain how to install and configure the SDK, and then to verify its connection to LaunchDarkly by fetching flag configuration information for a specific context.

After you complete the Get started process, follow these instructions to start using the LaunchDarkly C++ SDK:

• Incorporate the SDK
• Include the LaunchDarkly headers
• Understand the SDK namespaces
• Initialize the client
• Evaluate a flag

Incorporate the SDK

You can incorporate the SDK by building from source using cmake, or by using pre-built artifacts. Then, include the LaunchDarkly headers.

Include the LaunchDarkly headers

To include the LaunchDarkly SDK headers:

1
#include <launchdarkly/client_side/client.hpp>

The C wrapper is included in the release binaries.

Understand the SDK namespaces

SDK components common to the C++ (client-side) SDK v3.0 and the C++ (server-side) SDK v3.0 exist within the top-level launchdarkly namespace. Client-side components exist within launchdarkly::client_side.

To keep the examples in our documentation concise, we assume symbols in the top-level launchdarkly namespace are visible. You can bring launchdarkly, launchdarkly::client_side, or both into scope, or you can refer to SDK components by their fully-qualified names.

For example:

1
using namespace launchdarkly; # omitted in examples; assumed to be present
2
auto config_builder = client_side::ConfigBuilder("example-mobile-key");
3
auto config = config_builder.Build();

Initialize the client

After you install the SDK, initialize a single shared Client. To create a client instance, you need your environment’s mobile key and the context for which you want to evaluate flags. The mobile key authorizes your application to connect to a particular environment within LaunchDarkly.

Here’s how to configure the mobile key and define the context:

1
auto config_builder = client_side::ConfigBuilder("example-mobile-key");
2
auto config = config_builder.Build();
3
if (!config) {
4
   /* an error occurred, config is not valid */
5
}
6
auto context = ContextBuilder().Kind("user", "example-user-key").Build();

To learn more about the specific configuration options available in this SDK, read ConfigBuilder.

Next, construct the client and call StartAsync to initiate a remote call to the LaunchDarkly service and fetch the feature flag settings for a given context. The StartAsync method returns a future. We strongly recommend using StartAsync with a method that takes a timeout, such as wait_for.

To block on initialization for a specific amount of time:

1
client_side::Client client(config, context);
2
client.StartAsync().wait_for(std::chrono::seconds(10));

You can also initialize the client asynchronously:

1
client_side::Client client(config, context);
2
client.StartAsync();

If you request a feature flag before initialization completes, you will receive the fallback value you defined in your variation call. Whether you block on initialization or initialize asynchronously, you can examine the result to determine if initialization succeeded.

Here’s how:

1
client_side::Client client(config, context);
2
3
auto start_result = client.StartAsync();
4
auto status = start_result.wait_for(maxwait);
5
if (status == std::future_status::ready) {
6
    /* The client's attempt to initialize succeeded or failed in the specified amount of time. */
7
    if (start_result.get()) {
8
        /* Initialization succeeded. */
9
    } else {
10
        /* Initialization failed. */
11
    }
12
} else {
13
    /* The specified timeout was reached, but the client is still initializing. */
14
}

You may also choose to block until the client is ready by using StartAsync with wait rather than with wait_for. However, we strongly discourage this. If you block indefinitely, your application will hang if the client cannot connect to LaunchDarkly. To learn more, read StartAsync. If you do choose to block indefinitely for client initialization, you can listen to status updates. To learn more, read Monitoring SDK status.

Evaluate a flag

After you create the client, you can use it to check which variation a particular context will receive for a given feature flag.

Here’s how:

1
bool show_feature = client.BoolVariation("example-flag-key", false);
2
if (show_feature) {
3
    // Application code to show the feature
4
} else {
5
    // The code to run if the feature is off
6
}

Shut down the client

Shut down the client when your application terminates. To learn more, read Shutting down.

Supported features

This SDK supports the following features:

• Anonymous contexts and users
• Configuration, including
  • Application metadata configuration
  • Service endpoint configuration
• Context configuration
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Identifying and changing contexts
• Monitoring SDK status
• Offline mode
• Private attributes
• Relay Proxy configuration, using proxy mode
• Sending custom events
• Shutting down
• Subscribing to flag changes
• Web proxy configuration