Official Amplitude Flutter SDK #

This is the official Amplitude Flutter SDK developed and maintained by Amplitude Inc.

Installation and Quick Start #

• Please visit our 💯Developer Center for instructions on installing and using our the SDK.
• For developing the SDK, please visit our CONTRIBUTING.md to get started.

Autocapture #

Configure autocapture through the autocapture field of Configuration. Use AutocaptureEnabled() to turn on every supported option, AutocaptureDisabled() to turn them all off, or AutocaptureOptions(...) for granular control:

final analytics = Amplitude(Configuration(
  apiKey: 'API_KEY',
  autocapture: AutocaptureOptions(
    sessions: true,
    // Web: all default off; opt in explicitly. The DOM-based options
    // (forms/files/clicks) require Flutter's semantics tree, see "Web setup".
    attribution: AttributionOptions(),
    pageViews: PageViewsOptions(),                // off by default
    formInteractions: true,                       // off by default
    fileDownloads: true,                          // off by default
    elementInteractions: ElementInteractionsOptions(), // clicks; off by default
    pageUrlEnrichment: true,                      // off by default; needs SDK >= 2.29.0
    // Mobile (iOS/Android)
    appLifecycles: true, // installs, upgrades, opens
    deepLinks: true,     // Android
    screenViews: true,   // see "Screen views" below
  ),
));

Each platform ignores the options that don't apply to it.

Web defaults are conservative. Every web autocapture option (pageViews, formInteractions, fileDownloads, elementInteractions, pageUrlEnrichment) is off by default and must be opted into. The DOM-based options (formInteractions, fileDownloads, elementInteractions) also require the accessibility semantics tree to be enabled; see Web setup. Use AutocaptureEnabled() to turn every supported option on at once.

Upgrading: pageViews previously defaulted on; it now defaults off, since Flutter navigation is captured cross-platform by screenViews / AmplitudeNavigatorObserver (see Screen views). Set pageViews: PageViewsOptions() to keep the Browser SDK's URL-based [Amplitude] Page Viewed events.

Web setup #

The web plugin does not inject the Amplitude Browser SDK — your app's page must load it. Add the Amplitude loader snippet to your web/index.html (see example/web/index.html). Autocapture features gate on the Browser SDK version the page loads: elementInteractions needs >= 2.10.0 and pageUrlEnrichment needs >= 2.29.0 (older SDKs silently ignore the option) — the example snippet loads 2.44.4, which covers everything. If you change the snippet's SDK version, update the snippet's integrity (SRI) hash to match that exact file, otherwise the browser will refuse to load it. The SRI hash is the base64 sha384 of the decoded JS (the CDN serves it gzip-encoded): curl -s https://cdn.amplitude.com/libs/analytics-browser-<version>-min.js.gz | gzcat | openssl dgst -sha384 -binary | openssl base64 -A

DOM-based capture on Flutter web

elementInteractions, formInteractions, and fileDownloads are implemented by the Browser SDK, which only sees real DOM elements. With the default CanvasKit renderer the UI is painted to a <canvas>, so the only DOM the SDK can observe is Flutter's accessibility semantics tree. Two things are required for these options to capture anything:

1. Enable the semantics tree globally. It is off until something turns it on (a screen reader, or an explicit SemanticsBinding.instance.ensureSemantics() early in main()). Once enabled, semantic widgets render as <flt-semantics> nodes and text fields become real <input>/<form> elements the SDK can see.

   ⚠️ Enabling semantics app-wide has a runtime/performance cost and some known side effects. It is not recommended unless your app already relies on semantics, so weigh this before enabling DOM-based web capture.

2. Match Flutter's semantic roles. Flutter emits ARIA roles (e.g. role="button", role="link") rather than native <button>/<a> tags, so the Browser SDK's tag-based default cssSelectorAllowlist never matches Flutter UI. ElementInteractionsOptions() defaults its cssSelectorAllowlist to a Flutter-aware set (ElementInteractionsOptions.defaultCssSelectorAllowlist, which adds [role="button"], [role="link"], etc.) so opting in captures Flutter widgets out of the box. Pass your own list to extend or replace it.

Route/screen tracking does not depend on any of this; use the AmplitudeNavigatorObserver below.

Screen views #

A Flutter app runs inside a single native surface (one FlutterViewController on iOS, one FlutterActivity on Android), so the native SDK's screen view autocapture cannot observe Flutter route navigation. Instead, enable screenViews and attach an AmplitudeNavigatorObserver to your app's navigatorObservers:

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

MaterialApp(
  navigatorObservers: [AmplitudeNavigatorObserver(analytics)],
  // ...
);

The observer emits an [Amplitude] Screen Viewed event (with an [Amplitude] Screen Name property from the route name) on each navigation, on every platform including web. Both enabling screenViews and attaching the observer are required.

Screen names come from RouteSettings.name, so give your routes names (named routes, RouteSettings(name: ...), or a router such as go_router) — routes with no name are skipped, and in debug builds a log explains why. Pass a custom nameExtractor to derive names differently.

On web, pageViews and the observer are independent. A Flutter route change does not necessarily change the browser URL, so the observer (route-based) captures navigations the Browser SDK's URL-based pageViews would miss. If you enable both, a URL-changing navigation is recorded as both [Amplitude] Page Viewed and [Amplitude] Screen Viewed; to record a single event, disable the one you don't want. pageViews already defaults off, so screen views are the single navigation event unless you opt back into pageViews. Enable pageUrlEnrichment: true (Browser SDK >= 2.29.0) to attach page-URL properties to your navigation events.

Compatibility #

From Amplitude Flutter v4, we bump up the kotlin version to v1.9.22 to support latest Gradle.

The following matrix lists the minimum support for Amplitude Flutter SDK version.

Learn more about the Android Gradle Plugin compatibility, Gradle compatibility, and Kotlin compatibility.

Need Help? #

If you have any problems or issues over our SDK, feel free to create a github issue or submit a request on Amplitude Help.