# React Native / Expo

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

Updated 2026-11-21

`@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

```sh
npx expo install @liveactivity/expo expo-build-properties
```

In `app.json`:

```json
{ "expo": { "plugins": [
  ["expo-build-properties", { "ios": { "deploymentTarget": "16.2" } }],
  "@liveactivity/expo"
] } }
```

Then:

```sh
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

```ts
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:

```sh
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:

```json
["@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.
