Flutter plugin

This guide provides detailed information about our Flutter plugin which is built on top of our Android SDK and iOS mobile SDKs. The plugin provides you a way to interact with the native SDKs.

All of our SDKs are open source. Go to our Flutter GitHub repository to see the source code.

Language support

Dart SDK v2.16.2 and greater, and Flutter v2.5.0 and greater.

Initialization

Set up Split in your code base with the following two steps:

1. Add the package in your pubspec.yaml file

dependencies:
  splitio: 0.1.6

2. Instantiate the plugin

/// Initialize Split plugin
import 'package:splitio/split_client.dart';
import 'package:splitio/splitio.dart';
/// KEY represents your internal user id, or the account id that 
/// the user belongs to. 
/// This could also be a cookie you generate for anonymous users.
final Splitio _split = Splitio('YOUR_SDK_KEY', 'KEY');

We recommend keeping only one instance of the Splitio object at all times (singleton pattern) and reusing it throughout your application.

Include the API key for the environment that you are setting up the SDK for. The API key is available on your Organization settings page, on the API keys tab. Select the "Client-side" type. This is a special type of API token with limited privileges to be used on mobile clients. Learn more about API keys.

Using the plugin

Basic use

When the SDK is instantiated, it starts background tasks to update an in-memory cache with small amounts of data fetched from Split servers. This process can take up to a few hundred milliseconds, depending on the size of data. If the SDK is asked to evaluate which treatment to show to a customer for a specific feature flag while it's in this intermediate state, it may not have the data necessary to run the evaluation. In this case, the SDK does not fail, rather, it returns the control treatment.

To make sure the SDK is properly loaded before asking it for a treatment, wait until the SDK is ready, as shown below. You can use the onReady parameter when creating the client to get notified when this happens.

After the observable calls back, you can use the getTreatment method to return the proper treatment based on the FEATURE_FLAG_NAME and the key variable you passed when instantiating the SDK. Then use an if-else-if block as shown below and insert the code for the different treatments that you defined in the Split user interface. Remember the final else branch in your code to handle the client returning control.

/// Get treatment
_split.client(onReady: (client) async {
  final String treatment = await client.getTreatment('FEATURE_FLAG_NAME');

  if (treatment == 'on') {
    /// Insert code here to show on treatment
  } else if (treatment == 'off') {
    /// Insert code here to show off treatment
  } else {
    /// Insert your control treatment code here
  }
});

Shutdown

Call the client.destroy() method once you've stopped using the client, as this method gracefully shuts down the Split SDK by stopping all background threads, clearing caches, closing connections, and flushing the remaining unpublished impressions.

/// You should call destroy() on the client once it is no longer needed:
_client.destroy();

After destroy() is called and finishes, any subsequent invocations to getTreatment/getTreatments or manager methods result in control or empty list, respectively.

Multiple evaluations at once

In some instances, you may want to evaluate treatments for multiple feature flags at once. Use the client.getTreatments method to do this. Pass a list of the feature flag names you want treatments for and the method returns a map with the results.

const featureFlagNames = ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2'];
var treatments = {};

_split.client(onReady: (client) async {
  treatments = await client.getTreatments(featureFlagNames);
});

Attribute syntax

To target based on custom attributes, pass the client's getTreatment method as an attribute map at runtime.

In the example below, we are rolling out a feature flag to users. The provided attributes plan_type, registered_date, permissions, and deal_size are passed to the getTreatment call. These attributes are compared and evaluated against the attributes used in the rollout plan as defined in the Split user interface to decide whether to show the on or off treatment to this account. The getTreatment method supports five types of attributes: strings, numbers, dates, booleans, and sets. The proper data type and syntax for each are:

• Strings: Use type String.
• Numbers: Use type num (int or double).
• Dates: Express the value in milliseconds since epoch.
  Note: Milliseconds since epoch is expressed in UTC. If your date or date-time combination is in a different timezone, first convert it to UTC, then transform it to milliseconds since epoch.
• Booleans: Use type bool.
• Sets: Use type List or Set.

final attributes = {
  // date attributes are handled as `millis since epoch`
  'registered_date': DateTime.now().millisecondsSinceEpoch,
  // this string will be compared against a list called `plan_type` or against another string
  'plan_type': 'growth',
  // this number will be compared against a number value called `deal_size`
  'deal_size': 10000,
  // this array will be compared against a set called `permissions`
  'permissions': ['read', 'write']
};

final String treatment =
    await _client.getTreatment('FEATURE_FLAG_NAME', attributes);

if (treatment == 'on') {
  // insert on code here
} else if (treatment == 'off') {
  // insert off code here
} else {
  // insert control code here
}

Binding attributes to the client

