Configuration

Voltra provides several configuration options to control Live Activity behavior, lifecycle, and appearance. These options can be used when starting, updating, or stopping Live Activities.

For Expo plugin configuration options (like groupIdentifier, enablePushNotifications, deploymentTarget, and widgets), see the Plugin Configuration documentation.

Dismissal Policy

Voltra supports configuring how Live Activities behave after they end. You can control the dismissal timing using the dismissalPolicy option:

Dismissal Policy Options

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

Usage Examples

Immediate dismissal (default behavior):

import { startLiveActivity } from '@use-voltra/ios-client'

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

Delayed dismissal (keep visible for 30 seconds after ending):

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

Update dismissal policy for active Live Activities:

import { updateLiveActivity } from '@use-voltra/ios-client'

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

Set dismissal policy when ending a Live Activity:

import { stopLiveActivity } from '@use-voltra/ios-client'

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

The dismissal policy applies to both programmatic ending (stopLiveActivity) and natural ending (when timers reach their end time). This gives you fine-grained control over the user experience when Live Activities conclude.

Additional Configuration Options

Stale Date

The staleDate option allows you to specify when a Live Activity should be considered stale and automatically dismissed by the system.

import { startLiveActivity } from '@use-voltra/ios-client'

// Dismiss the Live Activity after 1 hour
await startLiveActivity(variants, {
  staleDate: Date.now() + 60 * 60 * 1000, // 1 hour from now
})

Note: If you provide a staleDate in the past, it will be ignored and the Live Activity will use default behavior.

Relevance Score

The relevanceScore option helps iOS prioritize which Live Activities to display when space is limited. Higher scores (closer to 1.0) indicate more important activities.

import { startLiveActivity } from '@use-voltra/ios-client'

// High priority Live Activity (e.g., active delivery)
await startLiveActivity(variants, {
  relevanceScore: 0.8,
})

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

Valid range: 0.0 to 1.0 (default: 0.0)

Channel ID (broadcast push, iOS 18+)

The channelId option subscribes the Live Activity to a broadcast channel for server-side updates. When provided, the activity receives updates via broadcast push notifications instead of individual device tokens—one server notification updates all activities on that channel. Requires enablePushNotifications: true and the Broadcast Capability enabled in your Apple Developer account.

import { startLiveActivity } from '@use-voltra/ios-client'

await startLiveActivity(variants, {
  activityName: 'match-123',
  channelId: 'CTrNsYq/Ee8AALLzHQaVlA==', // From APNs channel management
})

For full broadcast setup, see Server-side updates - Broadcast push notifications.

These options can be used together with dismissal policy and other configuration options:

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