# iOS

> Capture iOS identity, events, errors, crashes, and backend request context.

Canonical page: https://anectico.com/docs/instrument/ios/


The native `Anectico` package supports iOS 15 and later with no runtime dependencies beyond Apple system
frameworks.

## Install with Swift Package Manager

During early access, use the authorized repository and revision supplied during onboarding. In
Xcode, choose **File → Add Package Dependencies…** and add that repository. To follow the current
source while evaluating the SDK, add this to `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/anectico/anectico.git", branch: "main"),
],
targets: [
    .target(name: "MyApp", dependencies: [.product(name: "Anectico", package: "anectico")]),
],
```

Pin the onboarding commit before a reproducible build. After tagged SDK releases begin, replace the
branch requirement with the published semantic version.

## Configure once

Call `Anectico.configure` in your SwiftUI `App` initializer or
`application(_:didFinishLaunchingWithOptions:)`:

```swift
import Anectico

try Anectico.configure(
    AnecticoOptions(
        apiKey: "an_...",
        environment: "production",
        release: "com.acme.Shop@2.4.1+318",
        dist: "318"
    )
)
```

`configure` throws `AnecticoConfigurationError` for invalid options. Handle that setup error in
your application bootstrap. Telemetry methods called before configuration are no-ops with a warning. Async bootstrap is supported: if configuration finishes after the application is
already active, Anectico catches up the missed UIKit notification and emits that process's
`$app_opened` once. Later background-to-foreground transitions emit one additional
`$app_opened` each; duplicate notifications within one lifecycle phase are ignored. Recurring
flushes stay dormant in the background after one explicit background flush.

Use a project-scoped key with `ingest:write` and `analytics:write`. Do not include read, management,
or agent scopes in the application.

## Connect identity and events

```swift
Anectico.identify("user_8842", set: ["email": "buyer@acme.example", "plan": "pro"])
Anectico.group(type: "company", key: "acme")
Anectico.capture("checkout_started", properties: ["cart_size": 3])
Anectico.screen("Checkout")

// On logout:
Anectico.reset()
```

`reset` also clears global error-user context and buffered breadcrumbs, preventing
the prior account's diagnostic context from attaching to the next account on a
shared device.

Every captured event — not only the automatic `$app_opened`/`$app_backgrounded` lifecycle
events — carries the reserved `$release` and `$app_version` properties, sourced from the same
`release`/`serviceVersion` you pass to `configure` (or your app's bundle version when you don't
set them explicitly). Neither is invented: an app that never configures a release sends events
with neither property. See [Reserved event properties](/docs/investigate/event-schema#reserved-properties).

## Capture errors and crashes

```swift
Anectico.addBreadcrumb(category: "navigation", message: "opened checkout")
do {
    try checkout()
} catch {
    Anectico.captureError(error)
}
```

Fatal signals and uncaught exceptions are spooled and delivered on the next launch. Disable handler
installation with `enableCrashReporting: false` only when another crash SDK must own the process
handlers.

The SDK keeps the complete Mach-O image list only in its private crash sidecar. A recovered envelope
carries the per-frame UUID/load address plus a bounded table of frame-referenced images, preventing
large simulator image sets from exceeding the ingest attribute limit while preserving dSYM
symbolication.

Anectico classifies a caught Swift error or explicitly captured Objective-C exception as handled and
nonfatal. An uncaught Objective-C exception or fatal signal is unhandled and fatal, with a distinct
mechanism in each case. The occurrence also includes release/distribution, SDK/platform, hardware
model code/family, OS version, and app version/build. Fatal-signal recovery uses the crash-time
snapshot even when the application is upgraded before relaunch.

This context is privacy-safe: a model code such as `iPhone15,4` identifies a device family, not one
phone. Anectico does not collect IDFV, the user-assigned device name, serial number, or installation ID.
These automatic values and crash semantics cannot be replaced through `CaptureOptions.tags`.

Upload the release build's dSYM:

```bash
anectico symbols upload-dsym MyApp.dSYM
```

The CLI accepts either the `.dSYM` bundle or its exact Mach-O file under
`Contents/Resources/DWARF/`; it locates the bundle's Xcode-named executable and uploads a
fat/universal binary without splitting it. Anectico matches each in-app frame to an uploaded dSYM slice
by the exact Mach-O image UUID; release and distribution are not dSYM lookup keys. Use the artifact
from the archive that produced the installed application.

## Propagate to your backend

```swift
var request = URLRequest(url: url)
AnecticoPropagation.apply(to: &request)
```

This adds W3C trace and customer baggage. Apply it only to trusted application backends. iOS does not
swizzle networking, so propagation is explicit.

## Verify

Identify a test user, capture an event and caught error, then call `Anectico.flush`. Confirm both appear
under the same customer. For a crash test, relaunch before checking because fatal data is sent on the
next launch. In the Issue story, compare Handling, Mechanism, Release, Distribution, SDK / Platform,
Device, OS, and App version / build between the caught and fatal occurrences.

- [Capture errors and releases](/docs/instrument/errors)
- [iOS SDK API reference](/docs/reference/ios-sdk)
- [Customer activity is not connecting](/docs/help/identity-not-linking)