Flagsmith Flutter SDK

Flagsmith allows you to manage feature flags and remote config across multiple projects, environments and organisations.

This is the SDK for Flutter for https://www.flagsmith.com/.

Adding to your project

For full documentation visit https://docs.flagsmith.com/clients/flutter/

Experiments

Once an experiment is running, Flagsmith serves the variations automatically through the flag. Your application records exposures (when an identity experienced a variation) and conversion events (what your metrics aggregate).

Enable event collection with enableEvents. Users must be identified: exposures and conversion events are joined per identity, so use the same identifier for flags and events.

final flagsmith = await FlagsmithClient.init(
  apiKey: 'YOUR_CLIENT_SIDE_ENVIRONMENT_KEY',
  config: const FlagsmithConfig(enableEvents: true),
);
final user = Identity(identifier: 'user_42');
await flagsmith.getFeatureFlags(user: user);

// Evaluate the flag and record an exposure in one call
final flag = await flagsmith.getExperimentFlag('checkout_button', user: user);
// ...render based on flag?.variant / flag?.stateValue

// Record a conversion event; the name must match your metric's event name
flagsmith.trackEvent('purchase', value: 99.5);

Exposures

getExperimentFlag evaluates the flag and records a $flag_exposure event with the served variant as its value. It is only recorded when the flag exists, is enabled and the identity is enrolled (flag.experiment?.inExperiment == true). Anything else is logged and skipped, so it is safe to call against environments or servers without experiments.

If you evaluate in one place and render in another, call trackExposureEvent at the point of display instead:

final experiment = flag?.experiment;
if (flag != null && experiment != null) {
  flagsmith.trackExposureEvent('checkout_button',
      value: flag.variant, metadata: {'experiment_id': experiment.id});
}

Exposures are deduplicated per identity and variant within a flush window, so recording one more than once is safe.

Conversion events

trackEvent sends a named event, optionally with a value, traits and metadata. Names starting with $ are reserved. The event name is case-sensitive and must match the metric's configured event name.

Flushing

Events are buffered and posted to eventsURI every eventsFlushInterval ms (10 s), when eventsMaxBuffer (1000) events are queued, and when the app goes to the background (hidden, paused or detached). The background flush needs the Flutter binding initialised before the client is created, and is best effort: iOS may suspend the app before the POST completes, and nothing is sent on force-quit or web page unload. Delivery failures never throw:

• One batch is sent at a time, and each request times out after 3 s.
• Network errors, timeouts and 5xx, 408 or 429 responses are retried, up to 3 attempts, after a random wait of up to 1 s, then 2 s. A batch whose last attempt fails with a 500 (or another 5xx outside 502, 503 and 504) is dropped; otherwise it is kept for the next flush, ahead of newer events.
• Any other error response, such as 400, drops the batch, as does any error other than a network error or timeout, such as an event that cannot be encoded.
• A 401 or 403 drops the buffered events and stops event tracking: the environment key is not accepted.
• The buffer holds eventsMaxBuffer events (at least 1) and drops the oldest when full. While a kept batch waits, filling the buffer no longer flushes it at once: it waits for the next interval or flushEvents(), or, with eventsFlushInterval: 0, for 4 s.

await close() stops the client and returns once the final POST completes or the timeout (10 s by default) passes. To send events without closing the client, await flushEvents(). close() now returns Future<void>, so subclasses that override it must update their signature.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Getting Help

If you encounter a bug or feature request we would like to hear about it. Before you submit an issue please search existing issues in order to prevent duplicates.

Get in touch

If you have any questions about our projects you can email [email protected].