Flutter SDK Integration

The ConfigBee Flutter SDK lets you integrate feature flags and remote configuration into your Flutter app. Control your app’s behavior without redeploying — with real-time updates, user targeting, and Flutter-native widgets.

Installation

flutter pub add configbee_flutter

Setup

Wrap your app with ConfigbeeProvider to make the client available throughout the widget tree:

import 'package:configbee_flutter/configbee_flutter.dart';

void main() {
  final cb = ConfigbeeClient.init(
    ConfigbeeClientParams(
      accountId: "YOUR_ACCOUNT_ID",
      projectId: "YOUR_PROJECT_ID",
      environmentId: "YOUR_ENVIRONMENT_ID",
      onReady: () => print("ConfigBee is ready!"),
      onUpdate: () => print("Configuration updated!"),
    ),
  );
  runApp(ConfigbeeProvider(client: cb, child: const MyApp()));
}

Replace "YOUR_ACCOUNT_ID", "YOUR_PROJECT_ID", and "YOUR_ENVIRONMENT_ID" with your actual ConfigBee credentials.

Flutter Widgets

`ConfigbeeFlag` — declarative flag-based widget switching

Renders different widgets based on a boolean feature flag. Rebuilds automatically on config changes.

ConfigbeeFlag(
  flagKey: 'new_checkout_ui',
  onEnabled: const NewCheckoutPage(),
  onDisabled: const OldCheckoutPage(),
  onLoading: const CircularProgressIndicator(),
)

`ConfigbeeBuilder` — reactive access to all config values

Rebuilds automatically when any config value changes:

ConfigbeeBuilder(
  builder: (context, status, client) {
    if (status != CbStatus.active) return const CircularProgressIndicator();
    return Text(client.getText('welcome_message') ?? 'Welcome!');
  },
)

Both widgets also accept an optional client parameter if you want to use them without a ConfigbeeProvider ancestor.

Reading Config Values

Access the client anywhere in the widget tree:

final cb = ConfigbeeProvider.of(context);

// Get individual values
bool? isEnabled = cb.getFlag('new_feature');
num? maxRetries = cb.getNumber('max_retries');
String? apiEndpoint = cb.getText('api_endpoint');
Map<String, dynamic>? theme = cb.getJson('theme_config');

// Get all values of a type
Map<String, bool?>? allFlags = cb.getAllFlags();
Map<String, num?>? allNumbers = cb.getAllNumbers();
Map<String, String?>? allTexts = cb.getAllTexts();
Map<String, Map<String, dynamic>?>? allJsons = cb.getAllJsons();

Targeting

Set target properties to personalize configurations per user — for example, after login or logout:

final cb = ConfigbeeProvider.of(context);

// On login
cb.setTargetProperties({
  'user_id': '12345',
  'plan': 'premium',
});

// On logout
cb.unsetTargetProperties();

Wait for targeted config to load:

await cb.waitToLoadTargeting(timeout: const Duration(seconds: 10));

You can also pass target properties at initialization:

final cb = ConfigbeeClient.init(
  ConfigbeeClientParams(
    accountId: "YOUR_ACCOUNT_ID",
    projectId: "YOUR_PROJECT_ID",
    environmentId: "YOUR_ENVIRONMENT_ID",
    targetProperties: {
      'user_id': '12345',
      'plan': 'premium',
    },
  ),
);

App Lifecycle Awareness

Use ConfigbeeLifecycleObserver to hook into app foreground/background transitions:

class _MyWidgetState extends State<MyWidget>
    with WidgetsBindingObserver, ConfigbeeLifecycleObserver {
  @override
  ConfigbeeClient get configbeeClient => ConfigbeeProvider.of(context);

  @override
  void onConfigbeeAppResumed() {
    // Called when app returns to foreground — e.g. force a refresh
  }

  @override
  void onConfigbeeAppPaused() {
    // Called when app goes to background
  }
}

API Reference

`ConfigbeeClientParams`

Parameter	Type	Description
`accountId`	`String`	Your ConfigBee account ID
`projectId`	`String`	Your project ID
`environmentId`	`String`	Your environment ID
`targetProperties`	`Map<String, String>?`	Initial targeting properties
`onReady`	`Function?`	Called when config is first loaded
`onUpdate`	`Function?`	Called on every subsequent config update

`ConfigbeeClient` — Key Methods

Method	Returns	Description
`getFlag(key)`	`bool?`	Get a feature flag value
`getNumber(key)`	`num?`	Get a number config value
`getText(key)`	`String?`	Get a text config value
`getJson(key)`	`Map<String, dynamic>?`	Get a JSON config value
`getAllFlags()`	`Map<String, bool?>?`	Get all feature flags
`getAllNumbers()`	`Map<String, num?>?`	Get all number configs
`getAllTexts()`	`Map<String, String?>?`	Get all text configs
`getAllJsons()`	`Map<String, Map<String, dynamic>?>?`	Get all JSON configs
`setTargetProperties(props)`	`void`	Set targeting properties
`unsetTargetProperties()`	`void`	Clear targeting properties
`waitToLoad({timeout})`	`Future<CbStatus>`	Wait for SDK to become active (default timeout: 60s)
`waitToLoadTargeting({timeout})`	`Future<CbStatus>`	Wait for targeting data (default timeout: 60s)
`status`	`CbStatus`	Current SDK status
`targetingStatus`	`CbStatus`	Current targeting/session status
`dispose()`	`void`	Clean up resources

`ConfigbeeProvider`

InheritedWidget that injects a ConfigbeeClient into the widget tree.

Member	Description
`ConfigbeeProvider.of(context)`	Get the client; throws if not found
`ConfigbeeProvider.maybeOf(context)`	Get the client or `null`

`ConfigbeeBuilder`

Parameter	Type	Description
`builder`	`Widget Function(context, CbStatus, ConfigbeeClient)`	Builder callback
`client`	`ConfigbeeClient?`	Optional explicit client (falls back to `ConfigbeeProvider`)

`ConfigbeeFlag`

Parameter	Type	Description
`flagKey`	`String`	The feature flag key
`onEnabled`	`Widget`	Shown when flag is `true`
`onDisabled`	`Widget`	Shown when flag is `false` or `null`
`onLoading`	`Widget?`	Shown while initializing (default: empty box)
`client`	`ConfigbeeClient?`	Optional explicit client (falls back to `ConfigbeeProvider`)

`CbStatus`

Value	Description
`CbStatus.initializing`	SDK is starting up
`CbStatus.active`	Config data loaded and ready
`CbStatus.deactive`	No active session
`CbStatus.error`	Failed to load

Platform Support

Platform	Supported
Android	✅
iOS	✅
Web	✅
macOS	✅
Windows	✅
Linux	✅

Troubleshooting

Config not loading

Verify your accountId, projectId, and environmentId are correct
Check network connectivity
Ensure the environment is active in the ConfigBee dashboard

Targeted config not reflecting

Confirm setTargetProperties was called with the correct properties
Use await cb.waitToLoadTargeting() to ensure targeting is active before reading values
Check cb.targetingStatus == CbStatus.active