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

# C++ SDK reference (client-side)

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

> For the complete documentation index, see [llms.txt](/llms.txt). For the full documentation snapshot, see [llms-full.txt](/llms-full.txt).

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

<Note title="SDK quick links">
  LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:
</Note>

| Resource | Location |
| - | - |
| SDK API documentation | [SDK API docs](https://launchdarkly.github.io/cpp-sdks/libs/client-sdk/docs/html/) |
| Supported SDK Versions | [C++ client SDK](../concepts/supported-versions#c-client-sdk) |
| GitHub repository | [cpp-sdks](https://github.com/launchdarkly/cpp-sdks) |
| Sample applications | [C++ (client-side) (native)](https://github.com/launchdarkly/cpp-sdks/tree/main/examples/hello-cpp-client) ,  [C++ (client-side) (C binding)](https://github.com/launchdarkly/cpp-sdks/tree/main/examples/hello-c-client) |
| Published module | None |

## 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 title="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/C++ application and want to set up LaunchDarkly on the server-side, read the [server-side C/C++ SDK reference](/sdk/server-side/c-c--).

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

## Get started

<Note title="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](/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 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" theme={null}
             add_subdirectory(cpp-sdks)
    ```
  </CodeGroup>

  3. Link your project's target against the `launchdarkly::client` target:

  <CodeGroup>
    ```bash title="Linking your target" 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%](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" 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>

### Include the Launch

Darkly headers

To include the LaunchDarkly SDK headers:

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

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

  ```c title="C SDK v2.x (native)" theme={null}
      #include <launchdarkly/api.h>
  ```

  ```cpp title="C SDK v2.x (C++ binding)" theme={null}
      #include <launchdarkly/api.hpp>
  ```
</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" 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" theme={null}
      using namespace launchdarkly::client_side;
      auto config_builder = ConfigBuilder("example-mobile-key");
      auto config = config_builder.Build();
  ```

  ```cpp title="No namespace" 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 title="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 from **Project settings**, on the **Environments** list. To learn more about key types, read [Keys](/sdk/concepts/client-side-server-side#keys).

  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)" 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)" 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);
  ```

  ```c title="C SDK v2.x (native)" theme={null}
      struct LDConfig *config = LDConfigNew("example-mobile-key");
      struct LDUser *user = LDUserNew("example-user-key");
  ```

  ```cpp title="C SDK v2.x (C++ binding)" theme={null}
      LDConfig *config = LDConfigNew("example-mobile-key");
      LDUser *user = LDUserNew("example-user-key");
  ```
</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)" theme={null}
      client_side::Client client(config, context);
      client.StartAsync().wait_for(std::chrono::seconds(10));
  ```

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

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

  ```c title="C SDK v2.x (native)" theme={null}
      unsigned int maxwait = 10 * 1000; /* 10 seconds */
      struct LDClient *client = LDClientInit(config, user, maxwait);
  ```

  ```cpp title="C SDK v2.x (C++ binding)" theme={null}
      unsigned int maxwait = 10 * 1000; /* 10 seconds */
      LDClientCPP *client = LDClientCPP::Init(config, user, maxwait);
  ```
</CodeGroup>

You can also initialize the client asynchronously:

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

  ```c title="C++ SDK v3.0 (C binding)" 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)" 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)" 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](/sdk/features/monitoring).

<Warning title="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)" 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)" 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
      }
  ```

  ```c title="C SDK v2.x (native)" theme={null}
      bool show_feature = LDBoolVariation(client, "example-flag-key", false);
      if (show_feature) {
          // Application code to show the feature
      } else {
          // The code to run if the feature is off
      }
  ```

  ```cpp title="C SDK v2.x (C++ binding)" 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
      }
  ```
</CodeGroup>

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

## Shut down the client

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

## Supported features

This SDK supports the following features:

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