> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# C++ SDK reference (client-side)

**Developer**

**Federal docs**

**EU docs**

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

> [!NOTE]
>
> **SDK quick links**
>
> LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:
>
> <table>
>   <thead>
>     <tr>
>       <th>Resource</th>
>       <th>Location</th>
>     </tr>
>   </thead>
>
>   <tbody>
>     <tr>
>       <td>SDK API documentation</td>
>       <td>[SDK API docs](https://launchdarkly.github.io/cpp-sdks/libs/client-sdk/docs/html/)</td>
>     </tr>
>
>     <tr>
>       <td>Supported SDK Versions</td>
>       <td>[C++ client SDK](https://launchdarkly.com/docs/sdk/concepts/supported-versions.md#c-client-sdk)</td>
>     </tr>
>
>     <tr>
>       <td>GitHub repository</td>
>       <td>[cpp-sdks](https://github.com/launchdarkly/cpp-sdks)</td>
>     </tr>
>
>     <tr>
>       <td>Sample applications</td>
>
>       <td>
>         [C++ (client-side) (native)](https://github.com/launchdarkly/cpp-sdks/tree/main/examples/hello-cpp-client)
>         \
>         &#x20;[C++ (client-side) (C binding)](https://github.com/launchdarkly/cpp-sdks/tree/main/examples/hello-c-client)
>       </td>
>     </tr>
>
>     <tr>
>       <td>Published module</td>
>       <td>None</td>
>     </tr>
>   </tbody>
> </table>

## 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`](https://github.com/TartanLlama/expected)
* [`djarek/certify`](https://github.com/djarek/certify.git)

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

* [`nlohmann/json`](https://github.com/nlohmann/json)
* [`googletest`](https://github.com/google/googletest)

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

> [!NOTE]
>
> **For use in mobile, desktop, and embedded client applications only**
>
> This SDK is intended for use in single-user mobile, desktop, and embedded applications. If you have a C++ application and want to set up LaunchDarkly on the server-side, read the [server-side C++ SDK reference](https://launchdarkly.com/docs/sdk/server-side/c-c--).
>
> To learn more about the different LaunchDarkly SDK types, read [Choosing an SDK type](https://launchdarkly.com/docs/sdk/concepts/client-side-server-side.md).

## Get started

> [!NOTE]
>
> \*\*Version 3 of the C++ (client-side) SDK is a native C++ library \*\*
>
> Previous versions of this SDK were written in C, with a C++ wrapper available. In version 3.0 and higher, this SDK is written in C++, with a C wrapper available. The code samples below show all options, where applicable.

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](https://launchdarkly.com/docs/home/getting-started) process, follow these instructions to start using the LaunchDarkly C++ SDK:

* [Incorporate the SDK](#incorporate-the-sdk)
* [Include the LaunchDarkly headers](#include-the-launchdarkly-headers)
* [Understand the SDK namespaces](#understand-the-sdk-namespaces)
* [Initialize the client](#initialize-the-client)
* [Evaluate a flag](#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.

> [accordion] Expand Incorporate the SDK using cmake
>
> #### Incorporate the SDK using cmake
>
> To incorporate the SDK using `cmake`:
>
> 1. Clone the [GitHub repository](https://github.com/launchdarkly/cpp-sdks) as a subdirectory of your project.
> 2. Update your project's `CMakeLists.txt` to include the SDK repository:
>    ```bash title="Using add_subdirectory" lines wrap theme={null}
>    add_subdirectory(cpp-sdks)
>    ```
> 3. Link your project's target against the `launchdarkly::client` target:
>    ```bash title="Linking your target" lines wrap theme={null}
>    target_link_libraries(your-target PRIVATE launchdarkly::client)
>    ```

> [accordion] Expand Incorporate the SDK using prebuilt artifacts
>
> #### Incorporate the SDK using prebuilt artifacts
>
> The C++ (client-side) SDK releases include 64-bit static and dynamic libraries for Linux, Mac, and Windows.
>
> To incorporate the SDK using prebuilt artifacts:
>
> 1. Download the correct release for your platform from the GitHub [Releases](https://github.com/launchdarkly/cpp-sdks/releases?q=%22launchdarkly-cpp-client%22) page.
> 2. Ensure the SDK's headers are installed on the build system. One way to do this is to clone the [GitHub repository](https://github.com/launchdarkly/cpp-sdks) and install the headers using `cmake`:
>    ```bash title="Install headers" lines wrap theme={null}
>    cmake --build .
>    cmake --install .
>    ```
>
> You can now reference the installed headers and link against the prebuilt libraries.

> [accordion] Expand for how to install the SDK if you are using v2.x
>
> Here's how to install the SDK:
>
> 1. Clone [the GitHub repository](https://github.com/launchdarkly/c-client-sdk) or download a release archive from the [GitHub Releases](https://github.com/launchdarkly/c-client-sdk/releases) page.
>
> 2. Install the SDK locally.
>
> * If you use `cmake`, the build system will expect that `boost` and `openssl` exist on the system. The `cmake` configuration exports the target `ldclientapi`.
>
> * If you don't use `cmake` and you cannot use LaunchDarkly's artifacts, use `cmake install` to install the SDK in directory you choose. This copies the required headers, and binaries equivalent to LaunchDarkly's release bundles.
>
> 3. (Optional) Build the C++ wrapper, which is not included in the release binaries. Copy the [header](https://github.com/launchdarkly/c-client-sdk/blob/master/cpp/include/launchdarkly/api.hpp) and [source](https://github.com/launchdarkly/c-client-sdk/blob/master/cpp/api.cpp) files and add them to your own build system.

### Include the LaunchDarkly headers

To include the LaunchDarkly SDK headers:

```c title="C++ SDK v3 (native)" lines wrap theme={null}
#include <launchdarkly/client_side/client.hpp>
```

```c title="C++ SDK v3 (C binding)" lines wrap theme={null}
#include <launchdarkly/client_side/bindings/c/sdk.h>
```

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:

```cpp title="Using launchdarkly namespace" lines wrap theme={null}
using namespace launchdarkly; // omitted in examples; assumed to be present
auto config_builder = client_side::ConfigBuilder("example-mobile-key");
auto config = config_builder.Build();
```

```cpp title="Using launchdarkly::client_side namespace" lines wrap theme={null}
using namespace launchdarkly::client_side;
auto config_builder = ConfigBuilder("example-mobile-key");
auto config = config_builder.Build();
```

```cpp title="No namespace" lines wrap theme={null}
auto config_builder = launchdarkly::client_side::ConfigBuilder("example-mobile-key");
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.

> [!WARNING]
>
> **C++ (client-side) SDK credentials**
>
> The C++ (client-side) SDK uses a mobile key. Keys are specific to each project and environment. They are available on the **SDK keys** page under **Settings**. To learn more about key types, read [Keys](https://launchdarkly.com/docs/sdk/concepts/client-side-server-side.md#keys-and-credentials).
>
> Mobile keys are not secret and you can expose them in your client-side code without risk. However, never embed a server-side SDK key into a client-side application.

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

```cpp title="C++ SDK v3.0 (native)" lines wrap theme={null}

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

```c title="C++ SDK v3.0 (C binding)" lines wrap theme={null}
LDClientConfigBuilder builder = LDClientConfigBuilder_New("example-mobile-key");

LDClientConfig config;
LDStatus status = LDClientConfigBuilder_Build(builder, &config);

if (!LDStatus_Ok(status)) {
     /* an error occurred, config is not valid */
}

LDContextBuilder context_builder = LDContextBuilder_New();
LDContextBuilder_AddKind(context_builder, "user", "example-user-key");

LDContext context = LDContextBuilder_Build(context_builder);
```

To learn more about the specific configuration options available in this SDK, read [`ConfigBuilder`](https://launchdarkly.github.io/cpp-sdks/libs/client-sdk/docs/html/classlaunchdarkly_1_1config_1_1shared_1_1builders_1_1ConfigBuilder.html).

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:

```cpp title="C++ SDK v3.0 (native)" lines wrap theme={null}
client_side::Client client(config, context);
client.StartAsync().wait_for(std::chrono::seconds(10));
```

```c title="C++ SDK v3.0 (C binding)" lines wrap theme={null}
LDClientSDK client = LDClientSDK_New(config, context);

unsigned int maxwait = 10 * 1000; /* 10 seconds */
LDClientSDK_Start(client, maxwait, NULL);
```

You can also initialize the client asynchronously:

```cpp title="C++ SDK v3.0 (native)" lines wrap theme={null}
client_side::Client client(config, context);
client.StartAsync();
```

```c title="C++ SDK v3.0 (C binding)" lines wrap theme={null}
LDClientSDK client = LDClientSDK_New(config, context);

LDClientSDK_Start(client, LD_NONBLOCKING, NULL);
```

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:

```cpp title="C++ SDK v3.0 (native)" lines wrap theme={null}
client_side::Client client(config, context);

auto start_result = client.StartAsync();
auto status = start_result.wait_for(maxwait);
if (status == std::future_status::ready) {
    /* The client's attempt to initialize succeeded or failed in the specified amount of time. */
    if (start_result.get()) {
        /* Initialization succeeded. */
    } else {
        /* Initialization failed. */
    }
} else {
    /* The specified timeout was reached, but the client is still initializing. */
}
```

```c title="C++ SDK v3.0 (C binding)" lines wrap theme={null}
LDClientSDK client = LDClientSDK_New(config, context);

bool initialized_successfully;
if (LDClientSDK_Start(client, maxwait, &initialized_successfully)) {
  /* The client's attempt to initialize succeeded or failed in the specified amount of time. */
  if (initialized_successfully) {
    /* Initialization succeeded. */
  } else {
    /* Initialization failed. */
  }
} else {
   /* The specified timeout was reached, but the client is still initializing. */
}
```

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`](https://launchdarkly.github.io/cpp-sdks/libs/client-sdk/docs/html/classlaunchdarkly_1_1client__side_1_1Client.html). If you do choose to block indefinitely for client initialization, you can listen to status updates. To learn more, read [Monitoring SDK status](https://launchdarkly.com/docs/sdk/features/monitoring.md).

> [!WARNING]
>
> **Client must be a singleton**
>
> It's important to make `Client` a singleton for each LaunchDarkly project. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.
>
> If you have multiple LaunchDarkly projects, you can create one `Client` for each. In this situation, the clients operate independently. For example, they do not share a single connection to LaunchDarkly.

### 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:

```cpp title="C++ SDK v3.0 (native)" lines wrap theme={null}
bool show_feature = client.BoolVariation("example-flag-key", false);
if (show_feature) {
    // Application code to show the feature
} else {
    // The code to run if the feature is off
}
```

```c title="C++ SDK v3.0 (C binding)" lines wrap theme={null}
bool show_feature = LDClientSDK_BoolVariation(client, "example-flag-key", false);
if (show_feature) {
    // Application code to show the feature
} else {
    // The code to run if the feature is off
}
```

> [!WARNING]
>
> **Making feature flags available to this SDK**
>
> You must make feature flags available to mobile SDKs before the SDK can evaluate those flags. If an SDK tries to evaluate a feature flag that is not available, the context will receive the fallback value for that flag.
>
> To make a flag available to this SDK, check the **SDKs using Mobile key** checkbox during flag creation, or toggle on the option in the flag's right sidebar. To make all of a project's flags available to this SDK by default, check the **SDKs using Mobile key** checkbox on your project's [Flag settings page](https://launchdarkly.com/docs/home/account/edit-project.md).

## Shut down the client

Shut down the client when your application terminates. To learn more, read [Shutting down](https://launchdarkly.com/docs/sdk/features/shutdown.md#c++-client-side).

## Supported features

This SDK supports the following features:

* [SDK configuration](https://launchdarkly.com/docs/sdk/features/config#c++-client-side), including
  * [Application metadata configuration](https://launchdarkly.com/docs/sdk/features/app-config.md#c++-client-side)
  * [Service endpoint configuration](https://launchdarkly.com/docs/sdk/features/service-endpoint-configuration.md#c++-client-side)
* [Anonymous contexts and users](https://launchdarkly.com/docs/sdk/features/anonymous.md#c++-client-side)
* [Context configuration](https://launchdarkly.com/docs/sdk/features/context-config.md#c++-client-side)
* [Flag variation evaluation](https://launchdarkly.com/docs/sdk/features/evaluating.md#c++-client-side)
* [Flag variation evaluation details](https://launchdarkly.com/docs/sdk/features/evaluation-reasons.md#c++-client-side)
* [Flushing events](https://launchdarkly.com/docs/sdk/features/flush.md#c++-client-side)
* [Getting all flags](https://launchdarkly.com/docs/sdk/features/all-flags.md#c++-client-side)
* [Identifying and changing contexts](https://launchdarkly.com/docs/sdk/features/identify.md#c++-client-side)
* [Monitoring SDK status](https://launchdarkly.com/docs/sdk/features/monitoring.md#c++-client-side)
* [Offline mode](https://launchdarkly.com/docs/sdk/features/offline-mode.md#c++-client-side)
* [Private attributes](https://launchdarkly.com/docs/sdk/features/private-attributes.md#c++-client-side)
* [Relay Proxy configuration, using proxy mode](https://launchdarkly.com/docs/sdk/features/relay-proxy-configuration/proxy-mode.md#c++-client-side)
* [Tracking custom events](https://launchdarkly.com/docs/sdk/features/events.md#c++-client-side)
* [Shutting down](https://launchdarkly.com/docs/sdk/features/shutdown.md#c++-client-side)
* [Subscribing to flag changes](https://launchdarkly.com/docs/sdk/features/flag-changes.md#c++-client-side)
* [Web proxy configuration](https://launchdarkly.com/docs/sdk/features/web-proxy.md#c++-client-side)