# Install the iOS SDK

> Add the Union Swift package to your iOS app, configure it with your write key, and see your first session in Live in a few minutes.

Source: https://useunion.dev/docs/ios-sdk · Updated 2026-10-23

The Union SDK is a Swift package with no third-party dependencies, no IDFA and no App Tracking Transparency prompt. It needs **iOS 16** or later.

## Add the package

In Xcode, add the package `https://github.com/useunion/union-ios` from version **0.3.3** and link the `Union` library to your app target only — not to extensions or test targets. In a `Package.swift`:

```swift
.package(url: "https://github.com/useunion/union-ios", from: "0.3.3")
```

There are no CocoaPods or Carthage variants.

## Configure it once

Call `configure` exactly once, as early as possible — in your SwiftUI `App` initializer or at the top of `application(_:didFinishLaunchingWithOptions:)`:

```swift
import Union

Union.configure(writeKey: "av_…", privacyMode: .productAnalytics)
```

The write key is in **Settings → SDK write keys**. It is a client key, meant to ship inside your app, so it can be committed like any other app configuration. `privacyMode` must match the project’s setting in Union — `.productAnalytics` or `.strictAnonymous` (see [Privacy](/docs/privacy)).

`configure` already sends installs, updates, sessions, foreground and background, and device context. Do not send your own `app_opened` or `session_started`; they would duplicate what the panel already counts.

## Environments

One key serves every build. The SDK detects the environment itself and sends it with every batch:

| Build | Environment | Where it shows in the panel |
| --- | --- | --- |
| DEBUG | development | Sandbox |
| TestFlight | testflight | Sandbox |
| App Store | production | Production |

> **A DEBUG build never appears under Production**
> If Live looks empty while you test, switch the environment at the top of the panel to Sandbox.

## Screens

In SwiftUI, add `.trackScreen("Name")` to the root view of each screen. In UIKit, set `options.automaticScreenTracking = true` or call `Union.screen("Name")` in `viewDidAppear`. Screen names are stable and PascalCase (`"Checkout"`, `"WorkoutDetail"`) — never put data in a name, or every value becomes its own screen.

## Identify people

In product analytics mode, call `Union.identify(userId:)` after sign-in with your backend’s stable, opaque user id — never an email address — and `Union.reset()` on sign-out. Sessions before sign-in belong to the account the device signs in with. Strict anonymous projects skip this step entirely.

## Events

```swift
Union.track("settings_changed", properties: ["setting": "units"])
```

Names are lowercase `snake_case`, up to 64 characters, in the past tense (`workout_finished`). Up to 32 properties per event, each a string, number or bool, kept low-cardinality. An invalid event is logged and dropped; the SDK never throws. To group events into a funnel, declare a [feature](/docs/features).

## See your first session

Run a DEBUG build in the simulator, then background the app (or wait ten seconds) so the batch is sent. Open **Live** in the Sandbox scope — the session appears within seconds.

## Let your coding agent do it

[/llms.txt](/llms.txt) is the whole integration as one prompt for Claude Code, Cursor or Codex. In the panel, **Settings → SDK setup** gives the same prompt filled in with your project’s key, privacy mode and integrations.