0
# Live Activities (iOS)
1

2
iOS-specific Live Activity support for dynamic, real-time widget updates including push-to-start and push-to-update functionality.
3

4
**Note**: All Live Activities functionality is iOS-only and will have no effect on Android devices.
5

6
## Capabilities
7

8
### Live Activity Management
9

10
Manage individual Live Activity sessions with enter and exit functionality.
11

12
```typescript { .api }
13
/**
14
 * Indicate this device has entered a live activity, identified within OneSignal by the activityId.
15
 * Only applies to iOS.
16
 * @param activityId - The activity identifier the live activity on this device will receive updates for
17
 * @param token - The activity's update token to receive the updates
18
 * @param handler - Optional callback function
19
 */
20
function enter(activityId: string, token: string, handler?: Function): void;
21

22
/**
23
 * Indicate this device has exited a live activity, identified within OneSignal by the activityId.
24
 * Only applies to iOS.
25
 * @param activityId - The activity identifier the live activity on this device will no longer receive updates for
26
 * @param handler - Optional callback function
27
 */
28
function exit(activityId: string, handler?: Function): void;
29
```
30

31
**Usage Examples:**
32

33
```typescript
34
import { OneSignal } from "react-native-onesignal";
35
import { Platform } from "react-native";
36

37
if (Platform.OS === 'ios') {
38
  // Start tracking a live activity (e.g., sports game, delivery)
39
  OneSignal.LiveActivities.enter(
40
    "game-12345", 
41
    "activity-update-token",
42
    (result) => {
43
      console.log('Live activity entered:', result);
44
    }
45
  );
46
  
47
  // Stop tracking when activity is complete
48
  OneSignal.LiveActivities.exit("game-12345", (result) => {
49
    console.log('Live activity exited:', result);
50
  });
51
}
52
```
53

54
### Push-to-Start Token Management
55

56
Manage push-to-start tokens for Live Activities that can be remotely initiated.
57

58
```typescript { .api }
59
/**
60
 * Indicate this device is capable of receiving pushToStart live activities for the activityType. 
61
 * The activityType must be the name of the struct conforming to ActivityAttributes that will be used 
62
 * to start the live activity. Only applies to iOS.
63
 * @param activityType - The name of the specific ActivityAttributes structure tied to the live activity
64
 * @param token - The activity type's pushToStart token
65
 */
66
function setPushToStartToken(activityType: string, token: string): void;
67

68
/**
69
 * Indicate this device is no longer capable of receiving pushToStart live activities for the activityType.
70
 * The activityType must be the name of the struct conforming to ActivityAttributes that will be used 
71
 * to start the live activity. Only applies to iOS.
72
 * @param activityType - The name of the specific ActivityAttributes structure tied to the live activity
73
 */
74
function removePushToStartToken(activityType: string): void;
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
if (Platform.OS === 'ios') {
81
  // Register for push-to-start delivery tracking
82
  OneSignal.LiveActivities.setPushToStartToken(
83
    "DeliveryTrackingAttributes", 
84
    "push-to-start-token"
85
  );
86
  
87
  // Unregister when no longer needed
88
  OneSignal.LiveActivities.removePushToStartToken("DeliveryTrackingAttributes");
89
}
90
```
91

92
### Default Live Activity Setup
93

94
Use OneSignal's default Live Activity implementation for simplified setup.
95

96
```typescript { .api }
97
/**
98
 * Enable the OneSignalSDK to setup the default DefaultLiveActivityAttributes structure,
99
 * which conforms to the OneSignalLiveActivityAttributes. When using this function, the
100
 * widget attributes are owned by the OneSignal SDK, which will allow the SDK to handle the
101
 * entire lifecycle of the live activity. Only applies to iOS.
102
 * @param options - Optional structure to provide for more granular setup options
103
 */
104
function setupDefault(options?: LiveActivitySetupOptions): void;
105

106
/**
107
 * Start a new LiveActivity that is modelled by the default DefaultLiveActivityAttributes
108
 * structure. The DefaultLiveActivityAttributes is initialized with the dynamic attributes
109
 * and content passed in. Only applies to iOS.
110
 * @param activityId - The activity identifier the live activity on this device will be started and eligible to receive updates for
111
 * @param attributes - A dynamic type containing the static attributes passed into DefaultLiveActivityAttributes  
112
 * @param content - A dynamic type containing the content attributes passed into DefaultLiveActivityAttributes
113
 */
114
function startDefault(activityId: string, attributes: object, content: object): void;
115
```
116

117
**Usage Examples:**
118

