> ## 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 (server-side)

<View title="Developer" />

<View title="Federal docs" />

<View title="EU docs" />

This topic documents how to get started with the server-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 a sample application:
>
> <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/server-sdk/docs/html)</td>
>     </tr>
>
>     <tr>
>       <td>Supported SDK Versions</td>
>       <td>[C++ server SDK](/docs/sdk/concepts/supported-versions.md#c-server-sdk)</td>
>     </tr>
>
>     <tr>
>       <td>GitHub repository</td>
>       <td>[cpp-sdks](https://github.com/launchdarkly/cpp-sdks)</td>
>     </tr>
>
>     <tr>
>       <td>Sample application</td>
>       <td>[C++ (server-side) (native)](https://github.com/launchdarkly/cpp-sdks/tree/main/examples/hello-cpp-server)\
>       [C++ (server-side) (C binding)](https://github.com/launchdarkly/cpp-sdks/tree/main/examples/hello-c-server)</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.

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

## Get started

> [!NOTE]
>
> \*\*Version 3 of the C++ (server-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.

After you complete the [Getting started process](/docs/home/getting-started), follow these instructions to start using the LaunchDarkly SDK in your C application.

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

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

#### 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::server` target:

   ```bash title="Linking your target" lines wrap theme={null}
   target_link_libraries(your-target PRIVATE launchdarkly::server)
   ```

   ```bash title="Linking your target, if you are using Redis" lines wrap theme={null}
   # If you are using Redis for a persistent feature store,
   # ensure that the LD_BUILD_REDIS_SUPPORT option is ON.

   target_link_libraries(your-target PRIVATE launchdarkly::server_redis_source)
   ```

#### Incorporate the SDK using prebuilt artifacts

The C++ (server-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) 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.

#### Include the LaunchDarkly headers

To include the LaunchDarkly SDK headers:

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

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

The C wrapper is included in the release binaries.

> **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-server-sdk) or download a release archive from the [GitHub Releases](https://github.com/launchdarkly/c-server-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.

After cloning the repository, include the LaunchDarkly SDK headers:

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

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

### About the SDK namespaces

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

Individual server-side config builders, for example the `LoggingBuilder`, are within the `launchdarkly::server_side::config::builders` namespace. To reduce verbosity of configuration code, you may bring this namespace into scope.

To keep the examples in our documentation concise, we assume symbols in the top-level `launchdarkly` namespace are visible. You can bring `launchdarkly`, `launchdarkly::server_side`, `launchdarkly::server_side::config::builders`, or all of these 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 = server_side::ConfigBuilder("YOUR_SDK_KEY");
auto config = config_builder.Build();
```

```cpp title="Using launchdarkly::server_side namespace" lines wrap theme={null}
using namespace launchdarkly::server_side;
auto config_builder = ConfigBuilder("YOUR_SDK_KEY");
auto config = config_builder.Build();
```

using namespace launchdarkly::server\_side;
using namespace launchdarkly::server\_side::config::builders;

auto config\_builder = ConfigBuilder("YOUR\_SDK\_KEY");
config\_builder.Logging().Logging(
LoggingBuilder::BasicLogging().Level(LogLevel::kDebug) // LoggingBuilder is in scope
);

```cpp title="No namespace" lines wrap theme={null}
auto config_builder = launchdarkly::server_side::ConfigBuilder("YOUR_SDK_KEY");
auto config = config_builder.Build();
```

### Initialize the client

> [!NOTE]
>
> **The C++ (server-side) SDK uses an SDK key**
>
> The C++ (server-side) SDK uses an SDK 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.md#keys-and-credentials).

After you install and import the SDK, create a single, shared instance of `Client`. To create a client instance, you need your environment's SDK key to authorize your application to connect to a particular environment within LaunchDarkly.

Here's how to configure the SDK key and create the client:

```cpp title="C++ SDK v3.0 (native)" lines wrap theme={null}
auto config_builder = server_side::ConfigBuilder("YOUR_SDK_KEY");
auto config = config_builder.Build();
if (!config) {
   /* an error occurred, config is not valid */
}

server_side::Client client(*config);
```

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

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

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

LDClientSDK client = LDClientSDK_New(config);
```

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

Next, construct the client and call `StartAsync` to initiate a request to the LaunchDarkly service and fetch the feature flag settings.

Because the client initializes asynchronously, you may choose to block until the client is ready.

To block on initialization:

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

```c title="C++ SDK v3.0 (C binding)" lines wrap theme={null}
unsigned int maxwait = 10 * 1000; /* 10 seconds */
LDServerSDK_Start(client, maxwait, NULL);
```

To initialize asynchronously:

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

```c title="C++ SDK v3.0 (C binding)" lines wrap theme={null}
LDServerSDK_Start(client, LD_NONBLOCKING, NULL);
```

Whether you block on initialization or initialize asynchronously, you can also examine the result to determine if initialization succeeded. Here's how:

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

auto start_result = client.StartAsync();
if (auto const status = start_result.wait_for(maxwait); 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}
LDServerSDK client = LDServerSDK_New(config);

bool initialized_successfully;
if (LDServerSDK_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. */
}
```

If you block on initialization, the initialization call blocks up to the time `maxwait`. If you request a feature flag before initialization completes, you will receive the fallback value you defined in your `variation` call.

### Evaluate a context

Now you can check which variation a specific context should receive for a given feature flag. Here's how:

```cpp title="C++ SDK v3.0 (native)" lines wrap theme={null}
auto context = ContextBuilder().Kind("user", "example-user-key").Name("Sandy").Build();

bool show_feature = client.BoolVariation(context, "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}
LDContextBuilder context_builder = LDContextBuilder_New();
LDContextBuilder_AddKind(context_builder, "user", "example-user-key");
LDContextBuilder_Attributes_SetName(context_builder, "user", "Sandy");
LDContext context = LDContextBuilder_Build(context_builder);

bool show_feature = LDServerSDK_BoolVariation(client, context, "example-flag-key", false);

if (show_feature) {
    // application code to show the feature
} else {
    // the code to run if the feature is off
}
```

## Shut down the client

Lastly, shut down the client when your application terminates.

In the C++ SDK v3.0, the SDK will be automatically closed. If you are using the C binding, or if you are working with earlier versions of the SDK, you must specifically close the client. To learn more, read [Shutting down](/docs/sdk/features/shutdown.md#c++-server-side).

## Supported features

This SDK supports the following features:

* [SDK configuration](/docs/sdk/features/config#c++-server-side), including
  * [Application metadata configuration](/docs/sdk/features/app-config.md#c++-server-side)
  * [Service endpoint configuration](/docs/sdk/features/service-endpoint-configuration.md#c++-server-side)
* [Anonymous contexts and users](/docs/sdk/features/anonymous.md#c++-server-side)
* [Big segments](/docs/sdk/features/big-segments.md#c++-server-side)
* [Context configuration](/docs/sdk/features/context-config.md#c++-server-side)
* [Data saving mode](/docs/sdk/features/data-saving-mode.md#c++-server-side)
* [Flag variation evaluation](/docs/sdk/features/evaluating.md#c++-server-side)
* [Flag variation evaluation details](/docs/sdk/features/evaluation-reasons.md#c++-server-side)
* [Flushing events](/docs/sdk/features/flush.md#c++-server-side)
* [Getting all flags](/docs/sdk/features/all-flags.md#c++-server-side)
* [Identifying and changing contexts](/docs/sdk/features/identify.md#c++-server-side)
* [Logging configuration](/docs/sdk/features/logging.md#c++-server-side)
* [Monitoring SDK status](/docs/sdk/features/monitoring.md#c++-server-side)
* [Offline mode](/docs/sdk/features/offline-mode.md#c++-server-side)
* [Private attributes](/docs/sdk/features/private-attributes.md#c++-server-side)
* [Relay Proxy configuration](/docs/sdk/features/relay-proxy-configuration)
  * [Using proxy mode](/docs/sdk/features/relay-proxy-configuration/proxy-mode.md#c++-server-side)
  * [Using daemon mode](/docs/sdk/features/relay-proxy-configuration/daemon-mode.md#c++-server-side)
* [Tracking custom events](/docs/sdk/features/events.md#c++-server-side)
* [Shutting down](/docs/sdk/features/shutdown.md#c++-server-side)
* [Storing data](/docs/sdk/features/storing-data#c++-server-side)