Skip to main content

SDK overview

Unleash offers a number of client libraries (SDKs) designed to help you integrate Unleash into your applications. The SDKs provide an interface for fetching and evaluating feature flags.

With Unleash's architecture, feature flags can be evaluated within the SDKs or Unleash Edge, making evaluations incredibly fast. SDKs cache feature flag data in memory, providing high reliability.

Unleash provides official SDKs for a number of programming languages. Our community has also contributed SDKs for additional languages.

Official SDKs​

Server-side SDKs​

Server‑side SDKs run in backend services. They communicate with Unleash or Unleash Edge using the Client API and require a client token. Server-side SDKs perform the flag evaluation locally, meaning all user data is retained within the SDK.

Unleash offers the following server-side SDKs:

Client-side SDKs​

Client-side SDKs are used in frontend and mobile applications. They communicate with Unleash or Unleash Edge through the Frontend API and require a frontend token. Unlike server-side SDKs, client-side SDKs do not perform the flag evaluation locally. Instead, they fetch all enabled feature flags for a given Unleash Context. The flag evaluation happens either in Unleash Edge, or in the Unleash server, when using the Frontend API directly.

When the SDK initializes, it sets up an in-memory repository and retrieves a list of all enabled flags and their variants in a single request. Once fetched, the SDK serves flag values from memory, without making additional requests. It periodically refreshes the list of enabled flags to keep the data up to date.

Unleash offers the following client-side SDKs:

Feature compatibility in server-side SDKs​

The following tables show which features are supported by each server-side SDK. Some features are only applicable to specific SDKs, depending on the programming language or how the client is implemented.

Symbol reference

✅ Implemented | ❌ Not supported | ⭕ Not implemented, but under consideration | N/A Not applicable to this SDK

Initialization​

CapabilityJavaNode.jsGoPythonRuby.NETPHPRust
Async initialization✅✅✅✅✅✅❌✅
Block until synchronized✅✅✅⭕⭕✅✅⭕
Context provider✅N/AN/AN/AN/A✅✅N/A
Global fallback function✅✅✅✅❌❌❌❌
Flag Query: namePrefix, tags✅✅❌❌❌❌✅❌
Flag Query: project_name✅✅✅✅✅✅N/A⭕

Custom headers​

CapabilityJavaNode.jsGoPythonRuby.NETPHPRust
static✅✅✅✅✅✅✅⭕
function✅✅⭕✅✅ (4.3)✅✅⭕

Built-in strategies​

CapabilityJavaNode.jsGoPythonRuby.NETPHPRust
Gradual rollout✅✅✅✅✅✅✅✅
Gradual rollout with custom stickiness✅✅✅✅✅✅✅⭕
UserID, IP, hostname✅✅✅✅✅✅✅✅
IP with CIDR syntax✅✅✅✅✅⭕✅✅

Custom strategies​

All server-side SDKs have basic support.

Strategy constraints​

All server-side SDKs have support for the basic operators (IN, NOT_IN).

CapabilityJavaNode.jsGoPythonRuby.NETPHPRust
Advanced operators✅ (5.1)✅ (3.12)✅ (3.3)✅ (5.1)✅ (4.2)✅ (2.1)✅ (1.3.1)⭕

Unleash Context​

Static fields (environment, appName), defined fields, and custom properties are supported in all server-side SDKs.

isEnabled implementation​

CapabilityJavaNode.jsGoPythonRuby.NETPHPRust
Can take context and override fallback value✅✅✅✅✅✅✅✅
Fallback function✅✅✅✅✅⭕⭕⭕

Strategy variants​

CapabilityJavaNode.jsGoPythonRuby.NETPHPRust
Strategy variants and custom stickiness✅✅✅✅✅✅✅⭕

Local backup​

CapabilityJavaNode.jsGoPythonRuby.NETPHPRust
File-based local backup✅✅✅✅✅✅✅⭕

Metrics and impression data​

CapabilityJavaNode.jsGoPythonRuby.NETPHPRust
Usage metrics✅✅✅✅✅✅✅✅
Impression data✅✅✅✅⭕✅✅⭕

Bootstrap​

CapabilityJavaNode.jsGoPythonRuby.NETPHPRust
Bootstrap from file or custom implementation✅✅✅✅✅✅✅⭕

Default refresh and metrics intervals​

Server-side SDKs​

IntervalJavaNode.jsGoPythonRuby.NETPHPRust
Default refresh interval15s15s15s15s15s15s15s15s
Default metrics interval60s60s60s60s60s60s60s15s

Client-side SDKs​

IntervalAndroidFlutteriOSJavaScriptNext.jsReactSvelteVue
Default refresh interval60s30s15s30s30s30s30s30s
Default metrics interval60s30s30s60s60s60s60s60s

Community SDKs​

If you need a language or framework not covered officially, explore our community contributions:

Implement your own SDK​

If you can't find an SDK that fits your requirements, you can also develop your own SDK. To make implementation easier, check out these resources:

  • Unleash Client Specifications - Used by all official SDKs to make sure they behave correctly across different language implementations. This lets us verify that a gradual rollout to 10% of the users would affect the same users regardless of which SDK you're using.
  • Client SDK overview - A brief guide of the Unleash Architecture and important aspects of the SDK role in it all.

Offline behavior​

Once they have been initialized, all Unleash clients continue to function without an internet connection or in the event that the Unleash server has an outage.

Because the SDKs and the Unleash Edge cache their feature flag states locally and only communicate with the Unleash server or Edge at predetermined intervals, a broken connection only means that they won't get any new updates.

Unless the SDK supports bootstrapping, it needs to connect to Unleash at startup to get its initial feature flag data set. If the SDK doesn't have a feature flag data set available, all flags fall back to evaluating as disabled or as the specified default value.

Bootstrapping​

By default, all SDKs reach out to the Unleash server at startup to fetch their flag configuration. Additionally, most of the server-side SDKs and Unleash Edge support bootstrapping, which allows them to get their flag configuration from a file, the environment, or other local resources. These SDKs can function without any network connection.

Bootstrapping is also supported by the following frontend SDKs:

SDK identification headers​

To identify which SDK instances are connected to Unleash, the following headers must be attached to all requests made by the SDK to the server (/api/client for backend SDKs and /api/frontend for frontend SDKs):

unleash-connection-id

  • Description: A unique identifier for the current SDK instance.

  • Format: Automatically generated using the idiomatic unique identifier generator for the specific programming ecosystem. For example, randomUUID from crypto in Node.js.

  • Additional information: This connection ID represents a long-lived connection between the SDK and the Unleash server. An SDK should generate a new connection ID each time an SDK instance is instantiated (for example, when calling new Unleash() in a Node SDK). The same connection ID should be used for each request when an SDK instance polls the API. This header replaces the legacy unleash-instanceid which can be overwritten by the client.

    Backend SDKs used in short-lived request/response models (like Next.js server mode and PHP) should not provide this header.

unleash-sdk

  • Description: Provides information about the language/framework and version of the SDK making the request.
  • Format: The language/framework followed by the @ symbol and the semantic version of the SDK. For example, unleash-client-java@10.0.1 or unleash-client-node@6.4.4.
  • Additional information: Each SDK implementation should use a platform-idiomatic method to read the version from a package manager and update it with each version release.

unleash-appname (Optional)

  • Description: Specifies the name of your application that is communicating with Unleash.
  • Format: User-defined with some SDKs providing a default fallback value. For example, billing-service.