119
```typescript
120
if (Platform.OS === 'ios') {
121
  // Setup default live activity with push-to-start and push-to-update
122
  OneSignal.LiveActivities.setupDefault({
123
    enablePushToStart: true,
124
    enablePushToUpdate: true
125
  });
126
  
127
  // Start a default live activity
128
  OneSignal.LiveActivities.startDefault(
129
    "order-tracking-456",
130
    {
131
      // Static attributes (set once)
132
      orderNumber: "ORD-12345",
133
      customerName: "John Doe"
134
    },
135
    {
136
      // Dynamic content (can be updated)
137
      status: "preparing",
138
      estimatedTime: "15 minutes",
139
      progressPercent: 25
140
    }
141
  );
142
}
143
```
144

145
## Common Use Cases
146

147
### Sports Game Tracking
148

149
```typescript
150
if (Platform.OS === 'ios') {
151
  // Start tracking a live sports game
152
  const gameId = "nfl-game-" + Date.now();
153
  
154
  OneSignal.LiveActivities.enter(
155
    gameId,
156
    gameUpdateToken,
157
    (result) => {
158
      console.log('Started tracking game:', gameId);
159
    }
160
  );
161
  
162
  // End tracking when game is over
163
  setTimeout(() => {
164
    OneSignal.LiveActivities.exit(gameId, (result) => {
165
      console.log('Stopped tracking game:', gameId);
166
    });
167
  }, 3 * 60 * 60 * 1000); // 3 hours
168
}
169
```
170

171
### Delivery Tracking
172

173
```typescript
174
if (Platform.OS === 'ios') {
175
  // Setup push-to-start for delivery notifications
176
  OneSignal.LiveActivities.setPushToStartToken(
177
    "DeliveryAttributes",
178
    deliveryPushToken
179
  );
180
  
181
  // Start tracking a specific delivery
182
  OneSignal.LiveActivities.startDefault(
183
    "delivery-" + orderId,
184
    {
185
      orderNumber: orderId,
186
      restaurant: "Pizza Palace"
187
    },
188
    {
189
      status: "confirmed",
190
      driverName: "",
191
      estimatedArrival: "30 min"
192
    }
193
  );
194
}
195
```
196

197
### Workout Session
198

199
```typescript
200
if (Platform.OS === 'ios') {
201
  // Setup default live activity for workout tracking
202
  OneSignal.LiveActivities.setupDefault({
203
    enablePushToStart: false,
204
    enablePushToUpdate: true
205
  });
206
  
207
  // Start workout session
208
  const workoutId = "workout-" + userId + "-" + Date.now();
209
  
210
  OneSignal.LiveActivities.startDefault(
211
    workoutId,
212
    {
213
      workoutType: "Running",
214
      targetDistance: "5K"
215
    },
216
    {
217
      currentDistance: "0 km",
218
      pace: "0:00",
219
      duration: "00:00"
220
    }
221
  );
222
  
223
  // Update progress during workout (done via push notifications)
224
  // ...
225
  
226
  // End workout session
227
  OneSignal.LiveActivities.exit(workoutId);
228
}
229
```
230

231
### Ride Sharing
232

233
```typescript
234
if (Platform.OS === 'ios') {
235
  // Enable push-to-start for ride requests
236
  OneSignal.LiveActivities.setPushToStartToken(
237
    "RideRequestAttributes",
238
    rideToken
239
  );
240
  
241
  // When ride is confirmed, start live activity
242
  OneSignal.LiveActivities.startDefault(
243
    "ride-" + rideId,
244
    {
245
      pickup: "123 Main St",
246
      destination: "456 Oak Ave",
247
      driverName: "Sarah"
248
    },
249
    {
250
      status: "driver_assigned",
251
      eta: "5 minutes",
252
      vehicleInfo: "Blue Honda Civic - ABC123"
253
    }
254
  );
255
}
256
```
257

258
## Types
259

260
```typescript { .api }
261
interface LiveActivitySetupOptions {
262
  /**
263
   * When true, OneSignal will listen for pushToStart tokens for the OneSignalLiveActivityAttributes structure.
264
   */
265
  enablePushToStart: boolean;
266
  
267
  /**
268
   * When true, OneSignal will listen for pushToUpdate tokens for each start live activity that uses the
269
   * OneSignalLiveActivityAttributes structure.
270
   */
271
  enablePushToUpdate: boolean;
272
}
273
```
274

275
## Platform Compatibility
276

277
All Live Activities functions are iOS-only and will:
278
- Execute normally on iOS devices
279
- Be ignored on Android devices (no-op)
280
- Log appropriate warnings when called on Android in development builds
281

282
Always wrap Live Activities calls with platform checks for clean code:
283

284
```typescript
285
import { Platform } from 'react-native';
286

287
if (Platform.OS === 'ios') {
288
  // Live Activities code here
289
  OneSignal.LiveActivities.setupDefault({ 
290
    enablePushToStart: true, 
291
    enablePushToUpdate: true 
292
  });
293
}
294
```