Timer テンプレート

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.

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

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.

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