Client-side, server-side, and edge SDKs

Overview

This topic explains the differences between LaunchDarkly's client-side, server-side, and edge SDKs and helps you determine which type of SDK to use.

The SDK types have different security considerations as well as some behavioral and architectural differences. They handle flag evaluations differently, use different kinds of SDK keys, and support different languages.

Understanding the different types of SDKs

It is important to understand the types of SDKs we support. The different types of SDKs impact critical implementation details and use cases.

All of our SDKs belong to one of these categories:

• Client-side SDKs, including mobile SDKs
• Server-side SDKs
• Edge SDKs

The table below summarizes the differences between these categories:

Understanding mobile SDKs

We categorize SDKs designed for mobile devices as client-side SDKs because, like our client-side SDKs, most mobile applications have a single-user context. This includes our client-side .NET, Android, client-side C++, iOS, Flutter, React Native, and Roku SDKs. Each of these SDKs also has some mobile-specific functionality.

Here are some of the ways that mobile SDKs are different than other client-side SDKs:

• Mobile SDKs support multiple environments.
• Mobile SDKs receive updates from LaunchDarkly differently.

Functional differences between SDKs

LaunchDarkly attempts to keep all SDKs at feature parity with each other. Even so, slight feature differences exist between server-side, client-side, mobile, and edge SDKs.

Persistent feature store integrations

By default, our SDKs store transmitted data in in-memory caches. If you don't want to use an in-memory cache, we provide integrations for server-side SDKs to store data in persistent data stores like Redis or DynamoDB instead.

Client-side and mobile SDKs may have platform-specific storage mechanisms and can alternatively use our Relay Proxy.

To learn more, read Persistent data stores.

Multi-environment support

We designed our SDKs to work with one LaunchDarkly environment at a time. However, mobile application developers might want their applications to be able to access flags on multiple LaunchDarkly environments. We designed the mobile SDKs to support behavior across multiple environments.

For example, if your LaunchDarkly account is set up to have different "Android," "iOS," and "Core" environments or projects, you can use the multi-environment SDK feature to access flags in multiple places.

Receiving updates from LaunchDarkly

Server-side SDKs open a streaming connection to LaunchDarkly. The initial payload from the streaming connection contains the variations a context instance receives. Subsequently, server-side SDKs receive flag configuration changes over the stream. By default, server-side SDKs maintain this streaming connection and receive updated flag values when you change a flag. To increase connection resiliency for server-side SDKs, multiple options are available. They are:

• use a persistent feature store,
• use daemon mode, or
• use the Relay Proxy.

JavaScript-based client-side SDKs open an initial connection to LaunchDarkly using LaunchDarkly's polling endpoint. Then, these SDKs may open a streaming connection. Client-side SDKs receive flag value changes for a specific context.

Some of the JavaScript-based client-side SDKs, such as the React Web SDK, open a streaming connection by default. Others, such as the JavaScript SDK, do not explicitly set a default behavior. Instead, the JavaScript SDK opens a streaming connection when you register a change listener, and closes that streaming connection when you unregister the change listener. You can also explicitly configure the JavaScript SDK to maintain a streaming connection. Because opening and closing streaming connections can be expensive, you should explicitly enable streaming if your application frequently starts and stops listening to changes.

SDKs may periodically drop streaming connections. When the SDK loses connectivity to LaunchDarkly, it continues to try to reestablish a streaming connection until it succeeds. If you anticipate a poor connection, you can evaluate flags server-side and bootstrap your JavaScript-based SDKs with those values. This ensures end users receive the flag variations you intend even if there is no connection to LaunchDarkly. To learn more, read Bootstrapping.

Mobile SDKs monitor the connection state to LaunchDarkly and use different connection types depending on whether the mobile app is in the foreground or in the background. This design better accommodates mobile applications, which are more likely than web or desktop software to lose their network connection.

Security

The client-side, server-side, and edge SDKs have different security considerations.

Client-side SDKs

Client-side SDKs typically run on customers' own devices. They can be compromised by end users who unpack a mobile app to examine the SDK bytecode or use their browser's developer tools to inspect internal site data. As a result, you should never use a server-side SDK key in a client-side or mobile application.

Flag rules may include context identifiers or other personally identifiable information (PII) that you might not want to transmit to client-side applications. Consequently, client-side SDKs depend on LaunchDarkly's servers to safely store flag rules. To learn more, read Evaluation reasons.

Server-side SDKs

Server-side SDKs operate within server-architected applications running on your own infrastructure or trusted cloud-based infrastructure. Neither of these locations is directly accessible by end users. Because of the limited access to server-based applications, server-side SDKs can safely receive flag data and rulesets without needing to obscure or filter out sensitive data.

Edge SDKs

Edge SDKs typically run in the edge layer of your CDN. This location is not directly accessible by end users. Because of the limited access to CDNs, edge SDKs can safely receive flag data and rulesets without needing to obscure or filter out sensitive data. They receive this data through an integration.

Flag evaluations

The different types of SDKs evaluate feature flags differently. The different evaluation behavior supports data security and efficient data utilization.

Client-side SDKs

Client-side SDKs are configured to operate for a single end user at a time, although the end user may be represented by one or more contexts. For example, your application may be using both attributes pertaining to the user, such as name and email, and attributes pertaining to their environment, such as device model and operating system.

When a flag evaluation is requested, client-side SDKs delegate the flag evaluation to LaunchDarkly on behalf of a specific evaluation context, which comprises one or more contexts. LaunchDarkly's services are responsible for evaluating flag rules for the evaluation context. LaunchDarkly notifies the SDK of the evaluation results, through either the SDK's streaming or polling connections. Then the SDK stores these results for quick lookup.

For security reasons, client-side SDKs cannot download and store an entire ruleset. Client-side SDKs typically run on customers' own devices, so they are vulnerable to having end users investigate SDK content by unpacking the SDK on a mobile device or inspecting its behavior in a browser. Instead of storing potentially sensitive data, the client-side SDKs confirm and update flag rules by communicating with LaunchDarkly servers through streaming connections or with REST API requests.

This approach is also beneficial from a data management perspective. Client-side SDKs' bandwidth requirements are lower than server-side SDKs' requirements because LaunchDarkly sends client-side SDKs less data.

Server-side SDKs

Server-side SDKs receive the complete ruleset associated with an SDK key when they initialize a connection to LaunchDarkly's servers. LaunchDarkly continuously updates the SDK's cached flag ruleset whenever flag rules change on LaunchDarkly, using this persistent connection.

When your application requests flag evaluation, server-side SDKs evaluate feature flags using their cached ruleset, and determine the flag variation for a given evaluation context. To do this, they execute an in-process flag evaluation algorithm and return the resulting value.

Server-side SDKs can evaluate flags because these SDKs know your complete flag ruleset. These SDKs can determine contexts' flag variations without having to make requests to LaunchDarkly's servers for every evaluated flag.

You can think of each flag evaluation as a pure function, where LaunchDarkly uses the provided evaluation context along with the complete ruleset to check if a specific context should be included in an evaluation or not. It is important to note that LaunchDarkly passes along rule data, not context data. If a context does not have the correct attributes locally, then it will not be evaluated by the rules that are cached by the SDK.

Edge SDKs

Edge SDKs must be used in conjunction with an edge provider-specific integration:

• You can only use the Akamai SDK if you are also using the Akamai integration.
• You can only use the Cloudflare SDK if you are also using the Cloudflare integration.
• You can only use the Vercel SDK if you are also using the Vercel integration.

The integration writes the latest flag data from the configured environment directly to the edge provider store. It continuously updates the edge provider's cached flag ruleset whenever flag rules change on LaunchDarkly.

Because of this integration, edge SDKs can evaluate flags within the edge provider. The edge SDKs do not have to make requests to LaunchDarkly for every evaluated flag. Instead, these SDKs check with the edge provider store to determine which variation a particular context will receive for a given feature flag.

Flag evaluation comparison

The client-side SDKs require context information in order to initialize the client. The server-side and edge SDKs require the context only when the SDK evaluates a flag.

Here is an example of the differences in flag evaluation between SDKs:

// JavaScript pseudocode
var context = { kind: 'user', key: 'context-key-123abc' }
var ldclient = LDClient.initialize('client-side-id-123abc', context)
var flagValue = ldclient.variation('flag-key-123abc', false)
COPY

The client-side flag data does not include sensitive data, so no personally identifiable information (PII) is exposed on the client side if the code is unpacked or inspected. Additionally, bandwidth requirements are lower for the client-side SDKs, because LaunchDarkly sends less data to client-side SDKs. Edge SDKs do not send events.

Here is an example of the differences in flag data received by the different SDKs:

{
  "show-widgets": {
    "version": 97,
    "flagVersion": 4,
    "value": false,
    "variation": 1,
    "trackEvents": false
  }
}
COPY

Anonymous contexts

Whichever type of SDK you use, you can always designate a particular context as "anonymous." Anonymous contexts work just like other contexts, except that they don't appear on your Contexts list in the LaunchDarkly UI. You might use an anonymous context if you don't yet have much information about the end user, for example, if they have not yet logged in to your application.

