Widget-ul Hartă termică
O grilă de calendar cu valori zilnice, un pătrat pe zi, colorat de la palid la plin după valoare. Ideal pentru obiceiuri, antrenamente, consum de energie sau orice are un ritm zilnic.
Această secțiune descrie o funcție dintr-o actualizare a aplicației aflată în așteptarea verificării App Store. Se deblochează automat aici imediat ce actualizarea devine disponibilă.
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.