Configuration

Configure native iOS sampling, memory channels, screenshots, touch input, pairing, lifecycle capture, custom properties, and tool guard policy.

Configure iOS with AnsightOptions or AnsightOptions.createBuilder().

Recommended Setup

import Ansight

try AnsightRuntime.shared.initializeAndActivateAnsightSdk { options in
    options
        .withReadOnlyToolAccess()
        .withBatteryLevel()
}

The aggregate setup applies FPS sampling, 400ms sampling, 120s retention, JPEG capture at 2000ms / quality 60 / max width 480 with GPU-backed surface capture enabled, touch capture, UIKit lifecycle capture, host auto-probe, bundled developer pairing, full tool access, and standard native tool registration.

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

Core Options

import AnsightCore

let options = try AnsightOptions.createBuilder()
    .withSampleFrequencyMilliseconds(500)
    .withRetentionPeriodSeconds(600)
    .withFramesPerSecond()
    .withBatteryLevel()
    .withSessionJpegCapture(
        intervalMilliseconds: 2000,
        quality: 60,
        maxWidth: 480,
        captureGpuBackedSurfaces: true
    )
    .withReadOnlyToolAccess()
    .build()

try AnsightRuntime.shared.initializeAndActivate(options: options)

Defaults

AnsightOptions() starts with conservative core defaults:

sample frequency 500ms
retention 600s
FPS enabled
battery disabled
platform default memory channels
no session JPEG capture unless configured
touch capture enabled by default in native options
tool guard disabled
host auto-probe enabled

AnsightOptions.ansightDeveloperDefaults uses the aggregate local-development defaults.

Option Surface

Option	Purpose
`sampleFrequencyMilliseconds`	Built-in telemetry sampling interval. Clamped to `200-2000ms`.
`retentionPeriodSeconds`	Local metric/event retention window. Clamped to `60-3600s`.
`additionalChannels`	Custom metric channels. Reserved ids are rejected.
`defaultMemoryChannels`	Built-in memory channels such as managed heap and physical footprint.
`enableFramesPerSecond`	Enables CADisplayLink FPS sampling.
`enableBatteryLevel`	Enables UIDevice battery sampling.
`lifecycleCapture`	Controls automatic UIKit lifecycle and screen-view capture.
`sessionJpegCapture`	Configures live JPEG screen-frame streaming. `nil` disables it. `captureGpuBackedSurfaces` defaults to `true` for Metal, SceneKit, and similar GPU-backed views.
`touchCapture`	Configures app-local touch capture. `nil` disables it.
`toolGuard`	Controls remote-tool discovery and execution.
`customProperties`	Grouped string properties sent with `session.open`.
`hostAutoProbe`	Controls automatic reconnect attempts.
`hostConnection`	Configures saved, cached, bundled, and developer pairing sources.

Tool Guard

Preset	Allowed scopes
`.disabled`	None
`.readOnly`	`.read`
`.readWrite`	`.read`, `.write`
`.fullAccess`	`.read`, `.write`, `.delete`

Delete-scoped tools such as file delete, preference removal, secure-storage removal, and overlay removal require .fullAccess.

Host Auto-Probe

let options = try AnsightOptions.createBuilder()
    .withHostAutoProbe(
        AnsightHostAutoProbeOptions(
            enabled: true,
            initialDelayMilliseconds: 1_000,
            probeIntervalMilliseconds: 5_000,
            reconnectDelayMilliseconds: 10_000,
            clientName: "iOS App"
        )
    )
    .build()

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

Disable it when you want explicit pairing only:

let options = try AnsightOptions.createBuilder()
    .withoutHostAutoProbe()
    .build()