Flutter SDK 4.0 Migration Guide

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

Terminology

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

Dependencies

Open pubspec.yaml and update the dependency:

diff

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

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

Open Podfile and update:

diff

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

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

For Flutter Web, replace the "Amplitude-JavaScript" snippet located at web/index.html with the following "Browser SDK 2" snippet:

html

<script type="text/javascript">
  !(function () {
    "use strict";
    !(function (e, t) {
      var r = e.amplitude || { _q: [], _iq: {} };
      if (r.invoked)
        e.console &&
          console.error &&
          console.error("Amplitude snippet has been loaded.");
      else {
        var n = function (e, t) {
            e.prototype[t] = function () {
              return (
                this._q.push({
                  name: t,
                  args: Array.prototype.slice.call(arguments, 0),
                }),
                this
              );
            };
          },
          s = function (e, t, r) {
            return function (n) {
              e._q.push({
                name: t,
                args: Array.prototype.slice.call(r, 0),
                resolve: n,
              });
            };
          },
          o = function (e, t, r) {
            e._q.push({ name: t, args: Array.prototype.slice.call(r, 0) });
          },
          i = function (e, t, r) {
            e[t] = function () {
              if (r)
                return {
                  promise: new Promise(
                    s(e, t, Array.prototype.slice.call(arguments)),
                  ),
                };
              o(e, t, Array.prototype.slice.call(arguments));
            };
          },
          a = function (e) {
            for (var t = 0; t < g.length; t++) i(e, g[t], !1);
            for (var r = 0; r < m.length; r++) i(e, m[r], !0);
          };
        r.invoked = !0;
        var c = t.createElement("script");
        ((c.type = "text/javascript"),
          (c.integrity =
            "sha384-R0H1kXlk6r2aEQMtwVcPolpk0NAuIqM/8NlxAv24Gr3/PBJPl+9elu0bc3o/FDjR"),
          (c.crossOrigin = "anonymous"),
          (c.async = !0),
          (c.src =
            "https://cdn.amplitude.com/libs/analytics-browser-2.11.10-min.js.gz"),
          (c.onload = function () {
            e.amplitude.runQueuedFunctions ||
              console.log("[Amplitude] Error: could not load SDK");
          }));
        var l = t.getElementsByTagName("script")[0];
        l.parentNode.insertBefore(c, l);
        for (
          var u = function () {
              return ((this._q = []), this);
            },
            p = [
              "add",
              "append",
              "clearAll",
              "prepend",
              "set",
              "setOnce",
              "unset",
              "preInsert",
              "postInsert",
              "remove",
              "getUserProperties",
            ],
            d = 0;
          d < p.length;
          d++
        )
          n(u, p[d]);
        r.Identify = u;
        for (
          var f = function () {
              return ((this._q = []), this);
            },
            v = [
              "getEventProperties",
              "setProductId",
              "setQuantity",
              "setPrice",
              "setRevenue",
              "setRevenueType",
              "setEventProperties",
            ],
            y = 0;
          y < v.length;
          y++
        )
          n(f, v[y]);
        r.Revenue = f;
        var g = [
            "getDeviceId",
            "setDeviceId",
            "getSessionId",
            "setSessionId",
            "getUserId",
            "setUserId",
            "setOptOut",
            "setTransport",
            "reset",
            "extendSession",
          ],
          m = [
            "init",
            "add",
            "remove",
            "track",
            "logEvent",
            "identify",
            "groupIdentify",
            "setGroup",
            "revenue",
            "flush",
          ];
        (a(r),
          (r.createInstance = function (e) {
            return ((r._iq[e] = { _q: [] }), a(r._iq[e]), r._iq[e]);
          }),
          (e.amplitude = r));
      }
    })(window, document);
  })();
</script>

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

Flutter SDK 4.0 removes instance() along with the other legacy calls. Flutter SDK 4.0 uses the Configuration object to set the configuration. Refer to Configuration for more information.

dart

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/identify.dart';
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';

// 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:

Configuration is more consistent across runtimes.
Flutter SDK 4.0 no longer supports certain configurations.
Flutter SDK 4.0 uses an instance variable for configuration, instead of setters in SDK version 3.0.
Configuration becomes immutable after you pass it to Amplitude.

Flutter SDK 3.0	Flutter SDK 4.0
`enableCoppaControl()` or `disableCoppaControl()`	`config.enableCoppaControl`
`setMinTimeBetweenSessionsMillis()`	`config.minTimeBetweenSessionsMillis`
`setEventUploadThreshol(d)`	`config.flushQueueSize`
`setEventUploadPeriodMillis()`	`config.flushIntervalMillis`
`setServerZone()`	`config.serverZone`
`setServerUrl()`	`config.serverUrl`
`setUseDynamicConfig()`	NOT SUPPORTED
`setOptOut()`	`config.optOut`
`setOffline()`	NOT SUPPORTED
`trackingSessionEvents()`	`config.defaultTracking.sessions`
`useAppSetIdForDeviceId()`	`config.useAppSetIdForDeviceId`

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().

dart

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

logEvent() with event properties

dart

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 outOfSession. To track an event as out-of-session, set event.sessionId = -1.

dart

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

uploadEvents()

The uploadEvents() API maps to flush().

dart

amplitude.uploadEvents();
amplitude.flush();

Set user properties

The APIs for setting user properties are the same, except that Flutter SDK 4.0 removes instance(). The following code snippets show how to migrate user property APIs.

setUserId()

setUserId() no longer receives startNewSession and now has a default minimum length of 5. To override this default, set the minIdLength config option during initialization.

Minimum identifier length

The maintenance SDK uses an old SDK endpoint (api2.amplitude.com) that enforces no length limit for deviceId and userId. The latest SDK uses Amplitude's HTTP V2 API (api2.amplitude.com/2/httpapi) and requires identifiers of at least 5 characters by default. When you migrate to the latest SDK, set config.minIdLength to a smaller value if you allowed identifiers with fewer than 5 characters.

setDeviceId()

setDeviceId() now has a default minimum length of 5. To override this default, set the minIdLength config option during initialization.

Minimum identifier length

regenerateDeviceId()

Flutter SDK 4.0 doesn't support regenerateDeviceId().

clearUserProperties()

Flutter SDK 4.0 removes the clearUserProperties API. To remove user properties, use the unified identify API.

dart

amplitude.clearUserProperties();
final Identify identify = Identify()
  ..clearAll();
amplitude.identify(identify);

setUserProperties()

Flutter SDK 4.0 removes the setUserProperties API. To add user properties, use the unified identify API.

dart

- 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().

dart

final Identify identify = Identify()
                          ..set('gender','female')
                          ..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().

dart

// set group with a single group name
Amplitude.getInstance().setGroup("orgId", "15");
amplitude.setGroup("orgId", "15");
// 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().

dart

final Identify identify = Identify()
                          ..set("gender", "female")
                          ..set("age", 20);
Amplitude.getInstance().groupIdentify("groupType", "groupValue", identify);
amplitude.groupIdentify("groupType", "groupValue", identify);

Tracking revenue

The revenue() API replaces logRevenue() and logRevenueAmount().

dart

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);

Was this helpful?