Learn how to set up Live Activities on your iOS app with OneSignal to display real-time updates.
Add a new Widget Extension target for your app in Xcode.
OneSignalWidget
) and ensure Include Live Activity is selected. Then click Finish.
Widget Extension options for a Live Activity.
Widget Extension options for a Live Activity.
Info.plist
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
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.OneSignalFramework
under General > Frameworks, Libraries and Embedded Content:Add the OneSignalFramework to your Widget Extension target
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.OneSignalWidgetLiveActivity.swift
file.
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
OneSignal.LiveActivities.setup
in your AppDelegate
, after OneSignal SDK initialization.
Replace OneSignalWidgetAttributes
with the name of your Live Activity attributes struct.
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.
Live Activity on the lock screen
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
"event": "end"
.
exit()
method.Live Activity Ended
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).NSSupportsLiveActivitiesFrequentUpdates
to your app’s Info.plist
file, set as a Boolean YES
.support@onesignal.com
. For the latest plan details, please see here.
OneSignal.Initialize
method and the activity type must match that of the type you’ve defined in your Live Activity file.
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.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.
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.
support@onesignal.com
Please include: