# iOS SDK

CohorlySwift is a standalone Swift Package for Cohorly, supporting iOS 15+ and macOS 12+. It uses URLSession for transport, batches events, and persists its queue to UserDefaults by default.

## Install

`CohorlySwift` is distributed as a Swift Package - add it from the Cohorly
package repository.

### Xcode

File > Add Package Dependencies..., enter the repo URL, pick a version
rule, and add the **Cohorly** library product to your app target.

### Package.swift

```swift
dependencies: [
    .package(url: "https://github.com/Gitarcitano/cohorly-swift", from: "0.1.0"),
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [.product(name: "Cohorly", package: "cohorly-swift")]
    ),
]
```

## Initialize

Call `Cohorly.initialize` once near app launch. It configures and returns
the shared instance (`Cohorly.shared`). `token` is optional - omit it if
you don't use per-project tokens.

```swift
import Cohorly

let cohorly = Cohorly.initialize(token: "YOUR_PROJECT_TOKEN")

cohorly.register(["app_version": "1.2.0"])
cohorly.track("Screen Viewed", properties: ["screen": "Home"])

cohorly.identify("user_123")
cohorly.people.set(["plan": "pro"])

// Manually flush (also happens automatically every 5s or every 20 events).
await cohorly.flush()
```

## API

| Member                                                  | Notes                                                                                                                                                                         |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Cohorly.initialize(apiHost:token:...)`                 | Configures and returns `Cohorly.shared`. Also accepts `transport`, `storage`, `flushInterval`, `flushAt`.                                                                     |
| `track(_:properties:)`                                  | Queue an event.                                                                                                                                                               |
| `identify(_:)`                                          | Set the distinct id. On the first call after being anonymous, also posts `/alias` linking the previous anonymous id (best effort, not retried). No-op if the id is unchanged. |
| `reset()`                                               | Clears identity, super properties, and un-flushed events. Call this on logout - see [Identity](/reference/data-model#identity).                                               |
| `register(_:)` / `unregister(_:)`                       | Super properties merged into every event.                                                                                                                                     |
| `people.set / setOnce / increment / unset / deleteUser` | Profile updates sent to /engage.                                                                                                                                              |
| `flush() async`                                         | Manually flush; resolves once any auto-triggered flush completes.                                                                                                             |
| `currentDistinctId: String`                             | Current distinct id.                                                                                                                                                          |

## Auto-captured properties

Every event includes:

- `$lib` = `"ios"`
- `$os`, `$os_version`, `$model`
- `$screen_width` / `$screen_height` (via UIKit where available - skipped
  on macOS/watchOS)

Events and profile updates are queued in memory and persisted to storage
(UserDefaults by default) so nothing is lost across relaunch. All mutable
state is confined to a private serial `DispatchQueue`, so the client is
safe to call from any thread.