Flutter Setup

Add ansight_flutter to a development build, initialize it before runApp, and verify the first connection.

Open your app repository in your coding agent and send:

Copyable prompt:

Use https://www.ansight.ai/skills/flutter/ansight-install-flutter.md to install Ansight in this Flutter app. Keep it in a development build, verify a connected session, and show me the changes.

The Flutter installation skill handles native plugin setup, capture, and verification. The steps below are the manual reference.

1. Add the package

Install the latest release from pub.dev:

flutter pub add ansight_flutter

The plugin links the native Ansight runtime through the normal Flutter Android, iOS, and macOS plugin systems.

2. Initialize the development build

Initialize Ansight after WidgetsFlutterBinding.ensureInitialized() and before runApp(...):

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:ansight_flutter/ansight.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  if (kDebugMode) {
    await Ansight.instance.initializeAndActivate(
      AnsightOptions.developer(
        clientName: 'My Flutter App',
        toolGuard: AnsightToolGuard.readOnly,
      ),
    );
    await AnsightFlutterInstrumentation.instance.install();
  }

  runApp(
    AnsightFlutterCaptureBoundary(
      controller: AnsightFlutterCaptureController(),
      child: const MyApp(),
    ),
  );
}

install() is idempotent. It captures Flutter errors, frame timings, lifecycle changes, widget tools, and the Flutter visual-tree source by default.

AnsightFlutterCaptureBoundary is required on macOS for automatic Flutter-rendered screenshots, correlated visual trees, and pointer evidence. The default boundary follows the session JPEG cadence. Pass automaticCaptureOptions: null only when the app owns manual capture scheduling through its AnsightFlutterCaptureController.

Use an explicit development-flavor flag instead of kDebugMode when that is the approved Ansight variant. Use a separate development target when the native plugin must be absent from distributable builds.

3. Add navigation and stable keys

MaterialApp(
  navigatorObservers: <NavigatorObserver>[AnsightNavigatorObserver()],
  home: const HomePage(),
);

Give important widgets stable string ValueKey values so live and recorded Flutter trees remain easy to query:

ElevatedButton(
  key: const ValueKey<String>('login-button'),
  onPressed: signIn,
  child: const Text('Sign in'),
)

4. Run and verify

Start the host in one terminal:

ansight host run

Launch the app from your IDE or another terminal. For macOS, select the desktop target explicitly:

flutter run
flutter run -d macos

After the app is running, verify it from another terminal:

ansight session list --connected --json
ansight app tools <session-id> --detail summary --include-unavailable --max-results 50 --json

A physical device requires the one-time enrollment flow.

Platform requirements

  • Dart 2.17 or newer and earlier than 4.0.
  • Flutter 3.0 or newer.
  • Android: minSdkVersion 24 or newer and embedding v2.
  • iOS/iPadOS: deployment target 15.0 or newer.
  • iOS/iPadOS: add NSLocalNetworkUsageDescription when a physical device connects to the local Ansight host over the LAN.
  • macOS: deployment target 10.15 or newer. The desktop runtime connects over loopback and does not require QR enrollment.
<key>NSLocalNetworkUsageDescription</key>
<string>Connect to the Ansight developer host on the local network.</string>

Run the relevant target builds after integration:

flutter test
flutter build apk --debug
flutter build ios --simulator --no-codesign
flutter build macos --debug

Troubleshooting

  • No connected session: confirm the host is running and the app was built with kDebugMode or the approved development flavor enabled.
  • The widget tools are missing: confirm AnsightFlutterInstrumentation.instance.install() completed before runApp(...).
  • A macOS session has no screenshots, visual trees, or touches: confirm the visible Flutter content is inside AnsightFlutterCaptureBoundary and its automatic capture options are not null.
  • A hot restart leaves stale state: stop the app completely, relaunch it, and repeat the connection check.