Configuration

Configure React Native sampling, memory profiling, screenshots, touch capture, lifecycle tracking, pairing, custom properties, native tools, and tool guards.

Configure the bridge with an AnsightOptions object or Ansight.createOptionsBuilder().

const options = Ansight.createOptionsBuilder()
  .withNativeAllInOneDefaults()
  .withReadOnlyToolAccess()
  .withBatteryLevel()
  .registerCustomProperty("app", "region", "au")
  .build();

await Ansight.initializeAndActivate(options);

Option Surface

Option	Purpose
`useNativeAllInOneDefaults`	Applies native iOS/Android all-in-one defaults when true, including file-descriptor diagnostics and Android JNI-reference diagnostics. Defaults to false. This is not a master enable switch; configure `toolGuard`, capture options, and `hostConnection` separately.
`clientName`	Default client name for host auto-probe and connection calls.
`sampleFrequencyMilliseconds`	Built-in telemetry cadence.
`retentionPeriodSeconds`	Local metric/event retention.
`enableFramesPerSecond`	Native FPS sampling.
`enableBatteryLevel`	Native battery sampling where supported.
`enableOpenFileHandleTracking`	Native process open-file-handle sampling on reserved channel `7`. Defaults to false.
`enableJniReferenceCountTracking`	Android JNI global-reference sampling on reserved channel `6`. Defaults to false.
`defaultMemoryChannels`	Built-in native memory channels.
`reactNativeMemory`	React Native JS heap used/total profiling; set `false` to disable.
`additionalChannels`	App-defined metric channels.
`sessionJpegCapture`	Object to configure JPEG capture, visual-tree mode, keyboard-presence metadata, and GPU-backed surfaces, or `false` to disable.
`touchCapture`	Object to enable/configure touch capture, or `false` to disable.
`crashCapture`	Durable native crash policy, or `false` to disable. Enabled by default.
`lifecycleCapture`	Native lifecycle and screen-view capture options.
`toolGuard`	`"disabled"`, `"readOnly"`, `"readWrite"`, or `"fullAccess"`.
`customProperties`	Grouped string properties sent with `session.open`.
`hostAutoProbe`	Background reconnect settings.
`hostConnection`	Enrollment reconnect, scanner payload, host retry, and `allowCellularConnections` settings.
`remoteTools`	Native visual tree, file, database, preferences, reflection, and secure-storage tool options. File-descriptor and JNI-reference diagnostics have no suite-specific JavaScript options.
`lifecycle`	JavaScript AppState tracking toggle. Defaults to true.

Builder Methods

Method	Purpose
`withNativeAllInOneDefaults()` / `withAnsightDefaults()` / `withAnsightSdk(...)`	Apply native all-in-one defaults. `withNativeAllInOneDefaults()` and `withAnsightDefaults()` use read-only tool access; `withAnsightSdk(...)` opts into full all-in-one access.
`withSampleFrequencyMilliseconds(...)`	Set sampling cadence.
`withFramesPerSecond()` / `withoutFramesPerSecond()`	Toggle FPS sampling.
`withBatteryLevel()` / `withoutBatteryLevel()`	Toggle battery sampling.
`withOpenFileHandleTracking()` / `withoutOpenFileHandleTracking()`	Toggle native open-file-handle sampling.
`withJniReferenceCountTracking()` / `withoutJniReferenceCountTracking()`	Toggle Android JNI-reference sampling.
`withRetentionPeriodSeconds(...)`	Set retained telemetry window.
`withDefaultMemoryChannels(...)` / `withoutDefaultMemoryChannels(...)`	Configure native memory channels.
`withReactNativeMemoryProfiling(...)` / `withoutReactNativeMemoryProfiling()`	Configure RN JS heap channels.
`withSessionJpegCapture(...)` / `withoutSessionJpegCapture()`	Configure live JPEG capture, visual-tree mode, keyboard-presence metadata, and GPU-backed surfaces.
`withTouchCapture(...)` / `withoutTouchCapture()`	Configure touch capture.
`withCrashCapture(...)` / `withoutCrashCapture()`	Configure or disable durable native crash capture.
`withLifecycleCapture(...)`	Configure native lifecycle capture.
`withToolGuard(...)` and guard presets	Configure remote-tool discovery and execution.
`withHostAutoProbe(...)` / `withoutHostAutoProbe()`	Configure automatic reconnect probing.
`withHostConnection(...)`	Override advanced host connection policy. Normal simulator/emulator setup needs no connection object or bundled config.
`withCellularHostConnections(...)`	Permit or reject QR, saved-profile, and explicit connections over cellular.
`withRemoteTools(...)` and tool-specific helpers	Configure native tool suites.
`withVisualTreeTools()` / `withoutVisualTreeTools()`	Opt in or out of native VisualTree tools.

Host Auto-Probe

hostAutoProbe forwards to the native iOS/Android remembered-host retry behavior. When enabled, it retries previous host connections so the app can reconnect after the host disappears and later reappears.

await Ansight.initializeAndActivate({
  hostAutoProbe: {
    enabled: true,
    initialDelayMilliseconds: 1000,
    probeIntervalMilliseconds: 5000,
    reconnectDelayMilliseconds: 10000,
    clientName: "React Native App",
  },
});

Use withoutHostAutoProbe() or hostAutoProbe: { enabled: false } when reconnects should only happen after an explicit app action.

Cellular Host Connections

Cellular connections are rejected by default. Opt in only for intentional mobile-data or personal-hotspot development workflows:

const options = Ansight.createOptionsBuilder()
  .withCellularHostConnections()
  .build();

The setting applies to QR enrollment, saved profiles, and explicit connections. It can consume mobile data and does not change the clear-text local-development transport.

Crash Capture

Native crash capture is enabled by default:

await Ansight.initializeAndActivate({
  crashCapture: {
    hostHandoffEnabled: true,
    offlineCaptureAttachmentEnabled: true,
    maximumPendingReports: 8,
    retentionDays: 7,
    maximumBreadcrumbs: 64,
    maximumTraceBytes: 1_048_576,
  },
});

Set crashCapture: false or use withoutCrashCapture() when the app must not create an app-private crash outbox. See Crash Capture.

Memory Profiling

await Ansight.initializeAndActivate({
  reactNativeMemory: {
    enabled: true,
    jsHeapUsed: true,
    jsHeapTotal: true,
  },
});

Set reactNativeMemory: false to disable RN JS heap profiling.

Important: Screen capture will result in an FPS drop while native frames are captured, encoded, and transported. Disable sessionJpegCapture for trend-focused runs unless visual evidence is required.