Get started with Flutter SDK 4

For Flutter developers10 minBeginner

Install Flutter SDK 4 (amplitude_flutter), initialize it, and send one custom event to Amplitude. Each step ends with a table of the problems that commonly break it, so you can fix a problem where it happens. For the full option list, go to Configuration options. For changes between versions, go to the Flutter SDK 4 release notes.

The Flutter SDK runs the native Amplitude SDK on each platform: the Android-Kotlin SDK on Android, the iOS Swift SDK on iOS and macOS, and Browser SDK 2 on web. Your Dart code is the same on every platform.

Prerequisites

  • An Amplitude project and its API key. Find the key in Settings > Projects > [your project] > General.
  • The data center your organization uses: US (default) or EU.
  • Dart 3.3 or later and Flutter 3.19 or later.
  • For each platform you ship:
    • iOS: iOS 13.0 or later.
    • macOS: macOS 10.15 or later.
    • Android: Android Gradle Plugin 8.6 or later (Gradle 8.7 or later) and Java 17.
    • Web: the Browser SDK 2 snippet in web/index.html. The install step covers it.

Install the SDK

Add the package, then follow the tab for each platform your app targets.

bash
flutter pub add amplitude_flutter

To add the dependency by hand, add it to pubspec.yaml and run flutter pub get:

yaml
dependencies:
  amplitude_flutter: ^4.8.2

Set the minimum platform in ios/Podfile, then install pods:

ruby
platform :ios, '13.0'
bash
cd ios && pod install

Swift Package Manager also works. If your Flutter project uses it, Flutter adds the plugin's package for you and you can skip pod install.

Fix installation problems

Initialize the SDK

Create one Amplitude instance when your app starts, and reuse it everywhere. The SDK accepts calls you make while the platform SDK initializes and runs them in order.

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

final amplitude = Amplitude(Configuration(
  apiKey: 'AMPLITUDE_API_KEY',
));

// Optional: wait until the platform SDK is ready. Resolves to false on failure.
final ready = await amplitude.isBuilt;

If your project uses the EU data center, set serverZone:

dart
import 'package:amplitude_flutter/constants.dart';

final amplitude = Amplitude(Configuration(
  apiKey: 'AMPLITUDE_API_KEY',
  serverZone: ServerZone.eu,
));
await amplitude.isBuilt;

With no autocapture setting, the SDK tracks session start and end events on every platform and marketing attribution on web. To choose other events, go to Autocapture.

Fix initialization problems

Send a first event

Track one custom event, then ask the SDK to upload it now instead of waiting for the next scheduled upload.

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

await amplitude.setUserId('user-12345');
await amplitude.track(BaseEvent(
  'Sign Up Clicked',
  eventProperties: {'plan': 'starter'},
));
await amplitude.flush();

track() and flush() complete when the platform SDK accepts the call, not when Amplitude receives the event. The SDK doesn't return an upload result to Dart, so read the platform log to see what happened. Without flush(), the SDK uploads every 30 seconds or when the queue reaches 30 events, whichever comes first.

Fix upload problems

To view these messages, set logLevel: LogLevel.debug in Configuration. On Android, they appear in Logcat under the Amplitude tag. On iOS and macOS, they appear in the Xcode console. On web, they appear in the browser console.

Confirm the event in Amplitude

  1. In Amplitude, open User Lookup and search for user-12345, or for the device ID from await amplitude.getDeviceId().
  2. Open the Activity tab and turn on Live event updates.
  3. Confirm that Sign Up Clicked appears with the plan property.

If the event doesn't appear within a minute, follow Verify events. It walks through each stage between track() and Amplitude's servers.

Next steps

  • Identify signed-in users with setUserId(), and call reset() when they sign out.
  • Choose which Autocapture events to collect, including screen views.
  • Add the custom events, user properties, and revenue your tracking plan needs. Go to Track events.

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