通用範本

一個彈性的進度導向範本，適用於建置、下載、部署及任何長時間執行的工作。

Fields

Field	Type	Description
`template`	string	Required. Must be `"generic"`
`progress`	float	Required. Value between `0.0` and `1.0`
`state`	string	Short status text (e.g. "Building...", "Complete")
`icon`	string	SF Symbol name (e.g. `"arrow.triangle.branch"`, `"washer"`) or MDI icon with `mdi:` prefix (e.g. `"mdi:washing-machine"`, `"mdi:thermometer"`)
`remaining_time`	integer	Remaining time in seconds
`subtitle`	string	Secondary text below the progress bar
`accent_color`	string	Named color or hex (e.g. `"cyan"`, `"#00BCD4"`)
`background_color`	string	Background color override
`text_color`	string	Text color override
將在 app 版本 1.3.3 中推出
`end_date`	integer	Unix timestamp (seconds) for the estimated completion. Acts as the ETA anchor for `live_progress`. See Live progress.
`live_progress`	boolean	When `true`, iOS animates the progress bar and counts the ETA down natively between pushes instead of jumping only when you send an update. Requires `end_date`. See Live progress.

Example Payload

啟動一個通用 activity

{
  "state": "ongoing",
  "content": {
    "template": "generic",
    "progress": 0.65,
    "state": "Washing",
    "icon": "washer",
    "remaining_time": 1800,
    "subtitle": "Cycle 2 of 3",
    "accent_color": "blue"
  }
}

Live progress

將在 app 版本 1.3.3 中推出

本節介紹的功能來自一個正在等待 App Store 審核的 app 更新。更新上線後，此處會自動解鎖。

By default the progress bar only moves when you push an update, so a slow job looks frozen between pushes. Set live_progress: true together with an end_date (the estimated completion, as a Unix timestamp) and iOS animates the bar and counts the ETA down natively on the device between your pushes — smooth motion without spending extra push budget. As with the countdown template, you can send duration (e.g. "10m" or seconds) instead of end_date and the server computes end_date = now + duration for you.

iOS interpolates from the last pushed progress toward completion at end_date, so the bar glides instead of stepping.
Each push re-anchors the animation: send a fresh progress and, if the estimate changed, a new end_date.
If the job stalls and the ETA passes without an update, the bar freezes at the last pushed progress rather than running to 100% on its own — so a stuck task never looks finished.
Updates are merge-patches — fields you omit carry forward. On the update that finishes the job (or the push that ends the activity), clear the countdown explicitly with "end_date": null, "live_progress": null, or the finished card keeps counting toward an ETA that no longer means anything.

ℹ 資訊

live_progress requires end_date (or duration, which resolves to one). Without it there's nothing to animate toward, so the server rejects live_progress: true with 422.

Download with native live progress

{
  "state": "ongoing",
  "content": {
    "template": "generic",
    "progress": 0.4,
    "state": "Downloading",
    "icon": "arrow.down.circle",
    "subtitle": "ubuntu-24.04.iso",
    "end_date": 1750003600,
    "live_progress": true,
    "accent_color": "cyan"
  }
}

Typical Flow

Start (ended -> ongoing): Set progress: 0.0 with an initial status
Update (ongoing -> ongoing): Increment progress, change status text
End (ongoing -> ended): Set progress: 1.0 with a completion status

Buttons & tap targets

Renders url_action and secondary_url_action as buttons beneath the progress bar, and treats taps on the rest of the widget as tap_action. Buttons appear only when their action is present. See Tap actions for the action object shape.

💡 提示

The progress percentage is displayed in the top-right corner of the Live Activity. Use remaining_time to show a countdown alongside the progress bar.

Integrations Using This Template

SABnzbd — tracks download progress with speed and ETA
Bambu Lab — tracks 3D print progress with layer counts and temperature
Home Assistant — default template for entity state tracking