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. 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.
`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 enable/configure capture, or `false` to disable. Supports `captureGpuBackedSurfaces`; on iOS it defaults to `true` for Metal, SceneKit, and similar GPU-backed views.
`touchCapture`	Object to enable/configure touch capture, or `false` to disable.
`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`	Saved, bundled, and developer pairing settings.
`remoteTools`	Native visual tree, file, database, preferences, reflection, and secure-storage tool 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.
`withRetentionPeriodSeconds(...)`	Set retained telemetry window.
`withDefaultMemoryChannels(...)` / `withoutDefaultMemoryChannels(...)`	Configure native memory channels.
`withReactNativeMemoryProfiling(...)` / `withoutReactNativeMemoryProfiling()`	Configure RN JS heap channels.
`withSessionJpegCapture(...)` / `withoutSessionJpegCapture()`	Configure live JPEG frame capture, including `captureGpuBackedSurfaces`.
`withTouchCapture(...)` / `withoutTouchCapture()`	Configure touch capture.
`withLifecycleCapture(...)`	Configure native lifecycle capture.
`withToolGuard(...)` and guard presets	Configure remote-tool discovery and execution.
`withHostAutoProbe(...)` / `withoutHostAutoProbe()`	Configure automatic reconnect probing.
`withHostConnection(...)` / `withBundledHostConnection(...)`	Configure pairing sources.
`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.

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 performance-focused runs unless visual evidence is required.