### Example Payload for Starting Live Activity

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

This JSON payload demonstrates the structure for initiating a Live Activity via a push notification. It includes content state and attribute details. Ensure 'PushToStart' is enabled and the target device runs iOS 17.2 or higher.

```json
{
  "aps": {
    "event": "start",
    "content-state": {
      "title": "Live Activity title!",
      "subtitle": "Live Activity subtitle.",
      "timerEndDateInMilliseconds": 1754410997000,
      "progress": 0.5,
      "imageName": "live_activity_image",
      "dynamicIslandImageName": "dynamic_island_image",
      "elapsedTimerStartDateInMilliseconds": null
    },
    "timestamp": 1754491435000, // timestamp of when the push notification was sent
    "attributes-type": "LiveActivityAttributes",
    "attributes": {
      "name": "Test",
      "backgroundColor": "001A72",
      "titleColor": "EBEBF0",
      "subtitleColor": "FFFFFF75",
      "progressViewTint": "38ACDD",
      "progressViewLabelColor": "FFFFFF",
      "deepLinkUrl": "/dashboard",
      "timerType": "digital",
      "padding": 24, // or use object to control each side: { "horizontal": 20, "top": 16, "bottom": 16 }
      "imagePosition": "right",
      "imageSize": "default"
    },
    "alert": {
      "title": "",
      "body": "",
      "sound": "default"
    }
  }
}
```

--------------------------------

### Start a Live Activity

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Initiate a new Live Activity with an initial state and optional configuration. Returns the activity ID or undefined if not supported.

```javascript
LiveActivity.startActivity(state, config, relevanceScore)
```

--------------------------------

### Example Payload for Starting Live Activity with Elapsed Timer

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

This payload demonstrates starting a Live Activity with an elapsed timer. The `elapsedTimerStartDateInMilliseconds` field should contain the timestamp when the timer began counting up. This is an alternative to using `timerEndDateInMilliseconds` for countdowns.

```json
{
  "aps": {
    "event": "start",
    "content-state": {
      "title": "Walk in Progress",
      "subtitle": "With Max",
      "timerEndDateInMilliseconds": null,
      "progress": null,
      "imageName": "dog_walking",
      "dynamicIslandImageName": "dog_icon",
      "elapsedTimerStartDateInMilliseconds": 1754410997000
    },
    "timestamp": 1754491435000,
    "attributes-type": "LiveActivityAttributes",
    "attributes": {
      "name": "WalkActivity",
      "backgroundColor": "001A72",
      "titleColor": "EBEBF0",
      "progressViewLabelColor": "FFFFFF"
    }
  }
}
```

--------------------------------

### Configure Deep Linking for Live Activities

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Set up deep linking for Live Activities using React Navigation. Ensure your app.json has a URL scheme defined or relies on the bundle identifier. This example shows how to create a linking configuration and start an activity with a deep link.

```typescript
const prefix = Linking.createURL('')

export default function App() {
  const url = Linking.useLinkingURL()
  const linking = {
    enabled: 'auto' as const,
    prefixes: [prefix],
  }
}
```

```typescript
// Then start the activity with:
LiveActivity.startActivity(state, {
  deepLinkUrl: '/order',
})
```

--------------------------------

### Install expo-live-activity

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Run this command to add the expo-live-activity module to your project. Ensure you are using Expo DevClient as Expo Go is not supported.

```sh
npm install expo-live-activity
```

--------------------------------

### Start Live Activity

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Initiates a new Live Activity. It requires an initial state and can optionally be configured with custom settings and a relevance score. Returns the unique ID of the created activity.

```APIDOC
## startActivity

### Description
Starts a new Live Activity with the provided initial state and optional configuration. Returns the ID of the created Live Activity.

### Method Signature
`startActivity(state: LiveActivityState, config?: LiveActivityConfig, relevanceScore?: number): string | undefined`

### Parameters
- **state** (LiveActivityState) - Required - The initial state of the Live Activity.
- **config** (LiveActivityConfig) - Optional - Configuration object for customizing the Live Activity's appearance or behavior.
- **relevanceScore** (number) - Optional - A score between 0.0 and 1.0 that determines the activity's display order.

### Returns
- `string | undefined` - The ID of the created Live Activity, or undefined if it cannot be created.
```

--------------------------------

### Start Live Activity with Remote Images

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

This TypeScript code demonstrates starting a Live Activity using remote image URLs for 'imageName' and 'dynamicIslandImageName'. Ensure the App Groups capability is enabled for both targets.

```typescript
LiveActivity.startActivity({
  title: 'Live from the stadium',
  imageName: 'https://cdn.example.com/player-42.png',         // downloaded at start
  dynamicIslandImageName: 'https://cdn.example.com/badge.png',
})
```

--------------------------------

### Start Live Activity via Push Notification

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Use this JSON payload to start a Live Activity via APNs. Ensure the 'attributes-type' matches 'LiveActivityAttributes'.

