Voltra

https://www.use-voltra.dev
Admin
Voltra enables developers to build dynamic iOS Live Activities and interact with the Dynamic Island...
Tokens:29,402
Snippets:215
Trust Score:5.2
Update:8 months ago
Show doc for...
Tokens:
Raw
### Create First Voltra Live Activity (TypeScript/React Native)

Source: https://www.use-voltra.dev/getting-started/quick-start

A React Native component demonstrating how to create a basic 'Hello World' live activity using Voltra. It utilizes Voltra's UI components and the startLiveActivity function to display content on the iOS lock screen.

```tsx
import React from 'react'
import { startLiveActivity } from 'voltra/client'
import { Voltra } from 'voltra'

function HelloWorldActivity() {
  const activityUI = (
    <Voltra.VStack style={{ padding: 20, borderRadius: 18, backgroundColor: '#007AFF' }}>
      <Voltra.Text style={{ color: 'white', fontSize: 24, fontWeight: 'bold' }}>Hello World from Voltra!</Voltra.Text>
      <Voltra.Text style={{ color: 'white', fontSize: 16, marginTop: 8 }}>Your first live activity</Voltra.Text>
    </Voltra.VStack>
  )

  const startActivity = async () => {
    await startLiveActivity({
      lockScreen: activityUI,
    })
  }

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <TouchableOpacity onPress={startActivity} style={{ padding: 20, backgroundColor: '#007AFF', borderRadius: 10 }}>
        <Text style={{ color: 'white', fontSize: 18 }}>Start Live Activity</Text>
      </TouchableOpacity>
    </View>
  )
}

```

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

### Regenerate Native Project with Expo Prebuild (CLI)

Source: https://www.use-voltra.dev/getting-started/quick-start

Commands to regenerate your Expo native project and install Voltra's native dependencies. Supports npm, yarn, pnpm, and bun package managers.

```bash
npx expo prebuild --platform ios
```

```bash
yarn dlx expo prebuild --platform ios
```

```bash
pnpm dlx expo prebuild --platform ios
```

```bash
bunx expo prebuild --platform ios
```

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

### Start Live Activity

Source: https://www.use-voltra.dev/development/managing-live-activities-locally

Initiates and displays a new Live Activity with specified UI variants and configuration options.

```APIDOC
## POST /live-activities/start

### Description
Starts a new Live Activity with initial content and configuration.

### Method
POST

### Endpoint
/live-activities/start

### Parameters
#### Request Body
- **variants** (object) - Required - Defines the UI for different display contexts (lockScreen, compact, minimal, expanded).
- **options** (object) - Optional - Configuration options for the Live Activity.
  - **activityId** (string) - Optional - An identifier for re-binding on app restart.
  - **deepLinkUrl** (string) - Optional - URL to open when the Live Activity is tapped.
  - **dismissalPolicy** (object) - Optional - Policy for dismissing the activity.
    - **after** (number) - Optional - Number of seconds after which to dismiss.
  - **staleDate** (number) - Optional - Timestamp for when the activity becomes stale.
  - **relevanceScore** (number) - Optional - Score indicating the relevance of the activity.

### Request Example
```json
{
  "variants": {
    "lockScreen": "<VStack style=\"padding: 16; border-radius: 18; background-color: #101828\">
      <Text style=\"color: #F8FAFC; font-size: 18; font-weight: 600\">
        Order Confirmed
      </Text>
      <Text style=\"color: #94A3B8; font-size: 12; margin-top: 8\">
        Your order is being prepared
      </Text>
    </VStack>",
    "compact": "<Text>Order confirmed</Text>",
    "minimal": "<Symbol name=\"checkmark.circle.fill\" tintColor=\"#10B981" />",
    "expanded": "<VStack style=\"padding: 16\">
      <Text style=\"font-size: 16; font-weight: 600\">Order Confirmed</Text>
      <Text style=\"font-size: 12; color: #6B7280; margin-top: 4\">
        Your order is being prepared
      </Text>
    </VStack>"
  },
  "options": {
    "activityId": "order-123",
    "deepLinkUrl": "myapp://order/123",
    "dismissalPolicy": {
      "after": 30
    },
    "staleDate": 1700000000000,
    "relevanceScore": 0.8
  }
}
```

### Response
#### Success Response (200)
- **activityId** (string) - The ID of the newly created Live Activity.

#### Response Example
```json
{
  "activityId": "generated-activity-id-12345"
}
```
```

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

### Combine Voltra Live Activity Configuration Options (TypeScript)

Source: https://www.use-voltra.dev/api/configuration

Demonstrates how to use multiple Voltra Live Activity configuration options simultaneously when starting an activity. This example combines dismissal policy, stale date, and relevance score for comprehensive control.

```typescript
await startLiveActivity(variants, {
  dismissalPolicy: { after: 30 },
  staleDate: Date.now() + 2 * 60 * 60 * 1000, // 2 hours
  relevanceScore: 0.7,
})
```

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

### Listen for Push-to-Start Tokens (TypeScript/React)

Source: https://www.use-voltra.dev/development/server-side-updates

Listens for push-to-start tokens using Voltra's client library. This token is used to start new Live Activities remotely. It requires a `useEffect` hook for subscription management and cleanup.

```typescript
useEffect(() => {
  const subscription = addVoltraListener('activityPushToStartTokenReceived', ({ pushToStartToken, type }) => {
    // Send the token to your server for starting new Live Activities
    sendTokenToServer({
      token: pushToStartToken,
      type: 'start',
    })
  })

  return () => {
    subscription.remove()
  }
}, [])
```

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

