ヒートマップ ウィジェット
日ごとの値をカレンダー状に並べたグリッドで、1日1マス、値に応じて淡い色から濃い色まで塗り分けます。習慣、ワークアウト、電力使用量など、毎日のリズムがあるものに最適です。
このセクションでは、App Store の審査待ちのアプリアップデートに含まれる機能について説明します。アップデートが公開されると、ここで自動的に利用できるようになります。
Fields
| Field | Type | Notes |
|---|---|---|
template | string | Required. Must be "heatmap" |
cells | (number | null)[] | Required. One raw value per day, oldest first. Between 7 and 154 entries (22 weeks). Each entry is a finite number, or null for a day without data; at least one must be a number. Replaced wholesale on PATCH, so re-send the whole window (why) |
end_date | string | RFC 3339. The day of the last cell. Without it, the last cell is the day of the widget's last update |
min_value | float | Floor of the shading: a cell at or below it gets the faintest shade. Defaults to 0 |
max_value | float | Ceiling of the shading. Defaults to the largest number in cells. Must be greater than min_value when both are sent |
value | float | Headline number in the header, such as this week's total. The grid does not read it |
unit | string | Unit rendered after value and after today's value on the round Lock Screen widget (e.g. "min", "kWh"). Max 32 characters |
label, subtitle, icon, accent_color, background_color, text_color | string | Shared content fields, see the API reference. accent_color is the full-strength shade |
What to send
Send the raw daily values, oldest first, with null for a day you have no reading for:
a sensor that was offline, a watch left on the charger. Do not bucket the values into levels
yourself, and do not leave a missing day out. Every entry is one day, so a dropped entry moves
every older day one square back. A day that really was zero is 0, not null; the two are drawn differently.
The array is replaced on every update, so send the window you want drawn, up to the last 154 days. Once a day is enough for most sources; send again whenever today's number changes.
Shading
The app shades each cell from the raw value, the same way on every device. With min as min_value (0 when absent) and max as max_value (the largest non-null cell when absent):
nullis no data: an empty, outlined square, never the faintest shade.- A value at or below
minis level 0, the faintest tint of the accent colour. - Otherwise, when
maxis not abovemin, it is level 4. - Otherwise the level is
min(4, ceil((value - min) / (max - min) * 4)), and level 4 is the full accent colour.
With the defaults and a busiest day of 80, a 0 is level 0, 15 and 20 are level 1, 21 is level
2, 60 is level 3 and 80 is level 4. Without max_value, one unusually big day lowers
the shade of every other day. Set both bounds when updates should stay comparable from one day to
the next, for example a daily goal of 60 minutes as max_value.
Layout
Seven rows, one per weekday, and one column per week. The newest week is the right-hand column, and the last cell sits in it on its own weekday row; the days after it in that week stay empty. Whether the rows start on Sunday or Monday follows the device's region settings. When a widget has room for fewer weeks than you sent, it shows the newest ones. Once two full weeks stand before the newest one, a partial oldest week is left out, so the grid starts on a whole week. Today, the last cell, is ringed.
| Widget size | Shows |
|---|---|
| Small | The newest weeks that fit, edge to edge |
| Medium, large | As many weeks as fit, up to 22, with month labels over the columns and Monday, Wednesday and Friday marked |
| Lock Screen and watch, rectangular | One row of the most recent days |
| Lock Screen and watch, circular, inline and corner | Today's value (the last cell) with the unit |
The small and medium header carries label and the headline: value with its unit, or today's value when value is not set. The large widget shows the headline
as a big number with the first subtitle part beside it, the change of the last 7 days against
the 7 before (hidden when either week has no data), a Less to More legend, and the Total, Streak and Best
day of the days sent. The app works these three out from cells; the streak counts the days in a
row, ending today, above min_value. With buttons, a medium widget has no room for the labels and
shows the headline beside the grid, and a large one leaves out Total, Streak and Best day.
Example: daily exercise
curl -X PATCH https://api.pushward.app/widgets/exercise \
-H "Authorization: Bearer hlk_YOUR_TOKEN" \
-H "Content-Type: application/merge-patch+json" \
-d '{
"content": {
"template": "heatmap",
"label": "Exercise",
"icon": "flame.fill",
"accent_color": "orange",
"value": 245,
"unit": "min",
"min_value": 0,
"max_value": 60,
"cells": [
30, 0, 45, null, 25, 60, 0,
35, 0, 50, 20, 0, 75, 15,
40, 0, null, null, 30, 55, 0,
45, 10, 60, 30, 0, 80, 20
]
}
}'The last entry is today, so the grid ends on today's weekday. The three null days
draw as outlines; the 0 days are the faintest shade. The 75 and 80 sit above max_value and take the full accent colour.
App versions that predate this template cannot draw it; they show a prompt to update the app in its place.