Flutter surveys installation

  1. Install the package

    Required

    Add the PostHog Flutter SDK to your pubspec.yaml:

    pubspec.yaml
    posthog_flutter: ^5.0.0

  2. Platform setup

    Required

    Add these values to your AndroidManifest.xml:

    android/app/src/main/AndroidManifest.xml
    <application>
      <activity>
        [...]
      </activity>
      <meta-data android:name="com.posthog.posthog.API_KEY" android:value="<ph_project_token>" />
      <meta-data android:name="com.posthog.posthog.POSTHOG_HOST" android:value="https://us.i.posthog.com" />
      <meta-data android:name="com.posthog.posthog.TRACK_APPLICATION_LIFECYCLE_EVENTS" android:value="true" />
      <meta-data android:name="com.posthog.posthog.DEBUG" android:value="true" />
    </application>

    Update the minimum Android SDK version to 21 in android/app/build.gradle:

    android/app/build.gradle
    defaultConfig {
      minSdkVersion 21
      // rest of your config
    }

  3. Send events

    Recommended

    Once installed, PostHog will automatically start capturing events. You can also manually send events to test your integration:

    Dart
    import 'package:posthog_flutter/posthog_flutter.dart';
    

    await Posthog().capture(
        eventName: 'button_clicked',
        properties: {
          'button_name': 'signup'
        }
    );

  4. Install PosthogObserver

    Required

    For surveys to be shown, you need to add the PosthogObserver to your app. The observer allows PostHog to determine the appropriate context for displaying surveys.

    main.dart
    import 'package:flutter/material.dart';
    

    import 'package:posthog_flutter/posthog_flutter.dart';
    

    class MyApp extends StatefulWidget {
      const MyApp({super.key});
    

      @override
      State<MyApp> createState() => _MyAppState();
    }
    

    class _MyAppState extends State<MyApp> {
      @override
      void initState() {
        super.initState();
      }
    

      @override
      Widget build(BuildContext context) {
        return PostHogWidget(
          child: MaterialApp(
            navigatorObservers: [PosthogObserver()],
            title: 'My App',
            home: const HomeScreen(),
          ),
        );
      }
    }

    If you're using go_router, check this page to learn how to set up the PosthogObserver.

  5. Configuration

    Optional

    Important: For Flutter Web, surveys are powered by the JavaScript Web SDK, so any Flutter-specific survey configuration will be ignored. Please refer to the Web installation guide for proper setup.

    Surveys are enabled by default. If you want to disable surveys, you can do so when setting up your SDK instance:

    main.dart
    final config = PostHogConfig('<ph_project_token>');
    

    config.surveys = false; // Disable surveys

  6. Next steps

    Recommended

    After installing the PostHog SDK, you can create your first survey.

    ResourceDescription
    Creating surveysLearn how to build and customize your surveys
    Targeting surveysShow surveys to specific users based on properties, events, or feature flags
    How to create custom surveysBuild advanced survey experiences with custom code
    Framework guidesSetup guides for React, Next.js, Vue, and other frameworks
    More tutorialsOther real-world examples and use cases

    You should also identify users and capture events with PostHog to control who and when to show surveys to your users.

    Not all survey features are available on every SDK. See the SDK feature support matrix for a full comparison.

Limitations

  • On Android, requires API >= 26.
  • On iOS, minimum deployment target is iOS13.
  • On Web, surveys are powered by the JavaScript Web SDK.
  • Requires PostHog Flutter SDK version >= 5.8.0 (5.14.0+ recommended for latest features)

Troubleshooting

  • Update your SDK and iOS Pods.
  • Make sure to set the minimum platform version to iOS 13.0 in your Podfile.
  • Make sure you have disabled automatic SDK initialization.
  • Run a clean build if you experience issues.
  • If surveys are not being displayed when triggered, make sure you have installed the PosthogObserver.
  • If you are using multiple navigation observers and encounter a log message [PostHog] Cannot show survey: No valid context found..., try placing PosthogObserver first in the list of observers. We've noticed that order sometimes matters due to potential interference.

Community questions

Was this page useful?

Questions about this page? or post a community question.