```json
{
  "aps": {
    "event": "start",
    "timestamp": 1754491435000,
    "attributes-type": "LiveActivityAttributes",
    "attributes": {
      "name": "OrderActivity",
      "backgroundColor": "001A72",
      "titleColor": "EBEBF0",
      "subtitleColor": "FFFFFF75",
      "progressViewTint": "38ACDD",
      "progressViewLabelColor": "FFFFFF",
      "deepLinkUrl": "/order/1042",
      "timerType": "digital",
      "padding": 24
    },
    "content-state": {
      "title": "Order #1042",
      "subtitle": "Preparing your order",
      "timerEndDateInMilliseconds": 1754410997000,
      "progress": null,
      "imageName": "courier",
      "dynamicIslandImageName": "courier-dot",
      "elapsedTimerStartDateInMilliseconds": null
    },
    "alert": { "title": "", "body": "", "sound": "default" }
  }
}
```

--------------------------------

### Start Live Activity with Elapsed Timer

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Starts a Live Activity that displays an elapsed timer. The timer automatically updates every second based on the provided startDate. Ensure the image names are correctly configured in your assets.

```typescript
const elapsedTimerState: LiveActivity.LiveActivityState = {
  title: 'Walk in Progress',
  subtitle: 'With Max the Dog',
  progressBar: {
    elapsedTimer: {
      startDate: Date.now() - 5 * 60 * 1000, // Started 5 minutes ago
    },
  },
  imageName: 'dog_walking',
  dynamicIslandImageName: 'dog_icon',
}

const activityId = LiveActivity.startActivity(elapsedTimerState, config)
```

--------------------------------

### Start Live Activity with Elapsed Timer via Push

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Use this payload to start a Live Activity that features an elapsed timer. The 'elapsedTimerStartDateInMilliseconds' in 'content-state' is crucial for this.

```json
{
  "aps": {
    "event": "start",
    "timestamp": 1754491435000,
    "attributes-type": "LiveActivityAttributes",
    "attributes": {
      "name": "WalkActivity",
      "backgroundColor": "001A72",
      "titleColor": "EBEBF0"
    },
    "content-state": {
      "title": "Walk in Progress",
      "subtitle": "With Max",
      "timerEndDateInMilliseconds": null,
      "progress": null,
      "imageName": "dog_walking",
      "dynamicIslandImageName": "dog_icon",
      "elapsedTimerStartDateInMilliseconds": 1754410997000
    }
  }
}
```

--------------------------------

### addActivityPushToStartTokenListener

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Subscribes to the push-to-start token, which allows your server to start a Live Activity remotely without the user opening the app first.

```APIDOC
## addActivityPushToStartTokenListener

### Description
Subscribes to the push-to-start token, which allows your server to start a Live Activity remotely without the user opening the app first. Requires iOS 17.2+; returns `null` token on earlier OS versions.

### Parameters
#### Callback Function
- **listener** (function) - Required - A callback function that receives an object with `activityPushToStartToken`.

### Request Example
```typescript
const subscription = LiveActivity.addActivityPushToStartTokenListener(
  ({ activityPushToStartToken }) => {
    if (!activityPushToStartToken) return
    console.log('Push-to-start token:', activityPushToStartToken)
    fetch('https://api.example.com/live-activity/push-to-start-token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ token: activityPushToStartToken }),
    })
  }
)

// To unsubscribe:
// subscription?.remove()
```
```

--------------------------------

### Start a Live Activity

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Initiate a Live Activity with initial state and configuration. The `startActivity` function returns an activity ID or undefined on non-iOS platforms or older iOS versions. Ensure assets like images are placed in the `assets/liveActivity/` directory.

```typescript
import * as LiveActivity from 'expo-live-activity'
import type { LiveActivityState, LiveActivityConfig } from 'expo-live-activity'

const state: LiveActivityState = {
  title: 'Order #1042',
  subtitle: 'Arriving in ~5 min',
  progressBar: {
    date: new Date(Date.now() + 5 * 60 * 1000).getTime(), // countdown to epoch ms
  },
  imageName: 'courier',                  // file in assets/liveActivity/
  dynamicIslandImageName: 'courier-dot', // compact Dynamic Island image
  smallImageName: 'courier-small',       // Apple Watch / CarPlay
}

const config: LiveActivityConfig = {
  backgroundColor: '001A72',       // hex without '#' also accepted
  titleColor: '#EBEBF0',
  subtitleColor: '#FFFFFF75',
  progressViewTint: '38ACDD',
  progressViewLabelColor: '#FFFFFF',
  deepLinkUrl: '/order/1042',       // passed to the widget as a URL for deep linking
  timerType: 'circular',            // 'circular' | 'digital'
  imagePosition: 'right',           // 'left' | 'right' | 'leftStretch' | 'rightStretch'
  imageAlign: 'center',             // 'top' | 'center' | 'bottom'
  imageSize: { width: 64, height: '50%' }, // pt (number) or percentage string
  contentFit: 'contain',            // 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
  padding: { horizontal: 20, top: 16, bottom: 16 },
}

try {
  const activityId = LiveActivity.startActivity(state, config, 0.8) // relevanceScore 0–1
  if (activityId) {
    console.log('Live Activity started:', activityId)
    // store activityId in component state / AsyncStorage for later updates
  }
} catch (e) {
  console.error('Failed to start Live Activity:', e)
}
```

