> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Live Activities
> Show real-time updates on the iOS Lock Screen and Dynamic Island for deliveries, rides, and live scores, with setup, targeting, and analytics.
Live Activities put a live, updating view of an event on the iOS Lock Screen and in the Dynamic Island. Users watch an order arrive or a match unfold without opening your app and without a stream of push notifications. The activity updates in place for as long as the event lasts, then clears itself.
Live Activities are an iOS feature. For similar capability on Android, see [Android Live Updates](./android-live-notifications).
Android's version of iOS Live Activities.
## What makes Live Activities different
Live Activities combine four properties you get from no other channel:
* **Persistent placement.** The activity holds a fixed spot on the Lock Screen and in the Dynamic Island for the life of the event, so users check it instead of opening your app.
* **A separate permission.** iOS governs Live Activities with their own setting. Users who declined push notifications still see your Live Activities.
* **One call reaches every device.** Send one Update Live Activity request and OneSignal delivers it to every device registered to that `activity_id`. OneSignal stores and refreshes each device's APNs update token for you.
* **Per-send analytics.** Every update reports delivery, confirmed receipt, clicks, failures, and unsubscribes, using the same metric definitions as your other channels.
For customer examples, see the [Live Activities blog post](https://onesignal.com/blog/new-live-activities-support-to-help-you-drive-loyalty-faster).
***
## When to use Live Activities
Use a Live Activity when a user is waiting on something that changes while they wait. All four of the following must be true:
1. **The user already expects the event.** They started it, or they know it is coming. A Live Activity tracks something in progress. It does not announce something new.
2. **The status changes more than once.** If the status changes once, send a push notification. If it never changes, build a widget.
3. **The event ends within 8 hours.** Apple stops accepting updates after 8 hours.
4. **Each update is glanceable.** An ETA, a score, a delivery status, a timer, a workout metric. If an update needs a full sentence to make sense, send a push notification.
If any one of these is false, send a [push notification](./push) instead.
Do not use Live Activities for:
* Ads, promotions, or flash sales. Apple requires that a Live Activity provide user value, and prohibits purely promotional content.
* Always-on data with no end, such as a stock ticker or the weather.
* Events that run longer than a day, such as multi-day shipping. Send a push notification at each milestone.
* Re-engaging users who are not expecting an update.
* Sensitive information. The Lock Screen is visible without unlocking the device.
Users who receive unexpected or promotional Live Activities turn them off for your app in iOS Settings. That setting also stops the transactional Live Activities they do want, so keep every activity tied to an event the user is tracking.
### Choose your update pattern
Decide who sees the same content before you build, because it determines the `activity_id` you send.
Use a **shared `activity_id`** when many users follow the same event: a match, a concert, a launch, an auction close, or a service incident. One update request reaches every recipient. Target these sends with segments.
Use a **unique `activity_id` per user or per order** when each user tracks their own event: a delivery, a ride, an order, or a workout. Target these sends by user.
Target Live Activities with the same parameters as your other messages: Segments, Filters, aliases, and IDs. For details on choosing the value, see [Choose an activity ID](/reference/start-live-activity#choose-an-activity-id).
### What Live Activities require from your app
Plan for iOS engineering work. Your Live Activity layout is a widget extension compiled into your app, so each new use case needs development and an App Store release. You cannot add a Live Activity use case from the dashboard the way you can with a push notification.
Weigh that against how often you will use it. A use case that runs on every order or every match justifies the work. A single campaign does not.
***
## Get started
### Requirements
* iOS 16.1+ or iPadOS 17+.
* OneSignal [Mobile SDK](./mobile-sdk-setup) integrated.
* Setup completed per the [Live Activities Developer Setup](./live-activities-developer-setup).
* Click tracking and confirmed receipt require iOS SDK **5.2.15 or higher**.
* Remote push-to-start requires iOS 17.2+ and iOS SDK 5.2.0+.
### Start, update, and end an activity
Start an activity in one of two ways:
1. Remotely, by calling the [Start Live Activity API](/reference/start-live-activity) (push-to-start).
2. In-app, by using ActivityKit in your iOS code. See the [Live Activities Developer Setup](./live-activities-developer-setup).
Call the [Update Live Activity API](/reference/update-live-activity-api) with the `activity_id`. OneSignal delivers the update to every user registered under that `activity_id`, so choose the value based on who should see the same content. See [Choose an activity ID](/reference/start-live-activity#choose-an-activity-id).
End an activity in one of three ways:
* Tells OneSignal to stop sending updates for the given `activityId`. See [`exit()`](./mobile-sdk-reference#exit).
* Does **not** remove the activity from the screen. iOS removes it automatically after the 4-hour dismissal window or when the user dismisses it.
Call the [Update Live Activity API](/reference/update-live-activity-api) with `event: end` to stop further updates. Include a `dismissal_date` to control when iOS removes the activity from the screen:
* Omit `dismissal_date` and iOS removes the activity after the 4-hour dismissal window or when the user dismisses it.
* Set a **future** `dismissal_date` within the next 4 hours to remove it sooner.
* Set a **past** `dismissal_date` to remove it immediately. The user must have tapped **Allow** on the first Live Activity for programmatic dismissal to take effect.
* The user swipes the activity away or otherwise dismisses it.
* The user revokes Live Activity permission in iOS Settings.
### Lifecycle and limits
* **Active updates**: Up to 8 hours from when the activity starts.
* **Dismissal window**: After the activity ends, iOS keeps it visible for up to 4 more hours before removing it automatically. Set a `dismissal_date` to remove it sooner.
* **Stale period**: If you set a `stale_date`, iOS marks the activity as stale once that time passes, signaling the content is outdated so your widget can show a fallback message. The activity stays visible; stale is about freshness, not removal. See [Setting a fallback message](./live-activities-developer-setup#setting-a-fallback-message).
* **Limit**: Up to 5 simultaneous Live Activities per app.
* **Permissions**: The first activity is provisional, so it needs no push permission. Whether later activities appear depends on whether the user tapped **Allow** on the first one.
***
## Update frequency and throttling
Apple meters how often your Live Activities update, because frequent updates drain the device battery. Every update carries a `priority`, and only high-priority updates spend a budget that iOS maintains per device.
* `priority: 5` delivers opportunistically and does not spend the budget, so there is no limit on how many you send. Use it for routine updates.
* `priority: 10` delivers immediately and spends the budget. Reserve it for updates that need the user's immediate attention. When you omit `priority`, OneSignal sends `10`.
* Apple does not publish the size of the budget. iOS calculates it dynamically from device conditions and your app's recent `priority: 10` usage, then delays or drops updates once you exceed it.
* Your budget is per device, not per audience. One update request sends one push to every device registered to that `activity_id`, so a request every 10 seconds spends every recipient's budget at that rate.
* If your use case requires frequent high-priority updates, add `NSSupportsLiveActivitiesFrequentUpdates` to your app's `Info.plist` as a Boolean set to `YES`. Apple raises your budget. Apple does not remove it, so keep mixing in `priority: 5`. See [Apple's guidance on update frequency](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency).
* Users can turn frequent updates off for your app in iOS Settings. Detect this in your app with ActivityKit's `frequentPushesEnabled` and store the value as a [tag](./add-user-data-tags) so you can lower your send rate for those users. OneSignal does not sync this setting for you.
For the `priority` field, see the [Update Live Activity API](/reference/update-live-activity-api).
***
## Design your Live Activity
* Support every presentation: Compact, Minimal, Expanded, and Lock Screen.
* Apply your brand, spacing, and dark and light themes consistently.
* Prioritize clarity and tap targets. Do not try to draw attention to the Dynamic Island itself.
* Keep each activity only as long as the content remains useful, and set a `dismissal_date` proportional to the event. Apple suggests 15 to 30 minutes for most cases.
See Apple's [Live Activities Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/live-activities) for presentation detail and layout guidance.
***
## Measure results
Track delivery, confirmed receipt, clicks, failures, and unsubscribes on every Live Activity send. Metrics follow the same definitions used across channels. See the [Metrics glossary](./analytics-metrics-glossary) for canonical definitions, and [Live Activities analytics](./live-activities-analytics) for message reports, Audience Activity exports, and rate calculations.
***
## FAQ
### Do I have access to Live Activities in my plan?
Live Activities are available on all plans except Free plans with more than 10,000 opted-in subscribers. Upgrade from the Free plan to use Live Activities. [See pricing](https://onesignal.com/pricing) or contact `support@onesignal.com`.
### How often can I update a Live Activity?
As often as you need when you send `priority: 5`, which delivers opportunistically and is unmetered. Only `priority: 10` is metered: it spends a budget iOS calculates per device, and iOS delays or drops updates once you exceed it. Omitting `priority` sends `10`. See [Update frequency and throttling](#update-frequency-and-throttling).
### Where can I see Live Activities in the OneSignal dashboard?
Live Activities are sent only through the Live Activity APIs, but you can review historically sent activities in **All messages** filtered to Live Activities for up to 30 days. For aggregate trends, see [Engagement Trends](./engagement-analytics).
### Can I use Live Activities with cross-platform SDKs?
Yes. Live Activities work in apps built with React Native, Expo, Flutter, Unity, Cordova, Capacitor, and .NET MAUI. The SDK's `setupDefault` method manages the ActivityKit lifecycle so the only native code you write is the widget layout. See the [Cross-platform Live Activity SDK setup](./cross-platform-live-activity-setup).
Live Activities remain an iOS feature regardless of framework. They do not run on Android or the web. For Android, see [Android Live Updates](./android-live-notifications).
### Can I target Live Activities with segments?
Yes. Start Live Activities remotely with the same targeting parameters as your other messages: [Segments](./segmentation), filters, aliases, and IDs. Updates then go to every device registered to the `activity_id`. See [Choose an activity ID](/reference/start-live-activity#choose-an-activity-id).
### What devices support Live Activities?
Apple maintains the compatibility list for [iOS 16+](https://support.apple.com/guide/iphone/supported-models-iphe3fa5df43/16.0/ios/16.0) and [iPadOS 17+](https://support.apple.com/guide/ipad/ipad-models-compatible-with-ipados-17-ipad213a25b2/ipados).
### What's the difference between Delivered and Confirmed Receipt?
**Delivered** means APNs accepted the Live Activity update for delivery. **Confirmed Receipt** means the OneSignal SDK on the device confirmed that the update actually arrived. Confirmed Receipt requires iOS SDK 5.2.15+ and completed [Confirmed receipt](./confirmed-delivery) setup. See the [Metrics glossary](./analytics-metrics-glossary) for the full definitions.
## Related
Integrate the OneSignal iOS SDK and configure your app for Live Activities.
Message reports, Audience Activity, and CSV export for Live Activities.
Start an activity remotely with push-to-start, including audience targeting.
Update or end a running activity, and control when iOS dismisses it.
Deliver similar real-time experiences on Android devices.
Canonical definitions for every metric across dashboard, API, CSV, and Event Streams.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.