---
title: Get started with Flutter SDK 4
description: "Install the Amplitude Flutter SDK 4, initialize it on iOS, Android, macOS, or web, send a first event, and fix the platform problems that stop events from arriving."
product: analytics
lang: en
last_updated: 2026-11-17
token_estimate: 3661
---
# Get started with Flutter SDK 4

- **Package:** `amplitude_flutter` ([pubdev](https://pub.dev/packages/amplitude_flutter))
- **Latest version:** 4.8.2

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](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4/reference#configuration-options). For changes between versions, go to the [Flutter SDK 4 release notes](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4-release-notes).

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

The Flutter SDK runs the native Amplitude SDK on each platform: the [Android-Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk) on Android, the [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk) on iOS and macOS, and [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2/get-started) 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
```

#### iOS

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

#### macOS

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

```ruby
platform :osx, '10.15'
```

```bash
cd macos && pod install
```

A sandboxed macOS app can't make network requests by default. Add the outgoing connections entitlement to both `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`:

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

For details, go to Flutter's [macOS entitlements guide](https://docs.flutter.dev/platform-integration/macos/building#setting-up-entitlements).

#### Android

No extra steps. The plugin adds the Android-Kotlin SDK (`com.amplitude:analytics-android`) as a Gradle dependency.

#### Web

On web, the Flutter SDK calls Browser SDK 2 through JavaScript interop, so the Browser SDK must be on the page first. Paste this snippet into the `<head>` of `web/index.html`. Don't add an `amplitude.init()` call: the Flutter SDK initializes the Browser SDK for you.

```html
<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[t] = function () {
              if (r)
                return {
                  promise: new Promise(
                    s(e, t, Array.prototype.slice.call(arguments)),
                  ),
                };
              !(function (e, t, r) {
                e._q.push({ name: t, args: Array.prototype.slice.call(r, 0) });
              })(e, t, Array.prototype.slice.call(arguments));
            };
          },
          i = function (e) {
            for (var t = 0; t < v.length; t++) o(e, v[t], !1);
            for (var r = 0; r < y.length; r++) o(e, y[r], !0);
          };
        r.invoked = !0;
        var c = t.createElement("script");
        ((c.type = "text/javascript"),
          (c.integrity =
            "sha384-lUDMpxCLYsnroVQqNbtcMW8an6gKOeYD+lp8pILILRV5HggRTJEm0A1BokY4ErgJ"),
          (c.crossOrigin = "anonymous"),
          (c.async = !0),
          (c.src =
            "https://cdn.amplitude.com/libs/analytics-browser-2.45.5-min.js.gz"),
          (c.onload = function () {
            e.amplitude.runQueuedFunctions ||
              console.log("[Amplitude] Error: could not load SDK");
          }));
        var a = t.getElementsByTagName("script")[0];
        a.parentNode.insertBefore(c, a);
        for (
          var p = function () {
              return ((this._q = []), this);
            },
            u = [
              "add",
              "append",
              "clearAll",
              "prepend",
              "set",
              "setOnce",
              "unset",
              "preInsert",
              "postInsert",
              "remove",
              "getUserProperties",
            ],
            l = 0;
          l < u.length;
          l++
        )
          n(p, u[l]);
        r.Identify = p;
        for (
          var d = function () {
              return ((this._q = []), this);
            },
            f = [
              "getEventProperties",
              "setProductId",
              "setQuantity",
              "setPrice",
              "setRevenue",
              "setRevenueType",
              "setReceipt",
              "setReceiptSig",
              "setCurrency",
              "setEventProperties",
            ],
            g = 0;
          g < f.length;
          g++
        )
          n(d, f[g]);
        r.Revenue = d;
        var v = [
            "getDeviceId",
            "setDeviceId",
            "getSessionId",
            "setSessionId",
            "getUserId",
            "setUserId",
            "setOptOut",
            "setTransport",
            "reset",
            "extendSession",
          ],
          y = [
            "init",
            "add",
            "remove",
            "track",
            "logEvent",
            "identify",
            "groupIdentify",
            "setGroup",
            "revenue",
            "flush",
          ];
        (i(r),
          (r.createInstance = function (e) {
            return ((r._iq[e] = { _q: [] }), i(r._iq[e]), r._iq[e]);
          }),
          (e.amplitude = r));
      }
    })(window, document);
  })();
</script>
```

The snippet loads Browser SDK 2.45.5, which supports every autocapture option the Flutter SDK exposes. Element interactions need Browser SDK 2.10.0 or later, and page URL enrichment needs 2.29.0 or later. If you change the version in the URL, also change the `integrity` hash to match that file.

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

```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](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4/instrument-and-configure#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](#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.

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

| 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](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4/instrument-and-configure#send-events-through-a-proxy). |

## 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](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4/verify-events). It walks through each stage between `track()` and Amplitude's servers.

## Next steps

- Identify signed-in users with [`setUserId()`](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4/instrument-and-configure#set-the-user-id), and call `reset()` when they sign out.
- Choose which [Autocapture](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4/instrument-and-configure#autocapture) events to collect, including screen views.
- Add the custom events, user properties, and revenue your tracking plan needs. Go to [Track events](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk-4/instrument-and-configure#track-events).

