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

# iOS SDK

> Send events from your iPhone app to Tranthor, and register it for push

The Tranthor iOS SDK is a Swift package with no third-party dependencies. It sends `identify`, `track`, `page` and `screen` events from your app, keeps them on disk until they are delivered, and, with its optional push module, registers the iPhone for [mobile push](https://docs.tranthor.com/integrations/channels/mobile-push.md).

It needs iOS 15 or later.

## Installation

The package has three products. Add the ones you need to your app:

| Product | What it does |
| - | - |
| `TranthorSDK` | Events, identity and consent. Always needed. |
| `TranthorPush` | Registers the iPhone for push and reports what happens to each push. Add it to the app target. |
| `TranthorPushService` | Shows the push image and adds one to the badge. Add it to a Notification Service Extension target. |

> [!NOTE]
>
> The iOS SDK is not in a public package registry yet. Contact us at [support@tranthor.com](mailto:support@tranthor.com) for access to the Swift package.

## Usage

```swift theme={null}
import TranthorSDK

// The write key identifies your workspace. Find it in Tranthor under Settings.
// Pass the complete value, for example "Basic trn_abcdefg...".
let sdk = try await TranthorSDK.configure(Configuration(writeKey: "Basic trn_abcdefg..."))

// Tie the customer to their actions and record traits about them.
try await sdk.identify(userId: "user-123", traits: ["email": "alex@example.com", "plan": "trial"])

// Record an action, with any properties that describe it.
try await sdk.track(event: "Completed Order", properties: ["orderId": "ORD-789", "revenue": 99.99])

// Record a screen the customer saw.
try await sdk.screen(name: "Product Page", properties: ["category": "Electronics"])

// Wait until everything queued has been sent.
try await sdk.flush()
```

Create one instance and keep it for the life of the app. Each call returns once the event is saved on the phone. It does not wait for the network, so calls stay fast and events survive the app being closed.

## Methods

| Method | What it does |
| - | - |
| `identify(userId:traits:)` | Records traits and stores the user id for later events. |
| `track(event:properties:)` | Records an event. |
| `page(name:properties:)` and `screen(name:properties:)` | Record a view. The SDK does not track screens on its own. |
| `flush()` | Sends everything queued and waits. Throws if a batch could not be delivered. |
| `reset()` | Clears the stored user id and makes a new anonymous id. Call it on sign-out. It also stops push to this phone until the next `identify`. |
| `optOut()` and `optIn()` | Stop and resume tracking for this customer. The choice is stored on the phone. |
| `shutdown()` | Stops the instance without sending. Queued events stay on disk for the next instance. |

`anonymousId`, `userId` and `isOptedOut` read the current state.

Every event method also takes optional `userId`, `anonymousId`, `messageId`, `timestamp` and `context` arguments. Numbers are sent as doubles, so send identifiers larger than 2^53 as strings.

## Identity

Before `identify`, events carry an anonymous id that the SDK creates and stores on the phone. After `identify`, events carry the user id.

* The `identify` call sends both the user id and the anonymous id, which lets Tranthor attach the customer's earlier anonymous activity to them.
* If a different customer identifies on the same phone, the SDK first replaces the anonymous id with a new one. The second customer never inherits the first customer's anonymous activity.
* An empty `userId` is treated as no user id.
* `reset()` clears the user id and starts a new anonymous id.

## Consent

`optOut()` discards everything queued and ignores later calls until `optIn()`. While opted out, `flush()` returns without sending anything. If the phone is registered for push, opting out also tells Tranthor to stop sending push to it.

## Configuration

`Configuration` takes these options:

| Option | Default | Behavior |
| - | - | - |
| `writeKey` | Required | Your workspace's write key, sent as is. |
| `host` | `https://api.tranthor.com` | API host. |
| `batchSize` | `5` | Send when this many events are queued. |
| `flushIntervalMs` | `500` | Send this long after the first queued event. |
| `retries` | `5` | Retries after the first attempt. |
| `baseDelay` | `500` | Delay before the first retry in milliseconds; doubles each retry. |
| `automaticContext` | `true` | Adds the app, device, OS, locale and timezone to each event. Keys you pass yourself win. |
| `maxQueueSize` | `10000` | The most events kept on the phone. When full, the oldest waiting events are dropped. |
| `storageNamespace` | `default` | Use a different name for each instance if your app creates more than one. |
| `onError` | none | Called once for each batch that is dropped, with its events, the HTTP status and the number of attempts. |

## Delivery

* Events are sent in batches. Network errors and HTTP 408, 425, 429 and 5xx responses are retried, and a `Retry-After` header is honoured up to 30 seconds. Other statuses, such as an invalid write key (401), are dropped after one attempt and reported through `onError`.
* Queued events are stored on the phone and sent after a restart. The files are kept out of backups.
* The SDK sends what is queued when the app goes to the background and resumes when it returns.
* With the default settings a batch is dropped after about 15 seconds of failed attempts. An app that stays offline longer than that can lose events.

## Push

To send push to the app, add `TranthorPush` and follow [Set up iOS](https://docs.tranthor.com/integrations/channels/mobile-push.md#set-up-ios). The push module uses the same instance, write key and queue, so `identify`, `reset`, `optOut` and `optIn` keep the phone's registration in step with no extra calls. A phone is registered only while a customer is signed in: `identify` registers it and `reset()` removes it ([Who a phone belongs to](https://docs.tranthor.com/integrations/channels/mobile-push.md#who-a-phone-belongs-to)).

## Current limits

* No automatic screen tracking.
* No subscribe and unsubscribe methods. Use the [API](https://docs.tranthor.com/integrations/sources/api.md) or the [Web SDK](https://docs.tranthor.com/integrations/sdks/web.md) for those.
* The package is not in a public registry yet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.