Skip to main content

Real-time flag updates

When an application fetches its current feature flags, it usually caches the flags for a certain amount of time to make efficient use of the Flagsmith API and network resources. In some cases, you may want an application to be notified about feature flag updates without needing to repeatedly call the Flagsmith API. You can achieve this by subscribing to real-time flag updates.

Prerequisites​

Real-time flag updates require an Enterprise subscription.

Real-time flag updates are only available on the public SaaS Flagsmith instance. Self-hosted and private cloud Flagsmith installations do not support real-time flag updates.

Setup​

To enable real-time flag updates for your Flagsmith project:

  1. Log in to the Flagsmith dashboard as a user with project administrator permissions.
  2. Navigate to Project Settings > SDK Settings.
  3. Enable Real-time updates.

Applications using a supported Flagsmith SDK do not subscribe to real-time flag updates by default. Refer to your SDK's documentation for subscribing to real-time flag updates.

How it works​

The following sequence diagram shows how a typical application would use real-time flag updates. Billable API requests are highlighted in yellow.

Your application subscribes to real-time flag updates by opening a long-lived server-sent events (SSE) connection to Flagsmith, which is specific to its current environment.

When the environment is updated in some way, either via the Flagsmith dashboard or the Admin API, all clients connected to that environment's real-time stream will receive a message containing the latest update's timestamp. If your application's latest flags are older than the received timestamp, it requests the latest flags from Flagsmith. When your application receives the latest flags, you must propagate the latest flag state throughout your application as necessary.

Limitations​

Real-time flag update events only contain a timestamp indicating when any flag in the environment was last updated. Applications must still call the Flagsmith API to get the actual flags for their current environment or user.

Only environment-level feature changes result in flag update events. For example, the following operations will generate flag update events:

  • Manually toggling a flag on or off, or changing its value.
  • A scheduled Change Request for a feature goes live.
  • Creating or updating segment overrides for a feature.

Project-level or identity-level operations will not generate flag update events:

  • Changing a segment definition.
  • Updating an identity's traits.
  • Creating or updating an identity override.

The following SDK clients support subscribing to real-time flag updates:

  • JavaScript
  • Android
  • Flutter
  • Python

Implementation details​

The event source URL used by Flagsmith SDKs is:

https://realtime.flagsmith.com/sse/environments/ENVIRONMENT_ID/stream

Each real-time flag event message is a JSON object containing a Unix epoch timestamp of the environment's last update:

{
 "updated_at": 3133690620000
}