Skip to main content

Flutter reference

This category contains topics explaining how to configure Bucketeer's Flutter SDK.

Getting started

Before starting, ensure that you follow the Getting started guide.

Implementing dependency

Implement the dependency in your Pubspec file. Please refer to the SDK releases page to find the latest version.

dependencies:  bucketeer_flutter_client_sdk: LATEST_VERSION

Importing client

Import the Bucketeer client into your application code.

import 'package:bucketeer_flutter_client_sdk/bucketeer_flutter_client_sdk.dart';

Configuring client

Configure the SDK config and user configuration.

final config = BKTConfigBuilder()  .apiKey("YOUR_API_KEY")  .apiURL("YOUR_API_URL")  .featureTag("YOUR_FEATURE_TAG")  .build();final user = BKTUserBuilder  .id("USER_ID")  .build();
Custom configuration

Depending on your use, you may want to change the optional configurations available in the BKTConfig.Builder.

  • pollingInterval (Minimum 5 minutes. Default is 10 minutes)
  • backgroundPollingInterval (Minimum 20 minutes. Default is 1 hour)
  • eventsFlushInterval (Default is 30 seconds)
  • eventsMaxQueueSize (Default is 50 events)
note

The Bucketeer SDK doesn't save the user data. The Application must save and set it when initializing the client SDK.

Initializing client

Initialize the client by passing the configurations in the previous step.

final client = await BKTClient.initialize(config, user);
note

The initialize process starts polling the latest variations from Bucketeer in the background using the interval pollingInterval configuration. When your application moves to the background state, it will use the backgroundPollingInterval configuration.

If you want to use the feature flag on Splash or Main views, and the user opens your application for the first time, it may not have enough time to fetch the variations from the Bucketeer server.

For this case, we recommend using the timeout option in the initialize method. It will block until the SDK receives the latest user variations.

// It will unlock without waiting until the fetching variation process finishesint timeout = 1000;final client = await BKTClient.initialize(config, user, timeout);

Supported features

Evaluating user

The variation method determines whether or not a feature flag is enabled for a specific user.
To check which variation a specific user will receive, you can use the client like below.

final showNewFeature = await client.boolVariation("YOUR_FEATURE_FLAG_ID", false);if (showNewFeature) {    // The Application code to show the new feature} else {    // The code to run if the feature is off}
caution

In case of the feature flag is missing in the SDK, it will return the default value.

Variation types

The Bucketeer SDK supports the following variation types.

static Future<bool> boolVariation(String featureId, bool defaultValue);static Future<String> stringVariation(String featureId, String defaultValue);static Future<int> intVariation(String featureId, int defaultValue);static Future<double> doubleVariation(String featureId, double defaultValue);static Future<Map<String, dynamic>> jsonVariation(String featureId, LDValue defaultValue);

Updating user variations

Sometimes depending on your use, you may need to ensure the variations in the SDK are up to date before evaluating a user.

// It will unlock without waiting until the fetching variation process finishesint timeout = 1000;final result = await client.fetchEvaluations(timeout);if (result.isSuccess) {  final showNewFeature = await client.boolVariation("YOUR_FEATURE_FLAG_ID", false);  if (showNewFeature) {      // The Application code to show the new feature  } else {      // The code to run if the feature is off  }} else {   // The code to run if the feature is off}
caution

Depending on the client network, it could take a few seconds until the SDK fetches the data from the server, so use this carefully.

You don't need to call this method manually in regular use because the SDK is polling the latest variations in the background.

Updating user variations in real-time

The Bucketeer SDK supports FCM (Firebase Cloud Messaging). Every time you change some feature flag, Bucketeer will send notifications using the FCM API to notify the client so that you can update the variations in real-time.

Assuming you already have the FCM implementation in your application.

// TODO
note

1- You need to register your FCM API Key on the console UI. See more.

2- This feature may not work if the user has the notification disabled.

Reporting custom events

This method lets you save user actions in your application as events. You can connect these events to metrics in the experiments console UI.

In addition, you can pass a double value to the goal event. These values will sum and show as
Value total on the experiments console UI. This is useful if you have a goal event for tracking how much a user spent on your application buying items, etc.

await client.track("YOUR_GOAL_ID", 10.50);

Flushing events

This method will send all pending analytics events to the Bucketeer server as soon as possible. This process is asynchronous, so it returns before it is complete.

client.flush();
note

In regular use, you don't need to call the flush method because the events are sent every 30 seconds in the background.

User attributes configuration

This feature will give you robust and granular control over what users can see on your application. You can add rules using these attributes on the console UI's feature flag's targeting tab. See more.

final attributes = {  'app_version': '1.0.0',  'os_version': '11.0.0',  'device_model': 'pixel-5'  'language': 'english',  'genre': 'female'};final user = BKTUserBuilder()  .id("USER_ID")  .customAttributes(attributes)  .build();final client = await BKTClient.initialize(config, user);

Updating user attributes

This method will update all the current user attributes. This is useful in case the user attributes update dynamically on the application after initializing the SDK.

final attributes = {  'app_version': '1.0.1',  'os_version': '11.0.0',  'device_model': 'pixel-5'  'language': 'english',  'genre': 'female'  'country': 'japan'};await client.updateUserAttributes(attributes);
caution

This updating method will override the current data.

Getting user information

This method will return the current user configured in the SDK. This is useful when you want to check the current user id and attributes before updating them through updateUserAttributes.

final user = await client.currentUser();

Getting evaluation details

This method will return the evaluation details for a specific feature flag. This is useful if you need to know the variation reason or send this data elsewhere.

final evaluationDetails = await client.evaluationDetails("YOUR_FEATURE_FLAG_ID");
note

This method will return null if the feature flag is missing in the SDK.