Live Activities developer setup

​

Requirements

• Follow the iOS SDK setup if using native iOS (Swift/Objective-C).
  • If using a wrapper SDK (React Native, Flutter, Unity, etc.) follow Mobile SDK setup and then Cross-platform Live Activity SDK Setup.
• OneSignal iOS SDK version 5.2.0+ for push-to-start support (see release notes).
• iOS 16.1+ and iPadOS 17+
• Use a .p8 APNs key. Apple doesn’t support p12 certificates with Live Activities.
• Xcode 14 or higher

​

Setup

​

1. Add a Widget Extension

Add a new Widget Extension target for your app in Xcode.

Widget Extension options for a Live Activity.

Widget Extension options for a Live Activity.

​

2. Update Info.plist

Add Supports Live Activities key to Info and set its value to Boolean YES

<key>NSSupportsLiveActivities</key>
<true/>

​

3. Add SDK

• Package Manager
• Cocoapods

In your Widget Extension target, add the OneSignalFramework under General > Frameworks, Libraries and Embedded Content:

Add the OneSignalFramework to your Widget Extension target

​

4. Define widget attributes and UI

• your-nameAttributes describes the static content of your Live Activity.
• ContentState describes the dynamic content of your Live Activity.

import ActivityKit
import WidgetKit
import SwiftUI
// Import the OneSignalLiveActivities module
// If you get an error about the module not being found, return to step 3 and ensure you have added the OneSignalLiveActivities pod correctly.
import OneSignalLiveActivities

// Update to inherit from OneSignalLiveActivityAttributes
// This will be used in your API requests to start a Live Activity
struct OneSignalWidgetAttributes: OneSignalLiveActivityAttributes  {
    // Update to inherit from OneSignalLiveActivityContentState
    public struct ContentState: OneSignalLiveActivityContentState {
        // Dynamic stateful properties about your activity go here!
        var emoji: String
        // Add a reference to OneSignalLiveActivityContentStateData?
        var onesignal: OneSignalLiveActivityContentStateData?
    }
    // Fixed non-changing properties about your activity go here!
    var name: String
    // Add a reference to OneSignalLiveActivityAttributeData
    var onesignal: OneSignalLiveActivityAttributeData
}

struct OneSignalWidgetLiveActivity: Widget {
    var body: some WidgetConfiguration {
      // Update to use `for: the-name-of-your-attributes-struct`
      // This will be used in your API requests to start a Live Activity
        ActivityConfiguration(for: OneSignalWidgetAttributes.self) { context in
            // Lock screen/banner UI goes here
            // Update to show the attributes sent via the payload
            VStack {
                Text("Hello \(context.attributes.name) \(context.state.emoji)")
            }
            .activityBackgroundTint(Color.cyan)
            .activitySystemActionForegroundColor(Color.black)

        } dynamicIsland: { context in
            DynamicIsland {
                // Expanded UI goes here.  Compose the expanded UI through
                // various regions, like leading/trailing/center/bottom
                DynamicIslandExpandedRegion(.leading) {
                    Text("Leading")
                }
                DynamicIslandExpandedRegion(.trailing) {
                    Text("Trailing")
                }
                DynamicIslandExpandedRegion(.bottom) {
                    Text("Bottom \(context.state.emoji)")
                    // more content
                }
            } compactLeading: {
                Text("L")
            } compactTrailing: {
                Text("T \(context.state.emoji)")
            } minimal: {
                Text(context.state.emoji)
            }
            .widgetURL(URL(string: "http://www.apple.com"))
            .keylineTint(Color.red)
        }
    }
}

​

5. Allow main target membership

Allow main target membership

​

6. Add the setup method to your AppDelegate

// Import the OneSignalLiveActivities module
import OneSignalLiveActivities

// This should be added after initializing the OneSignal SDK
if #available(iOS 16.1, *) {
	OneSignal.LiveActivities.setup(OneSignalWidgetAttributes.self)
  // If you have multiple Live Activities, you can add them here with the setup method
  // OneSignal.LiveActivities.setup(LiveActivityWidgetAttributes-2.self)
}

​

Starting a Live Activity

• Push-to-start
• Trigger-in-app

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.
  curl

  Copy

  curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/activities/activity/OneSignalWidgetAttributes' \
  --header 'Authorization: key YOUR_APP_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "event": "start",
      "activity_id": "push-to-start",
      "included_segments": [
          "Subscribed Users"
      ],
      "event_attributes": {
          "name": "World"
      },
      "event_updates": {
          "emoji":"🤩"
      },
      "name": "Live Activities Test",
      "contents": {
          "en": "A push started this Live Activity"
      },
      "headings": {
        "en": "Live Activity Started"
      }
    }'
  

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.

