檢查清單範本
可在鎖定畫面、動態島或 Android 通知中勾選的簡短項目清單。伺服器會記錄每次勾選,推送到所有裝置,並交給你的整合。
本節介紹的功能來自一個正在等待 App Store 審核的 app 更新。更新上線後,此處會自動解鎖。
Send a short list in items and the user ticks it off from the Lock Screen, the expanded Dynamic Island, the Apple Watch or the Mac (Android: below). A tap goes to PushWard, not to your server: PushWard records the tick, pushes the new list to every device, and your integration reads it back from the activity. Your integration can tick items as well, with an ordinary PATCH.
Builds older than 1.30.0 show a checklist as the generic card. The server fills in progress (the share of checked items) and state ("3 of 8") for them, so the card still shows how far the list has come, without the rows.
Fields
| Field | Type | Description |
|---|---|---|
template | string | Required. Must be "checklist" |
items | array | Required, 1-8 items. The rows, see Items. Replaced as a whole on PATCH, so re-send the full list (what happens to ticks) |
auto_end | boolean | Optional, default true: the server ends the activity a few seconds after every item is checked. false keeps a finished list open until you end it (below). On a PATCH, leaving it out keeps the stored value and null sets it back to true |
subtitle | string | A short line beside the name in the card header. The expanded Dynamic Island leaves it out |
icon | string | SF Symbol or mdi: icon at the head of the card and in the compact leading ear |
accent_color | string | Named color or hex for the icon and the check marks |
background_color, text_color | string | Color overrides |
compact_label | string | Optional, max 4 characters. Replaces the icon in the Dynamic Island compact leading ear |
compact_trailing_label, compact_trailing_icon | string | Optional. Replace the count in the Dynamic Island compact trailing ear |
tick_url | string | Read-only, server-owned. The signed URL the devices post ticks to. Stripped from anything you send |
state, progress | string, float | Filled by the server from the items ("3 of 8" and the checked share) for builds that do not draw the checklist. Do not send them |
Every row is a tap target, so the button fields are rejected with 422 on this template: url_action, secondary_url_action and the older url and secondary_url. So are alarm and the approval, media, timer, board, log and image fields. items and auto_end are rejected on every other template. tap_action (tapping the card background) still opens a URL or an app. A webhook tap_action does not run in the background while the list is live, because every row is a button: on the iPhone a tap on the card opens PushWard, which then sends the webhook. Once the activity has ended, the rows are no longer buttons and the webhook runs in the background, as on a card without buttons.
Items
| Field | Type | Description |
|---|---|---|
id | string | Required. 1-16 characters of a-z A-Z 0-9 _ -, unique within items. Ticks name the item by it, so keep it stable while the label changes |
label | string | Required. The row text, 1-40 characters |
checked | boolean | Whether the item is ticked. Left out when the activity is created, it is false. Left out on a PATCH for an item that already exists, it keeps the stored value |
What the card shows
- The count, checked over total (
3/8), in the card header, in the compact Dynamic Island's trailing ear and beside the name in the expanded one. - Unchecked items first, in the order you sent them, then the checked ones, in theirs. The next thing to do is always at the top.
- The Lock Screen card shows up to 4 rows, and "+4 more" under them when there are more. Every row is a button: a tap on an unchecked row ticks it, a tap on a checked row unticks it.
- The expanded Dynamic Island shows the icon and name with the count on one line, a thin bar of the checked share, then the next 2 unchecked items as buttons.
- Once every item is checked, the card reads "All done" until the activity ends.
On a locked iPhone, iOS asks for Face ID or the passcode before any button on a Live Activity runs, and each row is one. That is the platform's rule, not a PushWard setting.
How a tick reaches the server
When it stores a checklist, the server mints one signed URL for the activity, tick_url, and the devices call it when someone taps a row. The server records the tick and pushes the new list to every device, and the row changes when that update arrives, not at the tap, so every device shows the same list. Your integration never calls tick_url: it reads the ticks with GET or ?wait= (below) and ticks items itself with a PATCH.
tick_url is a credential: anyone who holds it can tick and untick that list until the activity is deleted. It comes back in every read of the activity, so do not log or share those reads.
Reading the ticks
There is no callback and no answers feed: read the activity. GET /activities/{slug} returns the items with their current checked. With ?wait=N the request is held open until an item changes or the activity ends, and when the time runs out it returns the activity unchanged, so repeat it to keep waiting. Without wait, a few seconds between requests is plenty.
curl "https://api.pushward.app/activities/release-2-4?wait=25" \
-H "Authorization: Bearer hlk_YOUR_TOKEN"
{
"state": "ongoing",
"content": {
"template": "checklist",
"items": [
{ "id": "changelog", "label": "Write the changelog", "checked": true },
{ "id": "tag", "label": "Tag and push v2.4.0", "checked": true },
{ "id": "images", "label": "Publish the container images", "checked": false },
{ "id": "docs", "label": "Update the docs", "checked": false }
],
...
}
}Changing the list
items is replaced as a whole on every PATCH, so send the full list each time. An item missing from it is removed. For an item whose id is already stored, leaving out checked keeps the value the server has, so you can rename an item, reorder the list or add one without undoing a tick someone made on their phone in the meantime. Send checked only when your integration means to set it. The one exception is an update that restarts an ended activity: that is a new run, and every item sent without checked starts unticked.
curl -X PATCH https://api.pushward.app/activities/release-2-4 \
-H "Authorization: Bearer hlk_YOUR_TOKEN" \
-H "Content-Type: application/merge-patch+json" \
-d '{
"content": {
"items": [
{ "id": "changelog", "label": "Write the changelog" },
{ "id": "tag", "label": "Tag and push v2.4.0" },
{ "id": "images", "label": "Publish the container images", "checked": true },
{ "id": "docs", "label": "Update the docs" },
{ "id": "notes", "label": "Post the release notes" }
]
}
}'Here the first two items keep whatever the phones last ticked, images is ticked by the integration, and notes is new and starts unchecked.
When the list is done
When every item is checked, the server ends the activity a few seconds later, with the same delay as an answered approval. Unticking an item before then keeps it going. dismissal_ttl (an activity-level field) sets how long the ended card stays on the Lock Screen.
To keep a finished list on the devices instead, send "auto_end": false, when you create the list or later. The last tick then leaves the activity running: the card reads "All done" until your integration ends it, or its stale_ttl or the usual lifetime limits do. The flag stays on the server and is never pushed, so it works the same with every app build. Setting it back to true, or to null, while every item is checked ends the activity after the same short delay.
curl -X PATCH https://api.pushward.app/activities/release-2-4 \
-H "Authorization: Bearer hlk_YOUR_TOKEN"
-H "Content-Type: application/merge-patch+json" \
-d '{ "content": { "auto_end": false } }'A kept list never ends by itself, so an integration that waits on it with ?wait= should stop at the last tick rather than wait for an end.
On Android
The current Android app shows a checklist as the generic Live Update: the server's count as its state ("3 of 8") over a bar at the checked share, and the percentage in the status bar chip. It draws no item rows and no item buttons, so the list is ticked from the other devices or by your integration, and the count and the bar follow.
On Android a checklist is a Live Update in the notification shade. The expanded notification lists the items, unchecked first, with a check mark on the ticked ones: all of them when there are four or fewer, else the first three and "+N more". The header shows the count ("3 of 8 done"), and the status bar chip "3/8". Android shows at most three notification buttons, so only the next three unchecked items get one, labelled with the item; the others move up as those are ticked. A tap sends the same tick as on the iPhone. A webhook tap_action is not sent from a live checklist: a tap on the card only opens PushWard.
Example: a release checklist
One request creates the activity and puts the list on the devices; ?upsert=true creates the slug when it does not exist yet:
curl -X PATCH "https://api.pushward.app/activities/release-2-4?upsert=true" \
-H "Authorization: Bearer hlk_YOUR_TOKEN" \
-H "Content-Type: application/merge-patch+json" \
-d '{
"state": "ongoing",
"content": {
"template": "checklist",
"icon": "checklist",
"accent_color": "green",
"items": [
{ "id": "changelog", "label": "Write the changelog", "checked": true },
{ "id": "tag", "label": "Tag and push v2.4.0" },
{ "id": "images", "label": "Publish the container images" },
{ "id": "docs", "label": "Update the docs" }
]
}
}'Then wait on the activity as above and act on each item as it is ticked. The playground draws the card on the Lock Screen, the Dynamic Island and the Android shade before you send anything.
Use Cases
- The manual steps around a release pipeline, ticked from the phone while the pipeline runs
- A maintenance window: snapshot, update, reboot, check the backups
- A packing list or the jobs before a trip, started by a Home Assistant automation
- An agent's plan, where the user ticks off the steps they did by hand