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, 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 trend-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
open-file-handle tracking disabled
platform default memory channels
no session JPEG capture unless configured
touch capture enabled by default in native options
crash capture enabled with host handoff and offline attachment
tool guard disabled
host auto-probe enabled
cellular host connections disabled
unattended provisioning disabled

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.
`enableOpenFileHandleTracking`	Enables process open-file-handle sampling on reserved channel `7`.
`lifecycleCapture`	Controls automatic UIKit lifecycle and screen-view capture.
`sessionJpegCapture`	Configures live JPEG streaming, visual-tree capture mode, keyboard-presence metadata, and GPU-backed surface capture. `nil` disables it.
`touchCapture`	Configures app-local touch capture. `nil` disables it.
`crashCapture`	Controls durable native crash capture and next-launch delivery.
`toolGuard`	Controls remote-tool discovery and execution.
`customProperties`	Grouped string properties sent with `session.open`.
`hostAutoProbe`	Controls automatic reconnect attempts.
`hostConnection`	Configures enrollment reconnect, explicit payloads, and host retry behavior.

Tool Guard

Preset	Maximum policy
`.disabled`	None
`.readOnly`	`.read`
`.readWrite`	`.write`
`.fullAccess`	`.critical`

Critical tools such as file delete, preference removal, secure-storage access, arbitrary reflection, and sensitive UI operations 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()

Host Connection Policy

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

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

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

Unattended provisioning is separately disabled by default. A trusted native test runner can opt in with .withUnattendedProvisioning() and place a fresh one-use invite in the ANSIGHT_ENROLLMENT_PAYLOAD process environment variable before app launch. The SDK consumes it before remembered profiles and retains the successful installation registration in app-private storage. Use this only in development/test variants and never log the bearer payload.

Crash Capture

Crash capture is enabled by default. Configure it explicitly when retention or delivery policy differs:

let options = try AnsightOptions.createBuilder()
    .withCrashCapture(
        AnsightCrashCaptureOptions(
            hostHandoffEnabled: true,
            offlineCaptureAttachmentEnabled: true,
            maximumPendingReports: 8,
            retentionDays: 7,
            maximumBreadcrumbs: 64,
            maximumTraceBytes: 1_048_576
        )
    )
    .build()

Use .withoutCrashCapture() when the app must not write a crash outbox. See Crash Capture for recovery and privacy details.