Attributes can optionally be bound to the client at any time during the SDK lifecycle. These attributes are stored in memory and used in every evaluation to avoid the need to keep the attribute set accessible through the whole app. When an evaluation is called, the attributes provided (if any) at evaluation time are combined with the ones that are already loaded into the SDK memory, with the ones provided at function execution time taking precedence. This enables those attributes to be overridden or hidden for specific evaluations.

An attribute is considered valid if it follows one of the types listed below:

• String
• Number
• Boolean
• Array

The SDK validates these before storing them and if there are invalid or missing values, possibly indicating an issue, the methods return the boolean false and do not update any value.

To use these methods, refer to the example below:

var attributes = {
  'registered_date': DateTime.now().millisecondsSinceEpoch,
  'plan_type': 'growth',
  'deal_size': 10000,
  'paying_customer': true,
  'permissions': ['read', 'write']
};

// set attributes returns a future which completes with a true unless there is an issue storing it
var result = await client.setAttributes(attributes);

// set one attribute and returns a future which completes with a true value unless there is an issue storing it
var result = await client.setAttribute('paying_customer', false);

// Get an attribute
var planType = await client.getAttribute('plan_type');

// Get all attributes
var storedAttributes = await client.getAttributes();

// Remove an attribute
var result = await client.removeAttribute('permissions');

// Remove all attributes
var result = await client.clearAttributes();

Get treatments with configurations

To leverage dynamic configurations with your treatments, use the getTreatmentWithConfig method.

This method returns an object with the structure below:

class SplitResult {
  final String treatment;
  final String? config;
}

As you can see from the object structure, the config is a stringified version of the configuration JSON defined in the Split user interface. If there is no configuration defined for a treatment, the SDK returns null for the config parameter.

This method takes the exact same set of arguments as the standard getTreatment method. Refer to the examples below for proper usage:

SplitResult result = await client.getTreatmentWithConfig('FEATURE_FLAG_NAME');
var configs = result.config;
var treatment = result.treatment;

if (treatment == 'on') {
  // insert on code here and use configs here as necessary
} else if (treatment == 'off') {
  // insert off code here and use configs here as necessary
} else {
  // insert control code here
}

var result = await client.getTreatmentWithConfig('FEATURE_FLAG_NAME', attributes);
var configs = result.config;
var treatment = result.treatment;

if (treatment == 'on') {
  // insert on code here and use configs here as necessary
} else if (treatment == 'off') {
  // insert off code here and use configs here as necessary
} else {
  // insert control code here
}

If you need to get multiple evaluations at once, you can also use the getTreatmentsWithConfig. The method takes the exact same arguments as the getTreatments method, but just returns a mapping of feature flag names to SplitResult objects instead of strings. Example usage below.

var featureFlagNames = ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2'];

Future<Map<String, SplitResult>> treatmentsWithConfig = client.getTreatmentsWithConfig(featureFlagNames);

// SplitResult have the following form: 
// {
//   FEATURE_FLAG_NAME_1: {treatment: 'on',
//                  config: "{ 'color' : 'red'}}",
//   FEATURE_FLAG_NAME_2: {treatment: 'v2',
//                  config: "{ 'copy' : 'better copy'}}",
// }

Track

Use the track method to record any actions your customers perform. Each action is known as an event and corresponds to an event type. Calling track through one of our SDKs or via the API is the first step to getting experimentation data into Split and allows you to measure the impact of your feature flags on your users' actions and metrics. Learn more about using track events in Split.

In the examples below, you can see that the .track() method can take up to four arguments. The proper data type and syntax for each are:

• EVENT_TYPE: The event type that this event should correspond to. The expected data type is String. Full requirements on this argument are:
  • Contains 63 characters or fewer.
  • Starts with a letter or number.
  • Contains only letters, numbers, hyphen, underscore, or period.
  • This is the regular expression we use to validate the value: [a-zA-Z0-9][-_\.a-zA-Z0-9]{0,62}
• TRAFFIC_TYPE: (Optional) The traffic type of the key in the track call. The expected data type is String. You can only pass values that match the names of traffic types that you have defined in your instance of Split.
• VALUE: (Optional) The value is used to create the metric. The expected data type is double.
• PROPERTIES: (Optional) An object of key value pairs that can be used to filter your metrics. Learn more about event property capture. Split currently supports three types of properties: strings, numbers, and booleans.

The track method returns a boolean value of true or false to indicate whether or not the client was able to successfully queue the event to be sent back to Split's servers on the next event post. The service returns false if the current queue size is equal to the config set by eventsQueueSize or if an incorrect input to the track method is provided.

In the case that a bad input is provided, you can read more about our SDK's expected behavior.

_split.client(onReady: (client) async {
  /// Named parameters are optional
  client.track('EVENT_TYPE',
      trafficType: 'TRAFFIC_TYPE',
      value: 120.25,
      properties: {'package': 'premium', 'admin': true, 'discount': 50});
});

