ansight_flutter 1.0.2-preview.8

Cross-platform observability, inspection, and remote tooling for Flutter applications.

Ansight for Flutter

ansight_flutter adds Ansight observability and remote inspection to Flutter applications. It combines the native Android and iOS runtimes with Flutter-aware lifecycle, navigation, error, frame-timing, and widget-tree instrumentation.

The package supports Flutter 3.0 or newer, Android API 24 or newer, and iOS 15 or newer.

Install

Add the package to pubspec.yaml:

dependencies:
  ansight_flutter: ^1.0.2-preview.8

Then fetch dependencies:

flutter pub get

Initialize

Initialize the native runtime before starting the app, then install the Flutter instrumentation:

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

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

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

  runApp(const MyApp());
}

install() is idempotent. By default it captures Flutter errors, frame timings, app lifecycle changes, and exposes Flutter widget inspection tools. Its options can disable any of those integrations.

Add the navigator observer to record route changes and screen views:

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

For production-specific configuration, construct AnsightOptions directly. AnsightOptions.developer() enables the complete developer-oriented defaults; keep the tool guard at the least-permissive level appropriate for the build.

Telemetry

await Ansight.instance.registerMetricChannel(
  const AnsightChannel(id: 7, name: 'Queue depth'),
);
await Ansight.instance.metric(42, channel: 7);

await Ansight.instance.event(
  'Checkout completed',
  type: AnsightEventType.info,
  details: 'cart=primary',
);

await Ansight.instance.screenViewed(
  'Order details',
  details: <String, String>{'orderId': '123'},
);

The runtime also exposes built-in telemetry sampling, FPS control, screen-frame capture, touch capture, session properties, custom properties, runtime snapshots, recorded metrics/events, and log and connection-status streams.

Pairing and sessions

Pairing payloads may be JSON strings or decoded JSON-compatible objects:

final result = await Ansight.instance.openSession(
  pairingPayload,
  clientName: 'My Flutter App',
  expectedAppId: 'com.example.my_app',
);

final status = await Ansight.instance.hostConnectionStatus();
await Ansight.instance.completeSession();
await Ansight.instance.disconnect();

Saved pairing, automatic host probing, bundled development configuration, and host-address overrides are available through AnsightOptions and the connection APIs.

Cellular host connections are disabled by default for bundled configs, QR scans, remembered/saved profiles, and manual connections. Enable them only for a trusted development host or personal hotspot:

final options =
    createOptionsBuilder().withCellularHostConnections().build();

This opt-in can consume mobile data and allows connection attempts over a broader or carrier-managed network. Signed pairing-config validation still applies.

Custom tools

Flutter code can publish typed, security-described tools to a connected Ansight host:

final registration = await Ansight.instance.registerTool(
  const AnsightToolDefinition(
    id: 'app.current_user',
    name: 'Current user',
    description: 'Returns the non-sensitive current user summary.',
    category: 'app',
    scope: AnsightToolScope.read,
    security: AnsightToolSecurity(
      level: AnsightToolSecurityLevel.low,
    ),
  ),
  (arguments, context) async => const AnsightToolResult.success(
    result: <String, Object?>{'signedIn': true},
  ),
);

// Later:
await registration.unregister();

AnsightArtifactProvider supports discoverable text or binary artifacts. queueBinaryTransfer() is available for chunked native transfer of larger payloads.

Platform configuration

Android requires minSdkVersion 24 or newer and an app using Flutter's Android embedding v2. The plugin compiles against Android API 34.

iOS requires a deployment target of 15.0 or newer. Add a local-network usage description because development pairing connects to the Ansight host:

<key>NSLocalNetworkUsageDescription</key>
<string>Connect to the Ansight developer host on the local network.</string>

Harness and validation

The package includes a feature-complete app in example/. It exercises runtime state, all telemetry types, pairing and sessions, screenshots, touch capture, widget tools, navigation, errors, custom tools, artifacts, binary transfer, properties, options, capabilities, and logs.

Run the package and harness checks with:

flutter test
flutter test example/test
flutter test example/integration_test -d <device-id>
flutter build apk --debug --target example/lib/main.dart
flutter build ios --simulator --no-codesign --target example/lib/main.dart

tool/flutter_corpus.dart integrates and validates the SDK against the repository's 25-app open-source Flutter corpus. Its generated JSON, Markdown, and command logs provide reproducible build evidence.

Regenerate the Pigeon transports with dart run tool/generate_pigeon.dart. That wrapper reapplies the small compatibility transforms required by Flutter 3.0 after Pigeon emits its current Flutter, Kotlin, and Swift sources.

License

This SDK is source-available software, not open-source software. See LICENSE for the permitted uses and restrictions.