--------------------------------

### startActivity

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Starts a new Live Activity and returns its opaque string ID. The activity appears on the Lock Screen and, when available, in the Dynamic Island. Returns `undefined` on non-iOS platforms or on iOS < 16.2 (unless `silentOnUnsupportedOS` is set).

```APIDOC
## startActivity

### Description
Starts a new Live Activity and returns its opaque string ID. The activity appears on the Lock Screen and, when available, in the Dynamic Island. Returns `undefined` on non-iOS platforms or on iOS < 16.2 (unless `silentOnUnsupportedOS` is set).

### Method
```typescript
LiveActivity.startActivity(state: LiveActivityState, config?: LiveActivityConfig, relevanceScore?: number): string | undefined
```

### Parameters
#### State Parameters
- **title** (string) - Required - The main title for the Live Activity.
- **subtitle** (string) - Optional - The subtitle for the Live Activity.
- **progressBar** (object) - Optional - Configuration for the progress bar.
  - **date** (number) - Optional - Countdown to an epoch timestamp in milliseconds.
  - **progress** (number) - Optional - Static progress bar value between 0.0 and 1.0.
  - **elapsedTimer** (object) - Optional - Configuration for an elapsed timer.
    - **startDate** (number) - Required - Epoch timestamp in milliseconds when the timer started.
  - **currentStep** (number) - Optional - The current step in a step-based progress bar.
  - **totalSteps** (number) - Optional - The total number of steps in a step-based progress bar.
- **imageName** (string) - Optional - The name of the image file in `assets/liveActivity/` for the main display.
- **dynamicIslandImageName** (string) - Optional - The name of the image file for the compact Dynamic Island display.
- **smallImageName** (string) - Optional - The name of the image file for Apple Watch / CarPlay.

#### Configuration Parameters
- **backgroundColor** (string) - Optional - Background color of the Live Activity (hex string).
- **titleColor** (string) - Optional - Color of the title text.
- **subtitleColor** (string) - Optional - Color of the subtitle text.
- **progressViewTint** (string) - Optional - Tint color for the progress bar.
- **progressViewLabelColor** (string) - Optional - Color of the progress bar label.
- **deepLinkUrl** (string) - Optional - URL for deep linking into the app.
- **timerType** (string) - Optional - Type of timer display ('circular' or 'digital').
- **imagePosition** (string) - Optional - Position of the image ('left', 'right', 'leftStretch', 'rightStretch').
- **imageAlign** (string) - Optional - Alignment of the image ('top', 'center', 'bottom').
- **imageSize** (object) - Optional - Size of the image.
  - **width** (number | string) - Optional - Image width in points or percentage.
  - **height** (number | string) - Optional - Image height in points or percentage.
- **contentFit** (string) - Optional - How the image content should be scaled ('cover', 'contain', 'fill', 'none', 'scale-down').
- **padding** (object) - Optional - Padding around the content.
  - **horizontal** (number) - Optional - Horizontal padding.
  - **top** (number) - Optional - Top padding.
  - **bottom** (number) - Optional - Bottom padding.

#### Relevance Score
- **relevanceScore** (number) - Optional - A score from 0 to 1 indicating the relevance of the activity.

### Request Example
```typescript
import * as LiveActivity from 'expo-live-activity'
import type { LiveActivityState, LiveActivityConfig } from 'expo-live-activity'

const state: LiveActivityState = {
  title: 'Order #1042',
  subtitle: 'Arriving in ~5 min',
  progressBar: {
    date: new Date(Date.now() + 5 * 60 * 1000).getTime(), // countdown to epoch ms
  },
  imageName: 'courier',                  // file in assets/liveActivity/
  dynamicIslandImageName: 'courier-dot', // compact Dynamic Island image
  smallImageName: 'courier-small',       // Apple Watch / CarPlay
}

const config: LiveActivityConfig = {
  backgroundColor: '001A72',       // hex without '#' also accepted
  titleColor: '#EBEBF0',
  subtitleColor: '#FFFFFF75',
  progressViewTint: '38ACDD',
  progressViewLabelColor: '#FFFFFF',
  deepLinkUrl: '/order/1042',       // passed to the widget as a URL for deep linking
  timerType: 'circular',            // 'circular' | 'digital'
  imagePosition: 'right',           // 'left' | 'right' | 'leftStretch' | 'rightStretch'
  imageAlign: 'center',             // 'top' | 'center' | 'bottom'
  imageSize: { width: 64, height: '50%' }, // pt (number) or percentage string
  contentFit: 'contain',            // 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
  padding: { horizontal: 20, top: 16, bottom: 16 },
}

