> ## Documentation Index
> Fetch the complete documentation index at: https://usefantasma.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS SDK

> Install and use FantasmaSDK for iOS and macOS.

# Fantasma iOS SDK

The iOS SDK sources live in `sdks/ios/FantasmaSDK`, and the repo root publishes
them as the `FantasmaSDK` Swift package.

## Public API

* `configure(serverURL:writeKey:) async throws`
* `track(_:) async throws`
* `flush() async throws`
* `clear() async`

## Usage

```swift theme={null}
import Foundation
import FantasmaSDK

let serverURL = URL(string: "http://localhost:8081")!

Task {
    do {
        try await Fantasma.configure(
            serverURL: serverURL,
            writeKey: "<ingest-key-from-provision-project>"
        )
        try await Fantasma.track("app_open")
        try await Fantasma.track("screen_view")
        try await Fantasma.flush()
        await Fantasma.clear()
    } catch {
        print("Fantasma SDK error: \(error)")
    }
}
```

The SDK auto-populates `platform`, `device`, `app_version`, `os_version`, and
`locale` for each event.

Shared ingest and queue behavior lives on the [SDK behavior](/mintlify/sdk-behavior)
page.

## Install

Add `FantasmaSDK` from the repo root package URL:

```text theme={null}
https://github.com/RuiAAPeres/fantasma.git
```

Then use:

* Package: `FantasmaSDK`
* Minimum version: your tagged release, for example `0.4.0`

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/RuiAAPeres/fantasma.git", from: "0.4.0"),
]
```

For local development, you can also use an explicit path to this repository
until you have tags available.

```swift theme={null}
.package(path: "../fantasma"),
```

Supported platforms:

* iOS 17.0+
* macOS 14.0+

## iOS-Specific Notes

* The SDK exposes a static `Fantasma` facade instead of an instance-based client.
* iPhone emits `platform = "ios"`, `device = "phone"`.
* iPad emits `platform = "ios"`, `device = "tablet"`.
* Native macOS, Mac Catalyst, and iOS-on-Mac desktop-class runs emit `platform = "macos"`, `device = "desktop"`.
* `track(_:)` throws when the SDK has not been configured.
* `flush()` throws when the SDK has not been configured.
* Reconfiguring to a different server URL or write key discards any still-queued rows after the current upload boundary, even across app relaunches, then switches future uploads to the new destination.
* In addition to the shared upload triggers, the SDK also attempts uploads when the app enters background.