القالب العام

قالب مرن قائم على التقدّم يناسب عمليات البناء والتنزيلات وعمليات النشر وأي مهمة طويلة الأمد.

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

بدء نشاط عام

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