Flutter SDK 4

This is the official documentation for the Amplitude Analytics Flutter SDK. The Flutter SDK lets you send events from your Flutter application to Amplitude.

Compatibility

Amplitude Flutter v4 bumps the Kotlin version to v1.9.22 to support the latest Gradle.

The following matrix lists the minimum support for the Amplitude Flutter SDK version.

Install the SDK

Run the following command to get the latest version of amplitude_flutter, add it to your pubspec.yaml, then retrieve dependencies:

flutter pub add amplitude_flutter

iOS installation

Add platform :ios, '13.0' to your Podfile. Run pod install in the ios directory of your Flutter project to update the CocoaPods dependencies.

macOS installation

Add platform :osx, '10.15' to your Podfile. Run pod install in the macos directory of your Flutter project to update the CocoaPods dependencies. Ensure your app has the com.apple.security.network.client entitlement to be able to send requests. Manually edit the macos/Runner/Release.entitlements and macos/Runner/DebugProfile.entitlements files to include:

	<key>com.apple.security.network.client</key>
	<true/>

Web installation (optional)

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

Initialize the SDK

Before you instrument your application, initialize the SDK with your Amplitude project's API key.

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
import 'package:amplitude_flutter/events/base_event.dart';

class YourClass {
  Future<void> exampleForAmplitude() async {
    // Create and initialize the instance
    final Amplitude amplitude = Amplitude(Configuration(
        apiKey: 'YOUR-API-KEY',
    ));

    // Wait until the SDK is initialized
    await amplitude.isBuilt;

    // Track an event
    amplitude.track(BaseEvent(
        eventType: 'BUTTON_CLICKED',
        eventProperties: {'Hover Time': '100ms'},
    ));

    // Send events to the server
    amplitude.flush()
  }
}

Configure the SDK

Configuration for Android and iOS

Configuration for web and Android

Configuration for Android

Configuration for web

• appVersion
  • Description: String. Sets an app version for events tracked. This can be the version of your application. For example: "1.0.0".
  • Default Value: null
• cookieOptions.domain
  • Description: String. Sets the domain property of cookies created.
  • Default Value: null
• cookieOptions.expiration
  • Description: int. Sets expiration of cookies created in days.
  • Default Value: 365 days
• cookieOptions.sameSite
  • Description: String. Sets SameSite property of cookies created.
  • Default Value: null
• cookieOptions.secure
  • Description: bool. Sets Secure property of cookies created.
  • Default Value: null
• cookieOptions.upgrade
  • Description: bool. Sets upgrading from cookies created by maintenance Browser SDK. If true, new Browser SDK deletes cookies created by maintenance Browser SDK. If false, Browser SDK keeps cookies created by maintenance Browser SDK.
  • Default Value: null
• identityStorage
  • Description: String. Sets storage API for user identity. Options include cookie for document.cookie, localStorage for localStorage, or none to opt-out of persisting user identity.
  • Default Value: cookie
• userId
  • Description: String. Sets an identifier for the tracked user. Must have a minimum length of 5 characters unless overridden with the minIdLength option.
  • Default Value: null
• transport
  • Description: String. Sets request API to use by name. Options include fetch for fetch, xhr for XMLHTTPRequest, or beacon for navigator.sendBeacon.
  • Default Value: fetch
• fetchRemoteConfig
  • Description: bool. Whether the SDK fetches remote configuration. Review Browser SDK 2 for more information. The default depends on the Browser SDK version used. For Browser SDK 2.16.1+, the default is true.
  • Default Value: false (for Browser SDK = 2.16.1)

Configure batching behavior

To support high-performance environments, the SDK sends events in batches. The track method queues every event in memory, and the SDK flushes events in batches in the background. Customize batch behavior with flushQueueSize and flushIntervalMillis. By default, the serverUrl is https://api2.amplitude.com/2/httpapi.

If you need to send large batches of data at once, set useBatch to true. This sets setServerUrl to the batch event upload API https://api2.amplitude.com/batch. Both the regular mode and the batch mode use the same events upload threshold and flush time intervals.

