Flutter SDK 4 reference

This reference documents every public export of amplitude_flutter and every Configuration option, verified against version 4.8.2. For the release that added or changed a feature, go to the Flutter SDK 4 release notes.

The package has no single entry file. Import each library you use:

dart
import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
import 'package:amplitude_flutter/constants.dart'; // LogLevel, ServerZone
import 'package:amplitude_flutter/events/base_event.dart';
import 'package:amplitude_flutter/events/event_options.dart';
import 'package:amplitude_flutter/events/identify.dart';
import 'package:amplitude_flutter/events/revenue.dart';
import 'package:amplitude_flutter/autocapture/autocapture.dart';
import 'package:amplitude_flutter/observers/amplitude_navigator_observer.dart';

Each Amplitude object is an instance. Instances with the same instanceName share storage and identity on the native side, so create one per project and reuse it.

Return values

Every method returns a Future. The future completes when the native SDK (or the Browser SDK on web) accepts the call, not when Amplitude receives the event. No method returns an upload result. To check delivery, go to Verify events.

Setup

Amplitude

Creates an instance and starts initializing the platform SDK.

dart
Amplitude(Configuration configuration, [MethodChannel? methodChannel])
dart
final amplitude = Amplitude(Configuration(apiKey: 'AMPLITUDE_API_KEY'));
await amplitude.isBuilt;
await amplitude.track(BaseEvent('Song Played'));

isBuilt

A Future<bool> that completes when the platform SDK finishes initializing.

dart
late Future<bool> isBuilt;

It resolves to true on success and to false when the platform reports an initialization error. On Android it waits for the native SDK's build. On iOS and macOS it waits for the Swift SDK's setup. On web it waits for the Browser SDK's init() and resolves to false after 10 seconds if that never settles, for example when the SDK script is blocked. Calls you make before it completes still go through. Changed in 4.8.0: earlier versions resolved before the platform finished.

flush

Asks the platform SDK to upload queued events now. It returns after starting the upload, not after the upload finishes.

dart
Future<void> flush()
dart
await amplitude.track(BaseEvent('Checkout Started'));
await amplitude.flush();

Tracking

track

Queues an event.

dart
Future<void> track(BaseEvent event, [EventOptions? options])
dart
import 'package:amplitude_flutter/events/event_options.dart';

await amplitude.track(
  BaseEvent('Song Played', eventProperties: {'title': 'Happy Birthday'}),
  EventOptions(userId: 'user-12345'),
);

identify

Sends a $identify event that updates user properties. The changes apply to events you track afterward, not to earlier events.

dart
Future<void> identify(Identify identify, [EventOptions? options])
dart
final identify = Identify()
  ..set('plan', 'pro')
  ..add('logins', 1);
await amplitude.identify(identify);

setGroup

Assigns the current user to one or more groups, and sets the group as a user property.

dart
Future<void> setGroup(String groupType, dynamic groupName, [EventOptions? options])
dart
await amplitude.setGroup('orgId', '15');
await amplitude.setGroup('sport', ['tennis', 'soccer']);

groupIdentify

Sends a $groupidentify event that updates the properties of one group.

dart
Future<void> groupIdentify(String groupType, String groupName, Identify identify, [EventOptions? options])
dart
await amplitude.groupIdentify('plan', 'enterprise', Identify()..set('seats', 50));

revenue

Sends a revenue_amount event built from a Revenue object. If price is null, the SDK drops the call without an error.

dart
Future<void> revenue(Revenue revenue, [EventOptions? options])
dart
final revenue = Revenue()
  ..productId = 'com.example.coins'
  ..price = 3.99
  ..quantity = 3;
await amplitude.revenue(revenue);

Identity

getUserId and setUserId

Read or set the user ID. Pass null to clear it. getUserId() requires 4.1.0 or later.

dart
Future<String?> getUserId()
Future<void> setUserId(String? userId)
dart
await amplitude.setUserId('user-12345');
final userId = await amplitude.getUserId();

getDeviceId and setDeviceId

Read or set the device ID. Use a unique value, such as a UUID. getDeviceId() requires 4.1.0 or later. On Android it waits for the native SDK to finish building before it returns, and returns null if the build fails.