### Start Live Activity with JSX (Client-side)

Source: https://www.use-voltra.dev/getting-started/introduction

This snippet demonstrates how to initiate a live activity on the client-side using Voltra's JSX components. It requires the 'voltra/client' module and defines the UI for the lock screen.

```tsx
import { startLiveActivity } from 'voltra/client'
import { Voltra } from 'voltra'

const activityUI = (
  <Voltra.VStack style={{ padding: 16, borderRadius: 18, backgroundColor: '#101828' }}>
    <Voltra.Symbol name="car.fill" type="hierarchical" scale="large" tintColor="#38BDF8" />
    <Voltra.Text style={{ color: '#F8FAFC', fontSize: 18, fontWeight: '600' }}>Driver en route</Voltra.Text>
    <Voltra.Text style={{ color: '#94A3B8', fontSize: 12, marginTop: 8 }}>Building A · Lobby pickup</Voltra.Text>
    <Voltra.Button title="Contact driver" id="contact-driver" style={{ marginTop: 12 }} />
  </Voltra.VStack>
)

// Start the live activity
await startLiveActivity({
  lockScreen: activityUI,
})
```

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

### Integrate Live Activity with useLiveActivity Hook (TypeScript)

Source: https://www.use-voltra.dev/development/developing-live-activities

This example demonstrates integrating Live Activities into a React application using Voltra's `useLiveActivity` hook. It handles starting, updating, and ending activities, with options for auto-start and auto-update.

```typescript
import { useLiveActivity } from 'voltra/client'
import { Voltra } from 'voltra'

function OrderLiveActivity({ orderId, status }) {
  const variants = {
    lockScreen: (
      <Voltra.VStack style={{ padding: 16, borderRadius: 18, backgroundColor: '#101828' }}>
        <Voltra.Text style={{ color: '#F8FAFC', fontSize: 18, fontWeight: '600' }}>
          {status === 'confirmed' ? 'Order Confirmed' : 'Order Ready'}
        </Voltra.Text>
        <Voltra.Text style={{ color: '#94A3B8', fontSize: 12, marginTop: 8 }}>
          {status === 'confirmed' ? 'Your order is being prepared' : 'Your order is ready for pickup'}
        </Voltra.Text>
        {status === 'ready' && (
          <Voltra.Button onPress="pickup-order" style={{ marginTop: 12 }}>
            I'm Here
          </Voltra.Button>
        )}
      </Voltra.VStack>
    ),
  }

  const { start, update, end, isActive } = useLiveActivity(variants, {
    activityName: `order-${orderId}`,
    autoStart: true, // Automatically start when component mounts
    autoUpdate: true, // Automatically update when variants change
    deepLinkUrl: `myapp://order/${orderId}`,
  })

  // Manual control if needed
  const handleCancelOrder = async () => {
    await end()
  }

  return (
    <View>
      <Text>Live Activity: {isActive ? 'Active' : 'Inactive'}</Text>
      <Button onPress={handleCancelOrder} title="Cancel Order" />
    </View>
  )
}
```

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

### Obtain Push-to-Start Tokens with Voltra (iOS 17.2+)

Source: https://www.use-voltra.dev/development/events

Subscribes to 'activityPushToStartTokenReceived' events to get tokens for remotely starting Live Activities (iOS 17.2+). This functionality relies on the 'voltra/client' module. The event object includes a 'pushToStartToken' that needs to be sent to your server. The listener should be removed using 'subscription.remove()' when no longer needed.

```typescript
import { addVoltraListener } from 'voltra/client'

const subscription = addVoltraListener('activityPushToStartTokenReceived', (event) => {
  console.log('Push-to-start token:', event.pushToStartToken)

  // Send the token to your server
  sendTokenToServer({
    pushToStartToken: event.pushToStartToken,
  })
})

subscription.remove()
```

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

### Configure Voltra Expo Plugin (JSON)

Source: https://www.use-voltra.dev/getting-started/quick-start

This JSON configuration snippet shows how to add the Voltra plugin to your Expo project's app.json or app.config.js file. It includes essential options like groupIdentifier and enablePushNotifications.

```json
{
  "expo": {
    "plugins": [
      [
        "voltra",
        {
          "groupIdentifier": "group.your.bundle.identifier",
          "enablePushNotifications": true
        }
      ]
    ]
  }
}
```

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

### Start a Live Activity with Voltra

Source: https://www.use-voltra.dev/development/managing-live-activities-locally

Initiates and displays a new Live Activity using the `startLiveActivity` function. It requires UI variants for different display contexts and accepts optional configuration like activity ID, deep link URL, dismissal policy, stale date, and relevance score. Returns a promise resolving to the activity ID.

```typescript
import { startLiveActivity } from 'voltra/client'
import { Voltra } from 'voltra'

const variants = {
  lockScreen: (
    <Voltra.VStack style={{ padding: 16, borderRadius: 18, backgroundColor: '#101828' }}>
      <Voltra.Text style={{ color: '#F8FAFC', fontSize: 18, fontWeight: '600' }}>
        Order Confirmed
      </Voltra.Text>
      <Voltra.Text style={{ color: '#94A3B8', fontSize: 12, marginTop: 8 }}>
        Your order is being prepared
      </Voltra.Text>
    </Voltra.VStack>
  ),
  // Define compact, minimal, and expanded variants for Dynamic Island
  compact: <Voltra.Text>Order confirmed</Voltra.Text>,
  minimal: <Voltra.Symbol name="checkmark.circle.fill" tintColor="#10B981" />,
  expanded: (
    <Voltra.VStack style={{ padding: 16 }}>
      <Voltra.Text style={{ fontSize: 16, fontWeight: '600' }}>Order Confirmed</Voltra.Text>
      <Voltra.Text style={{ fontSize: 12, color: '#6B7280', marginTop: 4 }}>
        Your order is being prepared
      </Voltra.Text>
    </Voltra.VStack>
  ),
}