final Amplitude analytics = Amplitude(Configuration(
    apiKey: 'YOUR-API-KEY',
    flushIntervalMillis: 50000,
    flushQueueSize: 20,
));

EU data residency

Configure the server zone when you initialize the client to send data to Amplitude's EU servers. The SDK sends data based on the server zone if you set it.

final Amplitude analytics = Amplitude(Configuration(
    apiKey: 'YOUR-API-KEY',
    serverZone: ServerZone.eu,
));

Track

Events represent how users interact with your application. For example, "Song Played" can be an action you want to track.

amplitude.track(BaseEvent('Song Played'));

You can also optionally include event properties.

amplitude.track(BaseEvent('Song Played', eventProperties: {'title': 'Happy Birthday'}));

Identify

Use Identify to set the user properties of a particular user without sending any event. The SDK supports the set, setOnce, unset, add, append, prepend, preInsert, postInsert, remove, and clearAll operations on individual user properties. Declare the operations with the provided Identify interface. You can chain multiple operations in a single Identify object, then pass the Identify object to the Amplitude client to send to the server.

You can handle a user's identity using the identify methods. Proper use of these methods connects events to the correct user as the user moves across devices, browsers, and other platforms. Send an identify call containing those user property operations to the Amplitude server to tie a user's events to specific user properties.

final Identify identify = Identify()
    ..set('color', 'green')
amplitude.identify(identify)

Clear all user properties

Use clearAll to remove all user properties from a user. Use clearAll with care because the operation is irreversible.

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

Autocapture

The SDK tracks sessions, app lifecycle events, deep links, page views, and marketing attribution automatically without manual instrumentation. Configure this behavior with the autocapture parameter using AutocaptureDisabled(), AutocaptureEnabled(), or AutocaptureOptions().

When you omit both autocapture and defaultTracking, the SDK enables session tracking by default. On Web, it also enables page view and attribution tracking.

The SDK supports the following autocapture options:

Enable autocapture

To enable all autocapture features on every platform, use AutocaptureEnabled():

Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureEnabled(),
  )
);

On iOS and Android, AutocaptureEnabled() enables sessions, app lifecycles, and deep links. On Web, it also enables page views and attribution.

Disable autocapture

To disable all autocapture features, use AutocaptureDisabled():

Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureDisabled(),
  )
);

Configure autocapture

Use AutocaptureOptions for granular control:

Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureOptions(
      sessions: true,
      appLifecycles: true,
      deepLinks: true,
      pageViews: PageViewsOptions(
        trackHistoryChanges: 'pathOnly',
        eventType: '[Amplitude] Page Viewed',
      ),
      attribution: AttributionOptions(
        excludeReferrers: ['example.com'],
        initialEmptyValue: 'NONE',
        resetSessionOnNewCampaign: true,
      ),
    ),
  )
);

Track sessions

When you set sessions to true, Amplitude tracks session start and session end events. When you set sessions to false, Amplitude tracks sessionId only.

Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureOptions(
      sessions: true,
    )
  )
);

Track application lifecycles

When you set appLifecycles to true, Amplitude tracks application lifecycle events on iOS and Android.

Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureOptions(
      appLifecycles: true,
    )
  )
);

After you enable this setting, Amplitude tracks the following events:

• [Amplitude] Application Installed: fires when a user opens the application for the first time right after installation.
• [Amplitude] Application Updated: fires when a user opens the application after updating it.
• [Amplitude] Application Opened: fires when a user launches or foregrounds the application after the first open.
• [Amplitude] Application Backgrounded: fires when a user backgrounds the application.

Tracked event properties include: [Amplitude] Version, [Amplitude] Build, [Amplitude] Previous Version, [Amplitude] Previous Build, [Amplitude] From Background.

Track deep links

When you set deepLinks to true, Amplitude tracks events related to deep links in your Android application.

