Introducing LiveActivityRead more

SDKs / Swift SDKMenu

Swift SDK

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

Updated · Markdown · Ask Claude · Ask ChatGPT

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.

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, 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). The device has to report once before that check can work.

Demo

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