Introducing LiveActivityRead more

SDKs / React Native / ExpoMenu

React Native / Expo

Add LiveActivity to an Expo app with a config plugin and a default Live Activity view.

Updated · Markdown · Ask Claude · Ask ChatGPT

@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 NSSupportsLiveActivities and NSSupportsLiveActivitiesFrequentUpdates in Info.plist,
  • adds the aps-environment entitlement (development unless you already set it; Xcode switches to production when archiving),
  • adds a widget extension target LACWidget with LACAttributes.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.
  • schedule uses 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.