try {
  const activityId = LiveActivity.startActivity(state, config, 0.8) // relevanceScore 0–1
  if (activityId) {
    console.log('Live Activity started:', activityId)
    // store activityId in component state / AsyncStorage for later updates
  }
} catch (e) {
  console.error('Failed to start Live Activity:', e)
}
```

### Response
Returns the opaque string ID of the started Live Activity, or `undefined` if it could not be started.
```

--------------------------------

### Listen for Push-to-Start Token

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Subscribes to the push-to-start token, which allows your server to start a Live Activity remotely without the user opening the app first. Requires iOS 17.2+; returns `null` token on earlier OS versions.

```typescript
import * as LiveActivity from 'expo-live-activity'
import { useEffect } from 'react'

useEffect(() => {
  const subscription = LiveActivity.addActivityPushToStartTokenListener(
    ({ activityPushToStartToken }) => {
      if (!activityPushToStartToken) return
      console.log('Push-to-start token:', activityPushToStartToken)
      fetch('https://api.example.com/live-activity/push-to-start-token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token: activityPushToStartToken }),
      })
    }
  )
  return () => subscription?.remove()
}, [])
```

--------------------------------

### Live Activity State Object Structure

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Defines the structure of the `state` object used when starting or updating a Live Activity.

```APIDOC
## State Object Structure

### Description
The `state` object defines the content and dynamic elements of a Live Activity.

### Structure
```typescript
{
  title: string;
  subtitle?: string;
  progressBar: {
    date?: number; // Epoch time in milliseconds for countdown timer
    progress?: number; // Progress value (0-1)
    elapsedTimer?: {
      startDate: number; // Epoch time in milliseconds for elapsed timer
    };
  };
  imageName?: string; // Name of image in 'assets/liveActivity'
  dynamicIslandImageName?: string; // Name of image in 'assets/liveActivity'
}
```
```

--------------------------------

### Live Activity Config Object Structure

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Defines the structure of the `config` object used when starting or updating a Live Activity, controlling its appearance and behavior.

```APIDOC
## Config Object Structure

### Description
The `config` object allows customization of the Live Activity's appearance and behavior, including styling, deep linking, and timer types.

### Structure
```typescript
{
   backgroundColor?: string;
   titleColor?: string;
   subtitleColor?: string;
   progressViewTint?: string;
   progressViewLabelColor?: string;
   deepLinkUrl?: string;
   timerType?: DynamicIslandTimerType; // "circular" | "digital"
   padding?: Padding // number | {top?: number bottom?: number ...}
   imagePosition?: ImagePosition; // 'left' | 'right';
   imageAlign?: ImageAlign; // 'top' | 'center' | 'bottom'
   imageSize?: ImageSize // { width?: number|`${number}%`, height?: number|`${number}%` } | undefined (defaults to 64pt)
   contentFit?: ImageContentFit; // 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
}
```
```

--------------------------------

### Start Live Activity with Countdown Timer

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Initiates a Live Activity with a specified title, subtitle, image, and a countdown timer. Configuration options for colors, deep links, and image positioning are also included. Store the returned activityId for future reference.

```typescript
const state: LiveActivity.LiveActivityState = {
  title: 'Title',
  subtitle: 'This is a subtitle',
  progressBar: {
    date: new Date(Date.now() + 60 * 1000 * 5).getTime(),
  },
  imageName: 'live_activity_image',
  dynamicIslandImageName: 'dynamic_island_image',
}

const config: LiveActivity.LiveActivityConfig = {
  backgroundColor: '#FFFFFF',
  titleColor: '#000000',
  subtitleColor: '#333333',
  progressViewTint: '#4CAF50',
  progressViewLabelColor: '#FFFFFF',
  deepLinkUrl: '/dashboard',
  timerType: 'circular',
  padding: { horizontal: 20, top: 16, bottom: 16 },
  imagePosition: 'right',
  imageAlign: 'center',
  imageSize: { height: '50%', width: '50%' }, // number (pt) or percentage of the image container, if empty by default is 64pt.
  contentFit: 'cover',
}

const activityId = LiveActivity.startActivity(state, config)
// Store activityId for future reference
```

--------------------------------

### Live Activity Configuration Type Reference

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

TypeScript type definition for visual configuration options when starting a Live Activity. This includes colors, padding, deep link URLs, and image positioning/sizing.

```typescript
// Visual configuration (passed to startActivity only)
type LiveActivityConfig = {
  backgroundColor?: string             // hex with or without '#'
  titleColor?: string
  subtitleColor?: string
  progressViewTint?: string
  progressViewLabelColor?: string
  progressSegmentActiveColor?: string  // step-progress active segment
  progressSegmentInactiveColor?: string
  deepLinkUrl?: string
  timerType?: 'circular' | 'digital'
  padding?: number | {
    top?: number; bottom?: number; left?: number; right?: number
    vertical?: number; horizontal?: number
  }
  imagePosition?: 'left' | 'right' | 'leftStretch' | 'rightStretch'
  imageAlign?: 'top' | 'center' | 'bottom'
  imageSize?: { width?: number | `${number}%`; height?: number | `${number}%` }
  smallImageSize?: { width?: number | `${number}%`; height?: number | `${number}%` }
  contentFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
}
```

