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
NSSupportsLiveActivitiestoYESin Info (andNSSupportsLiveActivitiesFrequentUpdatesif 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.
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.
@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,staleorpending. - 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
startstill work and can be updated. - iOS 26+:
schedulealso 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). The device has to report once before that check can work.
Demo
examples/DemoApp in the repository is a complete native app and widget.