feat: add support for scheduled Live Activities via startDate

[ebellumat]

feat: add support for scheduled Live Activities via startDate

Adds support for Apple's Activity.request(startDate:) API, allowing Live Activities to be scheduled to appear at a future date instead of immediately. Requires iOS 17.2+. Fully backward-compatible.

Handles the iOS 26.0 deprecation — uses the new start: parameter on iOS 26+ and falls back to startDate: on earlier versions.

How it works

Three reserved attribute keys (prefixed with _ to avoid collisions):

Key	Type	Description
_startDate	Double	Unix timestamp (ms) — when the activity should appear
_alertTitle	String	Notification title shown at start
_alertBody	String	Notification body text

When _startDate is present, Activity.request(startDate:) is called with an AlertConfiguration. When absent, existing behavior is preserved.

Usage

ActivityKit.startActivity(
  {
    name: "My Activity",
    _startDate: Date.now() + 1000 * 60 * 30, // 30 min from now
    _alertTitle: "Activity is Live!",
    _alertBody: "Tap to open",
  },
  contentState,
  options
);

Use case

Schedule Live Activity state transitions on-device — no server push, no background tasks. Example: start a countdown now, schedule a "LIVE" activity to appear automatically at the target time.

Use case: I was struggling to change a counter to show a simple text after the countdown reaches zero, using two live activities scheduled instead of just one, did the job just right! This way we can transition between states easily.

Working example:
https://github.com/user-attachments/assets/dc4f84ef-32d5-4e85-bfea-3f3d69732dbe

[changeset-bot]

⚠️ No Changeset found

Latest commit: 047bbab

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR