# Swift SDK

> Add LiveActivity to a native iOS app with Swift Package Manager.

Updated 2026-11-21

The Swift SDK registers your Live Activity tokens with LiveActivity, so your backend can start, update and end
activities by push. It has no dependencies. The package targets iOS 17.

## Install

In Xcode: **File → Add Package Dependencies** and enter

```
https://github.com/liveactivity-dev/liveactivity-swift
```

Add the `LiveActivity` library to the app target **and** to the widget extension (the extension only needs
`LiveActivityAttributes`).

Then, on the app target:

- add the **Push Notifications** capability,
- set `NSSupportsLiveActivities` to `YES` in Info (and `NSSupportsLiveActivitiesFrequentUpdates` if you update often).

## Attributes

Your attributes must conform to `LiveActivityAttributes` and declare `var lacId: String?`. On push-to-start we put the
activity ID into `attributes.lacId`, which is how the activity the phone starts is matched to its record on our side.
Local starts leave it `nil`.

```swift
import LiveActivity

struct DeliveryAttributes: LiveActivityAttributes {   // shared by the app and the widget
  struct ContentState: Codable, Hashable { var status: String; var etaEpoch: Double }
  var orderId: String
  var lacId: String?
}
```

The `attributesType` you send from your backend is the struct name: `"DeliveryAttributes"`. Attributes types must be
`Sendable`, which plain structs are.

## Set it up at launch

Do this in `App.init` (or `application(_:didFinishLaunchingWithOptions:)`), not in a view. A push-to-start can launch
your app in the background, and the SDK has to be listening by then to deliver the new tokens.

```swift
@main struct MyApp: App {
  init() {
    LiveActivity.configure(publishableKey: "pk_…")
    LiveActivity.register(DeliveryAttributes.self)
  }
  var body: some Scene { WindowGroup { ContentView() } }
}

// After sign-in:
LiveActivity.identify(userId: "user_42")
```

`userId` is the ID you use as `userId` in `POST /api/v1/activities`. Use one stable ID per person.

## API

| Call | What it does |
|---|---|
| `LiveActivity.configure(publishableKey:baseURL:)` | Sets the key. `baseURL` defaults to `https://liveactivity.dev`. |
| `LiveActivity.register(_ type:)` | Call once per attributes type, at launch. Reports its push-to-start token, every new activity (also ones already running) and, per activity, every update token and state change. |
| `LiveActivity.identify(userId:)` | Links this install to your user. Sent to the server on each call with a non-nil ID; call it on every launch. |
| `LiveActivity.start(attributes:contentState:staleDate:)` | Starts an activity on this device now (`Activity.request` with push updates). Returns the `Activity<T>`. The SDK then reports it, so your backend can update it. |
| `LiveActivity.schedule(attributes:contentState:at:)` | Schedules a start at a date. Returns the activity ID (`act_…`), which is also written into `attributes.lacId`. |
| `LACError` | `notConfigured`, `badResponse(Int)`, `noId`. |

`start` and `schedule` are `async throws`.

**Logout.** There is no reset call. `identify(userId: nil)` only clears the user on the device for later reports; it
doesn't call the server.

## What the SDK reports

Everything goes to `/api/sdk/*` with the publishable key, which can only register things and can never send a push.

- The push-to-start token of each attributes type, with the OS version (iOS 17.2+). It rotates, and each new value is reported.
- Each activity: its ActivityKit ID, the `lacId`, the current content state and attributes, and the update token.
- Each state change: `active`, `ended`, `dismissed`, `stale` or `pending`.
- The link between the install and your `userId`.

The install ID is a UUID kept in `UserDefaults`, so reinstalling or clearing app data gives the device a new install.
Failed requests are retried up to 3 times (client errors other than 429 are not retried), then logged with
`os.Logger` (subsystem `cloud.liveactivity.sdk`). The SDK never throws from its observers.

## iOS versions

- **iOS 17.2+**: push-to-start. Below it the SDK reports no push-to-start token, so your backend can't start an
  activity on that device. Activities started in the app with `start` still work and can be updated.
- **iOS 26+**: `schedule` also asks the device to start the activity at the date (`Activity.request(…, start:)`), with an
  empty alert title and body. We only push if the device hasn't reported the activity 60 seconds after the date.
  Before iOS 26, we send push-to-start at the date.

## Dates in the content state

The SDK encodes `contentState` and `attributes` with a default `JSONEncoder`, and ActivityKit decodes pushes with a
default `JSONDecoder`. A `Date` then means seconds since 2001-01-01, not Unix time. Prefer `Double` epoch fields (as
`etaEpoch` above, converted with `Date(timeIntervalSince1970:)` in the view) or strings you parse yourself.

Your backend's `contentState` is checked against the keys and JSON types the SDK last reported for the attributes type
(see [Live Activities](/docs/live-activities)). The device has to report once before that check can work.

## Demo

`examples/DemoApp` in the repository is a complete native app and widget.
