Flutter SDK reference

Overview

This topic documents how to get started with the Flutter SDK, and links to reference information on all of the supported features.

Get started

After you complete the Get started process, follow these instructions to start using the LaunchDarkly SDK in your Flutter application.

Install the SDK

First, declare a dependency on the LaunchDarkly Flutter SDK:

launchdarkly_flutter_client_sdk: ^4.0.0
COPY

Then, import the package in your application code:

import 'package:launchdarkly_flutter_client_sdk/launchdarkly_flutter_client_sdk.dart';
COPY

The Flutter SDK version 4 uses either a mobile key or a client-side ID, depending on the platform that you build for. If you are building for Windows, Mac, Linux, Android, or iOS, you must use a mobile key. If you are building for a web browser, you must use a client-side ID.

You can set these credentials in the LAUNCHDARKLY_MOBILE_KEY and LAUNCHDARKLY_CLIENT_SIDE_ID environment variables, and then use the CredentialSource helper to select your credential and provide it to your configuration. CredentialSource expects one of the two environment variables to be set, but not both. You can set them in your IDE, like this:

Then, you can use the CredentialSource helper when creating your configuration object:

final config = LDConfig(CredentialSource.fromEnvironment, AutoEnvAttributes.enabled)
COPY

Alternatively, you can provide the correct credential on the command line when you build or run your application.

Here's how:

flutter run --dart-define LAUNCHDARKLY_CLIENT_SIDE_ID=YourClientSideId -d Chrome
COPY

Initialize the client

After you install the SDK, create a client instance. You need your environment's credential, either a mobile key or client-side ID. This authorizes your application to connect to a particular environment within LaunchDarkly.

The following example shows the simplest way to create a client:

final config = LDConfig(
  CredentialSource.fromEnvironment,
  AutoEnvAttributes.enabled,
  // all other configuration options are optional
);
final context = LDContextBuilder()
  .kind("user", "user-key-123abc")
  .build();
final client = LDClient(config, context);
await client.start();
COPY

This method of initializing the client lets you use the SDK as soon as it is ready to return evaluated flags.

However, the start function can take an indeterminate amount of time to complete. For example, if the SDK is started while a device is in airplane mode, then start may not complete until the device leaves airplane mode. However, if the SDK has been started before, with the same context, then it may have cached values and start will return once those cached values are loaded. Because of these possibilities, we recommend that you use a timeout when waiting for initialization.

Here's how:

await client.start().timeout(const Duration(seconds: 5));
COPY

Earlier versions of the SDK also supported a startFuture function that blocked until the SDK received the most recent feature flag values.

LDConfig config = LDConfigBuilder('mobile-key-123abc', AutoEnvAttributes.Enabled)
  .build();
LDContextBuilder builder = LDContextBuilder();
builder.kind('user', 'user-key-123abc');
LDContext context = builder.build();
await LDClient.start(config, context);
await LDClient.startFuture(timeLimit: Duration(seconds: 5));
COPY

To learn more about the specific configuration options available in this SDK, read LDConfig.

Evaluate a flag

You can use the client to check which variation a particular context will receive for a feature flag.

Here's how:

bool showFeature = await client.boolVariation(flagKey, false);
if (showFeature) {
    // Application code to show the feature
}
else {
    // The code to run if the feature is off
}
COPY

You can also create multiple clients, each tied to separate credentials and separate environments, if you need to.

Background fetch

If you are using the Flutter SDK version 4 on desktop or on the web, by default your application will continue to get updates. For example, if the end user minimizes your Windows app or moves to a different tab in their web browser, the SDK will continue to fetch flags in the background. You can change this behavior in your client configuration.

If you are using the Flutter SDK version 4 in a power-constrained situation, such as in a mobile application on iOS or Android, the SDK will not receive real-time events when backgrounded.

Shut down the client

Shut down the client when your application terminates. To learn more, read Shutting down.

Data collection

To learn more about data collection within this SDK and implications on submissions to the Apple App Store, read the Apple App Store data collection policy.

Supported features

This SDK supports the following features:

• Anonymous contexts and users
• Automatic environment attributes
• Configuration, including
  • Application metadata configuration
  • Service endpoint configuration
• Context configuration
• Evaluating flags
• Flag evaluation reasons
• Flushing events
• Getting all flags
• Identifying and changing contexts
• Logging configuration
• Monitoring SDK status
• Offline mode
• Private attributes
• Relay Proxy configuration, using proxy mode
• Sending custom events
• Shutting down
• Subscribing to flag changes