const activityId = await startLiveActivity(variants, {
  activityId: 'order-123', // Optional: for re-binding on app restart
  deepLinkUrl: 'myapp://order/123', // Optional: URL to open when tapped
  dismissalPolicy: { after: 30 },
  staleDate: Date.now() + 60 * 60 * 1000, // 1 hour
  relevanceScore: 0.8,
})
```

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

### Expo Config Plugin Setup

Source: https://www.use-voltra.dev/development/server-side-updates

Configure the Voltra plugin in your app.json or app.config.js to enable server-side updates via push notifications. Includes minimal and full configuration options.

```APIDOC
## Expo Config Plugin Setup

Configure the Voltra plugin in your `app.json` or `app.config.js` to enable server-side updates via push notifications.

### Minimal configuration (push notifications only):

```json
{
  "expo": {
    "plugins": [
      [
        "voltra",
        {
          "enablePushNotifications": true
        }
      ]
    ]
  }
}
```

### Full configuration (with App Groups for event forwarding and shared images):

```json
{
  "expo": {
    "plugins": [
      [
        "voltra",
        {
          "enablePushNotifications": true,
          "groupIdentifier": "group.your.app.voltraui",
          "deploymentTarget": "18.0"
        }
      ]
    ]
  }
}
```

**Note:** The `groupIdentifier` is optional and only needed for forwarding component events or sharing images between your app and the extension. Push notifications function without it.
```

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

### Import and Use Voltra Components in React

Source: https://www.use-voltra.dev/components/overview

Demonstrates how to import the Voltra namespace and use basic components like VStack, Text, and Button within a React component for Live Activities. This requires the 'voltra' package to be installed.

```tsx
import Voltra from 'voltra'

const MyComponent = () => {
  // Use any component
  return (
    <Voltra.VStack spacing={8}>
      <Voltra.Text>Hello Live Activity!</Voltra.Text>
      <Voltra.Button title="Tap me" />
    </Voltra.VStack>
  )
}
```

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

### Configure Deep Linking for Live Activity Taps (TypeScript)

Source: https://www.use-voltra.dev/development/interactions

Shows how to configure a deep link URL when starting a Live Activity using the `useLiveActivity` hook. This allows your app to be launched or brought to the foreground when a user taps on the Live Activity view itself, enabling navigation to specific content or actions.

```typescript
import { useLiveActivity } from 'voltra/client'

const { start } = useLiveActivity(
  {
    lockScreen: <YourComponent />,
  },
  {
    activityName: 'activity-detail',
    deepLinkUrl: '/voltraui/activity-detail',
  }
)
```

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

### Configure Live Activity Dismissal Policy (TypeScript)

Source: https://www.use-voltra.dev/api/configuration

Demonstrates how to set the dismissal policy for Voltra Live Activities. This controls when a Live Activity is automatically dismissed after it ends, either immediately or after a specified delay. It applies to starting, updating, and stopping activities.

```typescript
import { startLiveActivity } from 'voltra/client'

await startLiveActivity(variants, {
  dismissalPolicy: 'immediate', // or omit for default
})
```

```typescript
await startLiveActivity(variants, {
  dismissalPolicy: { after: 30 },
})
```

```typescript
import { updateLiveActivity } from 'voltra/client'

await updateLiveActivity(activityId, variants, {
  dismissalPolicy: { after: 60 },
})
```

```typescript
import { stopLiveActivity } from 'voltra/client'

await stopLiveActivity(activityId, {
  dismissalPolicy: { after: 10 },
})
```

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

### Display Preloaded Images using Asset Name in TypeScript

Source: https://www.use-voltra.dev/development/images

This example demonstrates how to use Voltra's image preloading for dynamic images from remote URLs. Once preloaded and cached in App Group shared storage, images are referenced using the 'assetName' property within the Voltra.Image component's source object, suitable for Live Activities.

```typescript
import { Voltra } from 'voltra'

function MusicPlayerLiveActivity({ song }) {
  return {
    lockScreen: (
      <Voltra.VStack style={{ padding: 16 }}>
        <Voltra.Image
          source={{ assetName: 'current-song-artwork' }}
          style={{ width: 60, height: 60, borderRadius: 8 }}
        />
        <Voltra.Text style={{ fontSize: 16, fontWeight: 'bold', marginTop: 8 }}>
          {song.title}
        </Voltra.Text>
        <Voltra.Text style={{ color: '#666', fontSize: 14 }}>
          {song.artist}
        </Voltra.Text>
      </Voltra.VStack>
    )
  }
}
```

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

### Handle Voltra Live Activity Interactions in TypeScript

Source: https://www.use-voltra.dev/development/interactions

This TypeScript code snippet demonstrates how to initialize a Voltra live activity with interactive UI elements and listen for user interactions. It uses the `useLiveActivity` hook and `addVoltraListener` to manage the activity's state and respond to button taps or toggle changes. Ensure Voltra client library is installed.

```typescript
import { useEffect } from 'react'
import { useLiveActivity } from 'voltra/client'
import { Voltra } from 'voltra'
import { addVoltraListener } from 'voltra/client'

