Flagsmith ships with SDKs for a bunch of different programming languages. We also have a REST API that you can use if you want to consume the API directly.
The SDKs are split into two different types: Client-side and Server-side sdks. These SDKs have different methods of operation due to the differences in their operating environment.
Environment Keys come in two different types: Client-side and Server-side keys. Make sure you use the correct key depending on the SDK you are using.
Client-side SDKs are also limited to the types of data that they have access to.
Client-side Environment keys are designed to be shared publicly, for example in your HTML/JS code that is sent to a web browser.
Client-side SDKs hit our Edge API directly to retrieve their flags.
Read more about our Client-Side SDKs for your language/platform:
Server-side SDKs run within trusted environments - typically the server infrastructure that you have control over. Because of this you need to should not share your Server-side Environment keys publicly - they should be treated as secrets.
The Server Side SDKs can operate in 2 different modes:
It's important to understand which mode is right for your use case, and what the pros and cons of each one are. This is detailed below.
1 - Remote Evaluation
In this mode, every time the SDK needs to get Flags, it will make a request to the Flagsmith API to get the Flags for the particular request.
Remote Evaluation is the default mode; initialise the SDK and you will be running in
Remote Evaluation mode.
This is the same way that the Client Side SDKs work.
2 - Local Evaluation
In this mode, all flag values are calculated locally, on your server. The Flagsmith SDK includes an implementation of the Flag Engine, and the engine runs within your server environment within the Flagsmith SDK.
You have to configure the SDK to run in
Local Evaluation mode. See the
SDK configuration options for details on how to do that in your particular
When the SDK is initialised in
Local Evaluation mode, it will grab the entire set of details about the Environment
from the Flagsmith API. This will include all the Flags, Flag values, Segment rules, Segment overrides etc for that
Environment. This full complement of data about the Environment enables the Flagsmith SDK to run the Flag Engine
locally and natively within your server infrastructure.
The benefits to doing this are mainly one of latency and performance. Your server side code does not need to hit the Flagsmith API each time a user requests their flags - the flags can be computed locally. Hence it does not need to block and wait for a response back from the Flagsmith API.
The SDK has to request all of the data about an Environment in order to run. Because some of this data could be
sensitive (for example, your Segment Rules), the SDK requires a specific
Server-side Environment Key. This is
different to the regular
Client-side Environment Key. The
Server-side Environment Key should not be shared, and
should be considered sensitive data.
In order to keep their Environment data up-to-date, SDKs running in
Local Evaluation mode will poll the Flagsmith API
regularly and update their local Environment data with any changes from the Flagsmith API. By default the SDK will poll
the Flagsmith every
60 seconds; this rate is configurable within each SDK.
It's important to understand the pros and cons for running
Client Side SDKs
All our Client Side SDKs run in
Remote Evaluation mode only; they cannot run in
Local Evaluation mode. The reason
for this is down to data sensitivity. Because some of this data could be sensitive (for example, your Segment Rules), we
only allow Client Side SDKs to run in
Remote Evaluation mode.
Because Clients are almost always operating remotely from your server infrastructure, there is little benefit to them
Local Evaluation mode.
Pros, Cons and Caveats
Remote Evaluation Mode
- Identities are persisted within the Flagsmith Datastore.
- Identity overrides specified within the Dashboard.
- All Integrations work as designed.
Local Evaluation Mode
- Identities are not sent to the API and so are not persisted in the datastore.
- Because Local mode does not connect to the datastore for each Flag request, it is not able to read the Trait data of Identities from the API. This means that you have to provide the full complement of Traits when requesting the Flags for a particular Identity. Our SDKs all provide relevant methods to achieve this.
- Identity overrides do not operate at all.
- Analytics-based Integrations do not run.
The benefit of running in Local Evaluation mode is that you can process flag evaluations much more efficiently as they are all computed locally.
In circumstances where you need to target a specific identity, you can do this by creating a segment to target that specific user and subsequently adding a segment override for that segment.