Amplitude(
  Configuration(
    apiKey: 'YOUR-API-KEY',
    autocapture: AutocaptureOptions(
      deepLinks: true,
    )
  )
);

After you enable this setting, Amplitude tracks the [Amplitude] Deep Link Opened event with the URL and referrer information. Tracked event properties include: [Amplitude] Link URL, [Amplitude] Link Referrer.

Page views

Configure page view tracking on Web with PageViewsOptions:

autocapture: AutocaptureOptions(
  pageViews: PageViewsOptions(
    trackHistoryChanges: 'pathOnly',
    eventType: 'Page View',
  ),
)

To disable page view tracking, use PageViewsDisabled():

autocapture: AutocaptureOptions(
  pageViews: PageViewsDisabled(),
)

Attribution

Configure marketing attribution tracking on Web with AttributionOptions:

autocapture: AutocaptureOptions(
  attribution: AttributionOptions(
    excludeReferrers: ['example.com', 'internal.com'],
    initialEmptyValue: 'NONE',
    resetSessionOnNewCampaign: true,
  ),
)

To disable attribution tracking, use AttributionDisabled():

autocapture: AutocaptureOptions(
  attribution: AttributionDisabled(),
)

User groups

Amplitude supports assigning users to groups and running queries, such as Count by Distinct, on those groups. If at least one member of the group has performed the specific event, the count includes the group.

For example, group your users by the organization they belong to using an 'orgId'. Joe is in 'orgId' '10', and Sue is in 'orgId' '15'. Sue and Joe both perform a certain event. You can query their organizations in the Event Segmentation Chart.

When setting groups, define a groupType and groupName. In the previous example, 'orgId' is the groupType and '10' and '15' are the values for groupName. Another example of a groupType could be 'sport' with groupName values like 'tennis' and 'baseball'.

Setting a group also sets the groupType:groupName as a user property and overwrites any existing groupName value for that user's groupType and the corresponding user property value. groupType is a string, and groupName can be either a string or an array of strings, where the array indicates that a user is in multiple groups.

// set group with a single group name
amplitude.setGroup('orgId', '15');

// set group with multiple group names
amplitude.setGroup('sport', ['tennis', 'soccer']);

You can also set event-level groups by passing an Event Object with groups to track. With event-level groups, the group designation applies only to the specific logged event and doesn't persist on the user unless you set the group explicitly with setGroup.

amplitude.track(BaseEvent('event type',
    eventProperties: {'event property': 'event property value'},
    groups: {'ordId': '15'}));

Group identify

Use the Group Identify API to set or update the properties of particular groups. Keep these considerations in mind:

• Updates affect only future events, and don't update historical events.
• You can track up to 5 unique group types and 10 total groups.

The groupIdentify method accepts a group type string parameter, a group name object parameter, and an Identify object that Amplitude applies to the group.

final groupType = 'plan';
final groupName = 'enterprise';

final identify = Identify().set('key', 'value');
amplitude.groupIdentify(groupType, groupName, identify);

Track revenue

Amplitude can track revenue generated by a user. Amplitude tracks revenue through distinct revenue objects, which have special fields that Amplitude's Event Segmentation and Revenue LTV charts use. Amplitude then displays revenue data in the platform automatically. Revenue objects support the following special properties, and also support user-defined properties through the eventProperties field.

final revenue = Revenue()
  ..productId = 'com.company.productId'
  ..price = 3.99
  ..quantity = 3;
amplitude.revenue(revenue);

Custom user ID

If your app has a login system you want to track users with, call setUserId at any time.

amplitude.setUserId('user@amplitude.com');

Custom device ID

Assign a new device ID using deviceId. When you set a custom device ID, make sure the value is sufficiently unique. Amplitude recommends using a UUID.

amplitude.setDeviceId('your-unique-device-id');

Reset when a user logs out

reset is a shortcut to anonymize users after they log out. It does the following:

• Sets userId to null.
• Sets deviceId to a new value based on the current configuration.

With an empty userId and a new deviceId, the current user appears as a new user in the dashboard.

amplitude.reset();