dart
Future<String?> getDeviceId()
Future<void> setDeviceId(String? deviceId)
dart
await amplitude.setDeviceId('8f9a1c52-6d1e-4b8e-9e2a-3c7d5f0b1a24');
final deviceId = await amplitude.getDeviceId();

reset

Sets the user ID to null and generates a new device ID. It doesn't clear user properties that Amplitude already stored.

dart
Future<void> reset()

Sessions

getSessionId

Returns the current session ID, a Unix timestamp in milliseconds. Requires 4.2.0 or later. On Android it waits for the native SDK to restore the stored session first. On a new install, it can return -1 until the first session starts.

dart
Future<int?> getSessionId()
dart
final sessionId = await amplitude.getSessionId();

Privacy

setOptOut

Stops (true) or resumes (false) tracking and uploads for this instance. iOS and Android support requires 4.5.0 or later.

dart
Future<void> setOptOut(bool enabled)
dart
await amplitude.setOptOut(true);
await amplitude.track(BaseEvent('Not Sent'));

BaseEvent

BaseEvent is the event you pass to track(). It extends EventOptions, so it accepts every EventOptions field as a named constructor argument.

dart
BaseEvent(String eventType, {Map<String, dynamic>? eventProperties, Map<String, dynamic>? userProperties, Map<String, dynamic>? groups, Map<String, dynamic>? groupProperties, /* EventOptions fields */})

EventOptions

EventOptions holds the event fields of the HTTP V2 API. Every field is optional. Set a field to override the value the platform SDK fills in.

Identify class

Identify builds user or group property operations for identify() and groupIdentify(). Each method returns the same object, so calls chain with ... The SDK silently ignores an operation in any of these cases: the property name is empty, the value is null, the property already has an operation in this object, or the object already contains clearAll().

The Flutter SDK has no postInsert() method.

Revenue class

Revenue describes one purchase. revenue() sends it as a revenue_amount event with $-prefixed event properties.

AmplitudeNavigatorObserver

A NavigatorObserver that tracks [Amplitude] Screen Viewed with the event property [Amplitude] Screen Name when the navigator pushes, replaces, or pops a route. It does nothing unless the instance's autocapture enables screenViews. Requires 4.7.0 or later.

dart
AmplitudeNavigatorObserver(Amplitude amplitude, {ScreenNameExtractor nameExtractor = defaultScreenNameExtractor, bool Function(Route<dynamic>? route) routeFilter = defaultRouteFilter})

The library also exports screenViewedEventType ('[Amplitude] Screen Viewed'), screenNameProperty ('[Amplitude] Screen Name'), defaultScreenNameExtractor, and defaultRouteFilter. Exceptions thrown by nameExtractor, routeFilter, or track() never reach the navigator. Debug builds print them.

dart
import 'package:flutter/material.dart';
import 'package:amplitude_flutter/observers/amplitude_navigator_observer.dart';

final observer = AmplitudeNavigatorObserver(
  amplitude,
  nameExtractor: (settings) => settings.name?.replaceAll('/', ' ').trim(),
);
final app = MaterialApp(navigatorObservers: [observer]);

Configuration options

This section lists every field of Configuration as of Flutter SDK 4.8.2. Only apiKey is required. Each table names the platforms that read the option. Other platforms ignore it.

dart
Configuration({required String apiKey, /* options below */})

General

Delivery

Identity and privacy

CookieOptions

TrackingOptions

Every field defaults to true. Set a field to false to stop collecting it.

Autocapture options

autocapture takes one of three classes:

AutocaptureOptions

AttributionOptions

PageViewsOptions

PageViewsEnabled() turns on page views with the Browser SDK's defaults.

ElementInteractionsOptions

ElementInteractionsOptions.defaultCssSelectorAllowlist is a, button, input, select, textarea, label, [role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="switch"], [role="tab"], [role="menuitem"], and [role="textbox"]. ElementInteractionsEnabled() uses the same list.

DefaultTrackingOptions

Deprecated since 4.6.0. Use autocapture. When you pass defaultTracking and no autocapture, the SDK converts it to AutocaptureOptions. When you pass both, autocapture wins.

DefaultTrackingOptions.all() turns every field on. DefaultTrackingOptions.none() turns every field off.

Was this helpful?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

On this page