Skip to main content

Flagsmith Flutter SDK

This SDK can be used for Flutter applications. The source code for the client is available on GitHub.

The Flagsmith Flutter SDK supports iOS, Android and Web targets.

Getting Started​

Install the client library by adding it to your application's pubspec.yaml file:

dependencies:
    flagsmith: ^6.0.0

Basic Usage​

The SDK is initialised against a single Environment. You can find your Environment key in the Environment settings page.

Retrieving feature flags for your project​

In your application, initialise the Flagsmith client with your API key:

import 'package:flagsmith/flagsmith.dart';

final flagsmithClient = FlagsmithClient(
        apiKey: 'YOUR_ENV_API_KEY'
        config: config,
        seeds: <Flag>[
            Flag.seed('feature', enabled: true),
        ],
    );
await flagsmithClient.initialize();
await flagsmithClient.getFeatureFlags(reload: true) // fetch updates from api

If you prefer async initialization then you can use:

import 'package:flagsmith/flagsmith.dart';

final flagsmithClient = await FlagsmithClient.init(
        apiKey: 'YOUR_ENV_API_KEY',
        config: config,
        seeds: <Flag>[
            Flag.seed('feature', enabled: true),
        ],
    );
await flagsmithClient.getFeatureFlags(reload: true) // fetch updates from api

To check if a feature flag exists:

bool featureExists = await flagsmithClient.hasFeatureFlag("my_test_feature");

Check if a feature flag exist and is enabled:

bool featureEnabled = await flagsmithClient.isFeatureFlagEnabled("my_test_feature");
if (featureEnabled) {
    // run the code to execute enabled feature
} else {
    // run the code if feature switched off
}

To get the configuration value for a feature flag:

final myRemoteConfig = await flagsmithClient.getFeatureFlagValue("my_test_feature");
if (myRemoteConfig != null) {
    // run the code to use remote config value
} else {
    // run the code without remote config
}

To listen for fetch request state:

flagsmithClient.loading.listen((state){
    // FlagsmithLoading.loading
    // FlagsmithLoading.loaded
});

To listen for feature flag changes:

flagsmithClient.stream("my_test_feature").listen((value){
    // call to action
});
StreamBuilder(
    stream: flagsmithClient.stream("my_test_feature"),
    builder: (context, AsyncSnapshot<String> snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
            return CircularProgressIndicator();
        }
        return TextButton(
            onPressed: snapshot.data.enabled ? (){} : null,
            child: Text('Call to Action'),);
    },
),

Cached flags​

You can use caches instead of async/await:

final config = FlagsmithConfig(
    baseURI: 'https://flagsmith.example.com/api/v1/',
    connectTimeout: 200,
    receiveTimeout: 500,
    sendTimeout: 500,
    storeType = StoreType.inMemory,
    caches: true, // mandatory if you want to use caches
);
await flagsmithClient.initialize();

final flagsmithClient = await FlagsmithClient.init(
        apiKey: 'YOUR_ENV_API_KEY',
        config: config,
        seeds: <Flag>[
            Flag.seed('feature', enabled: true),
        ],
    );

await flagsmithClient.getFeatureFlags(reload: true); // fetch updates from api
bool isFeatureEnabled = flagsmithClient.hasCachedFeatureFlag('feature');

Identifying users​

To check if a feature exists for an Identity:

final user = Identity(identifier: 'flagsmith_sample_user');
bool featureEnabled = await flagsmithClient.hasFeatureFlag('my_test_feature', user: user);
if (featureEnabled) {
    // run the code to execute enabled feature for given user
} else {
    // run the code when feature switched off
}

To get the feature flag configuration value for an Identity:

final myRemoteConfig = await flagsmithClient.getFeatureFlagValue('my_test_feature', user: user);
if (myRemoteConfig != null) {
    // run the code to use remote config value
} else {
    // run the code without remote config
}

To get the user traits for an Identity:

final userTraits = await flagsmithClient.getTraits(user)
if (userTraits != null && userTraits) {
    // run the code to use user traits
} else {
    // run the code without user traits
}

To get the trait value for an Identity and specific Trait key:

final userTrait = await flagsmithClient.getTrait(user, 'cookies_key');
if (userTrait != null) {
    // run the code to use user trait
} else {
    // run the code without user trait
}

Or get user traits for an Identity and specific Trait keys:

final userTraits = await flagsmithClient.getTraits(user, keys: ['cookies_key', 'other_trait']);
if (userTraits != null) {
    // run the code to use user traits
} else {
    // run the code without user traits
}

To update a user trait for an Identity:

final userTrait = await flagsmithClient.getTrait(user, 'cookies_key');
if (userTrait != null) {
    // update value for user trait
    var updatedTrait = userTrait.copyWith(value: 'new value');
    Trait updated = await flagsmithClient.updateTrait(user, updatedTrait);
} else {
    // run the code without user trait
}

Reset storage​

To reset storage and re-seed default values:

await flagsmithClient.reset();

Override default configuration​

By default, the client uses the default configuration. You can override this configuration as follows:

final flagsmithClient = FlagsmithClient(
      config: FlagsmithConfig(
          baseURI: 'https://flagsmith.example.com/api/v1/'
      ), apiKey: 'YOUR_ENV_API_KEY');

Override the default configuration with your own:

final flagsmithClient = FlagsmithClient(
      config: FlagsmithConfig(
          baseURI: 'https://flagsmith.example.com/api/v1/',
          connectTimeout: 200,
          receiveTimeout: 500,
          sendTimeout: 500,
          storeType = StoreType.inMemory,
          caches: true,
      ), apiKey: 'YOUR_ENV_API_KEY');

Real-time Flag Updates​

tip

Real-time Flags are part of our SaaS Scale-Up and Enterprise plans.

Real-time Flags are currently in beta. Please contact us to join the beta!

Real-time flag updates are disabled by default. You can enable them simply by changing the configuration as follows:

final flagsmithClient = FlagsmithClient(
      config: FlagsmithConfig(
          enableRealtimeUpdates: true,
      ), apiKey: 'YOUR_ENV_API_KEY');

This will use the default Flagsmith realtime updates URI: 'https://realtime.flagsmith.com/sse/environments/', with a reconnect interval of 29000 milliseconds.

You can change this configuration with your own SSE connection:

final flagsmithClient = FlagsmithClient(
      config: FlagsmithConfig(
          enableRealtimeUpdates: true,
          realtimeUpdatesBaseURI: 'https://your_sse_endpoint.com/sse/',
          reconnctToSSEInterval: 15000,
      ), apiKey: 'YOUR_ENV_API_KEY');

Known issues​

  • If using the package Dio, you may encounter an error saying Bad state: Future already completed. There is a bug in the Dio package, introduced in 4.0.5 (and as of writing this on 12/09/2022, is unresolved). To resolve, you'll need to pin your Dio version in pubspec.yaml to 4.0.4 or earlier. You can track the state of this issue here within our repo and also at the dio repo.