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

    EDIT ON GITHUB

    Client-side and server-side SDKs

    Read time: 8 minutes
    Last edited: Aug 03, 2022

    Overview

    This topic explains the differences between LaunchDarkly's client- and server-side 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 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

    The table below summarizes the differences between client- and server-side SDKs:

    SDK TypeDetails
    Client-sideThese SDKs are designed for single-user desktop, mobile, and embedded applications.
    These SDKs are intended to be used in a potentially less secure environment, such as a personal computer or mobile device.
    These SDKs include mobile SDKs.
    Server-sideThese SDKs are designed for multi-user systems.
    These SDKs are intended to be used in a trusted environment, such as inside a corporate network or on a web server.

    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/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 automatically populate values for the os and device built-in user attributes. To learn more, read Built-in user attributes.
    • Mobile SDKs support multiple environments. To learn more, read Multi-environment support.
    • Mobile SDKs handle streaming and polling connections differently than other client-side SDKs. To learn more, read Receiving updates from LaunchDarkly.

    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, and mobile 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 and/or projects, you can use the the multi-environment SDK feature to access flags in multiple places.

    Receiving updates from LaunchDarkly

    All SDKs open a Server-Sent Events streaming connection to LaunchDarkly. The initial payload from the streaming connection contains the variations your user receives.

    By default, most client-side and server-side SDKs receive updated flag values when you change a flag. Server-side SDKs receive flag configuration changes over the stream, while client-side SDKs receive flag value changes for a specific user.

    Mobile applications are more likely than web or desktop software to lose their network connection. To account for this, our mobile SDKs monitor the connection state to LaunchDarkly and use different connection types depending on whether the app is in the foreground or in the background.

    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 your user 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 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. To learn more, read Configuration.

    Streaming mode is not available on watchOS

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

    Security

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

    Client-side SDKs

    Client-side SDKs typically run on customers' own devices. They can be compromised by 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 user 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.

    Flag evaluations

    The two 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 user at a time. When a flag evaluation is requested, client-side SDKs delegate the flag evaluation to LaunchDarkly on behalf of the specific user. LaunchDarkly's services are responsible for evaluating flag rules for the user. 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 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 user. 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 users' 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 user context along with the complete ruleset to check if a specific user should be included in an evaluation or not. It is important to note that LaunchDarkly passes along rule data, not user data. If a user does not have the correct attributes locally, then it will not be evaluated by the rules that are cached by the SDK.

    Flag evaluation comparison

    The client-side SDK requires user information in order to initialize the client. The server-side SDK requires the user context only when the SDK evaluates a flag.

    Here is an example of the differences in flag evaluation between the client-side and server-side SDKs:

    // JavaScript pseudocode
    var user = {"key": "user_key_123"}
    var ldclient = LDClient.initialize("YOUR_CLIENT_SIDE_ID", user);
    var showFeature = ldclient.variation("FF_KEY", 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.

    Here is an example of the differences in flag data received by the client-side and server-side SDKs:

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

    Private user attributes

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

    All LaunchDarkly SDKs have configuration options to set all or specified user attributes as private attributes.

    You can use private user attributes with both client-side and server-side SDKs, although the SDKs' requirements are different. With a client-side SDK, LaunchDarkly's servers receive and process private attributes, but do not store them. Server-side SDKs work differently. They store a full list of rules, including user attributes. Because the rules are available locally to a server-side SDK, you do not need to send LaunchDarkly information about private attributes.

    Here is an example of setting all attributes as private:

    // JavaScript pseudocode
    var ldclient = LDClient.initialize('YOUR_CLIENT_SIDE_ID', user,
    options = { allAttributesPrivate: true });

    Note that the user key attribute can never be private.

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

    // JavaScript pseudocode
    var ldclient = LDClient.initialize('YOUR_CLIENT_SIDE_ID', user,
    options = { privateAttributeNames: ["email"] });

    To learn more, read Using private user attributes. For specifics on implementing private user attributes in a particular SDK, read User configuration.

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

    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.

    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.

    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 Resetting an environment's key.

    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 Resetting an environment's key.

    Client-side ID

    Configure JavaScript-based client-side SDKs to use the client-side ID. 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.

    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/C++ (client-side)Client-sideMobile key
    C/C++ (server-side)Server-sideSDK Key
    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
    VueClient-sideClient-side ID