Modèle Timer

Un minuteur dont le cycle de vie est géré par le serveur : envoyez un seul push de démarrage, et le serveur déclenche lui-même les mises à jour d'avertissement et de fin.

Fields

Field	Type	Description
`template`	string	Required. `"timer"`, or `"countdown"`, the template's original name. Both are accepted; responses and pushes report `"countdown"`
`progress`	float	Initial progress (usually `0.0`); the completion push sets `1.0`
`duration`	string	Required (or `end_date`). Server-side convenience — converted to `end_date` before reaching the device. Accepts: `"30s"`, `"5m"`, `"1h30m"`, or plain seconds (`"1500"`)
`end_date`	integer	Required (or `duration`). Unix timestamp when the countdown expires
`start_date`	integer	Unix timestamp when the countdown began. Must be less than `end_date`. Used to compute progress on-device.
`duration`	string	Counting down: required (or `end_date`). Server-side convenience — converted to `end_date` before reaching the device. Accepts: `"30s"`, `"5m"`, `"1h30m"`, or plain seconds (`"1500"`). Rejected counting up
`end_date`	integer	Counting down: required (or `duration`). Unix timestamp when the countdown expires. Rejected counting up
`start_date`	integer	Counting down: Unix timestamp when the countdown began, less than `end_date`; used to compute progress on-device. Counting up: the instant the clock counts up from; defaults to now and may be in the past, at most 5 minutes ahead
`warning_threshold`	integer	Seconds before `end_date` to send a warning push (accent turns orange)
`completion_message`	string	Text shown when countdown expires (default: "Completed")
`state`	string	Status text (e.g. "Baking", "Printing")
`icon`	string	SF Symbol name or MDI icon with `mdi:` prefix (e.g. `"mdi:timer-outline"`)
`subtitle`	string	Secondary text
`accent_color`	string	Named color or hex
`background_color`	string	Background color override
`text_color`	string	Text color override
`alarm`	boolean	Opt-in: schedule an iOS AlarmKit alarm at `end_date` that rings through silent mode and Focus, with built-in Dismiss and Snooze. iOS 26+ only. Persists across partial updates until cleared with `alarm: null` or a transition to `ended` — see Alarms.
`snooze_seconds`	integer	How long the alarm's Snooze button defers the alarm, in seconds (60–3600). Defaults to `300` (5 minutes).
Bientôt dans la version 1.14.0 de l'app
`compact_label`	string	Optional, max 4 characters. Replaces the icon in the Dynamic Island compact leading ear. The minimal presentation ignores it.
Bientôt dans la version 1.19.0 de l'app
`direction`	string	`"down"` (the default) counts down to `end_date`; `"up"` counts up from `start_date`. See Counting up
`goal`	integer or string	Counting up only: a target in seconds (`7200`) or a duration string (`"2h"`, `"90m"`), returned as seconds. See Goal
`show_ruler`	boolean	Whether the card draws its ruler, in either direction. Defaults to `true`. See Hiding the ruler
`paused`	boolean	Write-only switch: `true` pauses the clock, `false` resumes it, in either direction. Never stored or returned. See Pausing
`paused_at`	integer	Read-only, set by the server: the Unix timestamp the clock was paused at. Absent while it runs
`paused_seconds`	integer	Read-only, counting up only: the seconds spent paused so far, which the clock leaves out

Accepts url_action, secondary_url_action, and tap_action — tap_action is useful for deep-linking back into the timer's source app while it runs. See Tap actions.

Example Payload

Démarrer un compte à rebours

{
  "state": "ongoing",
  "content": {
    "template": "timer",
    "progress": 0.0,
    "state": "Baking",
    "icon": "flame",
    "subtitle": "25 min timer",
    "duration": "25m",
    "warning_threshold": 60,
    "completion_message": "Done baking!",
    "accent_color": "orange",
    "alarm": true
  }
}

Auto-Managed Lifecycle

After the start push the server manages the remaining lifecycle, in this order; the timer display itself is computed on-device from start_date and end_date, so it counts down in real time without additional pushes.

Phase	Trigger	What the server sends
Start	Your push	Nothing -- your update sets `ended -> ongoing` with the countdown content
Warning	`warning_threshold` seconds remain	An update with `accent_color: "orange"`, automatically
Completion	`end_date` reached	An end push with `completion_message` and `progress: 1.0`

