• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

EDIT ON GITHUB

Client-side, server-side, and edge SDKs

Read time: 15 minutes
Last edited: Aug 14, 2023

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.

Newer versions of LaunchDarkly SDKs replace 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."

Creating contexts and evaluating flags based on them is supported in the latest major versions of most of our SDKs. For these SDKs, the code samples on this page include the two most recent versions.

Understanding the different types of SDKs

It is important to understand the two 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:

SDK TypeThese SDKs:
Client-side
  • are designed for single-user desktop, mobile, and embedded applications.
  • are intended to be used in a potentially less secure environment, such as a personal computer or mobile device.
  • include mobile SDKs.
  • use client-side ID or mobile keys for authorization.
Server-side
  • are designed for multi-user systems.
  • are intended to be used in a trusted environment, such as inside a corporate network or on a web server.
  • use SDK keys for authorization.
Edge
  • are designed for edge layers in content delivery networks (CDNs). LaunchDarkly supports Akamai, Cloudflare, and Vercel.
  • are intended to be used together with a matching CDN integration. The CDN integration allows LaunchDarkly to write to your edge database. Then, you can use the edge SDK to read from that database to provide flag evaluations. This eliminates the need to make a remote call to LaunchDarkly.
  • use client-side IDs to associate LaunchDarkly environments with CDN integrations.

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:

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.

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.

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.

Here's how mobile connections work:

  • When the app is foregrounded, the SDK opens a streaming connection to LaunchDarkly.

    • The initial payload from the streaming connection contains the variations a context instance receives.
    • The streaming connection stays open as long as your app is in the foreground and is connected to the internet.
    • The streaming connection idles unless there are updates. This requires minimal data and battery power to maintain.
    • The SDK actively monitors network availability. They avoid requests when the network is unavailable, and reconnect when the network becomes available again.
  • When the app is backgrounded, the stream connection terminates and the SDK uses polling instead.

    • The SDK polls for flag updates every hour to stay in sync. This strategy has higher latency, but optimizes battery and data usage.
The iOS SDK does not support background fetch

Unlike other mobile SDKs, the iOS SDK does not fetch flag values from the background. To learn more, read Background fetch.

  • The SDK checks for network connectivity at the current polling interval, only making the request if the check succeeds. When it reconnects, it automatically syncs its local cache with LaunchDarkly.

  • When the app is foregrounded again, the SDK reconnects to the stream which sends the latest flag values.

  • If the app closes and reopens without a connection to LaunchDarkly, the flag values cached in local storage are still available.

Whether streaming or polling, the SDK monitors the device's network connectivity state and does not send network requests when the device is offline.

This configuration means that you get near real-time updates for your feature flag values when the app is in the foreground, and maximum device and SDK efficiency when backgrounded. You can configure these settings if needed.

Configure your SDK: Configuration

Streaming mode is not available on watchOS

WatchOS always operates in polling mode, as streaming mode is not available.

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:

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)

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
}
}

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.

Here is an example of setting all attributes as private:

// JavaScript pseudocode
var ldclient = LDClient.initialize('client-side-id-123abc', context, (options = { allAttributesPrivate: true }))

Note that the context key attribute can never be private.

Here is an example of setting just the end user's email address as private:

// JavaScript pseudocode
var ldclient = LDClient.initialize('client-sideID-123abc', context, (options = { privateAttributeNames: ['email'] }))

To learn more, read Using private context attributes.

Configure your SDK: Private 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 key.

Mobile key

Making flags available to mobile SDKs

Use the "Client-side SDK availability" section on a flag's Settings tab to make flags available to mobile SDKs.

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 key.

Client-side ID

Making flags available to client-side SDKs

Use the "Client-side SDK availability" section on a flag's Settings tab to make flags available to client-side SDKs.

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:

SDK nameSDK typeIdentifier
.NET (client-side)Client-side (mobile)Mobile key
.NET (server-side)Server-sideSDK Key
AndroidClient-side (mobile)Mobile key
ApexServer-sideSDK Key
C++ (client-side)Client-sideMobile key
C/C++ (server-side)Server-sideSDK Key
CloudflareEdgeClient-side ID
ElectronClient-sideClient-side ID
ErlangServer-sideSDK Key
FlutterClient-side (mobile)Mobile key
GoServer-sideSDK Key
HaskellServer-sideSDK Key
iOSClient-side (mobile)Mobile key
JavaServer-sideSDK Key
JavaScriptClient-sideClient-side ID
LuaServer-sideSDK Key
Node.js (client-side)Client-sideClient-side ID
Node.js (server-side)Server-sideSDK Key
PHPServer-sideSDK Key
PythonServer-sideSDK Key
ReactClient-sideClient-side ID
React NativeClient-side (mobile)Mobile key
RokuClient-sideMobile key
RubyServer-sideSDK Key
RustServer-sideSDK Key
VercelEdgeClient-side ID
VueClient-sideClient-side ID