AmplitudeNavigatorObserver class

A NavigatorObserver that autocaptures Flutter screen views as [Amplitude] Screen Viewed events.

A Flutter app runs inside a single native surface (one FlutterViewController on iOS, one FlutterActivity on Android), so the native SDKs' screenViews autocapture cannot observe Flutter route navigation. Attach this observer to your app's Navigator.observers to autocapture screen views on every platform, including web.

Capture is gated on the screenViews autocapture option of the Amplitude instance passed in — if screen views are disabled the observer is a no-op. Both attaching the observer AND enabling screenViews are required (Flutter cannot inject a NavigatorObserver automatically).

The observer tracks Flutter route changes on every platform, including web. This matters on web because a Flutter route change does not necessarily change the browser URL, so route-only navigations would be missed by the Browser SDK's URL-based pageViews autocapture.

On web, pageViews and this observer are independent. If you enable both, a navigation that also changes the URL is captured as both [Amplitude] Page Viewed and [Amplitude] Screen Viewed. To record a single navigation event, disable the one you don't want — typically pageViews: PageViewsDisabled() so the observer's route-based [Amplitude] Screen Viewed is authoritative (keep pageUrlEnrichment enabled to retain page-URL properties on the emitted events).

Screen names come from RouteSettings.name by default, so routes must be named — via named routes, RouteSettings(name: ...), or a router such as go_router — to be captured. Routes with no name are skipped (with a debug-mode log). Provide a custom nameExtractor to derive names another way.

final analytics = Amplitude(Configuration(
  apiKey: 'API_KEY',
  autocapture: AutocaptureOptions(screenViews: true),
));

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