@liveactivity/expo is a config plugin and native module for Expo. It ships one generic activity type,
LACAttributes, so you don’t have to write Swift to get started. iOS only.
Install
npx expo install @liveactivity/expo expo-build-properties
In app.json:
{ "expo": { "plugins": [
["expo-build-properties", { "ios": { "deploymentTarget": "16.2" } }],
"@liveactivity/expo"
] } }
Then:
npx expo prebuild --platform ios
npx expo run:ios --device
You need a development build on a real device. Expo Go doesn’t contain the native module, and the iOS Simulator doesn’t issue push tokens.
The plugin:
- sets
NSSupportsLiveActivitiesandNSSupportsLiveActivitiesFrequentUpdatesin Info.plist, - adds the
aps-environmententitlement (developmentunless you already set it; Xcode switches to production when archiving), - adds a widget extension target
LACWidgetwithLACAttributes.swift, the extension’s Info.plist and a default Live Activity and Dynamic Island view.
Use it
import * as LAC from "@liveactivity/expo";
LAC.configure({ publishableKey: "pk_…" }); // at startup; baseUrl is optional
LAC.identify(user.id); // null on logout
const id = await LAC.start(
{ title: "Order #1", progress: 0.2, endDate: Date.now() / 1000 + 600 },
{ name: "order" },
);
await LAC.update(id, { title: "Order #1", progress: 0.7 });
await LAC.end(id, { title: "Delivered", progress: 1 });
await LAC.schedule({ title: "Kickoff" }, new Date(Date.now() + 120_000)); // resolves with the activity ID
const sub = LAC.addTokenListener(({ kind, token }) => {});
| Call | What it does |
|---|---|
configure({ publishableKey, baseUrl? }) |
Call at startup. baseUrl defaults to the hosted API. |
identify(userId | null) |
Links the install to your user ID. null on logout. |
start(contentState, { name?, staleDate? }) |
Starts an activity on this device now. Resolves with an ID for update and end. |
schedule(contentState, startAt, { name? }) |
Schedules a start. Resolves with the server activity ID. |
update(id, contentState) |
Updates an activity started on this device. |
end(id, contentState?) |
Ends it, optionally with a final state. |
addTokenListener(cb) |
Calls cb({ kind: "pushToStart" | "activity", token }) on each new token. Returns { remove() }. |
name defaults to "default". It is stored in the attributes (attributes.name).
Content state
The content state is fixed:
| Field | Type |
|---|---|
title |
string |
subtitle |
string, optional |
progress |
number from 0 to 1, optional |
endDate |
epoch seconds, optional; shows a countdown |
status |
string, optional |
values |
map of string to string, optional |
Start it from your backend
Use the same shape with the REST API:
curl https://liveactivity.dev/api/v1/activities \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
-d '{
"appId": "<app id>",
"userId": "user_42",
"attributesType": "LACAttributes",
"attributes": { "name": "order" },
"contentState": { "title": "Order #1", "progress": 0.2 }
}'
userId is the ID you passed to identify.
Your own view
The default view lives in ios/LACWidget/LACLiveActivityView.swift after prebuild. Edit it freely: later prebuilds
don’t overwrite it. To replace it with your own SwiftUI file, pass viewFile, a path relative to the project root:
["@liveactivity/expo", { "viewFile": "native/MyLiveActivityView.swift" }]
The plugin copies that file over LACLiveActivityView.swift on every prebuild. Your view is built for LACAttributes,
so it can only show the fixed content state above. The default file is the best starting point.
iOS versions
- Push-to-start needs iOS 17.2+.
- Starting, updating and ending from the app work from iOS 16.2.
scheduleuses a scheduled start on the device on iOS 26+. Before that, the server starts it with a push, which needs a push-to-start token (iOS 17.2+).
The key and install ID are stored in UserDefaults, and observation starts in the app delegate, so a background launch
caused by a push-to-start still reports its tokens once configure has run at least once.
Demo
examples/ExpoDemo in the repository is a minimal app: start, schedule, update and end.