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).
• OneSignal iOS SDK version 5.2.15+ for click tracking and confirmed receipt.
• iOS 16.1+ or iPadOS 17+ allows starting Live Activities in-app.
• iOS 17.2+ allows starting Live Activities remotely.
• A .p8 APNs key. Apple does not support p12 certificates with Live Activities.
• Xcode 14 or higher.

​

Setup

​

1. Add a Widget Extension

​

2. Update Info.plist

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

​

3. Add SDK

• Package Manager
• Cocoapods

If you are using a wrapper SDK (e.g. Flutter) with SPM enabled, you can skip this step. The OneSignal package is already resolved and available to all targets.

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

Find the name of your widget extension target in your project’s Targets list. Example’s name is OneSignalWidgetExtension.

Open your Podfile and add the following code. Replace OneSignalWidgetExtension with the name of your widget extension target.

Podfile

Full Podfile example

target 'OneSignalWidgetExtension' do
  use_frameworks!
  pod 'OneSignal/OneSignal', '>= 5.0.0', '< 6.0'
end

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:

​

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

​

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 --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"
      }
    }'
  

This example uses the fixed activity_id of push-to-start so you can test quickly. In production, choose the value deliberately: it is the key that determines which devices a later update reaches. See Choose an activity ID.If you are following the example code provided, you should see the Live Activity on your device’s 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.This example uses a button to start the Live Activity manually.

import SwiftUI
import ActivityKit
import OneSignalFramework
import OneSignalLiveActivities

struct ContentView: View {
  @StateObject private var viewModel = LiveActivityViewModel()

  var body: some View {
    VStack {
      Button("Start Live Activity") {
        viewModel.startLiveActivity()
      }
    }
  }
}

class LiveActivityViewModel: ObservableObject {

  func startLiveActivity() {
    let osAttributes = OneSignalLiveActivityAttributeData.create(activityId: "click-to-start")
    let attributes = OneSignalWidgetAttributes(name: "OneSignal", onesignal: osAttributes)
    let contentState = OneSignalWidgetAttributes.ContentState(emoji:"🤩", onesignal: nil)
    do {
        let activity = try Activity<OneSignalWidgetAttributes>.request(
            attributes: attributes,
            contentState: contentState,
            pushType: .token)
    } catch {
        print(error.localizedDescription)
    }
  }
}

Upon clicking the button it will launch the Live Activity.

​

Tracking Live Activity clicks

​

Step 1: Add Click Tracking to Your Widget

import OneSignalLiveActivities

struct ExampleAppFirstWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: ExampleAppFirstWidgetAttributes.self) { context in
            VStack {
                Spacer()
                Text("Sample Text " + context.attributes.title).font(.headline)
                // Other UI code
            }
            .onesignalWidgetURL(URL(string: "myapp://settings"), context: context)
            // Pass nil if you don't need deep linking: .onesignalWidgetURL(nil, context: context)
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.leading) {
                    Text("Leading")
                }
                // Other Dynamic Island regions
            } compactLeading: {
                Text("L")
            } compactTrailing: {
                Text("T")
            } minimal: {
                Text("Min")
            }
            .onesignalWidgetURL(URL(string: "myapp://settings"), context: context)
            // Optional: Track Dynamic Island clicks separately
        }
    }
}

• You can pass a URL for deep linking or nil if you only want click tracking without navigation
• The view hierarchy cannot include Apple’s .widgetURL() modifier if you’re using .onesignalWidgetURL()
• Apply the modifier to both the main Live Activity view and Dynamic Island if you want to track clicks on both

​

Step 2: Handle URLs in Your App

import OneSignalLiveActivities

// AppDelegate example:
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)
    
    // Handle the original URL and navigate user
    if let url = originalURL {
        // Your custom URL routing logic
        return handleDeepLink(url)
    }
    return false
}

// SceneDelegate example:
func scene(_ scene: UIScene, openURLContexts URLContexts: Set) {
    guard let url = URLContexts.first?.url else { return }
    
    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)
    
    if let url = originalURL {
        // Your custom URL routing logic
        handleDeepLink(url)
    }
}

// SwiftUI example:
.onOpenURL { url in
    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)
    
    if let url = originalURL {
        // Your custom URL routing logic
        handleDeepLink(url)
    }
}

​

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_APP_API_KEY' \
--data '{
    "event": "update",
    "event_updates": {
        "emoji": "😎"
    },
    "contents": {
        "en": "A push updated this Live Activity"
    },
    "name": "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_APP_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.

​

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

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
        }
    }
}

​

Live Activity permission observer

import OneSignalLiveActivities

@available(iOS 16.1, *)
private func observeLiveActivityPermissionChanges() {
    let authInfo = ActivityAuthorizationInfo()
    Task.detached(priority: .background) {
        for await enabled in authInfo.activityEnablementUpdates {
            if enabled {
                print("User Clicked Allow")
            } else {
                print("User Clicked Don't Allow")
            }
        }
    }
}

​

FAQ

​

How often can I update a Live Activity?

• Set priority: 5 for routine updates. When you omit priority, OneSignal sends 10 and spends budget, so set it explicitly.
• Reserve priority: 10 for updates that need the user’s immediate attention, such as order status changes or game scores.

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

​

Can I read Live Activity updates from the main app?

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. Any Date fields must be sent as Unix timestamps, not ISO 8601 strings.
• 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. See Choose an activity ID.
• 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. Check the Confirmed Receipt count first. In your message report, if you see a Confirmed Receipt count, this means Apple successfully delivered the update to the device. The issue is likely that the device is preventing the widget from displaying, not a delivery problem. This could be due to:
   • The Live Activity being dismissed by the user
   • Widget configuration issues within the app
2. 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.

3. In your API request, check the priority level. If you are sending 10, try 5 and test again. Only priority: 10 counts against Apple’s budget, and exceeding it causes throttling. If your use case needs frequent high-priority updates, add NSSupportsLiveActivitiesFrequentUpdates to your Info.plist as a Boolean set to YES. See Update frequency and throttling.

​

Conflicts with ActivityKit async sequences

• activityStateUpdates
• pushTokenUpdates
• pushToStartTokenUpdates
• activityUpdates

1. Remove direct observation of these sequences from your app code if possible
2. Use OneSignal.LiveActivities.setup() which handles all observation automatically. Avoid manually observing sequences when using this method
3. If you must use the low-level approach with enter()/exit() and manual token observation, ensure your implementation doesn’t prevent OneSignal from receiving updates