iOS Setup

Prefer SwiftPM with the aggregate Ansight product for the first integration. See iOS Packages for the complete SwiftPM product and CocoaPods pod reference.

1. Add the package

SwiftPM

Add the Ansight SDK package to the app project:

.package(url: "https://github.com/ansight-ai/ansight-sdk.git", exact: "1.4.0-preview.1")

Add its aggregate product to the development target:

.product(name: "Ansight", package: "ansight-sdk")

CocoaPods

Add the aggregate pod to the development target:

pod 'Ansight', '1.4.0-preview.1'

For a core-only, Objective-C, or individually assembled tool integration, choose the products on iOS Packages. Swift application code should prefer AnsightRuntime.shared.

Platform requirements

• Swift 6.0 toolchain or newer for the SwiftPM package.
• iOS/iPadOS deployment target 15.0 or newer.
• macOS deployment target 11.0 or newer when consuming the macOS products.

2. Initialize the development build

Initialize Ansight once from application startup. In UIKit apps, add the code to AppDelegate.swift in application(_:didFinishLaunchingWithOptions:). In SwiftUI lifecycle apps, create an UIApplicationDelegate and attach it with @UIApplicationDelegateAdaptor. If the app has a SceneDelegate, keep scene-specific UI or pairing presentation there, but initialize the runtime once from the app delegate rather than once per scene.

The launch delegate is synchronous, so initialize the runtime directly. Host auto-probe handles loopback registration and remembered reconnects after initialization:

#if DEBUG
import Ansight
#endif
import UIKit

final class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        #if DEBUG
        do {
            try AnsightRuntime.shared.initializeAndActivateAnsightSdk()
        } catch {
            assertionFailure("Ansight failed to initialize: \(error)")
        }
        #endif

        return true
    }
}

For SwiftUI lifecycle apps, attach that delegate from the app entry point:

import SwiftUI

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate

    var body: some Scene {
        SpanGroup {
            ContentView()
        }
    }
}

The aggregate setup applies the iOS developer defaults, including session JPEG capture every 2000ms at quality 60, max width 480, and captureGpuBackedSurfaces: true, then registers native tool suites.

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.

Use an explicit internal-scheme compilation condition instead of DEBUG when that is the app’s approved Ansight build. Link the aggregate product only to development targets when it must be absent from distributable builds.

3. Add stable accessibility identifiers

Give important controls stable accessibility identifiers so visual-tree evidence stays easy to query across runs:

signInButton.accessibilityIdentifier = "login-button"

4. Run and verify

Start the host in one terminal:

ansight host run

Launch the app in Simulator. From another terminal, confirm its session and tool catalog:

ansight session list --connected --json
ansight app tools <session-id> --detail summary --include-unavailable --max-results 50 --json

A physical device requires the one-time enrollment flow.

Troubleshooting

• No connected session: confirm the host is running, the app uses the development scheme, and the app delegate executes the guarded initialization.
• Ansight cannot be imported: confirm the aggregate product or pod is linked to the current development target.
• A physical device cannot reach the host: check the local-network privacy description and complete the one-time enrollment flow.

Customize aggregate setup

Use the builder callback to narrow tools, change connection policy, or adjust telemetry while keeping the default setup convention. Put this in the same AppDelegate launch method shown above.

import Ansight

try AnsightRuntime.shared.initializeAndActivateAnsightSdk { options in
    options
        .withReadOnlyToolAccess()
        .withBatteryLevel()
        .registerCustomProperty("app", "region", "au")
}

The callback starts from AnsightOptions.ansightDeveloperDefaults.

Core-only setup

Put core-only setup in the same AppDelegate launch method. Register scene or view-specific behavior separately after the runtime is active.

import AnsightCore

let options = try AnsightOptions.createBuilder()
    .withSampleFrequencyMilliseconds(500)
    .withRetentionPeriodSeconds(600)
    .withFramesPerSecond()
    .withReadOnlyToolAccess()
    .build()

try AnsightRuntime.shared.initializeAndActivate(options: options)

Core-only setup is useful when you need telemetry and host connection without standard native tools.

Developer build flags

The SwiftPM build tool and CocoaPods build phase enforce remote-tool opt-in.

Keep enrollment UI and remote tools limited to local development builds. Do not ship them in TestFlight, App Store, CI release, or other distributable builds.