--------------------------------

### Live Activity Config Object Structure

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Defines the structure for the configuration object used when starting or updating a Live Activity. Allows customization of appearance (colors, padding, image settings) and behavior (deep linking, timer type).

```typescript
{
   backgroundColor?: string;
   titleColor?: string;
   subtitleColor?: string;
   progressViewTint?: string;
   progressViewLabelColor?: string;
   deepLinkUrl?: string;
   timerType?: DynamicIslandTimerType;
   padding?: Padding
   imagePosition?: ImagePosition;
   imageAlign?: ImageAlign;
   imageSize?: ImageSize
   contentFit?: ImageContentFit;
};
```

--------------------------------

### Subscribe to Live Activity Token Changes

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Sets up listeners for changes in Live Activity push tokens. These tokens are necessary for sending push notifications to update the Live Activity or to start a Live Activity with push notifications. Note that push token functionality may not work on simulators; use a physical device for testing.

```typescript
useEffect(() => {
  const updateTokenSubscription = LiveActivity.addActivityTokenListener(
    ({ activityID: newActivityID, activityName: newName, activityPushToken: newToken }) => {
      // Send token to a remote server to update Live Activity with push notifications
    }
  )
  const startTokenSubscription = LiveActivity.addActivityPushToStartTokenListener(
    ({ activityPushToStartToken: newActivityPushToStartToken }) => {
      // Send token to a remote server to start Live Activity with push notifications
    }
  )

  return () => {
    updateTokenSubscription?.remove()
    startTokenSubscription?.remove()
  }
}, [])
```

--------------------------------

### Example Payload for Updating Live Activity

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

This JSON payload is used to update an existing Live Activity. It specifies the 'update' event and provides new content-state values. The timestamp indicates when the push notification was sent.

```json
{
  "aps": {
    "event": "update",
    "content-state": {
      "title": "Hello",
      "subtitle": "World",
      "timerEndDateInMilliseconds": 1754064245000,
      "imageName": "live_activity_image",
      "dynamicIslandImageName": "dynamic_island_image"
    },
    "timestamp": 1754063621319 // timestamp of when the push notification was sent
  }
}
```

--------------------------------

### Live Activity State Object Structure

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Defines the structure for the state object used when starting or updating a Live Activity. Supports title, subtitle, progress visualization (countdown, progress bar, or elapsed timer), and image assets.

```typescript
{
  title: string;
  subtitle?: string;
  progressBar: {
    date?: number;
    progress?: number;
    elapsedTimer?: {
      startDate: number;
    };
  };
  imageName?: string;
  dynamicIslandImageName?: string;
};
```

--------------------------------

### Live Activity State Type Reference

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

TypeScript type definition for the state object used when starting, updating, or stopping a Live Activity. It includes properties for title, subtitle, progress, images, and timer configurations.

```typescript
// State passed to start / update / stop
type LiveActivityState = {
  title: string
  subtitle?: string
  progressBar?: // only ONE of the following sub-shapes at a time:
    | { date?: number }                                 // epoch ms countdown
    | { progress?: number }                             // 0.0–1.0 static bar
    | { elapsedTimer?: { startDate: number } }          // count-up timer (epoch ms)
    | { currentStep?: number; totalSteps?: number }     // segmented step bar
  imageName?: string                   // asset name or https:// URL
  dynamicIslandImageName?: string
  smallImageName?: string              // Apple Watch / CarPlay
}
```

--------------------------------

### Prebuild App After Configuration

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

After setting up the config plugin and assets, prebuild your app to apply the changes. Note that Live Activity assets cannot exceed 4KB.

```sh
npx expo prebuild --clean
```

--------------------------------

### Deep Linking Configuration

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Configuration details for enabling deep linking within Live Activities, allowing users to navigate to specific app screens when interacting with an activity.

```APIDOC
## Deep Linking Setup

### Description
Configure deep linking for Live Activities by setting up URL prefixes and using `deepLinkUrl` in the activity configuration. This allows navigation to specific screens within your app.

### Usage
1. Obtain the URL prefix using `Linking.createURL('')`.
2. Configure your app's linking settings, typically in `app.json` or directly in your app's navigation setup.
3. Pass the `deepLinkUrl` in the `config` object when starting an activity.

### Example
```typescript
const prefix = Linking.createURL('')

export default function App() {
  const url = Linking.useLinkingURL()
  const linking = {
    enabled: 'auto' as const,
    prefixes: [prefix],
  }
}

// Then start the activity with:
LiveActivity.startActivity(state, {
  deepLinkUrl: '/order',
})
```

### URL Scheme
The URL scheme is automatically taken from the `scheme` field in `app.json` or falls back to the `ios.bundleIdentifier`.
```

--------------------------------

### Handling Push Notification Tokens

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

APIs to subscribe to changes in push notification tokens for Live Activities. These are essential for enabling push-to-start functionality and receiving token updates.

