> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt # Flutter Canonical URL: https://posthog.com/docs/libraries/flutter > **Cloud region:** This page uses US Cloud hosts. For an EU Cloud project, use `https://eu.posthog.com` instead of `https://us.posthog.com` (app host for links). ## On this page - [Install with the wizard](#install-with-the-wizard) - [Installation](#installation) - [Capturing events](#capturing-events) - [Identifying users](#identifying-users) - [Get the current user's distinct ID](#get-the-current-users-distinct-id) - [Alias](#alias) - [Anonymous vs identified events](#anonymous-vs-identified-events) - [Super properties](#super-properties) - [Group analytics](#group-analytics) - [Feature flags](#feature-flags) - [Experiments (A/B tests)](#experiments-ab-tests) - [Error tracking](#error-tracking) - [Logs](#logs) - [Session replay](#session-replay) - [Surveys](#surveys) - [Push notifications](#push-notifications) - [Flush](#flush) - [Offline behavior](#offline-behavior) - [Opt out of data capture](#opt-out-of-data-capture) - [Amending or dropping events](#amending-or-dropping-events) - [Debug mode](#debug-mode) This is an optional library you can install if you're working with Flutter. It uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your mobile app. PostHog supports the iOS, macOS, Android, and Web platforms. ## Install with the wizard Run this command in your project directory to add PostHog to your Flutter project. The wizard detects your framework, installs the SDK, and sets up your first events. `npx @posthog/wizard` Or set it up manually by following the rest of this guide. ## Installation > **CocoaPods is becoming read-only.** [CocoaPods has announced](https://blog.cocoapods.org/CocoaPods-Specs-Repo/) the following schedule for its public specs repository: > > - November 2–6, 2026: A read-only dry run will prevent us from publishing new PostHog iOS SDK versions to CocoaPods. > - December 2, 2026 onward: The repository will be permanently read-only. New PostHog iOS SDK versions will only be available through Swift Package Manager (SPM). > > Existing native SDK versions will remain available through CocoaPods. To keep receiving native SDK updates on iOS and macOS, migrate your Flutter app to SPM. The `posthog_flutter` package supports SPM, and Flutter 3.44 and later enable it by default. On earlier Flutter versions that support SPM, or if you disabled it, run `flutter config --enable-swift-package-manager`, then rebuild your app. Follow [Flutter's SPM migration guide](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers) for project setup and troubleshooting. > > This change does not affect `posthog_flutter` releases on pub.dev, Android, or web. PostHog is available for install via [Pub](https://pub.dev/packages/posthog_flutter). ### Configuration Set your PostHog project token and enable automatic event tracking if you want the library to capture lifecycle events for you. Remember that the application lifecycle events won't have any special context set for you by the time it is initialized. If you are using a self-hosted instance of PostHog you will need to have the public hostname or IP for your instance as well. To start, add `posthog_flutter` to your `pubspec.yaml`: pubspec.yaml ```yaml # rest of your code dependencies: flutter: sdk: flutter posthog_flutter: ^5.26.0 # rest of your code ``` Then complete the setup for each platform: > For Session Replay and Surveys, you must set up the SDK manually by disabling the `com.posthog.posthog.AUTO_INIT` mode. #### Android setup There are 2 ways of initializing the SDK, automatically and manually. Automatically: Add your PostHog configuration to your `AndroidManifest.xml` file located in the `android/app/src/main`: android/app/src/main/AndroidManifest.xml ```xml ``` Or manually (more control and more configurations available): Add your PostHog configuration to your `AndroidManifest.xml` file located in the `android/app/src/main`: android/app/src/main/AndroidManifest.xml ```xml ``` In both cases, you'll also need to update the minimum Android SDK version to `23` in `android/app/build.gradle`: android/app/build.gradle ```kotlin // rest of your config defaultConfig { minSdkVersion 23 // rest of your config } // rest of your config ``` #### iOS setup There are 2 ways of initializing the SDK, automatically and manually. The SDK supports both [CocoaPods](https://guides.cocoapods.org/using/getting-started.html) and [Swift Package Manager (SPM)](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers). Flutter 3.44 and later enable SPM by default. On earlier versions, or if you disabled SPM, enable it with `flutter config --enable-swift-package-manager`. Automatically: Add your PostHog configuration to the `Info.plist` file located in the `ios/Runner` directory: ios/Runner/Info.plist ```xml com.posthog.posthog.PROJECT_TOKEN com.posthog.posthog.POSTHOG_HOST https://us.i.posthog.com com.posthog.posthog.DEBUG ``` Or manually (more control and more configurations available): Add your PostHog configuration to the `Info.plist` file located in the `ios/Runner` directory: ios/Runner/Info.plist ```xml com.posthog.posthog.AUTO_INIT ``` In both cases, you'll need to set the minimum platform version to iOS 13.0. For CocoaPods projects, set it in your `Podfile`: ios/Podfile ```yaml platform :ios, '13.0' # rest of your config ``` For Swift Package Manager projects without a `Podfile`, set the **Minimum Deployments** version to iOS 13.0 for the `Runner` target in Xcode (**Runner > General > Minimum Deployments**). After you change **Minimum Deployments**, regenerate the iOS project's configuration files: ```bash flutter build ios --config-only ``` #### Dart setup (For manual step only) If you followed the automatic SDK setup, then there's no more configuration needed in Dart. If you followed the manual SDK setup: ```dart import 'package:flutter/material.dart'; import 'package:posthog_flutter/posthog_flutter.dart'; Future main() async { // init WidgetsFlutterBinding if not yet WidgetsFlutterBinding.ensureInitialized(); final config = PostHogConfig(''); config.debug = true; // captureApplicationLifecycleEvents is enabled by default since version 5.23.0 config.host = 'https://us.i.posthog.com'; await Posthog().setup(config); runApp(MyApp()); } ``` #### Web setup If your project has a `web/` directory, this step is required. `Posthog().setup()` is a no-op on web, so a web build without the snippet below captures nothing. Add your `Web snippet` (which you can find in [your project settings](https://us.posthog.com/settings/project#snippet)) in the `
` of your `web/index.html` file. Write your project token into the snippet as a literal string. It's public, the same token ships to every visitor, and it needs no build-time or deploy-time injection: web/index.html ```html ``` For more information please check: /docs/libraries/js ### Reproducible Android builds and Shorebird The Flutter SDK uses the native PostHog Android SDK, which depends on the PostHog core library. The Flutter package permits a range of Android SDK versions, so Gradle can select a newer native version even when your `posthog_flutter` version hasn't changed. Your `pubspec.lock` doesn't lock these Gradle dependencies. This matters for [Shorebird](https://docs.shorebird.dev/code-push/troubleshooting/) patches, which can't update native Android code. To keep PostHog's native dependencies consistent between a release and its patches, pin both native libraries before creating the release: 1. Inspect the versions selected for your release build. From your app's `android` directory, run: ```bash ./gradlew :app:dependencyInsight --dependency com.posthog --configuration releaseRuntimeClasspath ``` If you use product flavors, replace `releaseRuntimeClasspath` with your release variant's configuration, such as `productionReleaseRuntimeClasspath`. Record the selected versions of `com.posthog:posthog-android` and `com.posthog:posthog`; their version numbers differ. 2. Add strict constraints to your app's `android/app/build.gradle.kts`. Replace the placeholders with the versions selected together in the previous step: ```kotlin dependencies { constraints { implementation("com.posthog:posthog-android") { version { strictly("") } } implementation("com.posthog:posthog") { version { strictly("") } } } } ``` For a Groovy `build.gradle`, use the same dependency declarations with `version { strictly "" }` inside each constraint. A plain version declaration can still be upgraded during Gradle conflict resolution; [strict constraints](https://docs.gradle.org/current/userguide/dependency_versions.html#sec:rich-version-constraints) enforce the selected versions. 3. Run the dependency report again, build your app, and verify that events arrive in PostHog. Commit the constraints and `pubspec.lock`, and use the same versions for the release and its patches. For an existing Shorebird release, use the native versions recorded for that release, not versions resolved by a fresh build today. Pinning PostHog alone doesn't freeze other plugins or your build tools. For broader dependency control, see [Gradle dependency locking](https://docs.gradle.org/current/userguide/dependency_locking.html). Pins also prevent automatic native bug fixes. When upgrading PostHog, review the pins, select compatible native versions together, and test event capture before shipping a new app-store release. Don't upgrade native dependencies in a Dart-only patch or force an old version below the Flutter package's required minimum. ## Capturing events You can send custom events using `capture`: ```dart await Posthog().capture( eventName: 'user_signed_up', ); ``` > **Tip:** We recommend using a `[object] [verb]` format for your event names, where `[object]` is the entity that the behavior relates to, and `[verb]` is the behavior itself. For example, `project created`, `user signed up`, or `invite sent`. ### Setting event properties Optionally, you can include additional information with the event by including a [properties](https://posthog.com/docs/data/events.md#event-properties) object: ```dart await Posthog().capture( eventName: 'user_signed_up', properties: { 'login_type': 'email', 'is_free_trial': true } ); ``` ### Autocapture PostHog autocapture automatically tracks the following events for you: - **Application Opened** – when the app is opened from a closed state or when the app comes to the foreground (e.g. from the app switcher) - **Application Backgrounded** – when the app is sent to the background by the user - **Application Installed** – when the app is installed. - **Application Updated** – when the app is updated. - **$screen** – when the user navigates, once you add the `PosthogObserver` - **$exception** – when the app throws exceptions. - **$autocapture** – when the user interacts with elements on Flutter Web, captured by posthog-js (see [Interaction autocapture](#interaction-autocapture)) - **$rageclick** – when the user rapidly taps in the same area (iOS/macCatalyst by default, Flutter Web via posthog-js) ### Capturing screen views Screen views aren't captured automatically. Add the `PosthogObserver` to your app yourself. Without it, your app sends no `$screen` events at all. This works with any routing package, not just the plain `Navigator` API. Add the observer wherever your router takes navigator observers, as shown below for `MaterialApp` and `go_router`. > Note: Screen names come from each route's `RouteSettings.name`. Most routing packages set this for you. If yours doesn't, name your routes so `$screen` events are readable. #### Using `navigatorObservers` Add the `PosthogObserver` to record screen views automatically: ```dart import 'package:flutter/material.dart'; import 'package:posthog_flutter/posthog_flutter.dart'; void main() => runApp(MyApp()); class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { // If you're using session replay, `PostHogWidget` has to be the root, and `MaterialApp` must be the child. return MaterialApp( navigatorObservers: [ // The PosthogObserver records screen views automatically PosthogObserver(), ], ... ); } } ``` Name your routes: ```dart ... MaterialPageRoute(builder: (context) => const HomeScreenRoute(), settings: const RouteSettings(name: 'Home Screen'), ), ... ``` #### Using `go_router` Add the `PosthogObserver` to record screen views automatically: ```dart import 'package:flutter/material.dart'; import 'package:posthog_flutter/posthog_flutter.dart'; import 'package:go_router/go_router.dart'; // GoRouter configuration final _router = GoRouter( routes: [ ... ], // The PosthogObserver records screen views automatically observers: [PosthogObserver()], ); class MyApp extends StatelessWidget { @override Widget build(BuildContext context) { // If you're using session replay, `PostHogWidget` has to be the root, and `MaterialApp` must be the child. return MaterialApp.router( routerConfig: _router, ); } } ``` Name your routes: ```dart ... GoRoute( name: 'Home Screen', ... ), ... ``` ### Interaction autocapture The Flutter SDK doesn't autocapture taps or other widget interactions on iOS or Android. On Flutter Web, interaction autocapture and rage clicks come from [posthog-js](https://posthog.com/docs/libraries/js.md), which you configure in the `posthog.init` call in your `web/index.html`. The Flutter SDK doesn't call `posthog.init` itself, so these options don't go in `PostHogConfig`. ### Rage click autocapture > **Note:** On iOS and macCatalyst, the native SDK captures `$rageclick` by default through `PostHogConfig.rageClickConfig`. These events don't name the widget. Android doesn't support rage clicks. See the [iOS rage click configuration](https://posthog.com/docs/libraries/ios/configuration.md#autocapture-configuration) for the thresholds. On Flutter Web, a `$rageclick` event names the widget a user tapped, but only after you enable autocapture in posthog-js and semantics in Flutter. Without both, you either get no rage clicks or rage clicks that only report `flutter-view`. 1. **Enable autocapture and rage clicks in `web/index.html`.** posthog-js detects rage clicks inside its autocapture click handler, so `$rageclick` doesn't fire while `autocapture` is off. ```javascript posthog.init('', { api_host: 'https://us.i.posthog.com', autocapture: true, rageclick: true, }) ``` If you want to limit autocapture to tappable widgets, use `css_selector_allowlist: ['[role="button"]']`. Don't use `element_allowlist: ['button']` – Flutter's semantics nodes are `flt-semantics` elements, not `