If you choose to use anonymous contexts, you have some options for how you set the anonymous context key. The application behavior you want determines which option you should use:

• If all anonymous contexts can receive the same flag variation, and the same experiment treatment, then you can use the same context key across multiple contexts.
• If a given end user should always receive the same flag variation, but not all end users should receive the same flag variation, then each anonymous context must have a different, but stable, context key. This is the behavior you need if you use percentage rollouts, or if you want to run experiments on anonymous users.

In client-side SDKs, typically each instance of a client-side SDK is being used by one end user at a time, in a browser or on a mobile device. The SDK can persist the context key, for example in local storage on the browser, and the context key for the anonymous context will remain stable. In most client-side SDKs, you can configure the SDK to automatically generate the context key for an anonymous context.

In server-side SDKs, the SDK instance is used by many end users at once. Your application determines which context is evaluating feature flags. Therefore, the SDK does not generate context keys for anonymous contexts. Your application code determines which context key to use for each context and passes the appropriate context into the flag evaluation call.

Private attributes

You may not want to send all of the context attributes that you are recording back to LaunchDarkly. The security or data protection requirements of your organization may require you to limit what customer data is transmitted from your service to a third-party platform like LaunchDarkly.

You can use private attributes with client-side, server-side, and edge SDKs. All LaunchDarkly SDKs have configuration options to set all or specified context attributes as private attributes. 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 an "email" attribute to be private 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.

Depending on the type of SDK you use, LaunchDarkly does not receive or store the information in private attributes:

• If you are using a server-side SDK, the SDK will not send the private attribute back to LaunchDarkly.

• If you are using a client-side SDK, the SDK will send the private attribute back to LaunchDarkly for evaluation. However, the SDK won't send the attribute to LaunchDarkly in events data, LaunchDarkly won't store the private attribute, and the private attribute will not appear on the Contexts list or on the detail page for the context.

• If you are using an edge SDK, the SDK does not support sending events. There is no ability to mark attributes as private.

Note that the context key attribute can never be private.

To learn more, read Using private context attributes.

Keys

Before embedding an SDK key into your application's LaunchDarkly configuration, you must identify which category of SDK you're using so that you can select the appropriate type of SDK key.

The Account settings page lists three keys for each environment:

• SDK key
• mobile key
• client-side ID

Each of these keys grants different access levels to LaunchDarkly's SDKs.

LaunchDarkly enforces that each of the SDK types use the appropriate key as described below. Requests made with one of the other two keys will be rejected. To identify which keys are used by each SDK, read Language support.

To find and copy your LaunchDarkly SDK key, mobile key, or client-side ID:

1. Navigate to the Account settings page.
2. Click the Projects tab.
3. Click the name of your project. The Environments tab appears.
4. Click the environment's SDK key, mobile key, or client-side ID to copy it to your clipboard.

SDK key

Configure server-side SDKs to use the SDK key. This key grants server-side SDKs read-only access to all flag data associated with the provided key's environment. With this key, server-side SDKs can download the entire flag ruleset for all flags in the environment.

The SDK key should be kept a secret. If an SDK key is exposed, you can reset it from the Account settings page. To learn how, read Finding and resetting an environment's keys.

Mobile key

Configure mobile SDKs, and other non-JavaScript client-side SDKs, to use the mobile key. The mobile key grants these SDKs access to evaluate any flag that is associated with the key's environment, and that you have enabled for client-side SDK availability by checking the flag's "SDKs using mobile key" checkbox.

Because you must manually connect flags to a client-side SDK, you can restrict which flags are accessible by the client-side ID.

The mobile key does not need to be kept a secret. However, if you wish to reset a mobile key, you can do so from the Account settings page. To learn how, read Finding and resetting an environment's keys.

Client-side ID

Configure JavaScript-based client-side SDKs to use the client-side ID. Configure edge SDKs to use the client-side ID to connect to the edge database for your CDN.

The client-side ID grants these SDKs access to evaluate any flags that are associated with the key's environment, and that you have enabled for client-side SDK availability by checking the flag's SDKs using Client-side key checkbox. Because you must manually connect flags to a client-side SDK, you can restrict which flags are accessible by the client-side ID.

Unlike a mobile key, the client-side ID for an environment never changes. The client-side ID does not need to be kept a secret.

Language support

We offer SDKs for many languages and technologies. Some, but not all, languages have client- and server-side SDKs available.

If the language or framework you use is not listed here, we may provide a sample application to help you get started. Sample applications demonstrate that an SDK is compatible with a particular language or framework. However, LaunchDarkly only provides full support for those languages or frameworks that have a dedicated SDK.

Explore the following SDK reference guides for specific details about how to use LaunchDarkly with your tech stack: