Mirrors/unleash.unleash
1
0
Fork 0
mirror of https://github.com/Unleash/unleash.git synced 2025-05-03 01:18:43 +02:00
Code Issues Projects Releases Wiki Activity
aabb364415
unleash.unleash/website/docs/reference/sdks/index.mdx
Melinda Fekete aabb364415
docs: Update hosting strategies page (#9729)
2025-04-16 12:42:39 +02:00

204 lines
17 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: 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](../understanding-unleash/unleash-overview#system-overview), feature flags can be evaluated within the SDKs or [Unleash Edge](./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](#community-sdks).
## Official SDKs
### Server-side SDKs
Server‑side SDKs run in backend services. They communicate with Unleash or [Unleash Edge](./unleash-edge) using the [Client API](../understanding-unleash/unleash-overview#client-api) and require a [client token](./api-tokens-and-client-keys#client-tokens).
Server-side SDKs perform the flag evaluation locally, meaning all user data is retained within the SDK.
Unleash offers the following server-side SDKs:
- [Go SDK](/docs/generated/sdks/server-side/go.md)
- [Java SDK](/docs/generated/sdks/server-side/java.md)
- [Node.js SDK](/docs/generated/sdks/server-side/node.md)
- [PHP SDK](/docs/generated/sdks/server-side/php.md)
- [Python SDK](/docs/generated/sdks/server-side/python.md)
- [Ruby SDK](/docs/generated/sdks/server-side/ruby.md)
- [Rust SDK](/docs/generated/sdks/server-side/rust.md)
- [.NET SDK](/docs/generated/sdks/server-side/dotnet.md)
### Client-side SDKs
Client-side SDKs are used in frontend and mobile applications. They communicate with Unleash or [Unleash Edge](./unleash-edge) through the [Frontend API](./front-end-api) and require a [frontend token](./api-tokens-and-client-keys#frontend-tokens). 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](./unleash-context). The flag evaluation happens either in [Unleash Edge](./unleash-edge), or in the Unleash server, when using the [Frontend API](./front-end-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:
- [Android SDK](/docs/generated/sdks/client-side/android-proxy.md)
- [Flutter SDK](/docs/generated/sdks/client-side/flutter.md)
- [iOS SDK](/docs/generated/sdks/client-side/ios-proxy.md)
- [JavaScript SDK](/docs/generated/sdks/client-side/javascript-browser.md)
- [Next.js](/docs/generated/sdks/client-side/next-js.md)
- [React SDK](/docs/generated/sdks/client-side/react.md)
- [Svelte SDK](/docs/generated/sdks/client-side/svelte.md)
- [Vue SDK](/docs/generated/sdks/client-side/vue.md)
### 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
| Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| Async initialization | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
| Block until synchronized | ✅ | ✅ | ✅ | ⭕ | ⭕ | ✅ | ✅ | ⭕ |
| Context provider | ✅ | N/A | N/A | N/A | N/A | ✅ | ✅ | N/A |
| Global fallback function | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Flag Query: `namePrefix`, `tags` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Flag Query: `project_name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A | ⭕ |
#### Custom headers
| Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| static | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
| function | ✅ | ✅ | ⭕ | ✅ | ✅ (4.3) | ✅ | ✅ | ⭕ |
#### Built-in strategies
| Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| [Gradual rollout](./activation-strategies) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Gradual rollout with custom stickiness](./stickiness#custom-stickiness) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
| [UserID](./predefined-strategy-types#userids), [IP](./predefined-strategy-types#ips), [hostname](./predefined-strategy-types#hosts) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [IP](./predefined-strategy-types#ips) 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`).
| Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| [Advanced operators](./activation-strategies#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
| Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| Can take context and override fallback value | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Fallback function | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ⭕ | ⭕ |
#### Strategy variants
| Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| [Strategy variants](./strategy-variants) and [custom stickiness](./stickiness#custom-stickiness) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
#### Local backup
| Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| File-based local backup | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
#### Metrics and impression data
| Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| Usage metrics | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Impression data](./impression-data) | ✅ | ✅ | ✅ | ✅ | ⭕ | ✅ | ✅ | ⭕ |
#### Bootstrap
| Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| Bootstrap from file or custom implementation | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
### Default refresh and metrics intervals
#### Server-side SDKs
| Interval | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| Default refresh interval | 15s | 15s | 15s | 15s | 15s | 15s | 15s | 15s |
| Default metrics interval | 60s | 60s | 60s | 60s | 60s | 60s | 60s | 15s |
#### Client-side SDKs
| Interval | [Android](/docs/generated/sdks/client-side/android-proxy.md) | [Flutter](/docs/generated/sdks/client-side/flutter.md) | [iOS](/docs/generated/sdks/client-side/ios-proxy.md) | [JavaScript](/docs/generated/sdks/client-side/javascript-browser.md) | [Next.js](/docs/generated/sdks/client-side/next-js.md) | [React](/docs/generated/sdks/client-side/react.md) | [Svelte](/docs/generated/sdks/client-side/svelte.md) | [Vue](/docs/generated/sdks/client-side/vue.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| Default refresh interval | 60s | 30s | 15s | 30s | 30s | 30s | 30s | 30s |
| Default metrics interval | 60s | 30s | 30s | 60s | 60s | 60s | 60s | 60s |
## Community SDKs
If you need a language or framework not covered officially, explore our community contributions:
- Angular - TypeScript ([angular-unleash-proxy-client](https://github.com/Karelics/angular-unleash-proxy-client) by [Karelics](https://karelics.fi/unleash-feature-flags-with-gitlab/))
- Angular - TypeScript ([ngx-unleash-proxy-client](https://github.com/snowfrogdev/snowfrogdev/tree/main/packages/ngx-unleash-proxy-client))
- Clojure ([AppsFlyer/clojure-unleash](https://github.com/AppsFlyer/unleash-client-clojure))
- C++ ([aruizs/unleash-client-cpp](https://github.com/aruizs/unleash-client-cpp))
- ColdBox - CFML ([coldbox-modules/unleashsdk](https://github.com/coldbox-modules/unleashsdk))
- Dart ([uekoetter.dev/unleash-client-dart](https://pub.dev/packages/unleash))
- Elixir ([afontaine/unleash_ex](https://gitlab.com/afontaine/unleash_ex))
- Haskell ([finn-no/unleash-client-haskell](https://github.com/finn-no/unleash-client-haskell))
- Kotlin ([silvercar/unleash-client-kotlin](https://github.com/silvercar/unleash-client-kotlin))
- NestJS - Node.js ([pmb0/nestjs-unleash](https://github.com/pmb0/nestjs-unleash))
- PHP ([minds/unleash-client-php](https://gitlab.com/minds/unleash-client-php))
- PHP - Symfony ([Stogon/unleash-bundle](https://github.com/Stogon/unleash-bundle))
- React Native / Expo ([nunogois/unleash-react-native](https://github.com/nunogois/unleash-react-native))
- Solid ([nunogois/proxy-client-solid](https://github.com/nunogois/proxy-client-solid))
### 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](https://github.com/Unleash/client-specification) - 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](/client-specification) - 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](#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](#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:
- [Android SDK](/docs/generated/sdks/client-side/android-proxy.md)
- [JavaScript SDK](/docs/generated/sdks/client-side/javascript-browser.md)
- [React SDK](/docs/generated/sdks/client-side/react.md)
- [Svelte SDK](/docs/generated/sdks/client-side/svelte.md)
- [Vue SDK](/docs/generated/sdks/client-side/vue.md)
### 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`.
Reference in New Issue View Git Blame Copy Permalink