Mẫu Generic

Một mẫu linh hoạt dựa trên tiến trình, phù hợp cho các bản dựng, tải xuống, triển khai và bất kỳ tác vụ chạy lâu nào.

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
Sắp có trong phiên bản ứng dụng 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

Bắt đầu một activity generic

{
  "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

Sắp có trong phiên bản ứng dụng 1.3.3

Phần này mô tả một tính năng trong bản cập nhật ứng dụng đang chờ App Store xét duyệt. Tính năng sẽ tự động mở khóa tại đây ngay khi bản cập nhật được phát hành.

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.

ℹ Thông tin

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.

💡 Mẹo

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