Bientôt dans la version 1.19.0 de l'app

Cette section décrit une fonctionnalité d'une mise à jour de l'app en attente de validation par l'App Store. Elle se déverrouille ici automatiquement dès que la mise à jour est disponible.

direction, goal, show_ruler and paused belong to this template: any other template rejects them.

Counting up

Set direction: "up" and the clock counts up from start_date instead of down to an end: how long a deploy has been running, how long the baby has been asleep, how long the dryer has been on. start_date defaults to now when the run starts and may lie in the past (and at most 5 minutes ahead, for clock drift), so a timer for something that began earlier shows the real elapsed time from the first push.

Compte progressif depuis le début, vers un objectif de 2 heures

{
  "state": "ongoing",
  "content": {
    "template": "timer",
    "direction": "up",
    "start_date": 1767225600,
    "goal": "2h",
    "state": "Sleeping",
    "icon": "moon.zzz.fill",
    "subtitle": "Afternoon nap",
    "accent_color": "indigo"
  }
}

No end. A count-up has no end_date, so end_date, duration, warning_threshold, completion_message, alarm and snooze_seconds are rejected while direction is "up". There is no warning and no completion push: it runs until you end it.
Nothing to push while it runs. The clock ticks on the device. The server keeps the activity alive past the 8-hour limit iOS puts on a Live Activity, for about three days, and redraws the card itself at the first hour, every whole day and the goal. A stale_ttl you set still ends a forgotten run.
Ending freezes the clock. Set state: "ended" and the card keeps the final elapsed time, captioned "Started 21:04 · ended 23:12".
Switching to up starts a new run. Switching to "up" from "down" or from another template, or setting an ended count-up back to ongoing, replaces an unsent start_date with now and drops the count-down fields. Switching back to "down" drops goal, the pause state and an unsent start_date, and needs end_date or duration again.
A different start_date restarts the clock and clears the time spent paused. Re-sending the stored one changes nothing.

Goal

goal gives a count-up a target: integer seconds (7200) or a duration string ("2h", "90m", "1h30m"), from 1 second to 5 years, stored and returned as seconds. The ruler fills toward it, captioned "Goal 2h" opposite the start time. Once the goal passes, the clock, the ruler and the caption turn orange and the clock keeps counting, with "+12:05 over 2h" for the overtime; the server redraws the card at that moment, so no push is needed. Clear it with "goal": null. Without a goal the card shows the clock and "Started 21:04". On a count-down, goal is a 422.

ℹ Info

Counting up, pausing and show_ruler need PushWard 1.19.0 or later on the device. Older versions show a count-up timer as finished, ignore show_ruler and keep counting down through a pause, so set state to text that still reads right there.

Pausing

paused is a switch, not a stored field: send true to pause a running clock and false to resume it, in either direction. Re-sending the switch's current state changes nothing, so a producer can include paused on every update; counting down, leave the window fields out of those updates (below). While paused the clock stands still, dimmed, with a Paused pill and the pause glyph in place of the icon.

Mettre en pause, puis reprendre

{ "content": { "paused": true } }

{ "content": { "paused": false } }

Counting up, the time spent paused is left out of the clock. On resume the server adds the gap to paused_seconds, so the clock carries on from where it stopped and "Started 18:19" stays true: the clock reads paused_at (or now, while running) minus start_date minus paused_seconds. A count-up that ends while paused stops at the moment it was paused.
Counting down, a resume moves end_date (and start_date) on by the paused time, so the time left is where it was and the activity is a plain countdown again. The warning and completion updates wait while it is paused, and an armed alarm is cancelled for the pause and rescheduled at the new end. A countdown that has already finished cannot be paused (422).
Any end_date or duration in a request starts a new window, even the stored value, and clears a count-down's pause. A producer that re-sends its whole state would re-pause at the moment of each update and lose the paused time on resume, so leave both out of a count-down's updates while it is paused and when resuming it.
Reading the state back. A paused activity carries the server-set paused_at, and a count-up carries paused_seconds once it has been resumed. Both are read-only: values you send are ignored, only the switch moves them.
No pushes while paused. A paused timer stays alive past the 8-hour limit the same way a running count-up does.

Hiding the ruler

The ruler under the clock shows the countdown's span, or a count-up's way to its goal. It is on by default; "show_ruler": false hides it in either direction and leaves the big clock and its caption. A count-up without a goal has no ruler to hide.