```APIDOC
## addActivityPushToStartTokenListener

### Description
Subscribe to changes in the push to start token for starting live activities with push notifications.

### Method
`addActivityPushToStartTokenListener(listener: (event: ActivityPushToStartTokenReceivedEvent) => void): EventSubscription | undefined`
```

```APIDOC
## addActivityTokenListener

### Description
Subscribe to changes in the push notification token associated with Live Activities.

### Method
`addActivityTokenListener(listener: (event: ActivityTokenReceivedEvent) => void): EventSubscription | undefined`
```

--------------------------------

### Enable Push Notifications for Live Activity

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Add this configuration to your app.json or app.config.ts to enable push notification support for Live Activities. This feature is required for sending push notifications to manage Live Activities.

```json
{
  "enablePushNotifications": true
}
```

--------------------------------

### Configure expo-live-activity Plugin

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Add the config plugin to your app.json or app.config.js. For push notification support, include the 'enablePushNotifications' option.

```json
{
  "expo": {
    "plugins": ["expo-live-activity"]
  }
}
```

```json
{
  "expo": {
    "plugins": [
      [
        "expo-live-activity",
        {
          "enablePushNotifications": true
        }
      ]
    ]
  }
}
```

--------------------------------

### Listen for Live Activity Updates

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Subscribes to Live Activity lifecycle state changes. The `activityState` field indicates the current phase of the activity. Handles states like 'ended', 'dismissed', and 'stale' by updating UI or pushing fresh content.

```typescript
import * as LiveActivity from 'expo-live-activity'
import { useEffect } from 'react'

// ActivityState: 'active' | 'dismissed' | 'pending' | 'stale' | 'ended'

useEffect(() => {
  const subscription = LiveActivity.addActivityUpdatesListener(
    ({ activityID, activityName, activityState }) => {
      console.log(`[${activityName}] ${activityID} → ${activityState}`)

      if (activityState === 'ended' || activityState === 'dismissed') {
        // Clear stored activityId, update UI
        setActivityId(null)
      }
      if (activityState === 'stale') {
        // Content is outdated — push a fresh update
        LiveActivity.updateActivity(activityID, freshState)
      }
    }
  )
  return () => subscription?.remove()
}, [])
```

--------------------------------

### Activity Updates Listener

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

API to subscribe to changes in the Live Activity's state, allowing for real-time updates.

```APIDOC
## LiveActivity.addActivityUpdatesListener

### Description
Subscribes to changes in the Live Activity state. This is useful for updating the Live Activity with new information in real-time.

### Method
`LiveActivity.addActivityUpdatesListener(listener: (event: ActivityUpdateEvent) => void): EventSubscription`

### Event Object Structure
The handler receives an `ActivityUpdateEvent` object containing:
- `activityId`: Identifier for the Live Activity.
- `activityName`: Name of the Live Activity.
- `activityState`: The current state of the activity, which can be one of: `'active'`, `'dismissed'`, `'pending'`, `'stale'`, or `'ended'`.
```

--------------------------------

### Listen for Activity Push Token Updates

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Subscribes to per-activity push notification token updates. The token must be forwarded to your server to send ActivityKit push updates. Requires `enablePushNotifications: true` in the config plugin.

```typescript
import * as LiveActivity from 'expo-live-activity'
import { useEffect } from 'react'

useEffect(() => {
  const subscription = LiveActivity.addActivityTokenListener(
    ({ activityID, activityName, activityPushToken }) => {
      console.log('New push token for', activityName, ':', activityPushToken)
      // Send to your backend:
      fetch('https://api.example.com/live-activity/token', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ activityID, activityPushToken }),
      })
    }
  )
  return () => subscription?.remove()
}, [])
```

--------------------------------

### addActivityUpdatesListener

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Subscribes to Live Activity lifecycle state changes. The `activityState` field indicates the current phase of the activity.

```APIDOC
## addActivityUpdatesListener

### Description
Subscribes to Live Activity lifecycle state changes. The `activityState` field indicates the current phase of the activity.

### Parameters
#### Callback Function
- **listener** (function) - Required - A callback function that receives an object with `activityID`, `activityName`, and `activityState`.

### Activity State
Possible values for `activityState`: `'active' | 'dismissed' | 'pending' | 'stale' | 'ended'`

### Request Example
```typescript
const subscription = LiveActivity.addActivityUpdatesListener(
  ({ activityID, activityName, activityState }) => {
    console.log(`[${activityName}] ${activityID} → ${activityState}`)

    if (activityState === 'ended' || activityState === 'dismissed') {
      // Clear stored activityId, update UI
      setActivityId(null)
    }
    if (activityState === 'stale') {
      // Content is outdated — push a fresh update
      LiveActivity.updateActivity(activityID, freshState)
    }
  }
)

// To unsubscribe:
// subscription?.remove()
```
```

--------------------------------

### addActivityTokenListener

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Subscribes to per-activity push notification token updates. The token must be forwarded to your server to send ActivityKit push updates.

