Pairing

The iOS runtime owns host connection state through AnsightRuntime.shared.

Auto-Connect

let result = await AnsightRuntime.shared.connect(
    .auto(clientName: "iOS App")
)

if !result.success {
    print(result.message)
}

Automatic connection tries:

1. hostConnection.bundledDeveloperConfigJson or the embedded developer pairing artifact.
2. remembered host profiles, newest first.
3. saved pairing config.
4. hostConnection.bundledConfigJson.

Host auto-probe is enabled by default while the runtime is active. It remembers previous host connections and retries them so the app can reconnect after the host disappears and later reappears. Probing pauses while a live session is connected and resumes after the retry delay when that session is lost.

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

Use withoutHostAutoProbe() for flows where reconnects should only happen after an explicit app action.

Developer Pairing

Enable developer pairing in local builds:

export ANSIGHT_DEVELOPER_PAIRING_ENABLED=true
export ANSIGHT_DEVELOPER_PAIRING_SOURCE_FILE=/absolute/path/to/ansight.json

The build tool generates an embedded developer pairing artifact. The aggregate defaults use:

AnsightDeveloperMode.embeddedPairingJson

Do not ship developer pairing resources in TestFlight, App Store, CI release, or other distributable builds.

Explicit Payload Pairing

Use payload pairing when the app already has a QR scanner, document picker, or pasted config string.

let result = await AnsightRuntime.shared.connect(
    .payloadText(
        pairingJson,
        clientName: "iOS App",
        expectedAppId: Bundle.main.bundleIdentifier
    )
)

Explicit payload requests override the current saved or cached session.

Saved Pairing

AnsightRuntime.shared.savePairingConfig(pairingJson)
AnsightRuntime.shared.clearSavedPairing()
AnsightRuntime.shared.clearCachedSession()
await AnsightRuntime.shared.disconnect()

Saved configs are stored in Keychain-backed storage by default.

Platform Pairing UI

The aggregate Ansight product registers PlatformHostConnectionConfigReader, which can read pairing payloads from SDK-owned file import and QR scanning flows.

Launch the SDK QR scanner:

let result = await AnsightRuntime.shared.connect(
    .qrCode(
        title: "Scan Pairing QR",
        clientName: "iOS App",
        expectedAppId: Bundle.main.bundleIdentifier
    )
)

if !result.success {
    print(result.message)
}

Launch the SDK file importer:

let result = await AnsightRuntime.shared.connect(
    .file(
        title: "Import Pairing Config",
        clientName: "iOS App",
        expectedAppId: Bundle.main.bundleIdentifier
    )
)

Use AnsightPairingQR directly when a core-only app wants the same native QR/file reader without the aggregate tool suites.

import AnsightCore
import AnsightPairingQR

AnsightRuntime.shared.setHostConnectionConfigReader(
    PlatformHostConnectionConfigReader()
)

iOS apps using QR scanning must include NSCameraUsageDescription in Info.plist.

Connection Status

Inspect HostConnectionResult for diagnostics:

• success
• message
• request kind and source
• optional reason code
• live-session details when a session opens

Use status listeners when app UI needs to reflect pairing state, cached sessions, or available pairing capabilities.