function MyLiveActivity() {
  const { start, update } = useLiveActivity(
    {
      lockScreen: (
        <Voltra.VStack>
          <Voltra.Text>Music Player</Voltra.Text>
          <Voltra.Button title="Play" id="play-button" />
          <Voltra.Button title="Pause" id="pause-button" />
          <Voltra.Toggle title="Shuffle" id="shuffle-toggle" />
        </Voltra.VStack>
      ),
    },
    {
      activityName: 'music-player',
      deepLinkUrl: '/music-player',
    }
  )

  useEffect(() => {
    const subscription = addVoltraListener('interaction', (event) => {
      switch (event.identifier) {
        case 'play-button':
          // Start playback
          console.log('Play button tapped')
          break
        case 'pause-button':
          // Pause playback
          console.log('Pause button tapped')
          break
        case 'shuffle-toggle':
          // Toggle shuffle mode
          console.log('Shuffle toggled')
          break
      }
    })

    return () => subscription.remove()
  }, [])

  return null
}
```

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

### Live Activity Payload Structures (JSON)

Source: https://www.use-voltra.dev/development/server-side-updates

Defines the JSON payload structures for updating an existing Live Activity and for starting a Live Activity remotely using push-to-start (iOS 17.2+). Key fields include event type, content state, and attributes for push-to-start.

```json
{
  "aps": {
    "event": "update",
    "content-state": {
      "uiJsonData": "{\"lockScreen\":{\"type\":\"VStack\",\"children\":{\"type\":\"Text\",\"children\":\"Hello\",\"props\":{}}},\"props\":{}}"
    },
    "timestamp": 1764145755
  }
}
```

```json
{
  "aps": {
    "event": "start",
    "content-state": {
      "uiJsonData": "{\"lockScreen\":{\"type\":\"VStack\",\"children\":{\"type\":\"Text\",\"children\":\"Hello\",\"props\":{}}},\"props\":{}}"
    },
    "attributes-type": "VoltraAttributes",
    "attributes": {
      "name": "some-name",
      "deepLinkUrl": "app://some-deep-link-url"
    },
    "timestamp": 1764145755
  }
}
```

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

### Xcode Configuration Steps

Source: https://www.use-voltra.dev/development/server-side-updates

Manual steps required in Xcode for push notification integration, including provisioning profiles, APNs certificates, and capabilities.

```APIDOC
## Xcode Configuration

The Voltra config plugin automates most Xcode setup. Complete these manual steps:

1.  **Provisioning Profiles:** Ensure your app has provisioning profiles with push notification capabilities enabled.
2.  **APNs Certificates:** Set up APNs authentication certificates or keys in your Apple Developer account for sending push notifications.
3.  **Capabilities:** Verify that the Push Notifications capability is enabled in your app's target settings in Xcode.

