Live Activities
A quick start guide to adding Live Activity support to your iOS application with the Pushly PushSDK
Live Activities, introduced by Apple in October 2022, allow app developers to display dynamic, live-updating, content via widgets on device lock screens and in the Dynamic Island (for capable devices).
The PushSDK helps you streamline Live Activity registration and updates by allowing developers to register and manage the short-lived push tokens associated with your Live Activities which can then be updated via our server API.
Prerequisites
Before you can integrate Live Activities with the SDK the following requirements must be met:
An iOS Send Integration configured with a .p8 key.
An iOS app (Live Activities are only available for iOS and iPadOS).
A device or emulator with iOS 16.1 or newer installed
PushSDK release supporting Live Activities (See version support chart below)
Step 1: iOS SDK Setup
For applications not already using the PushSDK please see our Native App Push setup guide for Apple / iOS.
For applications already using the PushSDK you might need to upgrade to a later version that includes Live Activity support. Use the following tables to determine if you need to upgrade your installation.
1.3.9+ (Requires iOS 17.2+)
Within the Xcode project navigator panel locate Package Dependencies
. Locate and right-click on Pushly
and select Update Package
.

If after an update the package is not >= version 1.2.0 select your Project in the project navigator, select your project, and then navigate to Package Dependencies
. Select Pushly
and ensure the Dependency Rule
is set to Up to Next Major Version
with 1.0.0, or greater, as the target.

Step 2: Add Live Activity Support to Info.plist
Applications implementing Live Activities must set the Supports Live Activities
key to YES
in their primary target info.plist.

If one of your use cases utilizes frequent updates you should also consider setting Supports Live Activities Frequent Updates
to YES
in the info.plist.
Step 3: Add a Live Activity Widget Extension
Within your app's Xcode project select File > New > Target
. Select Widget Extension
inside the iOS templates tab and click Next
.

Enter your desired Live Activity widget name for the Product Name
and any other configuration details for your widget extension, making sure that Include Live Activity
is selected, and then click Finish
. On the subsequent dialog click Cancel
to continue developing without activating the new widget extension as the current target.

Step 4: Setup a Live Activity
User Interface
Before starting your new Live Activity we recommend reading through Apple's guide to Displaying live data with Live Activities.
Starting Your Live Activity
Once your Live Activity has been designed and setup you are now ready to start and register it via the PushSDK.
To aid in tracking and updating multiple Live Activity instances across millions of devices via a single API call we use an activity ID. Activity IDs are string values provided by you, the developer.
In some scenarios, such as sporting events, you may want to send a single update to all devices registered to a single event. In these cases you should use a unique ID that identifies the event rather than an ID per individual user.
In other scenarios, such as meal orders, Live Activities are user specific. In these cases you should use a unique ID that identifies the individual user.
Step 5: Starting a Live Activity
Starting from Within the App
The following code snippet requests to start a Live Activity using the MyLiveActivityAttributes
struct with an eventId
attribute that will uniquely identify this instance of the activity and then registers the activity with the PushSDK to observe and collect any token updates.
import UIKit
import ActivityKit
import Pushly
class ViewController: UIViewController {
public func startLiveActivity() {
if #available(iOS 16.1, *) {
let attributes = MyLiveActivityAttributes(eventId: "my_activity_id")
let contentState = MyLiveActivityAttributes.ContentState(
home_team: "Chiefs",
home_team_score: 0,
away_team: "Chargers",
away_team_score: 0)
let activityContent = ActivityContent(
state: contentState,
staleDate: nil)
do {
let activity = try Activity<MyLiveActivityAttributes>.request(
attributes: attributes,
contentState: activityContent,
pushType: .token)
// Register the activity with Pushly using the eventId attribute
PushSDK.LiveActivities.register(
activity,
withId: activity.attributes.eventId)
} catch (let error) {
print(error.localizedDescription)
}
}
}
}
Registering an Activity Type for Starting via Push
The following code snippet will start observing an Activity type and register and push-to-start tokens as well as ensure any started or already running activities are registered for push token collection as well. We will once again be using the MyLiveActivityAttributes
class with an eventId
attribute that will uniquely identify this instance of the activity.
import UIKit
import ActivityKit
import Pushly
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
...
if #available(iOS 16.1, *) {
// Register the activity type with Pushly
PushSDK.LiveActivities.register(Activity<MyLiveActivityAttributes>.self) { activity in
// Register the specific activity with Pushly
PushSDK.LiveActivities.register(activity, withId: activity.attributes.eventId)
}
}
}
}
Sending the Start Event
Once you have registered the activity type with the PushSDK you can use our Live Activity API documentation to send a start event by specifying the corresponding attributes struct name in the activity.ios.data.attributes_type
property and passing the associated unique activity identifier in both the activity.ios.data.attributes
object and the request path - in this scenario we used the eventId
attribute set to my_activity_id
which we can then use in subsequent update events.
POST Request to:
https://api.pushly.com/domains/{domain_id}/live-activities/my_activity_id
{
"name": "my-request-event-name",
"event": "start",
"activity": {
"ios": {
"data": {
"relevance_score": 100,
"priority": 10,
"attributes_type": "MyLiveActivityAttributes",
"attributes": {
"eventId": "my_activity_id"
},
"content_state": {
"home_team": "Chiefs",
"home_team_score": 0,
"away_team": "Chargers",
"away_team_score": 0
},
"notification": {
"title": "A Live Event Has Started",
"body": "Stay tuned for more updates!"
}
}
}
}
}
PNActivityAttributes Protocol
The PushSDK also provides a simple protocol, PNActivityAttributes
, that requires an attribute of pnActivityId
which will be used to uniquely identify the activity. When using this protocol the method signatures are simplified as the ID is auto collected for token registrations in activities started both locally and via push.
import UIKit
import ActivityKit
import Pushly
struct MyLiveActivityAttributes: PNActivityAttributes {
public struct ContentState: Codable, Hashable {
var home_team: String
var home_team_score: Int
var away_team: String
var away_team_score: Int
}
var pnActivityId: String
}
class ViewController: UIViewController {
public func startLiveActivity() {
if #available(iOS 16.1, *) {
...
// Register the activity with Pushly
PushSDK.LiveActivities.register(activity)
}
}
}
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
...
if #available(iOS 16.1, *) {
// Register the activity type with Pushly
PushSDK.LiveActivities.register(Activity<MyLiveActivityAttributes>.self)
}
}
}
Step 5: Send Your Live Activity an Update
Once the short-lived push tokens have been registered with an activity ID you can use our Live Activity API documentation to send updates to all registered Live Activities via a single request.
POST Request to:
https://api.pushly.com/domains/{domain_id}/live-activities/my_activity_id
{
"name": "my-request-event-name",
"event": "update",
"activity": {
"ios": {
"data": {
"relevance_score": 100,
"priority": 10,
"content_state": {
"home_team": "Chiefs",
"home_team_score": 7,
"away_team": "Chargers",
"away_team_score": 0
}
}
}
}
}
For more information on Starting and updating Live Activities with ActivityKit push notifications see Apple's developer documentation.
Last updated