No results for ""
EXPAND ALL
  • Home
  • API docs

GIVE DOCS FEEDBACK

C++ SDK reference (client-side)

Read time: 9 minutes
Last edited: Mar 04, 2024
Version 3 of the C++ (client-side) SDK replaces users with contexts

A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users."

Code samples on this page are from the two most recent SDK versions where they differ. To learn more about upgrading, read C++ (client-side) SDK 2.x to 3.0 migration guide and Best practices for upgrading users to contexts.

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.

SDK quick links

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

ResourceLocation
SDK API documentationSDK API docs
GitHub repositorycpp-sdks
Sample applications

C++ (client-side) (native)
C++ (client-side) (C binding)

Published moduleNone

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:

If you are planning to run the C++ SDK test suite, you will also need the following:

You do not need to run the test suite in order to use the SDK.

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.

To learn more about LaunchDarkly's different SDK types, read Client-side, server-side, and edge SDKs.

Getting started

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.

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:
    add_subdirectory(cpp-sdks)
  3. Link your project's target against the launchdarkly::client target:
    target_link_libraries(your-target PRIVATE launchdarkly::client)

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:
    cmake --build .
    cmake --install .

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>

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.
  1. (Optional) Build the C++ wrapper, which is not included in the release binaries. Copy the header and source files and add them to your own build system.

  2. Include the LaunchDarkly SDK headers:

    #include <launchdarkly/api.h>

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

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

Initializing the client and fetching flag configuration

The C++ (client-side) SDK uses a mobile key

The C++ (client-side) SDK uses a mobile key. Your environment's mobile key is available in the Projects tab of your Account settings page. To learn more about key types, read Keys.

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.

Never embed a server-side SDK key into a client-side application

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.

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

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

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

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

To initialize asynchronously:

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

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

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.

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 on the flag's Settings tab. To make all of a project's flags available to this SDK by default, check the SDKs using Mobile key checkbox in your project Settings.

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
}

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: