Flutter Setup

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

1. Add the package

dependencies:
  ansight_flutter: ^1.3.0-preview.10
flutter pub get

The plugin links the native Ansight runtime through the normal Flutter Android and iOS 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(const MyApp());
}

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

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:

flutter run

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

ansight session list --connected --json
ansight app tools <session-id> --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.
<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

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 hot restart leaves stale state: stop the app completely, relaunch it, and repeat the connection check.