Skip to main content

SDKs Overview

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.

tip

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

Client-side SDKs run in web browsers or on mobile devices. These runtimes execute within untrusted environments. Anyone using the Javascript SDK in a web browser, for example, can find the Client-Side SDK, create a new Identity, look at their flags and potentially write Traits to the Identity.

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

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.

tip

The Server Side SDKs can operate in 2 different modes:

  1. Remote Evaluation
  2. Local Evaluation

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 Diagram

Remote Evaluation is the default mode; simply 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.

Local Evaluation Diagram

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

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.

tip

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 Local Evaluation.

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.

info

Because Clients are almost always operating remotely from your server infrastructure, there is little benefit to them running in 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.
  • Identity overrides do not operate at all.
  • 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.

tip

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.