5.3 KiB
Analytics report protocol
The phone app (app/analytics/) sends opt-in usage statistics to
https://stats.faceclaw.org/v1/report, at most about once a day per install,
plus hourly retries after a failure. Nothing is sent, or kept on the phone,
while Settings > Privacy > Data collection is None. What each level collects
is described in app/analytics/analytics-store.ts and in the privacy policy
(../PRIVACY); this file is the wire format.
Request
POST /v1/report with a JSON body of at most 64 KiB:
{
"schema": 1,
"reportId": "0f8fad5b-d9cb-469f-a165-70867728950e",
"installId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"level": "minimal",
"createdAt": "2026-10-10T12:00:00.000Z",
"app": { "version": "0.8.3", "platform": "android", "build": "official" },
"counters": { "2026-10-10": { "g2.connect-attempt": 3, "g2.session-ready": 3 } },
"snapshot": { "device.g2.paired": true, "device.r1.paired": false }
}
reportId: a random UUID per report. The phone resends a report until it gets a 2xx, so the server stores each id once and treats repeats as success.installId: a random UUID made when analytics is first turned on, deleted (with everything else) when it is turned off. It ties one install's reports together and nothing else.level:minimalorfull, the setting when the report was sent. A minimal report carries only minimal data.createdAt: when the phone sealed the report (its counters may cover earlier days, e.g. after a failed upload).app.build:official(signed with the release key),self-built(a release build signed with another key),debug(a debuggable build), orunknown.counters: UTC day, then counter name ([a-z0-9][a-z0-9_.:-]*), then a non-negative integer count.snapshot: state when the report was sealed, as flat keys ([A-Za-z0-9][A-Za-z0-9_.:-]*) to a boolean, number or string of up to 200 characters.
The server ignores unknown fields and rejects (400) a report with anything malformed or over its limits (100 days, 2000 counters, 500 snapshot keys).
Response
200 {"ok": true} once stored (or already stored). Errors are
{"error": "..."} with 400 (malformed, not retried), 405, 413 (too large),
429 (rate-limited by nginx, retried) or 500 (retried). Later versions may add
fields to the 200 response, such as the latest released version for update
checks.
Current counters and snapshot keys
Minimal level:
| Name | Kind | Meaning |
|---|---|---|
g2.connect-attempt, g2.session-ready |
counter | Connection attempts to the glasses, and those that got a working session |
g2.failure.<reason> |
counter | Transport failures that dropped or aborted a session, by reason (e.g. ack-timeout, write-failed, glasses-not-found, left-arm-not-found, heartbeat-ack-timeout, cfw-recovery-retry-limit) |
g2.session-end.<cause> |
counter | Working sessions ending: failure, arm-drop, requested |
g2.session-length.<bucket> |
counter | How long ended sessions lasted: under-1m, 1m-10m, 10m-1h, over-1h |
g2.arm-drop.left, g2.arm-drop.right |
counter | An arm's BLE link dropping mid-session |
g2.disconnect-requested |
counter | Disconnects the app asked for |
g2.unpaired, g2.incompatible-firmware |
counter | Connections halted for a missing bond or incompatible firmware |
g2.ack-timeout, g2.cfw-replay, g2.cfw-nack |
counter | Recovered message-level problems |
g2.firmware-abnormal-exit, g2.firmware-system-exit |
counter | Firmware closing the app's page outside a shutdown |
g2.auth-unacknowledged, g2.even-app-conflict |
counter | Security auth not acked; write failures blamed on the Even app |
ring.direct.connect, ring.direct.disconnect |
counter | Direct (not via glasses) R1 ring links |
ble.gatt-status.<code> |
counter | Android GATT connection-state callbacks with a non-success status (e.g. 8, 133) |
ble.ios-disconnect-error.<code> |
counter | iOS disconnects with an error |
device.g2.used, device.g2.touchpad-used, device.r1.used, device.wear.reachable, device.wear.used |
counter (1 per day) | Which devices were in use that day |
device.g2.paired, device.r1.paired |
snapshot | Whether glasses and a ring are paired |
device.g2.preview-only |
snapshot | Whether the app is in phone-preview-only mode |
device.r1.connection |
snapshot | glasses or direct ring connection |
Full level adds:
| Name | Kind | Meaning |
|---|---|---|
apikey.<kind> |
snapshot | Whether an API key or token of that kind is set (anthropic, openai, elevenlabs, soniox, mapbox, roam, nightscout, agent-bridge, evenhub), never the key |
config.nightscout-site |
snapshot | Whether a Nightscout site is set (not its URL) |
config.terminal-connections, config.t3code-environments |
snapshot | How many are configured |
config.ui-font |
snapshot | The UI font: a bundled font's name and size, installed:<size> for a user-installed one, or the bitmap face |
setting.<key> |
snapshot | The value of every setting chosen from fixed options (on/off and pick-one settings), by its storage key; free-text settings are never included |
Connection counts are kept by the shared Kotlin session core (ConnectionCounters.kt) and drained into the app's store every few minutes.