2021-05-04 16:08:21 +02:00
---
2022-09-15 09:02:10 +02:00
title: SDK overview
2021-05-04 16:08:21 +02:00
---
2023-09-27 21:06:41 +02:00
import VideoContent from '@site/src/components/VideoContent.jsx'
2024-05-24 12:28:49 +02:00
In order to connect your application to Unleash you will need a client SDK (software developer kit) for your programming language and an [API token ](../how-to/how-to-create-api-tokens ). The SDK will handle connecting to the Unleash server instance and retrieving feature flags based on your configuration. All versions of Unleash (OSS, Pro, and Enterprise) use the same client SDKs.
2021-05-04 16:08:21 +02:00
2022-02-07 13:02:07 +01:00
Unleash provides official client SDKs for a number of programming language. Additionally, our community have developed and contributed SDKs for other languages. So if you can't find your favorite language in the list of official SDKs, check out the [list of clients written by our fantastic community ](#community-sdks ).
2021-05-04 16:08:21 +02:00
2023-10-10 11:42:25 +02:00
## Official SDKs
2023-09-27 21:06:41 +02:00
2023-10-10 11:42:25 +02:00
< VideoContent videoUrls = {["https://www.youtube.com/embed/mCXSAWzdn3I"]}/ >
2021-12-09 13:33:30 +01:00
### Server-side SDKs:
Server-side clients run on your server and communicate directly with your Unleash instance. We provide these official clients:
2021-05-04 16:08:21 +02:00
docs: auto-generate remaining server-side SDK docs (#2858)
This PR builds on the preceding doc auto-generation PRs and generates
documentation for the remaining server-side SDKs.
## Why
Refer to https://github.com/Unleash/unleash/pull/2809 for more context
about generating SDK docs.
## What
- Adds generation for the remaining server-side SDKs
- Moves generated docs from the `/reference/sdks` directory to
`/generated` directory.
- Makes sure that the URLs do not change because of the move by using
the `slug` frontmatter property.
- replaces relative github links in the markdown documents so that they
become absolute github links. (refer to the next section)
- Updates some image styling so that it doesn't apply to readme badges
(we don't need them using `display: block`)
### On link replacing:
This PR adds handling of links in the generated documentation.
Specifically, it changes links in one case:
Relative links to github. Links to code and other files in the
repository. These are prefixed with the repository's URL.
While this should work in most cases, it will fail in cases where the
links to the files are not on the repository's primary branch.
(typically main, but could also be "v3", for instance). In these cases,
the links will get a double branch in the URL and will fail. However, I
see no easy way around this (though suggestions are definitely
accepted!), and think it's a fair tradeoff. It takes the links from
"definitely failing" to "will work in the vast majority of cases".
Note: I originally also wanted to handle the case where the link is an
absolute link to docs.getunleash.io. We could turn these into relative
urls to avoid full page reloads and enjoy a smoother experience.
However, the client-side redirects don't work correctly if the relative
URL goes to a redirect page, so you end up with a 404 page. As such, I
think it's better to leave the links as absolute for now.
2023-01-13 12:40:28 +01:00
- [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 )
2021-06-04 13:44:34 +02:00
2022-09-15 09:02:10 +02:00
### Client-side SDKs
2021-12-09 13:33:30 +01:00
Source proxy and Edge docs from GitHub (#3122)
## What
The main purpose of this PR is to
1. Delete the proxy docs in this repo and replace them with the proxy's
GitHub readme.
2. Add the docs for Unleash Edge.
### Detailed change description
This PR contains a lot of small changes in a large number of files. To
make it easier to get an overview, here's a detailed description of what
happens where:
#### In the `website/docs`directory
Except for the deletion of the proxy doc, all changes in this directory
are rewriting internal links, so that they point to the newly generated
document instead.
#### `package.json` and `yarn.lock`
When including the documentation for Edge, we also want to render the
mermaid diagrams it uses. Docusaurus supports this via a plugin. All
changes in these files are related to installing that plugin.
#### `docusaurus.config.js`
There's two types of changes in this file:
1. Mermaid-related changes: we ask docusaurus to render mermaid in
markdown files and add the plugin
2. Document generation. There's some rewrites to the sdk doc generation
plus an entirely new section that generates docs for Edge and the proxy
#### `sidebars.js`
Two things:
1. Add the edge docs
2. Move both the Edge and the proxy docs up a level, so that they're
directly under "reference docs" instead of nested inside "unleash
concepts".
#### In the `website/remote-content` directory
These are the remote content files. Previously, all of this lived only
in a `readme-fns.js` file, but with the introduction of Edge and proxy
docs, this has been moved into its own directory and refactored into
three files (`shared`, `sdks`, `edge-proxy`).
#### `custom.css`
Style updates to center mermaid diagrams and provide more space around
them.
#### In `static/img`
The image files that were included in the proxy doc and that have been
deleted.
## Why
For two reasons:
1. Reduce duplication for the proxy. Have one source of truth.
2. Add docs for edge.
## Discussion points and review wishes
This is a big PR, and I don't expect anyone to do a line-by-line review
of it, nor do I think that is particularly useful. Instead, I'd like to
ask reviewers to:
1. Visit the [documentation
preview](https://unleash-docs-git-docs-source-proxy-gh-unleash-team.vercel.app/reference/unleash-proxy)
and have a look at both the proxy docs and the Edge docs. Potentially
have a look at the SDK docs too to verify that everything still works.
2. Consider whether they think moving the proxy and edge docs up a level
(in the sidebar) makes sense.
3. Let me know what slug they'd prefer for the Edge docs. I've gone with
`unleash-edge` for now (so that it's
`docs.getunleash.io/reference/unleash-edge`), but we could potentially
also just use `edge`. WDYT?
4. Read through the detailed changes section.
5. Let me know if they have any other concerns or questions.
## Screenies
The new proxy doc:
The new edge doc:
2023-02-16 13:36:28 +01:00
Client-side SDKs can connect to the [Unleash Proxy ](../../generated/unleash-proxy.md ) or to the [Unleash front-end API ](../front-end-api.md ), but _not_ to the regular Unleash client API.
2021-06-04 13:44:34 +02:00
refactor: move docs into new structure / fix links for SEO (#2416)
## What
This (admittedly massive) PR updates the "physical" documentation
structure and fixes url inconsistencies and SEO problems reported by
marketing. The main points are:
- remove or move directories : advanced, user_guide, deploy, api
- move the files contained within to the appropriate one of topics,
how-to, tutorials, or reference
- update internal doc links and product links to the content
- create client-side redirects for all the urls that have changed.
A number of the files have been renamed in small ways to better match
their url and to make them easier to find. Additionally, the top-level
api directory has been moved to /reference/api/legacy/unleash (see the
discussion points section for more on this).
## Why
When moving our doc structure to diataxis a while back, we left the
"physical' files lying where they were, because it didn't matter much to
the new structure. However, that did introduce some inconsistencies with
where you place docs and how we organize them.
There's also the discrepancies in whether urls us underscores or hyphens
(which isn't necessarily the same as their file name), which has been
annoying me for a while, but now has also been raised by marketing as an
issue in terms of SEO.
## Discussion points
The old, hand-written API docs have been moved from /api to
/reference/api/legacy/unleash. There _is_ a /reference/api/unleash
directory, but this is being populated by the OpenAPI plugin, and mixing
those could only cause trouble. However, I'm unsure about putting
/legacy/ in the title, because the API isn't legacy, the docs are. Maybe
we could use another path? Like /old-docs/ or something? I'd appreciate
some input on this.
2022-11-22 10:05:30 +01:00
2023-01-25 14:36:50 +01:00
- [Android SDK ](/docs/generated/sdks/client-side/android-proxy.md )
- [Flutter Proxy SDK ](/docs/generated/sdks/client-side/flutter.md )
- [iOS Proxy SDK ](/docs/generated/sdks/client-side/ios-proxy.md )
- [Javascript SDK ](/docs/generated/sdks/client-side/javascript-browser.md )
- [React Proxy SDK ](/docs/generated/sdks/client-side/react.md )
- [Svelte Proxy SDK ](/docs/generated/sdks/client-side/svelte.md )
- [Vue Proxy SDK ](/docs/generated/sdks/client-side/vue.md )
2021-12-09 13:14:20 +01:00
2021-12-09 13:33:30 +01:00
### Server-side SDK compatibility table
2021-12-09 13:14:20 +01:00
2021-12-09 13:33:30 +01:00
The below table shows what features the various server-side SDKs support. Note that certain features make sense only for some clients due to how the programming language works or due to how the client works.
2021-12-09 13:14:20 +01:00
**Legend**:
- ✅: Implemented
- ⭕: Not yet implemented, but we're looking into it
- ❌: Not implemented, not planned
- **N/A**: Not applicable to this SDK
2021-12-09 13:33:30 +01:00
:::note
2022-06-29 13:04:21 +02:00
2022-05-20 08:17:36 +02:00
If you see an item marked with a ❌ that you would find useful, feel free to reach out to us ([on Slack](https://slack.unleash.run/), for instance) with your use case. It may not be something we can prioritize right now, but if you'd like to contribute it back to the community, we'd love to help you build it.
2021-12-09 13:14:20 +01:00
2022-06-29 13:04:21 +02:00
:::
2021-12-09 13:14:20 +01:00
2023-02-22 10:42:47 +01:00
| 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 ) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| **Category: Initialization** | | | | | | | | |
| Async initialization | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |
| Can block until synchronized | ✅ | ✅ | ✅ | ⭕ | ⭕ | ✅ | ✅ | ⭕ |
| Default refresh interval | 10s | 15s | 15s | 15s | 15s | 30s | 30s | 15s |
| Default metrics interval | 60s | 60s | 60s | 60s | 60s | 60s | 30s | 15s |
| Context provider | ✅ | N/A | N/A | N/A | N/A | ✅ | ✅ | N/A |
| Global fallback function | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
2024-05-24 12:28:49 +02:00
| Flag Query: `namePrefix` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Flag Query: `tags` | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Flag Query: `project_name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | N/A | ⭕ |
2023-02-22 10:42:47 +01:00
| **Category: Custom Headers** | | | | | | | | |
| static | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
| function | ✅ | ✅ | ⭕ | ✅ | ✅ (4.3) | ✅ | ✅ | ⭕ |
| **Category: Built-in strategies** | | | | | | | | |
| [Standard ](../reference/activation-strategies#standard ) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Gradual rollout ](../reference/activation-strategies#gradual-rollout ) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [Gradual rollout: custom stickiness ](../reference/activation-strategies#customize-stickiness-beta ) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
| [UserID ](../reference/activation-strategies#userids ) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [IP ](../reference/activation-strategies#ips ) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| [IP ](../reference/activation-strategies#ips ): CIDR syntax | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ✅ | ✅ |
| [Hostname ](../reference/activation-strategies#hostnames ) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Category: [Custom strategies](../custom-activation-strategies.md)** | | | | | | | | |
| Basic support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| < span id = "strategy-constraints" > **Category: [Strategy constraints ](../strategy-constraints.md )**</ span > | | | | | | | | |
| Basic support (`IN`, `NOT_IN` operators) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| < span id = "strategy-constraints-advanced-support" > Advanced support (Semver, date, numeric and extended string operators)< / span > (introduced in) | ✅ (5.1) | ✅ (3.12) | ✅ (3.3) | ✅ (5.1) | ✅ (4.2) | ✅ (2.1) | ✅ (1.3.1) | ⭕ |
| **Category: [Unleash Context](../reference/unleash-context)** | | | | | | | | |
| Static fields (`environment`, `appName` ) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Defined fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Custom properties | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| **Category: [`isEnabled`](../client-specification#implementation-of-isenabled)** | | | | | | | | |
| Can take context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Override fallback value | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Fallback function | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ | ⭕ | ⭕ |
| **Category: [Variants](../feature-toggle-variants.md)** | | | | | | | | |
| Basic support | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Custom fallback variant | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
| Custom weight | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
2023-09-08 10:34:04 +02:00
| [Custom stickiness ](../stickiness.md#custom-stickiness-beta ) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
| [Strategy Variants ](./strategy-variants )| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
2023-02-22 10:42:47 +01:00
| **Category: Local backup** | | | | | | | | |
| File based backup | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
| **Category: Usage metrics** | | | | | | | | |
| Can disable metrics | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Client registration | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Basic usage metrics (yes/no) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
2023-07-11 10:54:49 +02:00
| [Impression data ](../impression-data.md ) | ✅ | ✅ | ⭕ | ✅ | ⭕ | ⭕ | ✅ | ⭕ |
2023-02-22 10:42:47 +01:00
| **Category: Bootstrap (beta)** | | | | | | | | |
2023-04-07 10:34:38 +02:00
| Bootstrap from file | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
| Custom Bootstrap implementation | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⭕ |
2021-12-09 13:14:20 +01:00
2022-01-11 09:16:07 +01:00
## Community SDKs ❤️ {#community-sdks}
2021-12-09 13:33:30 +01:00
Here's some of the fantastic work our community has done to make Unleash work in even more contexts. If you still can't find your favorite language, let us know and we'd love to help you create the client for it!
2021-05-04 16:08:21 +02:00
2023-06-16 19:54:37 +02:00
- Angular - TypeScript ([angular-unleash-proxy-client](https://github.com/Karelics/angular-unleash-proxy-client) by [Karelics ](https://karelics.fi/unleash-feature-flags-with-gitlab/ ))
2022-06-29 13:04:21 +02:00
- 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))
2023-06-29 12:02:27 +02:00
- ColdBox - CFML ([coldbox-modules/unleashsdk](https://github.com/coldbox-modules/unleashsdk))
2022-06-29 13:04:21 +02:00
- Dart ([uekoetter.dev/unleash-client-dart](https://pub.dev/packages/unleash))
- Elixir ([afontaine/unleash_ex](https://gitlab.com/afontaine/unleash_ex))
2023-06-27 09:08:04 +02:00
- Haskell ([finn-no/unleash-client-haskell](https://github.com/finn-no/unleash-client-haskell))
2022-06-29 13:04:21 +02:00
- Kotlin ([silvercar/unleash-client-kotlin](https://github.com/silvercar/unleash-client-kotlin))
- Laravel - PHP ([mikefrancis/laravel-unleash](https://github.com/mikefrancis/laravel-unleash))
- NestJS - Node.js ([pmb0/nestjs-unleash](https://github.com/pmb0/nestjs-unleash))
- PHP ([minds/unleash-client-php](https://gitlab.com/minds/unleash-client-php))
2022-09-07 15:21:40 +02:00
- PHP - Symfony ([Stogon/unleash-bundle](https://github.com/Stogon/unleash-bundle))
2022-06-29 13:04:21 +02:00
- React Native / Expo ([nunogois/proxy-client-react-native](https://github.com/nunogois/proxy-client-react-native))
- Solid ([nunogois/proxy-client-solid](https://github.com/nunogois/proxy-client-solid))
2021-05-04 16:08:21 +02:00
- _...your implementation for your favorite language._
2022-01-10 14:53:41 +01:00
2022-03-04 12:56:16 +01:00
### Implement your own SDK {#implement-your-own-sdk}
2022-01-10 14:53:41 +01:00
If you can't find an SDK that fits your need, 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, overall guide of the _Unleash Architecture_ and important aspects of the SDK role in it all.
2022-03-04 12:56:16 +01:00
2023-11-02 14:43:39 +01:00
## Client-side SDK behavior
The following section details the behavior of frontend / client-side SDKs when initializing and fetching flags with respect to network connectivity.
When the SDK is initialized in the application, an in memory repository is setup and synchronized against the frontent API using the configured token and context. Note that the frontend API is hosted by either the Unleash Proxy/Edge or the upstream Unleash instance directly.
1. All feature flag evaluation is performed by the Proxy/Edge or Unleash instance. A payload of all enabled flags and their variants (if applicable) is returned as a single request. Disabled flags are not included.
2. When a page inside the application requests a feature flag, the SDK will return the flag state from memory. No network connection to the frontend API is performed.
2024-05-24 12:28:49 +02:00
3. The SDK periodically syncs with the frontend API to retrieve the latest set of enabled flags
2023-11-02 14:43:39 +01:00
2022-03-04 13:37:59 +01:00
## Working offline
2022-03-04 12:56:16 +01:00
2023-06-29 12:02:27 +02:00
Once they have been initialized, all Unleash clients will continue to work perfectly well without an internet connection or in the event that the Unleash Server has an outage.
2022-03-04 13:37:59 +01:00
2024-05-24 12:28:49 +02:00
Because the SDKs and the Unleash Proxy/Edge cache their feature flag states locally and only communicate with the Unleash server (in the case of the server-side SDKs and the Proxy) or the Proxy/Edge (in the case of front-end SDKs) at predetermined intervals, a broken connection only means that they won't get any new updates.
2022-03-04 13:37:59 +01:00
2024-05-24 12:28:49 +02:00
Unless the SDK supports [bootstrapping ](#bootstrapping ), it _will_ need 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 will fall back to evaluating as disabled or as the specified default value (in SDKs that support that).
2022-03-04 13:43:02 +01:00
2022-03-04 13:37:59 +01:00
### Bootstrapping
2024-05-24 12:28:49 +02:00
By default, all SDKs reach out to the Unleash Server at startup to fetch their flag configuration. Additionally, some of the server-side SDKs and the Proxy (see the above [compatibility table ](#server-side-sdk-compatibility-table )) also support _bootstrapping_ , which allows them to get their flag configuration from a file, the environment, or other local resources. These SDKs can work without any network connection whatsoever.
2022-03-04 13:37:59 +01:00
Bootstrapping is also supported by the following front-end client SDKs:
2022-06-29 13:04:21 +02:00
2023-01-25 14:36:50 +01:00
- [Android SDK ](/docs/generated/sdks/client-side/android-proxy.md )
- [Javascript SDK ](/docs/generated/sdks/client-side/javascript-browser.md )
- [React Proxy SDK ](/docs/generated/sdks/client-side/react.md )
- [Svelte Proxy SDK ](/docs/generated/sdks/client-side/svelte.md )
- [Vue Proxy SDK ](/docs/generated/sdks/client-side/vue.md )