Configuration

The SDK has a number of knobs for configuring performance. Each knob is tuned to a reasonable default. However, you can override values when instantiating the Splitio:

final SplitConfiguration configurationOptions = SplitConfiguration(
  trafficType: 'user',
  logLevel: SplitLogLevel.debug,
  persistentAttributesEnabled: true);

final Splitio _split =
  Splitio('YOUR_SDK_KEY', 'KEY', configuration: configurationOptions);

The parameters available for configuration are shown below.

Manager

Use these methods on Splitio instance to get a list of the feature flags available to the Split client.

/// Retrieves the feature flags that are currently registered with the SDK.
Future<List<SplitView>> splits();

/// Returns the feature flags registered with the SDK of this name.
Future<SplitView?> split(String splitName);

/// Returns the names of feature flags registered with the SDK.
Future<List<String>> splitNames();

The SplitView class referenced above has the following structure:

class SplitView {
  String name;
  String trafficType;
  bool killed = false;
  List<String> treatments = [];
  int changeNumber;
  Map<String, String> configs = {};
}

Listener

Split SDKs send impression data back to Split servers periodically as a result of evaluating feature flags. To additionally send this information to a location of your choice, use the impressionsStream.

This provides a stream that publishes Impression objects every time one is generated.

final Splitio _split = Splitio(_apiKey, _matchingKey,
  configuration: SplitConfiguration(
    trafficType: "user",
  ));

StreamSubscription<Impression> impressionsStream = _split.impressionsStream().listen((impression) {
  /// Fired each time an impression has been generated.
});

The Impression class has the following format.

class Impression {
  final String? key;
  final String? bucketingKey;
  final String? split;
  final String? treatment;
  final num? time;
  final String? appliedRule;
  final num? changeNumber;
  final Map<String, dynamic> attributes;
}

An impression listener is called asynchronously from the corresponding evaluation, but is almost immediate.

Logging

To enable logging, the logLevel setting is available in the configuration class:

final Splitio _split = Splitio(_sdkKey, _matchingKey,
  configuration: SplitConfiguration(
    logLevel: SplitLogLevel.debug,
  ));

final Splitio _split = Splitio('YOUR_SDK_KEY', 'ACCOUNT_ID');

/// Create a client for the default key, in this case, the account id.
final SplitClient _accountClient = _split.client(onReady: (client) async {
  var userPollTreatment = client.getTreatment('USER_POLL');
});

/// To create another client for a user instead, just pass in a
/// User ID to the splitService.initClient() method. (This is only valid after
/// at least one client has been initialized).
final SplitClient _userClient = _split.client(
    matchingKey: 'USER_ID',
    onReady: (client) async {
      var accountPermissioningTreatment =
          client.getTreatment('ACCOUNT_PERMISSIONING');
    });

/// Track events for accounts
_userClient.track('PAGELOAD', value: 7.86);

/// Track events for users
_accountClient.track('ACCOUNT_CREATED');

Subscribe to events and changes

You can subscribe specify up to four different callbacks when creating a client:

• onReady - The SDK is ready to be used and has the most up-to-date snapshot of your feature flags.
• onReadyFromCache - The SDK is ready to evaluate using locally cached data (which might be stale). If conditions are met, this event is emitted almost immediately since access to the cache is very fast. Otherwise it won't fire.
• onUpdate - This event fires whenever a feature flag or segment is changed. Use this if you want to reload your app every time you make a change in the Split user interface.
• onTimeout - This event fires when the time set for timeout in the configuration has elapsed and the SDK has not fully loaded.

final Splitio _split = Splitio('YOUR_SDK_KEY', 'ACCOUNT_ID');

_split.client(onReady: (client) {
  /// Client has fetched the most up-to-date definitions.
}, onReadyFromCache: (client) {
  /// Fired after the SDK could confirm the presence of the Split data.
  /// This event fires really quickly, since there's no actual fetching of information.
  /// Keep in mind that data might be stale, this is NOT a replacement of sdkReady.
}, onUpdated: (client) {
  /// Fired each time the client state changes, for example,
  /// when a feature flag or a segment changes.
}, onTimeout: (client) {
  /// Fired if the client was not able to be ready.
  /// GetTreatment can still be called but the result may be CONTROL.
});

You can also receive Futures (or a Stream, for the Update event) by accessing the following methods in the client.

_client.whenReady().then((client) {
  /// Client has fetched the most up-to-date definitions.
});

_client.whenReadyFromCache((client) {
  /// Fired after the SDK could confirm the presence of the Split data.
  /// This event fires really quickly, since there's no actual fetching of information.
  /// Keep in mind that data might be stale, this is NOT a replacement of sdkReady.
});

