Learn how to set up Live Activities on your iOS app with OneSignal to display real-time updates.
Live Activities let your iOS app show real-time updates directly on the lock screen and Dynamic Island. Ideal for delivery tracking, sports scores, or time-sensitive transactional updates, they keep users informed without opening the app.
These steps walk you through setting up Live Activities quickly. For more details and design customizations, see Apple’s Live Activities Developer docs.
In Xcode, go to File > New > Target… > Widget Extension.
Add a new Widget Extension target for your app in Xcode.
Select and press Next.
Configure the Widget Extension by providing a name (example: OneSignalWidget
) and ensure Include Live Activity is selected. Then click Finish.
Widget Extension options for a Live Activity.
Click Don’t Activate if prompted to activate the scheme.
Widget Extension options for a Live Activity.
Info.plist
In your main target’s Info.plist
, add the key Supports Live Activities
as Boolean, and set it to YES
.
Add Supports Live Activities key to Info and set its value to Boolean YES
If you set it programmatically, it should look like this:
When updating Live Activities, you have the option to set a “priority” which Apple uses to determine how urgent the update is. Apple has internal thresholds in which they will throttle requests that use the high priority flag too frequently.
If your use cases for Live Activities relies on more frequent high priority updates, you can add the key NSSupportsLiveActivitiesFrequentUpdates
to your Info.plist as a Boolean type set to YES as directed in Apple’s Developer Docs. Users will be presented with a dialog when the Live Activity exceeds its push budget, and if they allow the Live Activity to continue, the budget will automatically be increased for a seamless user experience.
In your Widget Extension target, add the OneSignalFramework
under General > Frameworks, Libraries and Embedded Content:
Add the OneSignalFramework to your Widget Extension target
In your Widget Extension target, add the OneSignalFramework
under General > Frameworks, Libraries and Embedded Content:
Add the OneSignalFramework to your Widget Extension target
Find the name of your widget extension target in your project’s Targets list. Example’s name is OneSignalWidgetExtension
.
Find the name of your widget extension target
Open your Podfile
and add the following code. Replace OneSignalWidgetExtension
with the name of your widget extension target.
Close Xcode and run pod repo update && pod install
to install the OneSignalLiveActivities
pod.
If you continue to see the error “No such module ‘OneSignalLiveActivities’” after doing this, you can add the dependency manually by going to your “Widget Extension Target” > General > Frameworks and Libraries > + icon. Select the OneSignalLiveActivities
framework:
Add dependencies manually
Open the your-nameLiveActivity.swift
file (example: OneSignalWidgetLiveActivity.swift
) to define the properties of the struct and to make changes to the widget UI.
your-nameAttributes
describes the static content of your Live Activity.ContentState
describes the dynamic content of your Live Activity.If you are following the example, copy-paste the code below into your OneSignalWidgetLiveActivity.swift
file.
Add your main app target to the Target Membership list in the your-nameLiveActivity.swift
file.
In Xcode, open the Inspector panel on the right side of the screen. Within Target Membership, click the + button and select your main app target containing the ContentView
and your OneSignal initialization code.
Allow main target membership
Call OneSignal.LiveActivities.setup
in your AppDelegate
, after OneSignal SDK initialization.
Replace OneSignalWidgetAttributes
with the name of your Live Activity attributes struct.
This manages and reports updates using ActivityKit async sequences.
If you also consume any of the following sequences directly in your app, it may interfere with OneSignal Live Activity behavior:
There are 2 options to start a Live Activity on a device:
Send a Push To Start API request. Be sure all names and IDs match your widget’s configuration exactly (parameters are case-sensitive). If anything is missing or incorrectly added, you may encounter issues when trying to launch the widget.
Here is an example request that will work for the example above.
Replace:
YOUR_APP_ID
with your OneSignal App ID.
YOUR_APP_API_KEY
with your OneSignal API key.
OneSignalWidgetAttributes
with the name of your Widget Attributes struct.
If you are following the example code provided, you should see the Live Activity on your device’s lock screen.
Live Activity on the lock screen
You successfully started a Live Activity with push-to-start!
Users will need to select “Allow” to continue getting updates.
Send a Push To Start API request. Be sure all names and IDs match your widget’s configuration exactly (parameters are case-sensitive). If anything is missing or incorrectly added, you may encounter issues when trying to launch the widget.
Here is an example request that will work for the example above.
Replace:
YOUR_APP_ID
with your OneSignal App ID.
YOUR_APP_API_KEY
with your OneSignal API key.
OneSignalWidgetAttributes
with the name of your Widget Attributes struct.
If you are following the example code provided, you should see the Live Activity on your device’s lock screen.
Live Activity on the lock screen
You successfully started a Live Activity with push-to-start!
Users will need to select “Allow” to continue getting updates.
You can have a user trigger a Live Activity while interacting with your app.
For example, when a user has an active event going on (they placed an order, a game is in progress, an event is about to start, etc.) and opens your app, you can display a Live Activity automatically.
In this example we will use a button to start the Live Activity manually.
Upon clicking the button it will launch the Live Activity.
Use the Update Live Activity API to update active widgets.
Match the activity_id
used when starting the activity.
This example request will update the push-to-start widget because it has the activity_id
titled push-to-start
that we defined.
To update the click-to-start widget, update the request path to use click-to-start
instead of push-to-start
.
Live Activity Updated
You successfully updated a Live Activity!
Checkout the Update Live Activity API for more information on updating a Live Activity.
Using the same Update Live Activity API, we can end a Live Activity by setting "event": "end"
.
Other ways a Live Activity can end:
exit()
method.Live Activity Ended
You successfully ended the Live Activity and completed the example!
Apple does not provide a fixed limit for high-priority (priority: 10
) updates, but they do enforce a dynamic system-level budget. Sending too many high-priority updates in a short period may result in throttling, where updates are delayed or dropped.
To reduce the risk of throttling:
priority: 5
(standard) and priority: 10
(high) for balance.priority: 10
for time-sensitive or critical updates only (e.g., order status changes, game scores).If your use case requires frequent updates:
NSSupportsLiveActivitiesFrequentUpdates
to your app’s Info.plist
file, set as a Boolean YES
.For more details, refer to Apple’s Developer Docs.
Yes. You can observe updates for debugging or UI sync:
Track lifecycle changes:
If your push subscriber count is greater than the Push Subscribers for your plan, please upgrade your account to the next plan, or reach out to support@onesignal.com
. For the latest plan details, please see here.
Your application may already send a series of Push Notifications, where your designed Live Activity replaces the need for these Push Notifications. For example, if you send score updates via Push, you could replace this through a Live Activity.
In order to ensure your users are not getting too many messages, we recommend as your user opts in for a Live Activity, to add a data tag. By adding this data tag, you can exclude users with this data tag from push messages that may contain the same or similar content. Read more on Data Tags and Segments.
In order for your users to be found when trying to start or update a Live Activity, you must ensure that the activity type, widget, and cURL request all have matching values.
Check the path parameters in your request to ensure that you are sending a correctly formatted request to the server. The App ID must match your App ID used in the OneSignal.Initialize
method and the activity type must match that of the type you’ve defined in your Live Activity file.
In the body of the Push To Start API request, you should have the following parameters:
event
: "start"
event_updates
: The dynamic data you have defined in your struct under activity type and that is used in your widget. Ensure the letter casing and variables all match between the request, the type, and the widget.event_attributes
: Static data follows the same logic as Event Updates and must include all variables in use, and must match across all parts of the live activity and the requestactivity_id
: This will assign an ID to the widget and is what will be used to update the activity after it has been launched on the user’s device.name
: The Live Activity Name.contents
: The message content required for sending push.headings
: The message heading required for sending push.included_segments
. Available options.Ensure that the request is formatted correctly. If any fields that are used in the Widget are omitted, the activity may not launch or update as expected.
In your API request, determine the priority
level you are setting. If you are setting this to 10
(highest priority), try lowering it to 5
and test again. Apple will throttle requests being sent out too frequently per their own internal rate limits.
If your use case relies on more frequent updates, add the key NSSupportsLiveActivitiesFrequentUpdates
to your Info.plist as a Boolean type set to YES as directed in Apple’s Developer Docs. User will be presented with a dialog when the Live Activity exceeds its push budget, and if they allow the Live Activity to continue, the budget will automatically be increased for a seamless user experience.
Need help?
Chat with our Support team or email support@onesignal.com
Please include:
We’re happy to help!
Learn how to set up Live Activities on your iOS app with OneSignal to display real-time updates.
Live Activities let your iOS app show real-time updates directly on the lock screen and Dynamic Island. Ideal for delivery tracking, sports scores, or time-sensitive transactional updates, they keep users informed without opening the app.
These steps walk you through setting up Live Activities quickly. For more details and design customizations, see Apple’s Live Activities Developer docs.
In Xcode, go to File > New > Target… > Widget Extension.
Add a new Widget Extension target for your app in Xcode.
Select and press Next.
Configure the Widget Extension by providing a name (example: OneSignalWidget
) and ensure Include Live Activity is selected. Then click Finish.
Widget Extension options for a Live Activity.
Click Don’t Activate if prompted to activate the scheme.
Widget Extension options for a Live Activity.
Info.plist
In your main target’s Info.plist
, add the key Supports Live Activities
as Boolean, and set it to YES
.
Add Supports Live Activities key to Info and set its value to Boolean YES
If you set it programmatically, it should look like this:
When updating Live Activities, you have the option to set a “priority” which Apple uses to determine how urgent the update is. Apple has internal thresholds in which they will throttle requests that use the high priority flag too frequently.
If your use cases for Live Activities relies on more frequent high priority updates, you can add the key NSSupportsLiveActivitiesFrequentUpdates
to your Info.plist as a Boolean type set to YES as directed in Apple’s Developer Docs. Users will be presented with a dialog when the Live Activity exceeds its push budget, and if they allow the Live Activity to continue, the budget will automatically be increased for a seamless user experience.
In your Widget Extension target, add the OneSignalFramework
under General > Frameworks, Libraries and Embedded Content:
Add the OneSignalFramework to your Widget Extension target
In your Widget Extension target, add the OneSignalFramework
under General > Frameworks, Libraries and Embedded Content:
Add the OneSignalFramework to your Widget Extension target
Find the name of your widget extension target in your project’s Targets list. Example’s name is OneSignalWidgetExtension
.
Find the name of your widget extension target
Open your Podfile
and add the following code. Replace OneSignalWidgetExtension
with the name of your widget extension target.
Close Xcode and run pod repo update && pod install
to install the OneSignalLiveActivities
pod.
If you continue to see the error “No such module ‘OneSignalLiveActivities’” after doing this, you can add the dependency manually by going to your “Widget Extension Target” > General > Frameworks and Libraries > + icon. Select the OneSignalLiveActivities
framework:
Add dependencies manually
Open the your-nameLiveActivity.swift
file (example: OneSignalWidgetLiveActivity.swift
) to define the properties of the struct and to make changes to the widget UI.
your-nameAttributes
describes the static content of your Live Activity.ContentState
describes the dynamic content of your Live Activity.If you are following the example, copy-paste the code below into your OneSignalWidgetLiveActivity.swift
file.
Add your main app target to the Target Membership list in the your-nameLiveActivity.swift
file.
In Xcode, open the Inspector panel on the right side of the screen. Within Target Membership, click the + button and select your main app target containing the ContentView
and your OneSignal initialization code.
Allow main target membership
Call OneSignal.LiveActivities.setup
in your AppDelegate
, after OneSignal SDK initialization.
Replace OneSignalWidgetAttributes
with the name of your Live Activity attributes struct.
This manages and reports updates using ActivityKit async sequences.
If you also consume any of the following sequences directly in your app, it may interfere with OneSignal Live Activity behavior:
There are 2 options to start a Live Activity on a device:
Send a Push To Start API request. Be sure all names and IDs match your widget’s configuration exactly (parameters are case-sensitive). If anything is missing or incorrectly added, you may encounter issues when trying to launch the widget.
Here is an example request that will work for the example above.
Replace:
YOUR_APP_ID
with your OneSignal App ID.
YOUR_APP_API_KEY
with your OneSignal API key.
OneSignalWidgetAttributes
with the name of your Widget Attributes struct.
If you are following the example code provided, you should see the Live Activity on your device’s lock screen.
Live Activity on the lock screen
You successfully started a Live Activity with push-to-start!
Users will need to select “Allow” to continue getting updates.
Send a Push To Start API request. Be sure all names and IDs match your widget’s configuration exactly (parameters are case-sensitive). If anything is missing or incorrectly added, you may encounter issues when trying to launch the widget.
Here is an example request that will work for the example above.
Replace:
YOUR_APP_ID
with your OneSignal App ID.
YOUR_APP_API_KEY
with your OneSignal API key.
OneSignalWidgetAttributes
with the name of your Widget Attributes struct.
If you are following the example code provided, you should see the Live Activity on your device’s lock screen.
Live Activity on the lock screen
You successfully started a Live Activity with push-to-start!
Users will need to select “Allow” to continue getting updates.
You can have a user trigger a Live Activity while interacting with your app.
For example, when a user has an active event going on (they placed an order, a game is in progress, an event is about to start, etc.) and opens your app, you can display a Live Activity automatically.
In this example we will use a button to start the Live Activity manually.
Upon clicking the button it will launch the Live Activity.
Use the Update Live Activity API to update active widgets.
Match the activity_id
used when starting the activity.
This example request will update the push-to-start widget because it has the activity_id
titled push-to-start
that we defined.
To update the click-to-start widget, update the request path to use click-to-start
instead of push-to-start
.
Live Activity Updated
You successfully updated a Live Activity!
Checkout the Update Live Activity API for more information on updating a Live Activity.
Using the same Update Live Activity API, we can end a Live Activity by setting "event": "end"
.
Other ways a Live Activity can end:
exit()
method.Live Activity Ended
You successfully ended the Live Activity and completed the example!
Apple does not provide a fixed limit for high-priority (priority: 10
) updates, but they do enforce a dynamic system-level budget. Sending too many high-priority updates in a short period may result in throttling, where updates are delayed or dropped.
To reduce the risk of throttling:
priority: 5
(standard) and priority: 10
(high) for balance.priority: 10
for time-sensitive or critical updates only (e.g., order status changes, game scores).If your use case requires frequent updates:
NSSupportsLiveActivitiesFrequentUpdates
to your app’s Info.plist
file, set as a Boolean YES
.For more details, refer to Apple’s Developer Docs.
Yes. You can observe updates for debugging or UI sync:
Track lifecycle changes:
If your push subscriber count is greater than the Push Subscribers for your plan, please upgrade your account to the next plan, or reach out to support@onesignal.com
. For the latest plan details, please see here.
Your application may already send a series of Push Notifications, where your designed Live Activity replaces the need for these Push Notifications. For example, if you send score updates via Push, you could replace this through a Live Activity.
In order to ensure your users are not getting too many messages, we recommend as your user opts in for a Live Activity, to add a data tag. By adding this data tag, you can exclude users with this data tag from push messages that may contain the same or similar content. Read more on Data Tags and Segments.
In order for your users to be found when trying to start or update a Live Activity, you must ensure that the activity type, widget, and cURL request all have matching values.
Check the path parameters in your request to ensure that you are sending a correctly formatted request to the server. The App ID must match your App ID used in the OneSignal.Initialize
method and the activity type must match that of the type you’ve defined in your Live Activity file.
In the body of the Push To Start API request, you should have the following parameters:
event
: "start"
event_updates
: The dynamic data you have defined in your struct under activity type and that is used in your widget. Ensure the letter casing and variables all match between the request, the type, and the widget.event_attributes
: Static data follows the same logic as Event Updates and must include all variables in use, and must match across all parts of the live activity and the requestactivity_id
: This will assign an ID to the widget and is what will be used to update the activity after it has been launched on the user’s device.name
: The Live Activity Name.contents
: The message content required for sending push.headings
: The message heading required for sending push.included_segments
. Available options.Ensure that the request is formatted correctly. If any fields that are used in the Widget are omitted, the activity may not launch or update as expected.
In your API request, determine the priority
level you are setting. If you are setting this to 10
(highest priority), try lowering it to 5
and test again. Apple will throttle requests being sent out too frequently per their own internal rate limits.
If your use case relies on more frequent updates, add the key NSSupportsLiveActivitiesFrequentUpdates
to your Info.plist as a Boolean type set to YES as directed in Apple’s Developer Docs. User will be presented with a dialog when the Live Activity exceeds its push budget, and if they allow the Live Activity to continue, the budget will automatically be increased for a seamless user experience.
Need help?
Chat with our Support team or email support@onesignal.com
Please include:
We’re happy to help!