Flutter SDK 4.0 Migration Guide

Amplitude Flutter SDK 4.0 features default event tracking, simplified interfaces, and wraps the latest Amplitude iOS and Android Kotlin SDKs.

Terminology

• amplitude_flutter:v3: Flutter SDK 3.0
• amplitude_flutter:v4: Flutter SDK 4.0

Dependencies

Open pubspec.yaml and update the dependency:

1dependencies:
2-  amplitude_flutter: ^3
3+  amplitude_flutter: ^4.0.0-beta.1

Run flutter pub get in the terminal to update the dependencies.

Open Podfile and update:

1- platform :ios, '10.0'
2+ platform :ios, '13.0'

Run pod install under the ios directory of your Flutter project to update the CocoaPods dependencies.

Instrumentation

Flutter SDK 4.0 offers an API to instrument events. To migrate to Flutter SDK 4.0, you need to update a few calls. The following sections detail which calls have changed.

Initialization

Like all other calls, instance() is removed. Flutter SDK 4.0 uses the Configuration object to set the configuration. See Configuration for more information.

 -import 'package:amplitude_flutter/amplitude.dart'; //
 -import 'package:amplitude_flutter/identify.dart';
 +import 'package:amplitude_flutter/amplitude.dart'; //
 +import 'package:amplitude_flutter/configuration.dart';
 5 
 6// Create the instance and initialize SDK
 -final Amplitude amplitude = Amplitude.getInstance(instanceName: "project"); //
 -amplitude.setServerUrl("https://your.endpoint.com")
 -amplitude.setServerZone("US")
 -amplitude.trackingSessionEvents(true)
 -amplitude.init(widget.apiKey);
 +final Amplitude amplitude = Amplitude(Configuration( //
 +    apiKey: "YOUR-API-KEY",
 +    serverUrl: "https://your.endpoint.com",
 +    serverZone: ServerZone.eu,
 +    defaultTracking: DefaultTrackingOptions(
 +       sessions: true
 +    )
 +  ));
 +await amplitude.isBuilt;

Configuration

Flutter SDK 4.0 includes the following configuration changes:

• It's more consistent across runtimes.
• It no longer supports certain configurations.
• It uses an instance variable for configuration, versus setters in SDK version 3.0.
• Configuration is immutable after you pass it to Amplitude.

Track events

Flutter SDK 4.0 uses a unified track API to replace the following logEvent API variations:

• withEventProperties
• withApiProperties
• withUserProperties
• withGroup
• withGroupProperties

logEvent()

The logEvent() API maps to track().

-amplitude.logEvent('BUTTON_CLICKED'); //
+amplitude.track(event: BaseEvent(eventType:'BUTTON_CLICKED')); //

logEvent() with event properties

-amplitude.logEvent('BUTTON_CLICKED', {"Hover Time": "100ms"}); //
+amplitude.track(event: BaseEvent(eventType:'BUTTON_CLICKED', eventProperties: {"Hover Time": "100ms"})); //

logEvent() with outOfSession

logEvent() receives an optional boolean argument outOfSession. The new track() API doesn't support it. You can still track an event as out-of-session by setting event.sessionId = -1.

-amplitude.logEvent("BUTTON_CLICKED", outOfSession: true); //
+amplitude.track(event: BaseEvent(eventType:'BUTTON_CLICKED', sessionId: -1)); //

uploadEvents()

The uploadEvents() API maps to flush().

-amplitude.uploadEvents(); //
+amplitude.flush(); //

Set user properties

The APIs for setting user properties are the same, except for the removal of instance(). Here are code snippets to migrate APIs for user properties.

setUserId()

setUserId() remains unchanged but doesn't receive startNewSession.

setDeviceId()

setDeviceId() remains unchanged.

regenerateDeviceId()

regenerateDeviceId() isn't supported in the Flutter SDK 4.0.

clearUserProperties()

The clearUserProperties API has been removed, but you can now use the unified identify API to remove user properties.

-amplitude.clearUserProperties(); //
+final Identify identify = Identify() //
+  ..clearAll();
+amplitude.identify(identify);

setUserProperties()

The setUserProperties API has been removed, but you can now use the unified identify API to add user properties.

-- Map<String, dynamic> userProps = { //
--   'gender': 'female',
--   'age': '20'
-- };
-- amplitude.setUserProperties(userProperties);
++ final Identify identify = Identify() //
++                          ..set('gender','female')
++                          ..set('age',20);
++ amplitude.identify(identify);

identify()

You can now make an identify call on amplitude without calling instance().

1final Identify identify = Identify()
2                          ..set('gender','female')
3                          ..set('age',20);
-Amplitude.getInstance().identify(identify); //
+amplitude.identify(identify); //

Set group properties

setGroup()

You can now make an identify call on amplitude without calling instance().

1// set group with a single group name
-Amplitude.getInstance().setGroup("orgId", "15"); //
+amplitude.setGroup("orgId", "15");//
4// set group with multiple group names
-Amplitude.getInstance().setGroup("sport", ["tennis", "soccer"]); //
+amplitude.setGroup("sport", ["tennis", "soccer"]); //

groupIdentify()

You can now make an identify call on amplitude without calling instance().

1final Identify identify = Identify()
2                          ..set("gender", "female")
3                          ..set("age", 20);
-Amplitude.getInstance().groupIdentify("groupType", "groupValue", identify); //
+amplitude.groupIdentify("groupType", "groupValue", identify); //

Tracking revenue

logRevenue() and logRevenueAmount() are replaced by revenue().

 -String productId = "product001"; //
 -int quantity = 2;
 -double price = 20;
 -double amount = 35;
 -amplitude.logRevenue(productId, quantity, price);
 -amplitude.logRevenueAmount(amount);
 +final Revenue revenue = Revenue() //
 +  ..price = 3.99
 +  ..quantity = 3
 +  ..productId = "com.company.productId";
 +amplitude.revenue(revenue);