Verify Flutter SDK 4 events
このページはまだあなたの言語に翻訳されていません。 現在取り組んでいますので、後でもう一度確認してください。
An event moves through four stages between your track() call and Amplitude's servers. Verify each stage in order. The problem is in the first stage where the event looks wrong.
| Stage | Question | Where to look |
|---|---|---|
| Captured | Did the platform SDK accept the call? | Debug logs in Logcat, the Xcode console, or the browser console |
| Transformed | What did the platform SDK add, change, or drop? | The event payload |
| Sent | Did the request leave the device, and with what payload? | A local endpoint or proxy, or the browser Network tab |
| Received | Did Amplitude accept and store the event? | Upload log lines, then User Lookup in Amplitude |
For problems common to every Amplitude SDK, go to SDK troubleshooting and debugging. If behavior changed after an SDK upgrade, check the Flutter SDK 4 release notes.
Turn on debug logging
Set logLevel to LogLevel.debug while you verify. The default, LogLevel.warn, hides the upload messages this page relies on.
import 'package:amplitude_flutter/constants.dart';
final amplitude = Amplitude(Configuration(
apiKey: 'AMPLITUDE_API_KEY',
logLevel: LogLevel.debug,
));
await amplitude.isBuilt;
await amplitude.track(BaseEvent('Debug Check'));
Where the messages appear depends on the platform:
| Platform | Where to read logs |
|---|---|
| Android | Logcat, filtered on the tag Amplitude. |
| iOS, macOS | The Xcode console, or Console.app filtered on the subsystem Amplitude. Messages start with Debug:, Log:, Warn:, or Error:. |
| Web | The browser console. Messages start with Amplitude Logger. |
Return logLevel to LogLevel.warn before you ship. Debug output includes event payloads and identifiers.
Check what the SDK captured
With debug logging on, the Flutter plugin logs each call it passes to the native SDK on Android, iOS, and macOS:
Track track event: {instanceName: $default_instance, event: {event_type: Sign Up Clicked, event_properties: {plan: starter}, ...}}
On Android, the native SDK then logs Logged event with type: Sign Up Clicked.
If neither line appears:
- Check that you call
track()on the instance you created, not a secondAmplitudeobject with a differentinstanceName. - Look for
Skip event for opt out config.(Android) orSkip event based on opt out configuration(iOS, macOS). Opt-out is on. CallsetOptOut(false). - Check that each
Revenuesetsprice.revenue()drops aRevenuewhosepriceisnullwithout a log line. - Check that
groupNameis aStringorList<String>.setGroup()drops any other type without a log line.
Check how plugins transformed the event
Flutter SDK 4 doesn't expose plugins in Dart, so your code can't add, change, or drop events after track(). The platform SDK changes each event in these ways before it uploads:
- Adds device, app, and location fields, unless you turned them off in
trackingOptionsor withenableCoppaControl. - Adds
user_id,device_id, andsession_idfrom the current identity, unless the event sets its own. - Sets
librarytoamplitude-flutter/<version>, so you can tell Flutter events apart from native ones. - Drops the event if it has neither a user ID nor a device ID, and logs
Event is invalid for missing information like userId and deviceId.
To see the final event, inspect the uploaded request as described in Check what the SDK sent.
Check what the SDK sent
The native SDKs don't log the request body. To read it, point serverUrl at an endpoint you control, such as a local proxy that forwards to Amplitude, and inspect the request there. Remove the override when you finish.
final amplitude = Amplitude(Configuration(
apiKey: 'AMPLITUDE_API_KEY',
// Android emulator: 10.0.2.2 reaches the host machine. iOS Simulator: use localhost.
serverUrl: 'http://10.0.2.2:8080/2/httpapi',
));
The native SDKs gzip request bodies when they upload to Amplitude's default URL, and send plain JSON when you set a custom serverUrl. Each request is an HTTP V2 API body: an api_key, an events array of up to flushQueueSize events, and options with min_id_length when you set it.
On Android, debug logs also show upload scheduling. After flushMaxRetries failed attempts, the SDK logs Max retries 5 reached, temporarily stop consuming upload signals. and keeps the events for later.
On web, open the browser Network tab and filter on amplitude. The request goes to api2.amplitude.com or api.eu.amplitude.com, or to your serverUrl.
Check what Amplitude received
Read the upload result
The Flutter SDK doesn't return upload results to Dart. The platform SDK logs the server's response instead. With debug logging on, look for these lines:
| Platform log line | Meaning | Fix |
|---|---|---|
Handle response, status: SUCCESS (Android) or Successfully completed request (iOS, macOS) | Amplitude accepted the batch. | Find the event in Amplitude. |
Handle response, status: BAD_REQUEST, error: ... (Android) or Response failed with code400: ... (iOS, macOS) | Amplitude rejected the batch. The error text names the cause, such as an invalid API key or a short ID. | Check the API key and serverZone. Make IDs at least minIdLength characters long (default 5). |
Handle response, status: PAYLOAD_TOO_LARGE, error: ... (Android) or Response failed with code413: ... (iOS, macOS) | The batch is too large. The SDK splits it and retries. | Lower flushQueueSize, or send fewer properties per event. |
Handle response, status: TOO_MANY_REQUESTS, error: ... (Android) or Response failed with code429: ... (iOS, macOS) | Amplitude throttled this device or user. The SDK keeps the events and retries. | Reduce event volume for that user or device. |
Request failed: ... (Android) or Request failed with error: ... (iOS, macOS) | The request didn't reach Amplitude. | Check the network, the macOS network entitlement, and any serverUrl override. |
Event rejected due to exceeded retry count (web) | The browser request failed every retry. | Check the Network tab for a blocked request. |
Find the event in Amplitude
- In Amplitude, open User Lookup and search for the user ID, or for the device ID from
await amplitude.getDeviceId(). - Open the Activity tab and turn on Live event updates.
- Find the event and check its properties,
library, and timestamp.
If the upload succeeded but the event isn't on that user, check that the user ID and device ID in the request match what you searched for. Events with an ID shorter than minIdLength arrive without that ID.
これは役に立ちましたか?
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.