Receiving Live Activity updates and alerts on an accessory
Enable your accessory to receive forwarded Live Activities by updating your data provider extension.
Overview
To receive forwarded Live Activities on your accessory and alert people about Live Activity updates, you use an extension model that handles secure communication between iPhone and your accessory. Before adding support for Live Activity forwarding, you need to adopt iOS system notification forwarding and implement the extensions that handle communication between iPhone and your accessory. For more information, see Receiving iOS notifications on an accessory.
In the AccessoryDataProvider extension you create when you add support for receiving notifications on your accessory:
Add the capability to receive forwarded Live Activities.
Add a LiveActivityForwarding.AccessoryLiveActivitiesHandler implementation to the extension to receive forwarded Live Activities and prepare them for transmission.
Add code to check if the person authorized Live Activity forwarding.
Add the capability
Your app receives and handles Live Activity alert updates in the AccessoryDataProvider extension you created when you implemented iOS system notification forwarding. In the extension’s target properties, update the extension point identifier com.apple.accessory-data-provider and add an entry to the EXCapabilities array for AccessoryLiveActivities.LiveActivityForwarding:
<plist>
<dict>
<key>EXAppExtensionAttributes</key>
<dict>
<key>EXExtensionPointIdentifier</key>
<string>com.apple.accessory-data-provider</string>
<key>EXCapabilities</key>
<array>
<string>AccessoryNotifications.NotificationsForwarding</string>
<string>AccessoryLiveActivities.LiveActivityForwarding</string>
</array>
</dict>
</dict>
</plist>Implement a handler in your data provider extension
Update the AccessoryDataProvider protocol to include LiveActivityForwarding and provide a handler that conforms to LiveActivityForwarding.AccessoryLiveActivitiesHandler. The following code shows the AccessoryDataProvider struct conformance:
@main
struct DataProvider: AccessoryDataProvider {
var extensionPoint: AppExtensionPoint {
Identifier("com.apple.accessory-data-provider")
Implementing {
LiveActivityForwarding {
LiveActivitiesHandler()
}
}
}
}Implement your handler class by conforming to LiveActivityForwarding.AccessoryLiveActivitiesHandler. At minimum, implement activate(for:) to store the session and sessionInvalidated() to clean up when the session ends:
/// Respond to Live Activity alert updates from the system.
final class LiveActivitiesHandler: LiveActivityForwarding.AccessoryLiveActivitiesHandler {
private var session: LiveActivityForwarding.Session?
func activate(for session: LiveActivityForwarding.Session) {
self.session = session
// Load existing Live Activities as described in the next section.
}
func sessionInvalidated() {
session = nil
// Clean up display state on the accessory.
}
// Implement remaining protocol methods.
}Load existing activities when a session starts
When a Live Activity starts, the system calls your handler’s activate(for:) function. Store its LiveActivityForwarding.Session object and use it to read the current set of Live Activities and to send AccessoryMessage payloads to the accessory.
When the system activates the session, use liveActivities to fetch a snapshot of all active Live Activities and synchronize the accessory’s display before new updates arrive:
func activate(for session: LiveActivityForwarding.Session) {
self.session = session
Task {
do {
let activities = try await session.liveActivities
for activity in activities {
// Send Live Activity information to your accessory.
}
} catch {
// Handle the error appropriately.
}
}
}Process Live Activity updates and forward them to your accessory
When the system forwards a Live Activity update to your data provider extension, it provides your handler with an AccessoryLiveActivity object you use to update the accessory’s display. Use activityUpdated(_:) to update your accessory to reflect the current Live Activity state. When the update includes an alert, the system calls activityUpdatedForAlert(_:) instead. Return a Bool indicating whether your accessory displayed the alert so the system coordinates alert delivery across devices.
If the callback’s activity’s state property equals ActivityState.dismissed, remove the Live Activity from the accessory’s display.
To send forwarded Live Activities from your data provider extension to your accessory, use the extension model and code you added to support iOS system notifications. For more information, see Receiving iOS notifications on an accessory.
Avoid duplicated alerts across devices
When a Live Activity update includes an alert, the system ensures the person receives the alert without duplication across devices. To coordinate between your accessory or iPhone and determine whether to display an alert, the system calls activityUpdatedForAlert(_:) and waits for your Bool return value before determining where to display the alert. Returning true tells the system to suppress the alert on iPhone — your accessory is responsible for notifying the person. The return value is a commitment. Only return true from activityUpdatedForAlert(_:) after confirming the accessory displays the alert. If the accessory can’t confirm it displayed the alert — for example, if the accessory is out of range — return false to let iPhone display the alert.
Display the source app icon
A person might have multiple active Live Activities. To help people keep track of multiple Live Activities, visually distinguish them by loading the app icon of the app that started the Live Activity. Use sourceBundleIcon to load the source app icon.
If the icon is available, immediately read it by using the url as shown in the following example. The URL is ephemeral. Don’t store it for later access.
func loadIcon(from iconFile: AccessoryLiveActivity.IconFile) async throws -> Data {
let url = try await iconFile.url
return try Data(contentsOf: url)
}Send forwarded Live Activities to your accessory securely
To send forwarded Live Activities to your accessory, use the AccessoryTransportSecurity and AccessoryTransportAppExtension extensions you create when you add support for receiving forwarded iOS system notifications. For more information about securely sending Live Activity and notification content to your accessory, see Receiving iOS notifications on an accessory.
Check for permission
The initial authorization to allow Live Activity forwarding happens in a unified system prompt that allows people to set permissions for iOS system notification and Live Activity forwarding when they configure the accessory. However, people can change permissions at any time in Settings, or choose to deny Live Activity forwarding during initial setup. Additionally, authorization is per physical accessory. As a result, check whether someone authorized Live Activity forwarding for your accessory before you perform any additional logic. For example, check for authorization before indicating in your UI that Live Activity forwarding is active.
Call authorization(forAccessory:) to check the current authorization state. The method returns an AccessoryAuthorizationResult, which specifies if the authorization is allowed, limited to some apps, or denied. If the authorization result is .undetermined, the person hasn’t seen the system UI for authorizing notification and Live Activity forwarding. Use the Accessory Notifications framework and requestForwarding(for:) to register for notification and activity forwarding and display the system UI.
If someone denies authorization — dismissing the system UI counts as denying forwarding — or only allows a limited scope, you can ask them to update their choice by calling presentAuthorizationSheet(forAccessory:) to display the system authorization UI. Pass the accessory’s corresponding ASAccessory instance from AccessorySetupKit each time — authorization is per accessory and isn’t cached globally.
The following code checks the current authorization state:
func checkAuthorization(for accessory: ASAccessory) async throws {
let result = try await LiveActivityForwarding.authorization(
forAccessory: accessory
)
switch result {
case .allow, .limited:
// Add code specific to your app that's related to Live Activity forwarding.
// For example, you might set a flag that helps the
// companion app display UI that indicates Live Activity forwarding.
case .deny:
// Present the system UI that lets the person update their Live Activity forwarding authorization.
let updatedAuthorization = try await LiveActivityForwarding
.presentAuthorizationSheet(forAccessory: accessory)
if updatedAuthorization == .allow || updatedAuthorization == .limited {
// Add code specific to your app that's related to Live Activity forwarding.
// For example, you might set a flag that helps the
// companion app display UI that indicates Live Activity forwarding.
}
case .undetermined:
// Prompt for permission to opt into notification and activity forwarding.
let center = AccessoryNotificationCenter()
try await center.requestForwarding(for: accessory)
}
}