C++ (client-side) SDK 2.x to 3.0 migration guide

This topic explains the changes in the C++ SDK 3.0 release and how to migrate to that version.

Overview

This topic explains the changes in the C++ SDK 3.0 release and how to adapt code that uses a 2.x version of the C++ (client-side) SDK to use version 3.0 or later.

Version 3.0 includes several breaking changes, including replacing the C SDK with a C++ SDK. These changes are described in the sections below.

Additionally, if you use the Relay Proxy, you must update your Relay Proxy to version 7.0 before you update your SDK to version 3.

0. To learn more, read the Relay Proxy 7.0 release notes. To upgrade to the latest Relay Proxy version, visit Relay Proxy releases on GitHub.

Introducing the C++ (client-side) SDK as a replacement for the C (client-side) SDK

In the 2.x versions of the C (client-side) SDK, LaunchDarkly provided a C SDK with a C++ wrapper. To work in C++, you needed to build and install the C SDK and then use the provided C++ bindings.

Starting with the 3.0 version of the C++ (client-side) SDK, LaunchDarkly is providing a C++ SDK and a C wrapper. You can build the SDK from source or incorporate prebuilt artifacts. To work in C, you need to use the provided C bindings. The C wrapper is included in the release binaries.

How to make the transition between the 2.x C SDK and the 3.0 C++ SDK depends on whether your application is in C or C++.

Expand for steps if you are working in C

If you are currently working in C, you’ll need to upgrade to the C++ v3.0 SDK and then work with the new C bindings.

Here’s how:

1. Decide whether to incorporate the SDK by building from source or by using prebuilt artifacts. The repository location has changed from version 2.x.

To build from source, read Incorporating the SDK using cmake.

To incorporate the SDK using prebuilt artifacts, read Incorporate the SDK using prebuilt artifacts.

2. Then, include the LaunchDarkly SDK headers for version 3:

C++ SDK v3.0 (C binding)

         #include <launchdarkly/client_side/bindings/c/sdk.h>

The C wrapper is included in the release binaries.

3. Update your configuration code that specifies your mobile key. In version 2.x, you specified configuration details using the LDConfig struct. In version 3.0, you must use the LDClientConfigBuilder instead. Here’s how:

C/C++ SDK v2.x

         struct LDConfig *config = LDConfigNew("example-mobile-key");

4. Update your code that creates a single shared instance of the client. In version 2.x, you created a client using the LDClient struct and an LDUser object. In version 3.0, you must use the LDClientSDK object and the LDContextBuilder instead. Here’s how:

C/C++ SDK v2.x

         struct LDUser *user = LDUserNew("example-user-key");
         struct LDClient *client = LDClientInit(config, user, maxwait);

The third parameter to LDClientSDK_Start is new. If you pass NULL, the call will block for maxwait milliseconds for the client to initialize. If you pass a pointer to a bool, you can also determine whether initialization succeeded.

Here’s how:

C++ SDK v3.0 (C binding)

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

Expand for steps if you are working in C++

If you are currently working in C++, you’ll need to upgrade to the C++ v3.0 SDK. You’ll be able to work in version 3.0 of the SDK natively. You will no longer need a C++ binding.

Here’s how:

1. Decide whether to incorporate the SDK by building from source or by using prebuilt artifacts. The repository location has changed from version 2.x.

To build from source, read Incorporate the SDK using cmake.

To incorporate the SDK using prebuilt artifacts, read Incorporate the SDK using prebuilt artifacts.

2. Then, include the LaunchDarkly SDK headers for version 3:

C++ SDK v3.0

         #include <launchdarkly/client_side/client.hpp>

3. Update your configuration code that specifies your mobile key. In version 2.x, you specified configuration details using the LDConfig struct. In version 3.0, you must use the ConfigBuilder instead. Here’s how:

C/C++ SDK v2.x

         struct LDConfig *config = LDConfigNew("example-mobile-key");

4. Update your code that creates a single shared instance of the client. In version 2.x, you created a client using the LDClient struct and an LDUser object. In version 3.0, you must use the Client object and the ContextBuilder instead. Here’s how:

C/C++ SDK v2.x

         struct LDUser *user = LDUserNew("example-user-key");
         struct LDClient *client = LDClientInit(config, user, maxwait);

You can also examine the result to determine if initialization succeeded. Here’s how:

C++ SDK v3.0 (native)

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

To learn more about contexts, read Understanding contexts, below. For a complete example of setting up the version 3.0 SDK, read Get started.

Understanding contexts

