Configuration

Configure native Android sampling, memory channels, screenshots, touch input, pairing, custom properties, artifacts, tools, and guard policy.

Configure Android with AnsightOptions or AnsightOptions.createBuilder().

import ai.ansight.Ansight
import ai.ansight.runtime.AnsightOptions

val options = Ansight.options(
    AnsightOptions.createBuilder(Ansight.developerOptions(clientName = "Android App"))
        .withReadOnlyToolAccess()
        .withBatteryLevel()
        .registerCustomProperty("app", "region", "au")
        .build(),
)

Core Defaults

AnsightOptions() starts with:

Option	Default
`sampleFrequencyMilliseconds`	`500`
`retentionPeriodSeconds`	`600`
`enableFramesPerSecond`	`true`
`enableBatteryLevel`	`false`
`enableOpenFileHandleTracking`	`false`
`enableJniReferenceCountTracking`	`false`
`defaultMemoryChannels`	Java heap, native heap, RSS
`sessionJpegCapture`	`null`
`touchCapture`	enabled with Android defaults
`crashCapture`	enabled; host handoff and offline attachment enabled
`toolGuard`	`AnsightToolGuard.Disabled`
`hostAutoProbe`	enabled
`hostConnection.allowCellularConnections`	`false`
`hostConnection.allowUnattendedProvisioning`	`false`

Ansight.developerOptions(...) changes the local-development defaults to 400 ms sampling, 120 s retention, JPEG capture 2000/60/480, touch capture, host auto-probe, full tool access, and standard native tools including file-descriptor and JNI-reference diagnostics. Open-file-handle and JNI-reference-count sampling remain opt-in.

Important: Screen capture will result in an FPS drop while the SDK captures, encodes, and transports frames. Disable session JPEG capture for trend-focused runs unless visual evidence is required.

Builder Methods

Method	Purpose
`withSampleFrequencyMilliseconds(...)`	Set built-in telemetry cadence.
`withFramesPerSecond()` / `withoutFramesPerSecond()`	Toggle FPS sampling.
`withBatteryLevel()` / `withoutBatteryLevel()`	Toggle battery sampling.
`withOpenFileHandleTracking()` / `withoutOpenFileHandleTracking()`	Toggle process open-file-handle sampling on reserved channel `7`.
`withJniReferenceCountTracking()` / `withoutJniReferenceCountTracking()`	Toggle JNI global-reference sampling on reserved channel `6`.
`withRetentionPeriodSeconds(...)`	Set local metric/event retention.
`withAdditionalChannels(...)` / `addAdditionalChannel(...)`	Register custom metric channels.
`withDefaultMemoryChannels(...)` / `withoutDefaultMemoryChannels(...)`	Configure Java heap, native heap, and RSS channels.
`withSessionJpegCapture(...)` / `withoutSessionJpegCapture()`	Configure live JPEG capture, visual-tree mode, keyboard-presence metadata, and GPU-backed surface behavior.
`withTouchCapture(...)` / `withoutTouchCapture()`	Configure touch input capture.
`withCrashCapture(...)` / `withoutCrashCapture()`	Configure or disable durable native crash capture and next-launch delivery.
`withToolGuard(...)`	Set an explicit tool guard.
`withToolsDisabled()`	Disable tool discovery and execution.
`withReadOnlyToolAccess()`	Set maximum tool policy to `Read`.
`withReadWriteToolAccess()`	Set maximum tool policy to `Write`.
`withAllToolAccess()`	Set maximum tool policy to `Critical`.
`withHostAutoProbe(...)` / `withoutHostAutoProbe()`	Configure background reconnect probing.
`withHostConnection(...)` / `configureHostConnection(...)`	Configure enrollment reconnect and explicit payload handling.
`withCellularHostConnections(...)`	Permit or reject host connections over a cellular network path. Defaults to rejected.
`withUnattendedProvisioning(...)` / `withoutUnattendedProvisioning()`	Opt into launch-time test-runner enrollment. Defaults to disabled.
`withSecureStorage(...)`	Configure secure-storage options.
`withTools(...)` / `addTool(...)` / `addTools(...)`	Register app or package tools.
`withArtifactProviders(...)` / `addArtifactProvider(...)`	Register artifact providers.

Validation clamps sample frequency to 200-2000 ms, retention to 60-3600 s, JPEG quality to 1-100, and JPEG max width to 8192.

captureGpuBackedSurfaces defaults to true. The capture-mode tradeoff is currently meaningful on iOS, where setting it to false selects a lower-overhead path that may miss GPU-backed surfaces.

Host Auto-Probe

AnsightHostAutoProbeOptions controls remembered-host retries while the runtime is active. When enabled, the SDK retries previous host connections so the app can reconnect after the host disappears and later reappears.

Property	Default
`enabled`	`true`
`initialDelayMilliseconds`	`1000`
`probeIntervalMilliseconds`	`5000`
`reconnectDelayMilliseconds`	`10000`
`clientName`	`null`

Use withoutHostAutoProbe() when reconnects should only happen after an explicit app action.

Host Connection Policy

Cellular host connections are rejected by default for QR enrollment, saved profiles, and explicit connection requests. Opt in only when the development workflow intentionally uses mobile data or a personal hotspot:

val options = AnsightOptions.createBuilder()
    .withCellularHostConnections()
    .build()

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

Unattended provisioning is a separate native Android test-runner feature. Enable it only for trusted development/test variants with withUnattendedProvisioning(). At process launch, the SDK can then consume a one-use invite from the ai.ansight.bootstrap.payload Activity intent string extra before trying remembered profiles. Never log or persist that bearer payload in the app. The successful installation registration remains in app-private storage.

Crash Capture

Crash capture is enabled by default. AnsightCrashCaptureOptions.hostHandoffEnabled controls delivery to the host. The options also configure offline attachment, report count, retention, breadcrumbs, and trace size. Use withoutCrashCapture() when the app must not write a crash outbox. See Crash Capture for defaults, validated bounds, delivery, and privacy guidance.

Tool Guard

Guard	Maximum policy
`AnsightToolGuard.Disabled`	none
`AnsightToolGuard.ReadOnly`	`Read`
`AnsightToolGuard.ReadWrite`	`Write`
`AnsightToolGuard.FullAccess`	`Critical`