C++ SDK reference (server-side)

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

Overview

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

LaunchDarkly’s SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:

Resource	Location
SDK API documentation	SDK API docs
Supported SDK Versions	C++ server SDK
GitHub repository	cpp-sdks
Sample application	C++ (server-side) (native) , C++ (server-side) (C binding)
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
• 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.

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.

To learn more about LaunchDarkly’s different SDK types, read Choosing an SDK type.

Get started

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, 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 as a subdirectory of your project.
2. Update your project’s CMakeLists.txt to include the SDK repository:

Using add_subdirectory

       add_subdirectory(cpp-sdks)

3. Link your project’s target against the launchdarkly::server target:

Linking your target

       target_link_libraries(your-target PRIVATE launchdarkly::server)

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 page.
2. Ensure the SDK’s headers are installed on the build system. One way to do this is to clone the GitHub repository and install the headers using cmake:

Install headers

       cmake --build .
       cmake --install .

You can now reference the installed headers and link against the prebuilt libraries.

Include the Launch

Darkly headers

To include the LaunchDarkly SDK headers:

C++ SDK v3 (native)

    #include <launchdarkly/server_side/client.hpp>

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 or download a release archive from the GitHub 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:

C++ SDK v3.0 (native)

    #include <launchdarkly/server_side/client.hpp>

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:

Using launchdarkly namespace

    using namespace launchdarkly; # omitted in examples; assumed to be present
    auto config_builder = server_side::ConfigBuilder("YOUR_SDK_KEY");
    auto config = config_builder.Build();

Initialize the client

The C++ (server-side) SDK uses an SDK 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.

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:

C++ SDK v3.0 (native)

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

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

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:

C++ SDK v3.0 (native)

    client.StartAsync().wait_for(std::chrono::seconds(10));

To initialize asynchronously:

C++ SDK v3.0 (native)

    client.StartAsync();

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

C++ SDK v3.0 (native)

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

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:

C++ SDK v3.0 (native)

    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
    }

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.

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
• Logging configuration
• Monitoring SDK status
• Offline mode
• Private attributes
• Reading flags from a file
• Relay Proxy configuration
  • Using proxy mode
  • Using daemon mode
• Sending custom events
• Shutting down
• Storing data
• Test data sources