LiveActivity#

The LiveActivity API enables you to display real-time, dynamic information from your script on the Lock Screen and, where supported, in the Dynamic Island on iOS devices. It provides a structured interface to start, update, and end Live Activities, and observe their state throughout their lifecycle.

Type Definitions#

LiveActivityState#

Represents the current lifecycle state of a Live Activity.

1type LiveActivityState = 'active' | 'dismissed' | 'ended' | 'stale'

• active: The Live Activity is visible and actively receiving updates.
• ended: The Live Activity has been ended, and no further updates will occur. It may still be visible.
• dismissed: The Live Activity has ended and is no longer visible, it has been removed by the user or the system.
• stale: The Live Activity is still visible, but its data is outdated. Consider updating the content.

LiveActivityDetail#

Describes a specific Live Activity instance.

1type LiveActivityDetail = {
2  id: string
3  state: LiveActivityState
4}

• id: A unique identifier for the Live Activity.
• state: The current state of the Live Activity.

LiveActivityUI#

Describes the UI layout of a Live Activity, for both Lock Screen and Dynamic Island presentation.

1type LiveActivityUI = {
2  content: VirtualNode
3  expanded: {
4    leading?: VirtualNode
5    trailing?: VirtualNode
6    center?: VirtualNode
7    bottom?: VirtualNode
8  }
9  compactLeading: VirtualNode
10  compactTrailing: VirtualNode
11  minimal: VirtualNode
12}

• content: The main view shown on the Lock Screen and as a banner on unsupported Dynamic Island devices.

• expanded: The expanded Dynamic Island layout with sections:

  • leading: Left-aligned content.
  • trailing: Right-aligned content.
  • center: Center-aligned content below the TrueDepth camera.
  • bottom: Content below the leading, trailing, and center areas.

• compactLeading: The compact leading view in the Dynamic Island.

• compactTrailing: The compact trailing view in the Dynamic Island.

• minimal: The minimal view used when the Dynamic Island is collapsed.

LiveActivityUIBuilder<T>#

A function that builds a LiveActivityUI layout using dynamic attributes of type T.

1interface LiveActivityUIBuilder<T> {
2  (attributes: T): LiveActivityUI
3}

LiveActivityOptions#

Optional configuration used when starting a Live Activity.

1type LiveActivityOptions = {
2  staleDate?: number
3  relevanceScore?: number
4}

• staleDate: A timestamp after which the system marks the activity as stale.
• relevanceScore: A number indicating display priority for multiple Live Activities. Higher scores appear more prominently.

LiveActivityUpdateOptions#

Extends LiveActivityOptions with alert configuration.

1type LiveActivityUpdateOptions = LiveActivityOptions & {
2  alert?: {
3    title: string
4    body: string
5  }
6}

• alert.title: Short title for the Apple Watch alert when updating the activity.
• alert.body: Main text for the Apple Watch alert.

LiveActivityEndOptions#

Extends LiveActivityOptions with dismissal configuration.

1type LiveActivityEndOptions = LiveActivityOptions & {
2  dismissTimeInterval?: number
3}

• dismissTimeInterval, duration in seconds:

  • Not provided: uses default system policy (up to 4 hours).
  • <= 0: immediate removal.
  • > 0: removal occurs after the specified interval or 4 hours, whichever is earlier.

Class: LiveActivity<T>#

Manages the lifecycle of a Live Activity.

1class LiveActivity<T> {
2  constructor(builder: LiveActivityUIBuilder<T>)
3}

Properties#

• activityId: string | undefined The unique identifier of the activity. Available after start() is successfully called.

• started: boolean Whether the activity has been started.

Methods#

start(attributes: T, options?: LiveActivityOptions): Promise<boolean>#

Starts the Live Activity.

• attributes: Dynamic data for rendering the activity.
• options: Optional configuration for relevance and stale date.
• Returns a Promise resolving to true if the activity starts successfully.

update(attributes: T, options?: LiveActivityUpdateOptions): Promise<boolean>#

Updates the activity’s content.

• attributes: Updated dynamic attributes.
• options: Optional configuration and alert.
• Returns a Promise resolving to true on success.

end(attributes: T, options?: LiveActivityEndOptions): Promise<boolean>#

Ends the Live Activity.

• attributes: Final set of attributes to display before dismissal.
• options: Optional dismissal timing.
• Returns a Promise resolving to true on success.

getActivityState(): Promise<LiveActivityState | null>#

Retrieves the current state of this Live Activity.

addUpdateListener(listener: (state: LiveActivityState) => void): void#

Adds a listener for state changes in this activity.

removeUpdateListener(listener: (state: LiveActivityState) => void): void#

Removes a previously added update listener.

Static Methods#

areActivitiesEnabled(): Promise<boolean>#

Checks whether Live Activities are supported and enabled on the current device.

addActivitiesEnabledListener(listener: (enabled: boolean) => void): void#

Adds a listener to observe availability changes.

removeActivitiesEnabledListener(listener: (enabled: boolean) => void): void#

Removes a previously added availability listener.

addActivityUpdateListener(listener: (detail: LiveActivityDetail) => void): void#

Adds a global listener for updates to any Live Activity.

removeActivityUpdateListener(listener: (detail: LiveActivityDetail) => void): void#

Removes a global update listener.

getActivityState(activityId: string): Promise<LiveActivityState | null>#

Returns the state of a Live Activity with the given activityId.

getAllActivities(): Promise<LiveActivityDetail[]>#

Retrieves all current Live Activities.

getAllActivitiesIds(): Promise<string[]>#

Returns a list of all active Live Activity IDs.

endAllActivities(options?: LiveActivityEndOptions): Promise<boolean>#

Ends all currently active Live Activities.

from<T>(activityId: string, builder: LiveActivityUIBuilder<T>): Promise<LiveActivity<T> | null>#

Recreates a LiveActivity instance using an existing activityId.

• Useful when a script reruns and needs to restore a previously started activity.

Usage Examples#

Example 1: Starting a Live Activity#

1const liveActivity = new LiveActivity(({ status, eta, icon }) => ({
2  content: <Text>{status}</Text>,
3  expanded: {
4    leading: <Text>ETA: {eta}</Text>,
5    trailing: <Image systemName={icon} />
6  },
7  compactLeading: <Text>{eta}</Text>,
8  compactTrailing: <Image systemName={icon} />,
9  minimal: <Text>{eta}</Text>
10}))
11
12await liveActivity.start({
13  status: "Tracking delivery",
14  eta: "20 min",
15  icon: "truck.box.badge.clock"
16})

Example 2: Updating a Live Activity#

1await liveActivity.update(
2  {
3    status: "Arriving soon",
4    eta: "10 min",
5    icon: "truck.box.badge.clock"
6  },
7  {
8    alert: {
9      title: "Order Update",
10      body: "Your order is arriving soon!"
11    }
12  }
13)

Example 3: Ending a Live Activity#

1await liveActivity.end(
2  {
3    status: "Delivered",
4    eta: "0 min",
5    icon: "checkmark.circle"
6  },
7  {
8    dismissTimeInterval: 0
9  }
10)