Live Activities Setup

How to set up Live Activities on your iOS Mobile App with OneSignal

Live Activities is an iOS feature introduced in October 2022 for displaying live information via a widget that is shown on the device lock screen and in the dynamic island (when available). They are intended to display data that changes during a time window, such as sports scores, delivery statuses, and other real-time transactional updates.

OneSignal is the easiest way to implement support for iOS Live Activities in your application. We take care of helping you start, update, and end live Activities, as well as:

  • Managing the temporary push tokens associated with Live Activities
  • Updating all active live activities with a single API call for up to tens of millions of devices
  • Providing real-time analytics on your delivery of Live Activities and how users are engaging with them
  • Powering your other user engagement channels, such as Push Notifications, Email, SMS, and In-App Messaging

📘

Live Activities are available on all plans except for Free plans with more than 10,000 opted-in subscribers.

If you have more than 10,000 opted-in subscribers on a Free Plan, you can upgrade to use Live Activities. Feel free to reach out to Support if you require any more guidance or help with pricing.

Requirements

  • An iOS / iPadOS Application (Live Activities are only available on the iPhone and iPad).
  • Ensure you are using a .p8 key. Check out our guide, iOS: Establishing a Token-Based Connection to APNs (.p8 Key), if migrating away from a .p12 certificate.
  • Live Activities are available on iOS 16.1+, which is supported on iPhones made in 2017 or newer, and iPadOS 17 and later.
  • Xcode 14 and later.
  • The latest iOS SDK or wrapper.

Setup

If you have not already integrated our iOS SDK, please refer to this iOS SDK Setup Guide. The following steps require updates to your mobile app project within Xcode.

1. Add a Widget Extension

1.1 Create a new target

Go to File > New > Target.

1.2 Select Widget Extension

Add a new widget extension target for your app in Xcode.

Add a new widget extension target for your app in Xcode.

1.3. Configure Widget Extension

Provide a name and ensure Include Live Activity is selected.

1000

Widget extension options for a Live Activity.

1.4 Click "Finish".

2. Update Info list

Locate the Info.plist in the main target, add the key “Supports Live Activities”, and set it to YES.

If you do not see this option, hover over "Information Property List" to reveal a "+" button, where you can then search for the “Supports Live Activities” key.

991

Adding support Live Activities key to Info list and setting its value to Yes

If you still do not see this property, ensure you are using Xcode 14+.

This adds to the Info.plist file is as follows:

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

3. Testing

Now you are ready to test a Live Activity! Once you have confirmed a successful Live Activity setup and are ready to create and send a custom Live Activity, read our guide on How to Create and Update iOS Live Activities.

1. Navigate to the ContentView file of your project in Xcode

2. Replace the existing ContentView code in the main target with the following:

import SwiftUI
import ActivityKit
import OneSignalFramework

class LiveActivityViewModel: ObservableObject {
    func startLiveActivity() {
        let attributes = [Your live activity extension name]Attributes(name: "Hello World")
        let contentState = [Your live activity extension name]Attributes.ContentState(emoji:"🤩")
        
        do {
           let activity = try Activity<[Your live activity extension name]Attributes>.request(
                attributes: attributes,
                contentState: contentState,
                pushType: .token)
            
            Task {
                for await data in activity.pushTokenUpdates {
                    let myToken = data.map { String(format: "%02x", $0) }.joined()
                    OneSignal.LiveActivities.enter("my_activity_id", withToken: myToken)
                }
            }
        } catch {
            print(error.localizedDescription)
        }
    }
}

struct ContentView: View {
    @StateObject private var viewModel = LiveActivityViewModel()    
    var body: some View {
        VStack {
            Button("Start Live Activity") {
                viewModel.startLiveActivity()
            }
        }
    }
}

Go back to the "[Your live activity extension name]Live Activity" file under your newly created widget target and ensure "Target Membership" is allowed at the main app level.

3. Run the build

Open your app on a device or in the simulator to reveal the "Start Live Activity" button. Click on it to launch the Live Activity.

4. Click "Start Live Activity"

Start a Live Activity button showing on app

Start a Live Activity button showing on app

5. Check the lock screen

Live Activity showing on the lock screen in the Simulator

Live Activity showing on the lock screen in the Simulator

Recommended

Review Apple's guide on displaying Live Activities

Live Activities use WidgetKit functionality and SwiftUI for their user interface. Read Apple's Guide Displaying live data with Live Activities.