```APIDOC
## addActivityTokenListener

### Description
Subscribes to per-activity push notification token updates. The token must be forwarded to your server to send ActivityKit push updates. Requires `enablePushNotifications: true` in the config plugin.

### Parameters
#### Callback Function
- **listener** (function) - Required - A callback function that receives an object with `activityID`, `activityName`, and `activityPushToken`.

### Request Example
```typescript
const subscription = LiveActivity.addActivityTokenListener(
  ({ activityID, activityName, activityPushToken }) => {
    console.log('New push token for', activityName, ':', activityPushToken)
    // Send to your backend:
    fetch('https://api.example.com/live-activity/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ activityID, activityPushToken }),
    })
  }
)

// To unsubscribe:
// subscription?.remove()
```
```

--------------------------------

### stopActivity

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Ends a Live Activity immediately. The final state snapshot is shown as the dismissal view.

```APIDOC
## stopActivity

### Description
Ends a Live Activity immediately. The final `state` snapshot is shown as the dismissal view.

### Parameters
#### Path Parameters
- **activityId** (string) - Required - The ID of the Live Activity to stop.
- **finalState** (LiveActivity.LiveActivityState) - Required - The final state to display before dismissal.

### Request Example
```typescript
const finalState: LiveActivity.LiveActivityState = {
  title: 'Order Delivered!',
  subtitle: 'Enjoy your meal 🎉',
  progressBar: {
    progress: 1, // complete
  },
  imageName: 'delivered',
}

LiveActivity.stopActivity(activityId, finalState)
```
```

--------------------------------

### Import LiveActivity Module

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Import the necessary functionalities from the expo-live-activity module into your JavaScript or TypeScript files.

```javascript
import * as LiveActivity from 'expo-live-activity'
```

--------------------------------

### Update Live Activity with Remote Image

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

This TypeScript snippet shows how to update an existing Live Activity with a new remote image. The native layer handles downloading and caching.

```typescript
// Update with a new remote image
LiveActivity.updateActivity(activityId, {
  title: 'GOAL! 2–1',
  imageName: 'https://cdn.example.com/goal-celebration.png',
})
```

--------------------------------

### Configure expo-live-activity plugin

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Add the expo-live-activity plugin to your app.json or app.config.js. The `enablePushNotifications` option adds push-notification entitlements and enables push-token emission. `silentOnUnsupportedOS` prevents errors on iOS versions below 16.2.

```json
{
  "expo": {
    "plugins": [
      [
        "expo-live-activity",
        {
          "enablePushNotifications": true,
          "silentOnUnsupportedOS": false
        }
      ]
    ]
  }
}
```

--------------------------------

### updateActivity

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Updates the content state of a running Live Activity identified by its ID. All state fields except `title` are optional; omitted fields clear their previous value.

```APIDOC
## updateActivity

### Description
Updates the content state of a running Live Activity identified by its ID. All state fields except `title` are optional; omitted fields clear their previous value.

### Method
```typescript
LiveActivity.updateActivity(activityId: string, state: Partial<LiveActivityState>, relevanceScore?: number): void
```

### Parameters
#### Activity ID
- **activityId** (string) - Required - The ID of the Live Activity to update.

#### State Parameters
- **title** (string) - Required - The main title for the Live Activity.
- **subtitle** (string) - Optional - The subtitle for the Live Activity.
- **progressBar** (object) - Optional - Configuration for the progress bar.
  - **date** (number) - Optional - Countdown to an epoch timestamp in milliseconds.
  - **progress** (number) - Optional - Static progress bar value between 0.0 and 1.0.
  - **elapsedTimer** (object) - Optional - Configuration for an elapsed timer.
    - **startDate** (number) - Required - Epoch timestamp in milliseconds when the timer started.
  - **currentStep** (number) - Optional - The current step in a step-based progress bar.
  - **totalSteps** (number) - Optional - The total number of steps in a step-based progress bar.
- **imageName** (string) - Optional - The name of the image file in `assets/liveActivity/` for the main display.
- **dynamicIslandImageName** (string) - Optional - The name of the image file for the compact Dynamic Island display.
- **smallImageName** (string) - Optional - The name of the image file for Apple Watch / CarPlay.

#### Relevance Score
- **relevanceScore** (number) - Optional - A score from 0 to 1 indicating the relevance of the activity.

### Request Example
```typescript
import * as LiveActivity from 'expo-live-activity'

// Advance an order-tracking activity to show 75 % progress
const updatedState: LiveActivity.LiveActivityState = {
  title: 'Order #1042',
  subtitle: 'Out for delivery',
  progressBar: {
    progress: 0.75, // static progress bar, 0.0–1.0
  },
  imageName: 'courier',
  dynamicIslandImageName: 'courier-dot',
}

try {
  LiveActivity.updateActivity(activityId, updatedState, 0.9)
} catch (e) {
  console.error('Failed to update Live Activity:', e)
}

