Flutter SDK 2.x to 3.0 migration guide

Read time: 5 minutes

Last edited: Aug 05, 2024

Overview

This topic explains the changes in the Flutter SDK 3.0 release and how to migrate to that version.

Version 3.0 includes breaking changes. It removes the deprecated LDUser. To learn more, read Understanding what was removed.

Version 3 also introduces the ability to have LaunchDarkly automatically provide data about the mobile environment where the application is running. This data makes it simpler to target your mobile customers based on application name or version, or on device characteristics including manufacturer, model, operating system, and so on.

When you configure the SDK, starting in version 3.0 you must indicate whether LaunchDarkly should or should not include this data.

This data is provided in two new context kinds. The data is added automatically to each evaluation context you provide.

Customers who are billed by primary context kind may be charged based on the ld_device context kind if it becomes the context kind with the highest volume of monthly activity in their account. This feature does not affect customers on other billing models. To learn more, read Account usage metrics.

Before you migrate to version 3.0, we recommend updating to the latest 2.x version. If you update to the latest 2.x version, deprecation warnings appear in areas of your code that need to be changed for 3.0, for example, any use of LDUser. You can update these areas at your own pace while still using 2.x, rather than migrating everything simultaneously. To learn more about updating to the latest 2.x version, visit the SDK's GitHub repository.

Understanding changes to configuration options

Version 3.0 introduces a new, required configuration parameter. Use this to indicate whether LaunchDarkly should automatically provide data about the mobile environment where the application is running as part of each evaluation context. You must include this parameter when building your LDConfig.

Here's how:

final LDConfig ldConfig = LDConfigBuilder('mobile-key-123abc', AutoEnvAttributes.Enabled)
    .build();

To disable this option, pass in AutoEnvAttributes.Disabled instead.

Understanding the automatically added environment attributes

If you use AutoEnvAttributes.Enabled in the SDK client configuration, the SDK automatically adds two additional contexts to each context that you evaluate. You can use attributes from these contexts in your targeting rules.

Working with multi-contexts

Because the SDK automatically adds contexts, every evaluation context is now a set of multiple contexts, which is called a multi-context. This means to you can create targeting rules in your feature flags based on data from multiple contexts at once. To learn more, read Multi-contexts.

These automatically added contexts include the following attributes:

Context kind	Context attribute	Description	Example
ld_application	key	Unique for this context kind. Automatically generated by the SDK.	randomly generated
	id	Unique identifier of the application.	com.launchdarkly.example
	locale	Locale of the device, in IETF BCP 47 Language Tag format.	en-US
	name	Human-friendly name of the application.	Example Mobile App
	version	Version of the application used for update comparison.	5
	versionName	Human-friendly name of the version. May or may not be a semantic version.	5
	envAttributesVersion	Version of the environment attributes schema being used. This may change in later versions of the SDK.	1.0
ld_device	key	Unique for this context kind. Automatically generated by the SDK.	randomly generated
	manufacturer	Manufacturer of the device.	Google
	model	Model of the device.	Pixel 6 Pro
	os	Operating system of the device. Includes properties for family, name, and version.	family: Android version: 13 name: Android33
	envAttributesVersion	Version of the environment attributes schema being used. This may change in later versions of the SDK.	1.0

If the SDK cannot determine the information for a particular attribute, it will not include that attribute. For example, if the SDK cannot determine the device's model, it will not include the model attribute.

Automatic environment attributes and application metadata configuration

If you are already setting application metadata as part of your SDK configuration, you can still use this new environment attributes feature. Any application metadata that you set will override the automatically collected environment attributes.

Specifically, ld_application context attributes are set based on the following priority order:

If you set values for application id, name, version, or version name using application metadata configuration in the SDK, then the ld_application context will reflect those values.
Otherwise, if you have set values for the application id, name, version, or version name within your mobile app, the ld_application context will reflect those values.
Otherwise, the ld_application context will use the LaunchDarkly SDK name and version.

Understanding changes to application information

In previous versions, you could use the LDConfigBuilder's .applicationInfo method to set the application id and application version. Starting with version 3, you can also set the application name and version name.

Here's how:

final LDConfig ldConfig = LDConfigBuilder("mobile-key-123abc", AutoEnvAttributes.Enabled)
  .applicationId("authentication-service")
  .applicationName("Authentication-Service")
  .applicationVersion("1.0.0")
  .applicationVersionName("v1")
  .build();

Understanding what was removed

Version 3.0 removes the deprecated LDUser. Version 2 of the Flutter SDK replaced users with contexts. Starting in version 3, the deprecated LDUser is removed.

LDUser user = new LDUser('user-key-123abc');

To learn more about replacing users with contexts, read the Flutter SDK 1.x to 2.0 migration guide and Best practices for upgrading users to contexts.

As part of this change, the identifyWithContext method available in version 2 has been renamed to identify in version 3. To learn more, read Identifying and changing contexts. Additionally, the startWithContext method available in version 2 has been renamed to start in version 3. To learn more, read Flutter SDK reference.