Refer to [Apple's official push notification documentation](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server) for detailed iOS setup.
```

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

### Implement Widget Initial State Export

Source: https://www.use-voltra.dev/development/widget-pre-rendering

This TypeScript code demonstrates how to create a file at the specified `initialStatePath`. It exports a `WidgetVariants` object containing the initial UI content for different widget sizes, using Voltra components.

```typescript
import { Voltra, type WidgetVariants } from 'voltra'

const initialState: WidgetVariants = {
  systemSmall: <Voltra.Text>Content</Voltra.Text>,
  systemMedium: <Voltra.Text>Content</Voltra.Text>,
  systemLarge: <Voltra.Text>Content</Voltra.Text>,
}

export default initialState
```

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

### Live Activity Payload Structures

Source: https://www.use-voltra.dev/development/server-side-updates

Defines the JSON payload structures for updating existing Live Activities and starting new ones remotely via push notifications.

```APIDOC
## Live Activity Payload Structures

### Updating an Existing Live Activity

This payload is used to send updates to an already running Live Activity.

#### Request Body

```json
{
  "aps": {
    "event": "update",
    "content-state": {
      "uiJsonData": "{\"lockScreen\":{\"type\":\"VStack\",\"children\":{\"type\":\"Text\",\"children\":\"Hello\",\"props\":{}}},\"props\":{}}"}
    },
    "timestamp": 1764145755
  }
}
```

### Starting a Live Activity Remotely (iOS 17.2+)

This payload is used to initiate a new Live Activity remotely using the push-to-start feature.

#### Request Body

```json
{
  "aps": {
    "event": "start",
    "content-state": {
      "uiJsonData": "{\"lockScreen\":{\"type\":\"VStack\",\"children\":{\"type\":\"Text\",\"children\":\"Hello\",\"props\":{}}},\"props\":{}}"}
    },
    "attributes-type": "VoltraAttributes",
    "attributes": {
      "name": "some-name",
      "deepLinkUrl": "app://some-deep-link-url"
    },
    "timestamp": 1764145755
  }
}
```

### Key Fields

*   **`aps.event`** (string) - Required - Set to `"update"` for updating an existing Live Activity, or `"start"` for push-to-start (iOS 17.2+).
*   **`aps.content-state.uiJsonData`** (string) - Required - The JSON string returned by `renderLiveActivityToString`, embedded as a string value.
*   **`aps.timestamp`** (integer) - Required - Unix timestamp in seconds.
*   **`aps.attributes-type`** (string) - Required for push-to-start - Must be `"VoltraAttributes"`.
*   **`aps.attributes.name`** (string) - Required for push-to-start - A user-defined name for the activity (can be any string).

:::danger
ActivityKit enforces a strict payload size limit of approximately 4 KB. Keep your UI JSON minimal to stay within this limit. Avoid deeply nested component trees and excessive styling to ensure your payloads fit within the constraint.
:::

```

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

### Live Activity Configuration Options

Source: https://www.use-voltra.dev/development/managing-live-activities-locally

Details on configuring Live Activities using dismissal policies, stale dates, and relevance scores.

```APIDOC
## Configuration Options

Voltra provides configuration options for `startLiveActivity()`, `updateLiveActivity()`, and `stopLiveActivity()` to control Live Activity behavior.

### Dismissal Policy

Controls how Live Activities behave after they end.

**Options:**
* `'immediate'` (default): Live Activity is dismissed immediately when it ends.
* `{ after: number }`: Live Activity remains visible for the specified number of seconds after ending, then automatically dismisses.

**Examples:**
```typescript
// Immediate dismissal (default)
await startLiveActivity(variants, {
  dismissalPolicy: 'immediate',
})

// Keep visible for 30 seconds after ending
await startLiveActivity(variants, {
  dismissalPolicy: { after: 30 },
})

// Update dismissal timing for active Live Activities
await updateLiveActivity(activityId, variants, {
  dismissalPolicy: { after: 300 }, // 5 minutes
})

// Set dismissal timing when stopping
await stopLiveActivity(activityId, {
  dismissalPolicy: { after: 10 },
})
```

### Stale Date

Specifies when a Live Activity should be considered stale and automatically dismissed by iOS.

**Parameters:**
* `staleDate` (Date | number): A timestamp or Date object indicating when the activity should be considered stale.

**Examples:**
```typescript
// Dismiss after 1 hour
await startLiveActivity(variants, {
  staleDate: Date.now() + 60 * 60 * 1000,
})

// Dismiss after 2 hours
await startLiveActivity(variants, {
  staleDate: Date.now() + 2 * 60 * 60 * 1000,
})
```

**Note:** If you provide a `staleDate` in the past, it will be ignored.

### Relevance Score

Helps iOS prioritize which Live Activities to display when space is limited.

**Parameters:**
* `relevanceScore` (number): A score between 0.0 and 1.0 (default: 0.0).

**Examples:**
```typescript
// High priority (e.g., active delivery)
await startLiveActivity(variants, {
  relevanceScore: 0.8,
})

// Low priority (e.g., background task)
await startLiveActivity(variants, {
  relevanceScore: 0.2,
})
```
```

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

### Configure Widget Pre-rendering in app.json

Source: https://www.use-voltra.dev/development/widget-pre-rendering

This JSON snippet shows how to add the `initialStatePath` to your widget configuration within the `app.json` file for Voltra integration. It specifies the path to the file containing the initial state for the widget.

```json
{
  "expo": {
    "plugins": [
      [
        "voltra",
        {
          "widgets": [
            {
              "id": "weather",
              "displayName": "Weather Widget",
              "description": "Shows current weather conditions",
              "supportedFamilies": ["systemSmall", "systemMedium", "systemLarge"],
              "initialStatePath": "./widgets/weather-initial.tsx"
            }
          ]
        }
      ]
    ]
  }
}
```

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

### Platform Detection and Ending Live Activities

Source: https://www.use-voltra.dev/development/managing-live-activities-locally

APIs for detecting platform support (Liquid Glass, headless launch) and for ending all active Live Activities.

```APIDOC
## Platform Detection

### Description
Check if the current device supports Liquid Glass (iOS 26+) or if the app was launched in a headless state (e.g., from a Live Activity interaction).

### Method
`isGlassSupported()`
`isHeadless()`

### Endpoint
N/A (Client-side functions)

### Parameters
None

### Request Example
```typescript
import { isGlassSupported, isHeadless } from 'voltra/client'

if (isGlassSupported()) {
  // Use Liquid Glass features
}

if (isHeadless()) {
  // App was launched in background
}
```

### Response
- `isGlassSupported()`: boolean - True if Liquid Glass is supported, false otherwise.
- `isHeadless()`: boolean - True if the app was launched in a headless state, false otherwise.

## Ending all Live Activities

### Description
Immediately end all active Live Activities in your application. Useful for cleanup or logout scenarios.

### Method
`endAllLiveActivities()`

### Endpoint
N/A (Client-side function)

### Parameters
None

### Request Example
```typescript
import { endAllLiveActivities } from 'voltra/client'

await endAllLiveActivities()
```

### Response
This function performs an action and does not return a specific value upon success. It may throw an error if the operation fails.
```

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

### Handling Background Execution

Source: https://www.use-voltra.dev/development/server-side-updates

Guidance on detecting and handling background execution scenarios, particularly for Live Activity token refreshes.

```APIDOC
## Handling Background Execution

When Live Activity tokens change or require refreshing, iOS may launch your app in the background. You have a limited time (around 30 seconds) to process these events before the background process may be suspended or terminated.

### Detecting Background Execution

Use the `isHeadless()` function to determine if your application is running in a background or headless state.

#### Example Usage

```typescript
import { isHeadless } from 'voltra/client';

// Place this check early in your application's entry point or root component
if (isHeadless()) {
  // App is running in background/headless mode (e.g., for token refresh)
  console.log('App launched in headless mode for token refresh');
  // Add logic here to handle background events, like fetching and sending updated tokens.
} else {
  // App is running in the foreground
  console.log('App launched in foreground');
  // Add foreground-specific logic.
}
```

### Background Execution Considerations

*   Ensure your background task is efficient and completes within the allotted time.
*   Communicate necessary token updates to your server promptly.
*   Handle potential errors gracefully within the background execution context.
```

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

### Apply Google Font to Voltra Text Component

Source: https://www.use-voltra.dev/development/styling

This React Native TypeScript example demonstrates applying a Google Font, previously configured via `expo-font`, to a Voltra Text component. The `fontFamily` style property is set to the font's PostScript name, enabling its use within the application.

```tsx
<Voltra.Text style={{ fontFamily: 'Inter_400Regular' }}>
  Text using Google Font
</Voltra.Text>
```

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

### Specify Font Weights with Custom Fonts in Voltra

Source: https://www.use-voltra.dev/development/styling

This example illustrates how to handle different font weights when using custom fonts with Voltra. Since `fontWeight` is ignored, you must add separate font files for each weight (e.g., Regular, Bold) and specify their complete PostScript names in the `fontFamily` style property.

```tsx
// Regular weight
<Voltra.Text style={{ fontFamily: 'Inter-Regular' }}>
  Regular Text
</Voltra.Text>

// Bold weight
<Voltra.Text style={{ fontFamily: 'Inter-Bold' }}>
  Bold Text
</Voltra.Text>
```

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

### Apply Custom Font to Voltra Text Component

Source: https://www.use-voltra.dev/development/styling

This React Native TypeScript example demonstrates how to apply a custom font to a Voltra Text component using the `fontFamily` style property. The `fontFamily` value should match the font's PostScript name, not its file name. Font size and color are also shown.

```tsx
import { Voltra } from 'voltra'

const element = (
  <Voltra.Text
    style={{
      fontFamily: 'CustomFontName',
      fontSize: 20,
      color: '#FFFFFF',
    }}
  >
    Text with Custom Font
  </Voltra.Text>
)
```

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

### Reference Build-Time Copied Assets in JSX

Source: https://www.use-voltra.dev/development/images

Images placed in the `/assets/voltra/` directory are automatically copied to the iOS extension bundle during build. These images, validated to be under 4KB, can be referenced in JSX using their asset name via the 'assetName' property in the Voltra.Image component's source object.

```tsx
<Voltra.Image source={{ assetName: 'logo.png' }} />
<Voltra.Image source={{ assetName: 'icon-star.png' }} />
```

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

### Reference Preloaded Image in Live Activity (TypeScript)

Source: https://www.use-voltra.dev/development/image-preloading

Demonstrates how to use a preloaded image within a Live Activity component using the `assetName` property. This assumes the image has already been preloaded and its `key` matches the `assetName` provided.

```typescript
import { Voltra } from 'voltra';

function MusicPlayerLiveActivity({
  song,
}: {
  song: {
    title: string;
    artist: string;
  };
}) {
  return {
    lockScreen: (
      <Voltra.VStack style={{ padding: 16 }}>
        <Voltra.Image
          source={{ assetName: 'current-song-artwork' }}
          style={{ width: 60, height: 60, borderRadius: 8 }}
        />
        <Voltra.Text style={{ fontSize: 16, fontWeight: 'bold', marginTop: 8 }}>
          {song.title}
        </Voltra.Text>
        <Voltra.Text style={{ color: '#666', fontSize: 14 }}>
          {song.artist}
        </Voltra.Text>
      </Voltra.VStack>
    ),
  };
}
```

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

### Define Home Screen Widget Configuration

Source: https://www.use-voltra.dev/api/plugin-configuration

This JSON object outlines the configuration for a Home Screen widget, specifying its unique ID, display name, description, supported sizes, and the path to its initial state file.

```json
{
  "widgets": [
    {
      "id": "weather",
      "displayName": "Weather Widget",
      "description": "Current weather conditions",
      "supportedFamilies": ["systemSmall", "systemMedium", "systemLarge"],
      "initialStatePath": "./widgets/weather-initial.tsx"
    }
  ]
}
```

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

### Display SF Symbols with Configuration

Source: https://www.use-voltra.dev/components/visual

Shows SF Symbols with options for rendering type, scale, weight, size, tint color, and animation. Requires valid SF Symbol names and configuration parameters.

```tsx
// Example with monochrome symbol
<Voltra.Symbol name="heart.fill" type="monochrome" weight="bold" tintColor="#FF0000" />

// Example with palette symbol
<Voltra.Symbol name="circle.lefthalf.filled" type="palette" colors="red|blue" scale="large" />
```

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

### Receive Activity Push Tokens with Voltra

Source: https://www.use-voltra.dev/development/events

Listens for 'activityTokenReceived' events from Voltra to obtain push tokens for server-side updates. This requires the 'voltra/client' module. The listener is provided with an event object containing 'activityName' and 'pushToken', which should be sent to your server. Ensure to call 'subscription.remove()' to clean up the listener.

```typescript
import { addVoltraListener } from 'voltra/client'

const subscription = addVoltraListener('activityTokenReceived', (event) => {
  console.log('Activity name:', event.activityName)
  console.log('Push token:', event.pushToken)

  // Send the token to your server
  sendTokenToServer({
    activityName: event.activityName,
    pushToken: event.pushToken,
  })
})

subscription.remove()
```

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

### Handle User Interactions in Live Activities with Voltra

Source: https://www.use-voltra.dev/development/events

Listens for 'interaction' events triggered by user actions on Live Activity components like buttons or toggles. This uses the 'voltra/client' module and leverages Apple's AppIntents framework. The listener receives an event with 'identifier' and 'payload' for handling specific interactions. Remember to unsubscribe using 'subscription.remove()'.

```typescript
import { addVoltraListener } from 'voltra/client'

const subscription = addVoltraListener('interaction', (event) => {
  console.log('Component interacted:', event.identifier)
  console.log('Payload:', event.payload)

  // Handle the interaction based on the identifier
  if (event.identifier === 'contact-driver') {
    // Open contact screen
  } else if (event.identifier === 'notifications-toggle') {
    // Handle toggle state change
  }
})

subscription.remove()
```

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

### Configure Voltra Expo Plugin with Live Activity and Widgets

Source: https://www.use-voltra.dev/api/plugin-configuration

This JSON configuration sets up the Voltra Expo plugin, defining settings for Live Activities such as group identifiers and target names, and configuring Home Screen widgets with their properties and initial states.

```json
{
  "expo": {
    "plugins": [
      [
        "voltra",
        {
          "groupIdentifier": "group.your.bundle.identifier",
          "enablePushNotifications": true,
          "deploymentTarget": "18.0",
          "targetName": "MyAppLiveActivity",
          "widgets": [
            {
              "id": "weather",
              "displayName": "Weather Widget",
              "description": "Shows current weather conditions",
              "supportedFamilies": ["systemSmall", "systemMedium", "systemLarge"],
              "initialStatePath": "./widgets/weather-initial.tsx"
            }
          ]
        }
      ]
    ]
  }
}
```

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

### Error Handling for Image Preloading (TypeScript)

Source: https://www.use-voltra.dev/development/image-preloading

Illustrates how to handle potential errors during the image preloading process using the `preloadImages` function. It shows how to check the `failed` array in the result for specific error messages and conditionally reload Live Activities.

```typescript
const result = await preloadImages([
  { url: 'https://example.com/large-image.jpg', key: 'big-image' },
  { url: 'https://invalid-url.com/image.jpg', key: 'broken-url' },
]);

// Handle results
if (result.failed.length > 0) {
  result.failed.forEach(({ key, error }) => {
    console.error(`Failed to preload ${key}: ${error}`);
  });
}

// Only proceed if all images succeeded
if (result.succeeded.length === 2) {
  await reloadLiveActivities();
}
```

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

### Detect Voltra Platform Support (TypeScript)

Source: https://www.use-voltra.dev/development/managing-live-activities-locally

Checks if the current device supports Liquid Glass features or if the app was launched in a background state. This is useful for conditionally enabling platform-specific functionalities.

```typescript
import { isGlassSupported, isHeadless } from 'voltra/client'

// Check if the device supports Liquid Glass (iOS 26+)
if (isGlassSupported()) {
  // Use Liquid Glass features
}

// Check if app was launched in background
if (isHeadless()) {
  // App was launched in background (e.g., from Live Activity interaction)
  // Perform background tasks without UI
}
```

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

### Image Preloading API

Source: https://www.use-voltra.dev/development/image-preloading

This section details the core functions for preloading, reloading, and clearing images used in Live Activities.

```APIDOC
## POST /api/images/preload

### Description
Downloads images from provided URLs to App Group shared storage, validating them against the 4KB ActivityKit limit. This makes images accessible to Live Activities via the `assetName` property.

### Method
POST

### Endpoint
`/api/images/preload`

### Parameters
#### Request Body
- **images** (array[object]) - Required - An array of image objects to preload.
  - **url** (string) - Required - The URL of the image to download.
  - **key** (string) - Required - The asset name to use when referencing this image in Live Activities.
  - **method** (string) - Optional - The HTTP method to use for downloading the image. Defaults to 'GET'. Allowed values: 'GET', 'POST', 'PUT'.
  - **headers** (object) - Optional - An object containing custom HTTP headers for the download request.

### Request Example
```json
{
  "images": [
    {
      "url": "https://example.com/album-art.jpg",
      "key": "current-song-artwork",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **succeeded** (array[string]) - An array of keys for images that were successfully downloaded and validated.
- **failed** (array[object]) - An array of objects, each containing the key of a failed image and the corresponding error message.
  - **key** (string) - The key of the image that failed to preload.
  - **error** (string) - A descriptive error message explaining the failure.

#### Response Example
```json
{
  "succeeded": ["current-song-artwork"],
  "failed": [
    {
      "key": "large-image",
      "error": "Image 'large-image' is too large: 5120 bytes (max 4096 bytes for Live Activities)"
    }
  ]
}
```
```

```APIDOC
## POST /api/activities/reload

### Description
Reloads Live Activities to display newly preloaded images. If no specific activity names are provided, all active Live Activities will be reloaded.

### Method
POST

### Endpoint
`/api/activities/reload`

### Parameters
#### Query Parameters
- **activityNames** (array[string]) - Optional - An array of specific activity identifiers to reload. If omitted, all activities are reloaded.

### Request Example
```json
{
  "activityNames": ["music-player", "order-tracker"]
}
```

### Response
#### Success Response (200)
- Returns an empty JSON object `{}` upon successful reload.

#### Response Example
```json
{}
```
```

```APIDOC
## DELETE /api/images/preload

### Description
Removes preloaded images from App Group storage. If no specific keys are provided, all preloaded images will be cleared.

### Method
DELETE

### Endpoint
`/api/images/preload`

### Parameters
#### Query Parameters
- **keys** (array[string]) - Optional - An array of keys corresponding to the preloaded images to remove. If omitted, all preloaded images are cleared.

### Request Example
```json
{
  "keys": ["album-art", "profile-pic"]
}
```

### Response
#### Success Response (200)
- Returns an empty JSON object `{}` upon successful clearing of images.

#### Response Example
```json
{}
```
```

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

### Listen for Live Activity State Changes with Voltra

Source: https://www.use-voltra.dev/development/events

Subscribes to 'stateChange' events from Voltra to monitor Live Activity lifecycle changes like 'dismissed', 'ended', or 'active'. Requires the 'voltra/client' module. The listener receives an event object with 'activityName' and 'activityState'. Remember to unsubscribe using the returned subscription's 'remove' method.

```typescript
import { addVoltraListener } from 'voltra/client'

const subscription = addVoltraListener('stateChange', (event) => {
  console.log('Activity name:', event.activityName)
  console.log('New state:', event.activityState)

  // Handle different states
  if (event.activityState === 'dismissed') {
    // User dismissed the Live Activity
  } else if (event.activityState === 'ended') {
    // Live Activity ended
  } else if (event.activityState === 'active') {
    // Live Activity is active
  }
})

// Don't forget to clean up
subscription.remove()
```

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

### Configure Voltra Expo Plugin for Push Notifications

Source: https://www.use-voltra.dev/development/server-side-updates

This configuration enables server-side updates for Live Activities using push notifications. It requires adding the 'voltra' plugin to your Expo project's configuration file (`app.json` or `app.config.js`). The `enablePushNotifications` flag must be set to `true`.

```json
{
  "expo": {
    "plugins": [
      [
        "voltra",
        {
          "enablePushNotifications": true
        }
      ]
    ]
  }
}
```

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

### Fallback Logic for Widget Variants in Voltra

Source: https://www.use-voltra.dev/development/developing-widgets

Explains Voltra's fallback mechanism for widget content variants when a specific size is not defined. It prioritizes `systemMedium`, then `systemSmall`, `systemLarge`, and so on, ensuring content is displayed across different widget sizes.

```typescript
// Only defining systemSmall and systemLarge
await updateWidget('minimal', {
  systemSmall: <Voltra.Text>72°F</Voltra.Text>,
  systemLarge: <Voltra.Text>Weather: 72°F - Sunny</Voltra.Text>,
})

// systemMedium will automatically use systemSmall content as fallback
```

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

### Positioning Elements with ZStack in Voltra/React Native

Source: https://www.use-voltra.dev/components/layout

Demonstrates how to overlay elements using Voltra's ZStack component. It shows positioning a badge over an image using the `alignment` prop and fine-tuning with `offsetX` and `offsetY` styles. This is useful for creating UI elements like notifications or status indicators.

```tsx
<Voltra.ZStack alignment="topTrailing">
  <Voltra.Image
    source={{ assetName: 'avatar' }}
    style={{ width: 60, height: 60, borderRadius: 30 }}
  />
  <Voltra.Text
    style={{
      backgroundColor: '#FF3B30',
      color: '#FFFFFF',
      fontSize: 10,
      paddingHorizontal: 4,
      paddingVertical: 2,
      borderRadius: 6,
      offsetX: 4,
      offsetY: -4,
    }}>
    3
  </Voltra.Text>
</Voltra.ZStack>
```

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

### Define Dynamic Island Live Activity UI Variants (TypeScript)

Source: https://www.use-voltra.dev/development/developing-live-activities

This code defines the UI variants for a Live Activity in the iOS Dynamic Island. It includes configurations for minimal, compact, and expanded states, with optional styling.

```typescript
const variants = {
  island: {
    keylineTint: '#10B981', // Optional tint color for the Dynamic Island keyline
    minimal: <Voltra.Symbol name="checkmark.circle.fill" tintColor="#10B981" />,
    compact: {
      leading: <Voltra.Text>Order</Voltra.Text>,
      trailing: <Voltra.Text>Confirmed</Voltra.Text>,
    },
    expanded: {
      center: <Voltra.Text style={{ fontSize: 16, fontWeight: '600' }}>Order Confirmed</Voltra.Text>,
      leading: <Voltra.Symbol name="checkmark.circle.fill" />,
      trailing: <Voltra.Text>ETA: 15 min</Voltra.Text>,
      bottom: <Voltra.Text style={{ fontSize: 12 }}>Your order is being prepared</Voltra.Text>,
    },
  },
}
```

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

### Configure Voltra Expo Plugin with App Groups

Source: https://www.use-voltra.dev/development/server-side-updates

This configuration enables push notifications and sets up App Groups for event forwarding and shared image capabilities between your app and the Live Activity extension. It requires the `enablePushNotifications` flag and an optional `groupIdentifier` for the App Group. The `deploymentTarget` specifies the minimum iOS version.

```json
{
  "expo": {
    "plugins": [
      [
        "voltra",
        {
          "enablePushNotifications": true,
          "groupIdentifier": "group.your.app.voltraui",
          "deploymentTarget": "18.0"
        }
      ]
    ]
  }
}
```

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

### Preload Images to App Group Storage (TypeScript)

Source: https://www.use-voltra.dev/development/image-preloading

Downloads images from provided URLs to App Group storage for use in Live Activities. It accepts an array of `PreloadImageOptions`, specifying the URL, a key for referencing the image, and optional HTTP method and headers. It returns a `PreloadImagesResult` object indicating which images succeeded and which failed, along with error messages.

```typescript
type PreloadImageOptions = {
  url: string; // The URL to download the image from
  key: string; // The assetName to use when referencing this image
  method?: 'GET' | 'POST' | 'PUT'; // HTTP method (default: 'GET')
  headers?: Record<string, string>; // Optional HTTP headers
};

type PreloadImagesResult = {
  succeeded: string[]; // Keys of successfully downloaded images
  failed: { key: string; error: string }[]; // Failed downloads with error messages
};

import { preloadImages } from 'voltra/client';

const result = await preloadImages([
  {
    url: 'https://example.com/album-art.jpg',
    key: 'current-song-artwork',
    headers: { Authorization: 'Bearer token' },
  },
]);

console.log('Succeeded:', result.succeeded);
console.log('Failed:', result.failed);
```
Tokens:
Raw