跪拜 Guibai
← All articles
Backend · iOS

Build iOS Live Activities on Windows: KXBuild Handles Extensions, Dynamic Island, and APNs Push

By 00后程序员 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

This tutorial removes the macOS requirement for one of Apple's most engaging features: developers on Windows can now build, sign, and ship Live Activities using KXBuild. The push mechanics and the strict limits (4 KB payload, 8-hour lifespan) are practical constraints that shape real-world use, and the step-by-step approach makes the whole pipeline reproducible.

Summary

KXBuild, a VSCode plugin and CLI for building iOS apps on Windows, adds a Live Activity widget extension to a SwiftUI project with one command. The extension contains both a regular widget and an ActivityConfiguration that renders lock screen and Dynamic Island styles. Data is split into immutable attributes and a mutable ContentState; the app and extension must hold identical definitions. The app starts an activity with Activity.request, updates its state with activity.update, and ends it with activity.end. For server-driven updates, pushType: .token yields a per-activity push token delivered through pushTokenUpdates. APNs pushes use the liveactivity push type and a topic constructed from the app's bundle ID plus .push-type.liveactivity. A Node.js script signs a JWT with a .p8 key and sends test pushes to the sandbox or production endpoint. The tutorial also covers signing profiles, debugging with F5, common failure modes, and packaging a Release IPA that includes the extension.

Takeaways
— Live Activities require iOS 16.1, and the ActivityContent API used in this article needs iOS 16.2; the extension itself targets iOS 17 or later.
— A Live Activity runs for at most 8 hours, then auto-ends; it can remain on the lock screen for up to 4 more hours, making 12 hours the lock screen maximum.
— The combined size of immutable attributes and ContentState must not exceed 4 KB per update, and each push also respects this limit.
— Only iPhones with a Dynamic Island (Pro models from iPhone 14 Pro onward) show the Dynamic Island UI; other models only get the lock screen view.
— The app must declare NSSupportsLiveActivities in Info.plist or build settings, otherwise Activity.request fails.
— Use Activity.request to start, activity.update to change ContentState, and activity.end to finish; wrap request in do/catch to handle authorization or capacity failures.
— Setting pushType: .token generates a per-activity push token; pushTokenUpdates is an async sequence that can emit new tokens at any time.
— APNs pushes for Live Activities require apns-push-type: liveactivity and an apns-topic of <App bundle ID>.push-type.liveactivity (not the extension's ID).
— Date fields in content-state are decoded by the system as seconds since 2001-01-01, not Unix time; subtract 978307200 when constructing the payload.
— Frequent updates require NSSupportsLiveActivitiesFrequentUpdates in Info.plist and user consent; ActivityAuthorizationInfo().frequentPushesEnabled checks the permission.
— Push-to-start is only supported on newer systems; the article notes that iOS 17.1 and earlier cannot use it.
Conclusions

The requirement to keep an identical ActivityAttributes definition in both the app and the widget extension invites maintainability hazards; a single field change must be mirrored or the Live Activity will fail to decode.

The 4 KB payload limit and the 8-hour cap push Live Activity design toward short, event-driven status displays rather than long-running trackers, which constrains the kinds of use cases that fit.

Shipping a Node.js script for APNs pushes demonstrates that the push pipeline is independent of Xcode, making it feasible to automate entirely from a Windows environment.

Concepts & terms
Live Activity
A widget that displays a real-time event (like a food order or a flight) on the lock screen and the Dynamic Island. It is driven by ActivityKit and can be updated by the app directly or through APNs pushes.
ActivityAttributes
A protocol that defines the data structure for a Live Activity. It contains immutable attributes set at launch and a nested ContentState for mutable data that changes on each update.
apns-push-type: liveactivity
An APNs header that tells Apple the push is intended for a Live Activity. It must be paired with an apns-topic ending in .push-type.liveactivity and a per-activity push token obtained from pushTokenUpdates.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