ansight_flutter 1.3.0-preview.11

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.3.0-preview.11

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.

The native iOS Simulator or Android emulator runtime registers automatically with a running, signed-in Studio. No build-time Studio probe or enrollment payload is required.

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: 42, name: 'Queue depth'),
);
await Ansight.instance.metric(42, channel: 42);

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.

Network capture

Wrap the package:http client explicitly used by the app:

final client = AnsightHttpClient(
  inner: http.Client(),
  sanitizationOptions: AnsightNetworkSanitizationOptions(
    maximumBodyBytes: 64 * 1024,
    additionalSensitiveHeaderNames: <String>['x-tenant-secret'],
    additionalSensitiveQueryParameterNames: <String>['session'],
    requestSanitizer: (request) =>
        request.url.contains('/health') ? null : request,
  ),
);

final response = await client.get(Uri.parse('https://api.example.test/orders'));

Import package:http/http.dart as http in the calling app. The wrapper is an explicit opt-in and short-circuits directly to the inner client while no host is connected. Text request and response bodies are included by default with a 64 KiB per-body limit; use AnsightNetworkSanitizationOptionsBuilder to disable either side independently or configure a larger limit. Binary bodies remain an explicit opt-in. The Dart and native sanitizers redact credentials, cloud signed URLs, and sensitive text-body assignments before transport.

Call Ansight.instance.recordNetworkRequest(...) for another HTTP stack or a manual record. AnsightNetworkRequestSanitizer.sanitize(...) exposes the app-side sanitizer for inspection and tests.

Set the JPEG capture option mode to AnsightSessionJpegCaptureMode.screenshotWithVisualTreeOnTouch to retain periodic screenshots while the native runtime captures visual trees only on touch down and touch up. Move and cancel events do not trigger capture. Rapid boundaries are coalesced and rate-limited to protect screenshot cadence. Native touch capture and visual-tree providers must remain enabled.

Open-file-handle and JNI reference-count diagnostics are disabled by default. Enable them with withOpenFileHandleTracking() and withJniReferenceCountTracking(); matching without... methods disable them again. Open handles are sampled by the native Android/iOS runtime. JNI counts are available on Android only when the host integration can supply them.

Automatic session properties

The Dart bridge adds a flutter property group to every session with the Ansight plugin version, Dart version, platform, build mode, JIT/AOT mode, and development mode. The group identifies Dart as the runtime language. If the app is compiled with a FLUTTER_VERSION Dart define, that value is included as flutterVersion; Flutter does not otherwise expose its framework version or active renderer through a stable runtime API.

It also adds a localization group containing the platform locale, language, optional region, platform-reported time-zone name, and UTC offset in minutes. PlatformDispatcher reports the platform locale, so an app that overrides its locale in MaterialApp should override the corresponding localization properties too.

Caller values win when they use the same group and key. Clearing session properties, or removing one automatic property, restores the current bridge-owned values.

Pairing and sessions

No connection call is needed for a simulator or emulator. On a physical device, scan the QR displayed by Studio once:

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

No pairing file, build variable, or host address is required. The physical device's first scan stores its app-installation registration; later launches reconnect automatically.

For advanced paste, file-import, CI, or custom-UI flows, 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',
);

Saved enrollment, automatic runtime connection, and host-address overrides are available through AnsightOptions and the connection APIs. Bundling an enrollment payload is not part of the normal setup.

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. Use it only with a trusted development host.

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
(cd example && flutter 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 22-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.