Get started with Flutter SDK 4
このページはまだあなたの言語に翻訳されていません。 現在取り組んでいますので、後でもう一度確認してください。
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.
flutter pub add amplitude_flutter
To add the dependency by hand, add it to pubspec.yaml and run flutter pub get:
dependencies:
amplitude_flutter: ^4.8.2
Set the minimum platform in ios/Podfile, then install pods:
platform :ios, '13.0'
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
| Symptom | Cause | Fix |
|---|---|---|
MissingPluginException(No implementation found for method init on channel amplitude_flutter) | You hot reloaded or hot restarted the app after you added the package, so the native plugin isn't registered. | Stop the app and run it again with flutter run. |
pod install fails with Specs satisfying the amplitude_flutter ... dependency were found, but they required a higher minimum deployment target. | The Podfile's platform is lower than iOS 13.0 or macOS 10.15. | Raise platform in the Podfile, then run pod install again. |
[Amplitude] Error: could not load SDK in the browser console | The Browser SDK file didn't load. An ad blocker, a Content Security Policy, or a changed URL with a stale integrity hash blocks it. | Allow https://cdn.amplitude.com in script-src, test without extensions, and keep the URL and integrity hash in sync. |
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.
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:
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
| Symptom | Cause | Fix |
|---|---|---|
isBuilt resolves to false, and the console prints Error initializing Amplitude: PlatformException(amplitude_init_failed, ...) | The platform SDK failed to start. The message after amplitude_init_failed names the reason. | Read the full message. On web, go to the next row. |
Error initializing Amplitude: PlatformException(amplitude_init_failed, Timed out after 10s waiting for the Amplitude Browser SDK to initialize. ...) | On web, the Browser SDK snippet is missing from web/index.html, or the browser blocked it. | Add the snippet from Install the SDK and check the browser console for a blocked script. |
Amplitude instance <name> not found (Android) or instance not found: <name> (web) | A method ran on an instance whose init never reached the platform, for example in a test with a fake channel or after the engine restarted. | Create the Amplitude instance before you call its methods, in the same Flutter engine. |
| Events go to the wrong region, or uploads fail with an invalid API key error | serverZone doesn't match the project's data center. | Set serverZone: ServerZone.eu for EU projects. Omit it for US projects. |
Send a first event
Track one custom event, then ask the SDK to upload it now instead of waiting for the next scheduled upload.
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.
| Symptom | Cause | Fix |
|---|---|---|
Skip event for opt out config. (Android) or Skip event based on opt out configuration (iOS, macOS) | Opt-out is on for this instance, from optOut: true or an earlier setOptOut(true). | Call amplitude.setOptOut(false). |
Event is invalid for missing information like userId and deviceId | The event has neither a user ID nor a device ID, for example after setDeviceId(null). | Don't clear the device ID. Call reset() to get a new one. |
Handle response, status: BAD_REQUEST, error: ... (Android) or Response failed with code400: ... (iOS, macOS) | Amplitude rejected the batch. The text after error: or the code names the reason, such as an invalid API key or an ID shorter than minIdLength. | Copy the API key again, check serverZone, and make user and device IDs at least five characters long. |
Request failed with error: ... or Conection failed with error: ..., marking offline (iOS, macOS) | The request didn't reach Amplitude. On macOS, the app is missing the network entitlement. | Add com.apple.security.network.client to both entitlements files. Check the device's network. |
Request failed: java.net.UnknownHostException: ... (Android) | The device has no network, or the app lacks network access. | Check the device's connection. Events stay queued and upload later. |
Event rejected due to exceeded retry count (web) | The browser request never reached Amplitude, often because of an ad blocker or a Content Security Policy. | Add https://*.amplitude.com to connect-src, or send events through a proxy. |
Confirm the event in Amplitude
- In Amplitude, open User Lookup and search for
user-12345, or for the device ID fromawait amplitude.getDeviceId(). - Open the Activity tab and turn on Live event updates.
- Confirm that
Sign Up Clickedappears with theplanproperty.
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 callreset()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.
これは役に立ちましたか?
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.