Many LaunchDarkly customers create targeting rules for feature flags based on a variety of different information, including attributes pertaining to users, organizations, devices, and more. In previous versions of the LaunchDarkly SDK, you could define this information in a user object, using a combination of built-in and custom attributes. Now you can define this information in a more structured way, using contexts.

Each context has a required attribute called kind that you can use to categorize context instances for targeting and Experimentation. You can also add other attributes. Attributes can be strings, booleans, numbers, arrays, or JSON objects.

When you evaluate a feature flag within your application, the flag’s targeting rules use information from one or more kinds of contexts. For example, you may know:

• the username, first name, last name, and email address of a person, as part of a context with kind of “user”
• the company, department, and location of an organization, as part of a context with kind of “organization”
• the device, model, and operating system of an environment, as part of a context with kind of “device”

This new version of the LaunchDarkly SDK requires you to evaluate feature flags using an evaluation context, which is an object containing one or more contexts.

To learn more about contexts, read Contexts.

Migrating from users to contexts

The 3.0 version of this SDK lets you use contexts. When you migrate from version 2.x, you must replace every instance of a user with a context. For the 3.0 version of the C++ SDK, this means changing each use of LDUser to a context that you’ve created with the ContextBuilder.

A context always has a kind attribute. When older versions of the C++ SDK send events to LaunchDarkly, LaunchDarkly will convert the users in those events to contexts with a kind of user.

If a flag configuration specifies any context kinds other than user, older versions of the C++ SDK will not evaluate the flag correctly. You must upgrade your SDK if you are going to use context kinds other than user in your flag configurations.

The primary differences between working with users and working with contexts include the following:

• Create contexts, not users: Where you previously created users, now you can create contexts.
• Changes to attributes: There are now fewer built-in attributes. You can still add as many custom attributes as you like, although the format has changed slightly. A flag’s targeting rules can now address fields within a JSON object.
• Changes to private attributes: You can mark specific attributes of a context as private, either across all contexts of any kind, or within a particular context or context kind.
• Changes to anonymous users: Client-side SDKs no longer automatically populate the device ID.
• Changes to alias events: The alias method has been removed.

Understanding differences between users and contexts

Where you previously created users, now you can create contexts.

Here’s how to construct a basic context, as compared with constructing a user:

2.x syntax, user with key

    struct LDUser *user = LDUserNew("example-user-key");

Here’s how to construct a basic context, with a context kind of something other than “user”:

3.0 syntax, single context with key

    auto context = ContextBuilder()
      .Kind("organization", "example-organization-key")
      .Build();

Here’s how to construct a multi-context, which includes multiple context kinds:

3.0 syntax, multi-context

    auto context = ContextBuilder()
      .Kind("user", "example-user-key")
      .Name("Sandy")
      .Kind("organization", "example-organization-key")
      .Name("Global Health Services")
      .Build();

Understanding changes to built-in and custom attributes

This section describes the changes to built-in and custom attributes in the 3.0 version of the SDK.

Working with built-in and custom attributes

In previous SDK versions, the user object included several built-in attributes for describing the user. It also included optional custom attributes, which you could set with the LDUserSetCustom method.

In version 3.0, the only built-in attributes are kind, key, name, and anonymous. Kind, key, and name are strings, and anonymous is a boolean.

You can define additional attributes for a context by passing in a name and value for each. Additional attributes can be any JSON type, including boolean, number, string, array, or object.

Here’s how to construct a context with additional attributes, as compared with constructing a similar user:

2.x syntax, user with attributes

    struct LDUser *user = LDUserNew("example-user-key");
    LDUserSetName(user, "Sandy");
    LDUserSetEmail(user, "[e-mail]");

Referencing properties of an attribute object

In previous versions of the SDK, if you set the value of a user’s custom attribute to an object, you could not reference that object in evaluations. In version 3.0, if a context attribute’s value is an object, you can reference properties of that object as the attribute in the targeting rules for a flag or segment.

Here’s how to add object attributes to a context:

3.0 syntax, context with object attributes

    auto context = ContextBuilder()
      .Kind("user", "example-user-key")
      .Set("address", Value::Object({{"street", "123 Main St"}, {"city", "Springfield"}}))
      .Build();

In your flag or segment targeting, use / as the delimiter to refer to specific object fields. For example, you can use /address/city in your targeting. To learn more, read Target with flags.

Removing the secondary attribute

In previous versions of the SDK, you could set the value of a user’s secondary attribute, as an optional secondary key for a user, using LDUserSetSecondary. The SDK would incorporate this attribute into the variation bucket assignment hash.