// Switch to an elapsed-timer progress bar (count-up)
LiveActivity.updateActivity(activityId, {
  title: 'Walk in Progress',
  subtitle: 'With Max the Dog',
  progressBar: {
    elapsedTimer: {
      startDate: Date.now() - 5 * 60 * 1000, // started 5 minutes ago
    },
  },
  imageName: 'dog',
})

// Switch to a step-based segmented progress bar
LiveActivity.updateActivity(activityId, {
  title: 'Order #1042',
  subtitle: 'Step 2 of 4',
  progressBar: {
    currentStep: 2,
    totalSteps: 4,
  },
})
```

### Response
This method does not return a value. Errors are thrown if the update fails.
```

--------------------------------

### Update Live Activity

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Updates an existing Live Activity identified by its ID with new state information and an optional relevance score.

```APIDOC
## updateActivity

### Description
Updates an existing Live Activity with new state information and an optional relevance score.

### Method Signature
`updateActivity(id: string, state: LiveActivityState, relevanceScore?: number)`

### Parameters
- **id** (string) - Required - The ID of the Live Activity to update.
- **state** (LiveActivityState) - Required - The updated state information for the Live Activity.
- **relevanceScore** (number) - Optional - A score between 0.0 and 1.0 that determines the activity's display order.
```

--------------------------------

### Update an Existing Live Activity

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Modify an ongoing Live Activity by providing its ID and the updated state. The relevance score can also be adjusted.

```javascript
LiveActivity.updateActivity(id, state, relevanceScore)
```

--------------------------------

### Stop Live Activity

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Terminates an ongoing Live Activity. Requires the activity's ID and the final state, along with an optional relevance score.

```APIDOC
## stopActivity

### Description
Terminates an ongoing Live Activity with the provided final state and an optional relevance score.

### Method Signature
`stopActivity(id: string, state: LiveActivityState, relevanceScore?: number)`

### Parameters
- **id** (string) - Required - The ID of the Live Activity to stop.
- **state** (LiveActivityState) - Required - The final state of the Live Activity.
- **relevanceScore** (number) - Optional - A score between 0.0 and 1.0 that determines the activity's display order.
```

--------------------------------

### Stop a Live Activity

Source: https://github.com/software-mansion-labs/expo-live-activity/blob/main/README.md

Terminate an ongoing Live Activity by providing its ID and the final state. The relevance score can also be updated upon stopping.

```javascript
LiveActivity.stopActivity(id, state, relevanceScore)
```

--------------------------------

### Update Live Activity content

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Modify the state of an existing Live Activity using its ID. Omitted fields will clear their previous values. Supports static progress bars, countdown timers, elapsed timers, and step-based progress.

```typescript
import * as LiveActivity from 'expo-live-activity'

// Advance an order-tracking activity to show 75 % progress
const updatedState: LiveActivity.LiveActivityState = {
  title: 'Order #1042',
  subtitle: 'Out for delivery',
  progressBar: {
    progress: 0.75, // static progress bar, 0.0–1.0
  },
  imageName: 'courier',
  dynamicIslandImageName: 'courier-dot',
}

try {
  LiveActivity.updateActivity(activityId, updatedState, 0.9)
} catch (e) {
  console.error('Failed to update Live Activity:', e)
}

// Switch to an elapsed-timer progress bar (count-up)
LiveActivity.updateActivity(activityId, {
  title: 'Walk in Progress',
  subtitle: 'With Max the Dog',
  progressBar: {
    elapsedTimer: {
      startDate: Date.now() - 5 * 60 * 1000, // started 5 minutes ago
    },
  },
  imageName: 'dog',
})

// Switch to a step-based segmented progress bar
LiveActivity.updateActivity(activityId, {
  title: 'Order #1042',
  subtitle: 'Step 2 of 4',
  progressBar: {
    currentStep: 2,
    totalSteps: 4,
  },
})
```

--------------------------------

### Stop a Live Activity

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

Ends a Live Activity immediately. The final state snapshot is displayed as the dismissal view. Ensure the `finalState` object accurately reflects the activity's conclusion.

```typescript
import * as LiveActivity from 'expo-live-activity'

const finalState: LiveActivity.LiveActivityState = {
  title: 'Order Delivered!',
  subtitle: 'Enjoy your meal 🎉',
  progressBar: {
    progress: 1, // complete
  },
  imageName: 'delivered',
}

try {
  LiveActivity.stopActivity(activityId, finalState)
  console.log('Live Activity stopped')
} catch (e) {
  console.error('Failed to stop Live Activity:', e)
}
```

--------------------------------

### Update Live Activity via Push Notification

Source: https://context7.com/software-mansion-labs/expo-live-activity/llms.txt

This JSON payload is used to update an existing Live Activity via APNs. It only requires the 'event' set to 'update' and the 'content-state' to be modified.

```json
{
  "aps": {
    "event": "update",
    "timestamp": 1754063621319,
    "content-state": {
      "title": "Order #1042",
      "subtitle": "Out for delivery",
      "timerEndDateInMilliseconds": 1754064245000,
      "imageName": "courier",
      "dynamicIslandImageName": "courier-dot"
    }
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.