​

Updating a Live Activity

curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/live_activities/push-to-start/notifications' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key YOUR_API_KEY' \
--data '{
    "event": "update",
    "event_updates": {
        "emoji": "😎"
    },
    "contents": {
        "en": "A push updated this Live Activity"
    },
    "name": "Live Activity Updated"
}'

Live Activity Updated

​

Ending a Live Activity

curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/live_activities/my_activity_id/notifications' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key YOUR_API_KEY' \
--data '{
    "event": "end",
    "event_updates": {
        "emoji": "👋"
    },
    "contents": {
        "en": "A push ended this Live Activity"
    },
    "name": "Live Activity Ended"
}'

• Use our SDK exit() method.
• User manually swipes the Live Activity away.
• User revokes permission for Live Activities in their iOS Settings.

Live Activity Ended

​

Best practices & recommendations

​

Design considerations

• Follow Apple’s Live Activities Human Interface Guidelines.
  • Prioritize important information to make it easy to understand at a quick glance.
  • Don’t add elements to your app that draw attention to the Dynamic Island.
  • Use margins and maintain space between elements.
  • Use a bold color for the background. Design for both Light and Dark mode.

​

Functionality

• Apple requires each Live Activity presentation to be supported.
  • Compact
  • Minimal
  • Expanded
  • Lock Screen
• Test your deep links.
• Review Apple’s guide on Displaying Live Data with Live Activities.
• Avoid displaying sensitive information in a Live Activity.

​

Setting a fallback message

• In certain cases where the user is unable to receive an update to their live activity, after one has been started, opening the app should refresh them to continue
  • To account for this, you would set the stale date to a date and time in the future, after you know you would have sent your first update to the user, and those who have not received the update would get shown the fallback message.
  • You can listen for this “stale” state in your widget UI to show a fallback message:
  swift

  Copy

    struct ptsLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: ptsAttributes.self) { context in
            //This will flip to true after the stale date
            let isStale = context.isStale 
            if !isStale{
                VStack {
                    Text("\(context.attributes.name) \(context.state.emoji)")
                        .activityBackgroundTint(Color.cyan)
                        .activitySystemActionForegroundColor(Color.black)
                }
            }  else {
            //If the message is stale, we request the user clicks the widget to open the app
                VStack {
                    Text("Something went wrong, please click to refresh")
                }
            }
    //... Rest of the widget UI
    }
  

---

## FAQ

### What is the budget for high-priority updates?

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:
- Use a mix of priority levels: Apple recommends using both `priority: 5` (standard) and `priority: 10` (high) for balance.
- Reserve `priority: 10` for time-sensitive or critical updates only (e.g., order status changes, game scores).

If your use case requires frequent updates:
- Add the key `NSSupportsLiveActivitiesFrequentUpdates` to your app’s `Info.plist` file, set as a Boolean `YES`.
- When this budget is exceeded, iOS may prompt the user to allow additional updates. If the user agrees, Apple will automatically expand the allowed update limit to maintain a seamless experience.

For more details, refer to [Apple's Developer Docs](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency).

### Can I read Live Activity updates from the main app?

Yes. You can observe updates for debugging or UI sync:

```swift
Task {
    for await content in activity.contentUpdates {
        print("LA activity id: \(activity.id), content update: \(content.state)")
    }
}
// Example output:
// LA activity id: EFE6D54D-F7E1-45EF-9514-4C2598F8DED2, content update: ContentState(message: "My message from payload")

Task {
    for await state in activity.activityStateUpdates {
        print("LA state update: \(state)")
        //If you wanted to do something based on the state, you would use this:
      	if state != ActivityState.active {
            //Do something here
        }
    }
}

// Example output 1 - LA ended, but still visible
// LA state update: active

/* State can be equal to 4 possible values on the ActivityState enum
active, dismissed, ended, and stale
*/

​

The API returned a 400 with an error message stating I’m over the subscriber limit. What do I do?

​

How do I avoid sending both push and Live Activities?

​

Troubleshooting

​

No recipients

1. 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.
2. 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 request
• activity_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.
• A targeting parameter like included_segments. Available options.

​

Activity sent, but not received

1. 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.
2. 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.