Configuration

Configure Flutter sampling, capture, lifecycle, pairing, properties, native tools, and tool guards.

Use AnsightOptions, AnsightOptions.developer(...), or createOptionsBuilder():

final options = createOptionsBuilder()
    .withAnsightDefaults()
    .withReadOnlyToolAccess()
    .withSessionJpegCapture(
      const AnsightSessionJpegCaptureOptions(
        intervalMilliseconds: 2000,
        quality: 60,
        maxWidth: 480,
      ),
    )
    .withTouchCapture()
    .registerCustomProperty('app', 'flavour', 'development')
    .build();

await Ansight.instance.initializeAndActivate(options);

AnsightOptions.developer() enables native all-in-one defaults, 400 ms sampling, 120 s retention, FPS, JPEG capture, touch capture, host auto-probe, and native visual-tree tools. It defaults the tool guard to read-only. Open-file-handle and JNI-reference sampling remain disabled; native crash capture remains enabled.

Configure Flutter-specific instrumentation separately:

await AnsightFlutterInstrumentation.instance.install(
  captureFrames: true,
  captureErrors: true,
  registerWidgetTools: true,
);

Use withRemoteTools(...) for native visual-tree, file-system, database, preferences, reflection, and secure-storage suites.

Diagnostic and Capture Options

Option or builder method	Purpose
`enableOpenFileHandleTracking` / `withOpenFileHandleTracking()`	Sample native process open-file-handle count on channel `7`. Defaults to false.
`enableJniReferenceCountTracking` / `withJniReferenceCountTracking()`	Sample JNI global references on Android channel `6`. Defaults to false.
`sessionJpegCapture.mode`	`screenshotOnly`, `screenshotAndVisualTree`, or `screenshotWithVisualTreeOnTouch`.
`sessionJpegCapture.captureKeyboardPresence`	Record keyboard presence only. Defaults to false.
`crashCapture` / `withCrashCapture(...)`	Configure durable native crash capture. Enabled by default.
`withoutCrashCapture()`	Disable the app-private crash outbox.

See JPEG Screenshots for visual-tree capture behavior and Crash Capture for recovery, retention, and privacy.

Cellular Host Connections

Cellular connections are rejected by default for QR enrollment, saved profiles, and explicit connections. Opt in only for an intentional mobile-data or personal-hotspot workflow:

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

This can consume mobile data and does not change the clear-text local-development transport.

Crash Capture

final options = createOptionsBuilder()
    .withCrashCapture(
      const AnsightCrashCaptureOptions(
        studioHandoffEnabled: true,
        offlineCaptureAttachmentEnabled: true,
        maximumPendingReports: 8,
        retentionDays: 7,
        maximumBreadcrumbs: 64,
        maximumTraceBytes: 1048576,
      ),
    )
    .build();

Use withoutCrashCapture() when the app must not persist crash evidence.