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

<View title="Developer" />

<View title="Federal docs" />

<View title="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](/docs/sdk/concepts/supported-versions#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)
          <br /> [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>
</Note>

## 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](/docs/sdk/server-side/c-c--).

  To learn more about the different LaunchDarkly SDK types, read [Choosing an SDK type](/docs/sdk/concepts/client-side-server-side).
</Note>

## 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.
</Note>

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](/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.

<AccordionGroup>
  <Accordion title="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:
           <CodeGroup>
             ```bash title="Using add_subdirectory" lines wrap theme={null}
             add_subdirectory(cpp-sdks)
             ```
           </CodeGroup>
    3. Link your project's target against the `launchdarkly::client` target:
           <CodeGroup>
             ```bash title="Linking your target" lines wrap theme={null}
             target_link_libraries(your-target PRIVATE launchdarkly::client)
             ```
           </CodeGroup>
  </Accordion>

  <Accordion title="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`:
           <CodeGroup>
             ```bash title="Install headers" lines wrap theme={null}
             cmake --build .
             cmake --install .
             ```
           </CodeGroup>

    You can now reference the installed headers and link against the prebuilt libraries.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### Include the LaunchDarkly headers

To include the LaunchDarkly SDK headers:

<CodeGroup>
  ```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>
  ```
</CodeGroup>

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:

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

### 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](/docs/sdk/concepts/client-side-server-side#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.
</Warning>

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

<CodeGroup>
  ```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);
  ```
</CodeGroup>

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:

<CodeGroup>
  ```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);
  ```
</CodeGroup>

You can also initialize the client asynchronously:

<CodeGroup>
  ```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);
  ```
</CodeGroup>

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:

<CodeGroup>
  ```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. */
  }
  ```
</CodeGroup>

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](/docs/sdk/features/monitoring).

<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.
</Warning>

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

<CodeGroup>
  ```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
  }
  ```
</CodeGroup>

<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](/docs/home/account/edit-project).
</Warning>

## Shut down the client

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

## Supported features

This SDK supports the following features:

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