In version 3.0, the secondary attribute has been removed. If you were previously using this attribute as part of distinguishing percentage rollouts, that will no longer work for your users.

Understanding changes to private attributes

As in previous versions of the SDK, you can mark specific attributes of a context as private. This restricts the context data your application sends to LaunchDarkly, while still using that data for flag targeting.

In version 3.0, there are two scopes for which you can mark attributes as private:

• Across all contexts of any context kind. You might use this if you want to ensure that the SDK never stores an “email” attribute in LaunchDarkly, no matter whether it occurs in a user context, an organization context, or something else.
• Within a particular context or context kind. You might use this if you want an “email” attribute to be private in a user context, but not in an organization context.

In the first example below, all attributes are marked private for all contexts. In the second example, the “email” and “address” attributes are private for all contexts:

3.0 syntax, all attributes marked private

    auto config_builder = client_side::ConfigBuilder("example-mobile-key");
    config_builder.Events().AllAttributesPrivate(true);
    auto config = config_builder.Build();

To learn more, read [AllAttributesPrivate](https://launchdarkly.github.io/cpp-sdks/libs/client-sdk/docs/html/classlaunchdarkly_1_1config_1_1shared_1_1builders_1_1EventsBuilder.html#a9c4c34e10bae53dd6f676d1c89740eb

2. and PrivateAttributes.

Here’s how to mark an attribute as private for a particular context:

3.0 syntax, attribute marked private for one context

    auto context = ContextBuilder()
      .Kind("user", "example-user-key")
      .Name("Sandy Smith")
      .SetPrivate("email", "[e-mail]")
      .Build();

For attributes that are objects, you can mark specific fields private, using the / delimiter followed by the attribute name, then the / delimiter followed by the JSON property within the value.

For example, for the attribute "address": { "street": "Main St", "city": "Springfield" }, you could set just the /address/street as private:

3.0 syntax, specific fields of an attribute marked private

    auto context = ContextBuilder()
      .Kind("user", "example-user-key")
      .Name("Sandy Smith")
      .Set("address", Value::Object({{"street", "Main St"}, {"city", "Springfield"}}))
      .AddPrivateAttribute("/address/street")
      .Build()

Understanding changes to anonymous users

In 2.x versions of the SDK, you could omit the user key when building an anonymous user. On mobile devices, the SDK set the user key to the device ID. On non-mobile platforms, the SDK set the user key to a generated UUID.

In the 3.0 version of the SDK, you must include a key for each context. It is not autogenerated, even if you set the context as anonymous.

If you currently have feature flags that target the device ID, you will need to determine what context you want the device ID to be part of, and populate the device ID attribute yourself.

Here’s how:

3.0 syntax, setting the device ID

    auto context = ContextBuilder()
      .Kind("device", "example-device-key")
      .Set("deviceID", "example-device-ID")
      .Build();

Understanding changes to alias events

In previous versions of the SDK, multiple user objects could represent one person. For example, this could happen the first time a person logged in to your application. The person might be represented by an anonymous user before they logged in, and a different user after they logged in. You could associate these two LaunchDarkly users by sending an alias event in the SDK.

With the introduction of contexts, the person in this scenario is represented by two different context kinds. For example, before they log in, they might be represented by a device context. After they log in, they might be represented by a multi-context, for example, by one context kind based on their device and simultaneously by another context kind based on their user information.

The 3.0 version of the SDK removes the ability to send an alias event. If you currently alias users, you will need to remove this code when you migrate to version 3.0.

If you want to continue associating two contexts with each other, you can use two different context kinds within the same context.

Here’s how:

3.0 syntax, working with associated contexts

    /* before end user logs in */
    auto context = ContextBuilder()
      .Kind("device", "example-device-key")
      .Build();


    /* after end user logs in */
    auto updated_context = ContextBuilder(context)
      .Kind("user", "example-user-key")
      .Name("Sandy")
      .Build();

    client.IdentifyAsync(updated_context);

To learn more, read IdentifyAsync.

Understanding changes to configuration options

In the 3.0 version of the SDK, several configuration options have changed:

• The LDConfig struct has been replaced by a Config and ConfigBuilder.
• The PrivateAttributes and AllAttributesPrivate configuration options both now apply to all contexts of any context kind. To learn more, read Understanding changes to private attributes.
• The LDConfigAutoAliasOptOut option has been removed.
• The LDConfigSetInlineUsersInEvents option has been removed.

To learn more, read ConfigBuilder.