StreamSubscription<SplitClient> streamSubscription = _client.whenUpdated().listen((client) {
  /// Fired each time the client state changes, for example,
  /// when a feature flag or a segment changes.
});

_client.whenTimeout().then((client) {
  /// Fired if the client was not able to be ready.
  /// GetTreatment can still be called but the result may be CONTROL.
});

User consent

The plugin allows you to disable the tracking of events and impressions until user consent is explicitly granted or declined.

The userConsent configuration parameter lets you set the initial consent status of the SDK, and the Splitio method setUserConsent(enabled: bool) lets you grant (enable) or decline (disable) the dynamic data tracking.

The following are the three possible initial states:

• UserConsent.granted. The user grants consent for tracking events and impressions. The SDK sends them to the Split cloud. This is the default value if the userConsent param is not defined.
• UserConsent.declined. The user declines consent for tracking events and impressions. The SDK does not send them to the Split cloud.
• UserConsent.unknown. The user neither grants nor declines consent for tracking events and impressions. The SDK tracks them in its internal storage, and eventually either sends them or not if the consent status is updated to 'GRANTED' or 'DECLINED' respectively. The status can be updated at any time with the setUserConsent factory method.

  // Overwrites the initial consent status of the factory instance, which is 'GRANTED' by default.
  // 'UNKNOWN' status represents that the user has neither granted nor declined consent for tracking data, 
  // so the SDK locally tracks data but not send it to Split cloud until consent is changed to 'GRANTED'.

  final Splitio _split = Splitio(_sdkKey, _matchingKey,
    configuration: SplitConfiguration(
      userConsent: UserConsent.unknown,
    ));

  // Changed User Consent status to 'GRANTED'. Data will be sent to Split cloud.
  _split.setUserConsent(true);
  // Changed User Consent status to 'DECLINED'. Data will not be sent to Split cloud.
  _split.setUserConsent(false);

  // The 'getUserConsent' method returns User Consent status.
  // We expose the constants for customer checks and tracking.

  UserConsent userConsent = await _split.getUserConsent();
  if (userConsent == UserConsent.declined) {
    print("USER CONSENT DECLINED");
  }

  if (userConsent == UserConsent.granted) {
    print("USER CONSENT GRANTED");
  }

  if (userConsent == UserConsent.unknown) {
    print("USER CONSENT UNKNOWN");
  }

Link with native factory

A native Split Factory instance can be shared with the plugin to save resources when evaluations need to be performed on native platform logic. To do so, do the following:

Android

1. If not created already, create a subclass of Android's Application, and add its name to the Manifest.

public class CustomApplication extends Application {

}

   <application
        android:label="my_app"
        android:name=".CustomApplication"
        android:icon="@mipmap/ic_launcher">

2. Add the Split Android SDK dependency to your project's build.gradle file.

dependencies {
    implementation 'io.split.client:android-client:split_version'
    ...
}

3. Create a property in your subclass of Application to hold your factory instance.
4. Initialize the factory in the onCreate callback of your Application subclass.

public class CustomApplication extends Application {
    private SplitFactory factory;

    @Override
    public void onCreate() {
        super.onCreate();

        try {
            factory = SplitFactoryBuilder
                .build("YOUR_SDK_KEY",
                    new Key("USER_KEY"),
                    SplitClientConfig.builder()
                        .build(),
                    getApplicationContext());
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }
}

5. Make the Application subclass implement the SplitFactoryProvider interface, and return the previously created factory in the overridden getSplitFactory() method.

public class CustomApplication extends Application implements SplitFactoryProvider {
    private SplitFactory factory;

    @Override
    public void onCreate() {
        ...
    }

    @Override
    public SplitFactory getSplitFactory() {
        return factory;
    }
}

iOS

1. Add the Split iOS SDK dependency to your app's Podfile.

  pod 'Split', '~> 2.15.0'
...

2. Add a property in your AppDelegate class to hold the factory instance. Make sure to import Split.

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {

  private var splitFactory: SplitFactory?

  ...
}

3. Initialize the factory just before the GeneratedPluginRegistrant.register(with: self) line.

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {

  private var splitFactory: SplitFactory?

  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    let config = SplitClientConfig()
    splitFactory = DefaultSplitFactoryBuilder()
            .setConfig(config)
            .setApiKey("YOUR_SDK_KEY")
            .setKey(Key(matchingKey: "USER_KEY"))
            .build()
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }

  ...
}

4. Implement the SplitFactoryProvider protocol in your AppDelegate and return the previously created factory in the overridden getFactory() method.

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate, SplitFactorProvider {

  private var splitFactory: SplitFactory?

  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    ...
  }

  func getFactory() -> SplitFactory? {
    splitFactory
  }
}