일반 템플릿

빌드, 다운로드, 배포 등 오래 실행되는 모든 작업에 적합한 유연한 진행률 기반 템플릿입니다.

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
앱 버전 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

앱 버전 1.3.3에서 제공 예정

이 섹션은 App Store 심사를 기다리고 있는 앱 업데이트의 기능을 설명합니다. 업데이트가 출시되면 여기에서 자동으로 잠금 해제됩니다.

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