feat: add supplemental activity families support for iOS 18+

example/app.json

@@ -24,6 +24,9 @@
         {
           "groupIdentifier": "group.callstackincubator.voltraexample",
           "enablePushNotifications": true,
+          "liveActivity": {
+            "supplementalActivityFamilies": ["small"]
+          },
           "widgets": [
             {
               "id": "weather",

example/components/live-activities/SupplementalFamiliesUI.tsx

@@ -0,0 +1,51 @@
+import React from 'react'
+import { Voltra } from 'voltra'
+
+export function SupplementalFamiliesLockScreen() {
+  return (
+    <Voltra.VStack id="supplemental-families-lock-screen" spacing={12} style={{ padding: 16 }}>
+      <Voltra.Text
+        style={{
+          color: '#F0F9FF',
+          fontSize: 24,
+          fontWeight: '700',
+        }}
+      >
+        Lock Screen
+      </Voltra.Text>
+    </Voltra.VStack>
+  )
+}
+
+export function SupplementalFamiliesSmall() {
+  return (
+    <Voltra.VStack id="supplemental-families-small" spacing={4} alignment="center" style={{ padding: 8 }}>
+      <Voltra.Text style={{ color: '#3B82F6', fontSize: 16, fontWeight: '700' }}>Watch</Voltra.Text>
+      <Voltra.Text style={{ color: '#94A3B8', fontSize: 11 }}>watchOS / CarPlay</Voltra.Text>
+    </Voltra.VStack>
+  )
+}
+
+export function SupplementalFamiliesCompactLeading() {
+  return (
+    <Voltra.VStack id="supplemental-families-compact-leading" alignment="center" style={{ padding: 6 }}>
+      <Voltra.Text style={{ color: '#10B981', fontSize: 14, fontWeight: '700' }}>L</Voltra.Text>
+    </Voltra.VStack>
+  )
+}
+
+export function SupplementalFamiliesCompactTrailing() {
+  return (
+    <Voltra.VStack id="supplemental-families-compact-trailing" alignment="center" style={{ padding: 6 }}>
+      <Voltra.Text style={{ color: '#10B981', fontSize: 14, fontWeight: '700' }}>R</Voltra.Text>
+    </Voltra.VStack>
+  )
+}
+
+export function SupplementalFamiliesMinimal() {
+  return (
+    <Voltra.VStack id="supplemental-families-minimal" alignment="center" style={{ padding: 6 }}>
+      <Voltra.Symbol name="checkmark.circle.fill" tintColor="#10B981" />
+    </Voltra.VStack>
+  )
+}

example/screens/live-activities/LiveActivitiesScreen.tsx

@@ -12,11 +12,12 @@ import CompassLiveActivity from '~/screens/live-activities/CompassLiveActivity'
 import FlightLiveActivity from '~/screens/live-activities/FlightLiveActivity'
 import LiquidGlassLiveActivity from '~/screens/live-activities/LiquidGlassLiveActivity'
 import MusicPlayerLiveActivity from '~/screens/live-activities/MusicPlayerLiveActivity'
+import SupplementalFamiliesLiveActivity from '~/screens/live-activities/SupplementalFamiliesLiveActivity'
 import WorkoutLiveActivity from '~/screens/live-activities/WorkoutLiveActivity'
 
 import { LiveActivityExampleComponentRef } from './types'
 
-type ActivityKey = 'basic' | 'stylesheet' | 'glass' | 'flight' | 'workout' | 'compass'
+type ActivityKey = 'basic' | 'stylesheet' | 'glass' | 'flight' | 'workout' | 'compass' | 'supplementalFamilies'
 
 const ACTIVITY_METADATA: Record<ActivityKey, { title: string; description: string }> = {
   basic: {
@@ -43,9 +44,22 @@ const ACTIVITY_METADATA: Record<ActivityKey, { title: string; description: strin
     title: 'Compass',
     description: 'Real-time compass using magnetometer with rotating arrow indicator.',
   },
+  supplementalFamilies: {
+    title: 'Supplemental Families (iOS 18+)',
+    description:
+      'Demonstrates supplemental activity families: small (Watch/CarPlay) with compact Dynamic Island fallback. StandBy displays lock screen.',
+  },
 }
 
-const CARD_ORDER: ActivityKey[] = ['basic', 'stylesheet', 'glass', 'flight', 'workout', 'compass']
+const CARD_ORDER: ActivityKey[] = [
+  'basic',
+  'stylesheet',
+  'glass',
+  'flight',
+  'workout',
+  'compass',
+  'supplementalFamilies',
+]
 
 export default function LiveActivitiesScreen() {
   const insets = useSafeAreaInsets()
@@ -57,6 +71,7 @@ export default function LiveActivitiesScreen() {
     flight: false,
     workout: false,
     compass: false,
+    supplementalFamilies: false,
   })
 
   const basicRef = useRef<LiveActivityExampleComponentRef>(null)
@@ -65,6 +80,7 @@ export default function LiveActivitiesScreen() {
   const flightRef = useRef<LiveActivityExampleComponentRef>(null)
   const workoutRef = useRef<LiveActivityExampleComponentRef>(null)
   const compassRef = useRef<LiveActivityExampleComponentRef>(null)
+  const supplementalFamiliesRef = useRef<LiveActivityExampleComponentRef>(null)
 
   const activityRefs = useMemo(
     () => ({
@@ -74,6 +90,7 @@ export default function LiveActivitiesScreen() {
       flight: flightRef,
       workout: workoutRef,
       compass: compassRef,
+      supplementalFamilies: supplementalFamiliesRef,
     }),
     []
   )
@@ -109,6 +126,10 @@ export default function LiveActivitiesScreen() {
     (isActive: boolean) => handleStatusChange('compass', isActive),
     [handleStatusChange]
   )
+  const handleSupplementalFamiliesStatusChange = useCallback(
+    (isActive: boolean) => handleStatusChange('supplementalFamilies', isActive),
+    [handleStatusChange]
+  )
 
   const handleStart = async (key: ActivityKey) => {
     await activityRefs[key].current?.start?.().catch(console.error)
@@ -187,6 +208,10 @@ export default function LiveActivitiesScreen() {
         <FlightLiveActivity ref={flightRef} onIsActiveChange={handleFlightStatusChange} />
         <WorkoutLiveActivity ref={workoutRef} onIsActiveChange={handleWorkoutStatusChange} />
         <CompassLiveActivity ref={compassRef} onIsActiveChange={handleCompassStatusChange} />
+        <SupplementalFamiliesLiveActivity
+          ref={supplementalFamiliesRef}
+          onIsActiveChange={handleSupplementalFamiliesStatusChange}
+        />
       </ScrollView>
     </View>
   )

example/screens/live-activities/SupplementalFamiliesLiveActivity.tsx

@@ -0,0 +1,56 @@
+import React, { forwardRef, useEffect, useImperativeHandle } from 'react'
+import { useLiveActivity } from 'voltra/client'
+
+import {
+  SupplementalFamiliesCompactLeading,
+  SupplementalFamiliesCompactTrailing,
+  SupplementalFamiliesLockScreen,
+  SupplementalFamiliesMinimal,
+  SupplementalFamiliesSmall,
+} from '../../components/live-activities/SupplementalFamiliesUI'
+import { LiveActivityExampleComponent } from './types'
+
+const SupplementalFamiliesLiveActivity: LiveActivityExampleComponent = forwardRef(
+  ({ autoUpdate = true, autoStart = false, onIsActiveChange }, ref) => {
+    const { start, update, end, isActive } = useLiveActivity(
+      {
+        lockScreen: {
+          content: <SupplementalFamiliesLockScreen />,
+        },
+        supplementalActivityFamilies: {
+          small: <SupplementalFamiliesSmall />,
+        },
+        island: {
+          keylineTint: '#10B981',
+          compact: {
+            leading: <SupplementalFamiliesCompactLeading />,
+            trailing: <SupplementalFamiliesCompactTrailing />,
+          },
+          minimal: <SupplementalFamiliesMinimal />,
+        },
+      },
+      {
+        activityName: 'supplemental-families-demo',
+        autoUpdate,
+        autoStart,
+        deepLinkUrl: '/voltraui/supplemental-families-demo',
+      }
+    )
+
+    useEffect(() => {
+      onIsActiveChange?.(isActive)
+    }, [isActive, onIsActiveChange])
+
+    useImperativeHandle(ref, () => ({
+      start,
+      update,
+      end,
+    }))
+
+    return null
+  }
+)
+
+SupplementalFamiliesLiveActivity.displayName = 'SupplementalFamiliesLiveActivity'
+
+export default SupplementalFamiliesLiveActivity

ios/app/VoltraActivity.swift

@@ -0,0 +1,5 @@
+import ActivityKit
+import Foundation
+
+/// Type alias for Live Activity with unified attributes
+public typealias VoltraActivity = Activity<VoltraAttributes>

ios/app/VoltraLiveActivityService.swift

@@ -113,13 +113,14 @@ public class VoltraLiveActivityService {
     return Array(Activity<VoltraAttributes>.activities)
   }
 
-  /// Get the latest (most recently created) activity
-  public func getLatestActivity() -> Activity<VoltraAttributes>? {
+  /// Get the latest (most recently created) activity across both types
+  public func getLatestActivity() -> VoltraActivity? {
     guard Self.isSupported() else { return nil }
-    return Activity<VoltraAttributes>.activities.last
+    let allActivities = getAllActivities()
+    return allActivities.last
   }
 
-  /// Check if an activity with the given name exists
+  /// Check if an activity with the given name exists across both types
   public func isActivityActive(name: String) -> Bool {
     findActivity(byName: name) != nil
   }
@@ -153,7 +154,7 @@ public class VoltraLiveActivityService {
     let initialState = try VoltraAttributes.ContentState(uiJsonData: request.jsonString)
 
     // Request the activity
-    let activity = try Activity.request(
+    _ = try Activity.request(
       attributes: attributes,
       content: .init(
         state: initialState,
@@ -174,7 +175,7 @@ public class VoltraLiveActivityService {
   ///   - request: Parameters for updating the activity
   /// - Throws: Error if update fails
   public func updateActivity(
-    _ activity: Activity<VoltraAttributes>,
+    _ activity: VoltraActivity,
     request: UpdateActivityRequest
   ) async throws {
     guard Self.isSupported() else {
@@ -212,7 +213,7 @@ public class VoltraLiveActivityService {
   /// - Parameter activity: The activity to end
   /// - Parameter dismissalPolicy: How the activity should be dismissed
   public func endActivity(
-    _ activity: Activity<VoltraAttributes>,
+    _ activity: VoltraActivity,
     dismissalPolicy: ActivityUIDismissalPolicy = .immediate
   ) async {
     guard Self.isSupported() else { return }
@@ -254,6 +255,101 @@ public class VoltraLiveActivityService {
       await endActivity(activity)
     }
   }
+
+  // MARK: - Monitoring
+
+  private var monitoredActivityIds: Set<String> = []
+  private var monitoringTasks: [Task<Void, Never>] = []
+
+  /// Start monitoring all Live Activities and Push Tokens
+  public func startMonitoring(enablePush: Bool) {
+    guard Self.isSupported() else { return }
+
+    // 1. Monitor Push-to-Start Tokens
+    if enablePush {
+      if #available(iOS 17.2, *) {
+        startPushToStartTokenObservation()
+      }
+    }
+
+    // 2. Monitor Live Activity Updates (Creation & Lifecycle)
+    startActivityUpdatesObservation(enablePush: enablePush)
+  }
+
+  /// Stop all monitoring tasks
+  public func stopMonitoring() {
+    monitoredActivityIds.removeAll()
+    monitoringTasks.forEach { $0.cancel() }
+    monitoringTasks.removeAll()
+  }
+
+  @available(iOS 17.2, *)
+  private func startPushToStartTokenObservation() {
+    if let initialTokenData = Activity<VoltraAttributes>.pushToStartToken {
+      let token = initialTokenData.hexString
+      VoltraEventBus.shared.send(.pushToStartTokenReceived(token: token))
+    }
+    let task = Task {
+      for await tokenData in Activity<VoltraAttributes>.pushToStartTokenUpdates {
+        let token = tokenData.hexString
+        VoltraEventBus.shared.send(.pushToStartTokenReceived(token: token))
+      }
+    }
+    monitoringTasks.append(task)
+  }
+
+  private func startActivityUpdatesObservation(enablePush: Bool) {
+    // 1. Handle currently existing activities
+    for activity in Activity<VoltraAttributes>.activities {
+      monitorActivity(activity, enablePush: enablePush)
+    }
+
+    // 2. Listen for NEW activities
+    let updatesTask = Task {
+      for await newActivity in Activity<VoltraAttributes>.activityUpdates {
+        monitorActivity(newActivity, enablePush: enablePush)
+      }
+    }
+    monitoringTasks.append(updatesTask)
+  }
+
+  /// Set up observers for an activity's lifecycle
+  private func monitorActivity(_ activity: Activity<VoltraAttributes>, enablePush: Bool) {
+    let activityId = activity.id
+
+    // Avoid duplicate monitoring
+    guard !monitoredActivityIds.contains(activityId) else { return }
+    monitoredActivityIds.insert(activityId)
+
+    // Lifecycle state changes
+    let stateTask = Task {
+      for await state in activity.activityStateUpdates {
+        VoltraEventBus.shared.send(
+          .stateChange(
+            activityName: activity.attributes.name,
+            state: String(describing: state)
+          )
+        )
+      }
+    }
+    monitoringTasks.append(stateTask)
+
+    // Push token updates
+    if enablePush {
+      let tokenTask = Task {
+        for await pushTokenData in activity.pushTokenUpdates {
+          let pushTokenString = pushTokenData.hexString
+          VoltraEventBus.shared.send(
+            .tokenReceived(
+              activityName: activity.attributes.name,
+              pushToken: pushTokenString
+            )
+          )
+        }
+      }
+      monitoringTasks.append(tokenTask)
+    }
+  }
 }
 
 // MARK: - Errors