C++ SDK reference (client-side)

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.

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.

Getting started

After you complete the Getting started process, follow these instructions to start using the LaunchDarkly C++ SDK.

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.

Incorporating the SDK

You can incorporate the SDK by building from source using cmake, or by using pre-built artifacts. Then, include the LaunchDarkly headers.

Incorporating 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)
   COPY

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

   target_link_libraries(your-target PRIVATE launchdarkly::client)
   COPY

Incorporating 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 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 .
   COPY

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

Including the LaunchDarkly headers

To include the LaunchDarkly SDK headers:

#include <launchdarkly/client_side/client.hpp>
COPY

The C wrapper is included in the release binaries.

Understanding the SDK namespaces

SDK components common to the C++ (client-side) SDK v3.0 and the upcoming 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:

using namespace launchdarkly; # omitted in examples; assumed to be present
auto config = client_side::ConfigBuilder("mobile-key-123abc").Build();
COPY

Initializing the client and fetching flag configuration

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.

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

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

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.

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

To block on initialization:

client_side::Client client(config, context);
client.StartAsync().wait_for(std::chrono::seconds(10));
COPY

To initialize asynchronously:

client_side::Client client(config, context);
client.StartAsync();
COPY

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

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

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.

If you want to wait indefinitely for client initialization, you can listen to status updates. To learn more, read Monitoring SDK status.

Now you can check which variation a specific context should receive for a certain feature flag.

Here's how:

bool show_feature = client.BoolVariation("flag-key-123abc", false);
if (show_feature) {
    // Application code to show the feature
} else {
    // The code to run if the feature is off
}
COPY

Shut down the client

Shut down the client when your application terminates. 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
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Identifying and changing contexts
• Monitoring SDK status
• Private attributes
• Relay Proxy configuration, using proxy mode
• Sending custom events
• Shutting down
• Subscribing to flag changes
• User and context configuration
• Web proxy configuration