forked from Blendman974/faceclaw
Add stats collection and first-run on-glasses onboarding app
This commit is contained in:
1 parent
84baee9c76
commit
406cefe0c5
73 files changed
+3906
-98
No files matched your search
@@ -0,0 +1,92 @@
|
||||
# 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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`: `minimal` or `full`, 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), or
|
||||
`unknown`.
|
||||
- `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.
|
||||
Reference in new issue
Block a user