Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat(mobile): know where phone onboarding stalls, by release and OS

Dev jacobd547fb97ceba
diff --git a/backend/src/analytics/productHealth.test.ts b/backend/src/analytics/productHealth.test.ts
index 91077cf28..fced19899 100644
--- a/backend/src/analytics/productHealth.test.ts
+++ b/backend/src/analytics/productHealth.test.ts
@@ -18,6 +18,22 @@ it('creates two independent margins with no joint dimensions or arbitrary labels
expect(cleanUsageContext({ ...context, release: 'PRIVATE/custom-build', private: 'PRIVATE' })).toEqual({ ...context, release: 'unknown' })
expect(cleanUsageContext({ ...context, platform: 'PRIVATE' })).toBeUndefined()
})
+it('splits phone onboarding counts by release and platform, and drops a development build', () => {
+ const phone = { surface: 'phone', release: '1.0.3', platform: 'android', channel: 'production' } as const
+ expect(healthBreakdowns(phone, 'ui_phone_computer_wait_started')).toEqual([
+ 'breakdown:release:phone:1.0.3:ui_phone_computer_wait_started', 'breakdown:platform:phone:android:ui_phone_computer_wait_started'])
+ expect(healthBreakdowns({ ...phone, channel: 'development' }, 'ui_phone_computer_wait_started')).toEqual([])
+ const row = (metric: string, value: number) => ({ dayUtc: new Date('2026-10-01'), metric, value })
+ const data = dailyProductHealth([
+ row('health_phone_collector_days', 25),
+ row('breakdown:platform:phone:android:health_phone_collector_days', 25),
+ row('breakdown:platform:phone:android:ui_phone_computer_wait_started', 12),
+ ], new Date('2026-10-04'))
+ expect(data.daily[0].coverage.phoneSessions).toBe(25)
+ expect(data.breakdowns).toEqual([expect.objectContaining({ dimension: 'platform', surface: 'phone', bucket: 'android',
+ counters: expect.objectContaining({ ui_phone_computer_wait_started: 12 }) })])
+})
+
it('suppresses sparse labels, distinguishes missing from zero, and matures first-work cohorts', () => {
const row = (day: string, metric: string, value: number) => ({ dayUtc: new Date(day), metric, value })
const data = dailyProductHealth([
diff --git a/backend/src/analytics/productHealth.ts b/backend/src/analytics/productHealth.ts
index 45341aeb6..500eee884 100644
--- a/backend/src/analytics/productHealth.ts
+++ b/backend/src/analytics/productHealth.ts
@@ -24,7 +24,7 @@ export function dailyProductHealth(rows: Row[], now: Date) {
if (readable.has(row.metric)) {
const c = days.get(day) ?? {}; c[row.metric] = (c[row.metric] ?? 0) + row.value; days.set(day, c)
} else {
- const m = /^breakdown:(release|platform):(cli|desktop):([^:]+):(.+)$/.exec(row.metric)
+ const m = /^breakdown:(release|platform):(cli|desktop|phone):([^:]+):(.+)$/.exec(row.metric)
if (!m || !allowed.has(m[4])) continue
const context = cleanUsageContext({ surface: m[2], release: m[1] === 'release' ? m[3] : 'unknown',
platform: m[1] === 'platform' ? m[3] : 'other', channel: 'production' })
@@ -36,7 +36,8 @@ export function dailyProductHealth(rows: Row[], now: Date) {
}
const daily = [...days].sort(([a], [b]) => a.localeCompare(b)).map(([day, c]) => ({
day, complete: day < today,
- coverage: { cli: c.health_cli_collector_days ?? null, desktopSessions: c.health_desktop_collector_days ?? null },
+ coverage: { cli: c.health_cli_collector_days ?? null, desktopSessions: c.health_desktop_collector_days ?? null,
+ phoneSessions: c.health_phone_collector_days ?? null },
requestReconciliation: PRODUCT_USAGE_ACTIONS.map(action => {
const starts = c[`${action}_requests`] ?? null
const outcomes = ['ok', 'failed', 'pending', 'unknown'].reduce((sum, outcome) => sum + (c[`${action}_${outcome}`] ?? 0), 0)
diff --git a/backend/src/routes/productUsage.test.ts b/backend/src/routes/productUsage.test.ts
index d11cbff02..ce3742a77 100644
--- a/backend/src/routes/productUsage.test.ts
+++ b/backend/src/routes/productUsage.test.ts
@@ -86,6 +86,15 @@ it('the complete vocabulary fits bounded chunks, including the longest metric ke
}
})
+it('takes a phone build context: its release and iOS or Android, nothing finer', async () => {
+ for (const platform of ['ios', 'android']) {
+ const response = await submit({ ...good, context: { surface: 'phone', release: '1.0.3', platform, channel: 'production' } })
+ expect(response.statusCode).toBe(200)
+ }
+ const model = await submit({ ...good, context: { surface: 'phone', release: '1.0.3', platform: 'iPhone15,2', channel: 'production' } })
+ expect(model.statusCode).toBe(400)
+})
+
it('rejects extra context, custom versions and device fingerprints without echoing them', async () => {
const context = { surface: 'desktop', release: '1.2.73', platform: 'macos', channel: 'production' }
for (const c of [{ ...context, path: 'PRIVATE_CANARY' }, { ...context, release: 'PRIVATE_CANARY' },
diff --git a/backend/src/routes/productUsage.ts b/backend/src/routes/productUsage.ts
index f996b8f56..fd6763998 100644
--- a/backend/src/routes/productUsage.ts
+++ b/backend/src/routes/productUsage.ts
@@ -6,9 +6,9 @@ import { releaseBucket } from '../types/productHealthContract.js'
import { sendError, sendSuccess } from '../utils/response.js'
const contextSchema = z.strictObject({
- surface: z.enum(['cli', 'desktop']),
+ surface: z.enum(['cli', 'desktop', 'phone']),
release: z.string().max(11).refine(v => v === 'unknown' || releaseBucket(v) === v),
- platform: z.enum(['macos', 'linux', 'windows', 'other']),
+ platform: z.enum(['macos', 'linux', 'windows', 'ios', 'android', 'other']),
channel: z.enum(['production', 'development']),
})
diff --git a/backend/src/types/productHealthContract.ts b/backend/src/types/productHealthContract.ts
index 1e3a7dca0..6beddfcfc 100644
--- a/backend/src/types/productHealthContract.ts
+++ b/backend/src/types/productHealthContract.ts
@@ -36,6 +36,8 @@ export const PRODUCT_HEALTH_METRICS = [
...CLI_REPORT_FAILURES.map(reason => `health_cli_report_failure_${reason}` as const),
...HEALTH_SOURCES.flatMap(source => RESUME_REASONS.map(reason => `request_${source}_resume_reason_${reason}` as const)),
...(['cli', 'desktop'] as const).flatMap(surface => HEALTH_MEASURES.map(m => `health_${surface}_${m}` as const)),
+ // The phone reports only its coverage (the threshold its breakdowns need) and late deliveries.
+ 'health_phone_collector_days', 'health_phone_report_late',
...HEALTH_SOURCES.flatMap(source => HEALTH_ACTIONS.flatMap(action => [
...HEALTH_RESULTS.map(result => `request_${source}_${action}_${result}` as const),
...HEALTH_FAILURES.map(failure => `request_${source}_${action}_error_${failure}` as const),
@@ -44,9 +46,9 @@ export const PRODUCT_HEALTH_METRICS = [
export type ProductHealthMetric = typeof PRODUCT_HEALTH_METRICS[number]
export type HealthSource = typeof HEALTH_SOURCES[number]
export interface ProductUsageContext {
- surface: 'cli' | 'desktop'
+ surface: 'cli' | 'desktop' | 'phone'
release: string
- platform: 'macos' | 'linux' | 'windows' | 'other'
+ platform: 'macos' | 'linux' | 'windows' | 'ios' | 'android' | 'other'
channel: 'production' | 'development'
}
/** Public numeric release only. Custom build names, hashes and suffixes cannot become labels. */
@@ -56,7 +58,7 @@ export function releaseBucket(value: unknown): string {
export function cleanUsageContext(value: unknown): ProductUsageContext | undefined {
if (!value || typeof value !== 'object') return
const c = value as ProductUsageContext
- if (!['cli', 'desktop'].includes(c.surface) || !['macos', 'linux', 'windows', 'other'].includes(c.platform)
+ if (!['cli', 'desktop', 'phone'].includes(c.surface) || !['macos', 'linux', 'windows', 'ios', 'android', 'other'].includes(c.platform)
|| !['production', 'development'].includes(c.channel)) return
return { surface: c.surface, release: releaseBucket(c.release), platform: c.platform, channel: c.channel }
}
diff --git a/backend/src/types/productUsage.ts b/backend/src/types/productUsage.ts
index 6b1b9b1f3..df3dce79e 100644
--- a/backend/src/types/productUsage.ts
+++ b/backend/src/types/productUsage.ts
@@ -31,8 +31,11 @@ export const PRODUCT_USAGE_LONG_FLOWS = ['computer_wait', 'first_message'] as co
export const PRODUCT_USAGE_LONG_MEASURES = ['1m_to_5m', '5m_to_15m', '15m_to_1h', 'over_1h'] as const
/** What happened on the way through a phone onboarding step, at most once per step per sign-in.
* `resumed`: the step started in an app run that did not sign in (reopened mid-step), so it is not a
- * new person; the rest are the step's own ways out or walls. */
-export const PRODUCT_USAGE_ONBOARDING_MARKS = ['ui_phone_computer_wait_resumed', 'ui_phone_computer_wait_not_you',
+ * new person; the rest are the step's own ways out or walls. The sign_in marks are counted with a
+ * sign-in that went through: `retried`, an attempt before it in this app run failed or was
+ * cancelled; `switched`, it used another button than the first one tried. */
+export const PRODUCT_USAGE_ONBOARDING_MARKS = ['ui_phone_sign_in_retried', 'ui_phone_sign_in_switched',
+ 'ui_phone_computer_wait_resumed', 'ui_phone_computer_wait_not_you',
'ui_phone_computer_wait_link_shared', 'ui_phone_session_open_resumed', 'ui_phone_session_open_blocked_password',
'ui_phone_session_open_blocked_offline', 'ui_phone_first_message_resumed'] as const
export const PRODUCT_USAGE_ONBOARDING_METRICS = [...PRODUCT_USAGE_ONBOARDING_MARKS,
diff --git a/cli/src/lib/productHealthContract.ts b/cli/src/lib/productHealthContract.ts
index 1e3a7dca0..6beddfcfc 100644
--- a/cli/src/lib/productHealthContract.ts
+++ b/cli/src/lib/productHealthContract.ts
@@ -36,6 +36,8 @@ export const PRODUCT_HEALTH_METRICS = [
...CLI_REPORT_FAILURES.map(reason => `health_cli_report_failure_${reason}` as const),
...HEALTH_SOURCES.flatMap(source => RESUME_REASONS.map(reason => `request_${source}_resume_reason_${reason}` as const)),
...(['cli', 'desktop'] as const).flatMap(surface => HEALTH_MEASURES.map(m => `health_${surface}_${m}` as const)),
+ // The phone reports only its coverage (the threshold its breakdowns need) and late deliveries.
+ 'health_phone_collector_days', 'health_phone_report_late',
...HEALTH_SOURCES.flatMap(source => HEALTH_ACTIONS.flatMap(action => [
...HEALTH_RESULTS.map(result => `request_${source}_${action}_${result}` as const),
...HEALTH_FAILURES.map(failure => `request_${source}_${action}_error_${failure}` as const),
@@ -44,9 +46,9 @@ export const PRODUCT_HEALTH_METRICS = [
export type ProductHealthMetric = typeof PRODUCT_HEALTH_METRICS[number]
export type HealthSource = typeof HEALTH_SOURCES[number]
export interface ProductUsageContext {
- surface: 'cli' | 'desktop'
+ surface: 'cli' | 'desktop' | 'phone'
release: string
- platform: 'macos' | 'linux' | 'windows' | 'other'
+ platform: 'macos' | 'linux' | 'windows' | 'ios' | 'android' | 'other'
channel: 'production' | 'development'
}
/** Public numeric release only. Custom build names, hashes and suffixes cannot become labels. */
@@ -56,7 +58,7 @@ export function releaseBucket(value: unknown): string {
export function cleanUsageContext(value: unknown): ProductUsageContext | undefined {
if (!value || typeof value !== 'object') return
const c = value as ProductUsageContext
- if (!['cli', 'desktop'].includes(c.surface) || !['macos', 'linux', 'windows', 'other'].includes(c.platform)
+ if (!['cli', 'desktop', 'phone'].includes(c.surface) || !['macos', 'linux', 'windows', 'ios', 'android', 'other'].includes(c.platform)
|| !['production', 'development'].includes(c.channel)) return
return { surface: c.surface, release: releaseBucket(c.release), platform: c.platform, channel: c.channel }
}
diff --git a/cli/src/lib/productUsageContract.ts b/cli/src/lib/productUsageContract.ts
index 6b1b9b1f3..df3dce79e 100644
--- a/cli/src/lib/productUsageContract.ts
+++ b/cli/src/lib/productUsageContract.ts
@@ -31,8 +31,11 @@ export const PRODUCT_USAGE_LONG_FLOWS = ['computer_wait', 'first_message'] as co
export const PRODUCT_USAGE_LONG_MEASURES = ['1m_to_5m', '5m_to_15m', '15m_to_1h', 'over_1h'] as const
/** What happened on the way through a phone onboarding step, at most once per step per sign-in.
* `resumed`: the step started in an app run that did not sign in (reopened mid-step), so it is not a
- * new person; the rest are the step's own ways out or walls. */
-export const PRODUCT_USAGE_ONBOARDING_MARKS = ['ui_phone_computer_wait_resumed', 'ui_phone_computer_wait_not_you',
+ * new person; the rest are the step's own ways out or walls. The sign_in marks are counted with a
+ * sign-in that went through: `retried`, an attempt before it in this app run failed or was
+ * cancelled; `switched`, it used another button than the first one tried. */
+export const PRODUCT_USAGE_ONBOARDING_MARKS = ['ui_phone_sign_in_retried', 'ui_phone_sign_in_switched',
+ 'ui_phone_computer_wait_resumed', 'ui_phone_computer_wait_not_you',
'ui_phone_computer_wait_link_shared', 'ui_phone_session_open_resumed', 'ui_phone_session_open_blocked_password',
'ui_phone_session_open_blocked_offline', 'ui_phone_first_message_resumed'] as const
export const PRODUCT_USAGE_ONBOARDING_METRICS = [...PRODUCT_USAGE_ONBOARDING_MARKS,
diff --git a/docs/product-measurement.md b/docs/product-measurement.md
index 4a4ca84cf..71b892de3 100644
--- a/docs/product-measurement.md
+++ b/docs/product-measurement.md
@@ -18,7 +18,7 @@ automatically proven improvement. Changes still need review, tests and a deliber
| Which features get tried and used again? | First measured installations and daily first/repeat feature reach | Locally deduplicated installation-days, not unique accounts. Reads the apps make on their own (history, history paging, Store list, model list; `PRODUCT_USAGE_AUTOMATIC_ACTIONS`) count reliability only. The Store and model lists get reach only from the request an app marks `userAction` when a person opens them (`<action>_user_*`, `PRODUCT_USAGE_USER_OPENED_ACTIONS`); history has none. |
| Where do app flows break? | Setup, Harness/tmux/clipboard steps, sign-in, workspace/remote connections, computer linking, viewer-pane opening and manual update checking/staging | Fixed started/ok/failed/cancelled/unknown counts and coarse duration buckets. Opening a viewer pane is not rendering its content; staging an update is not a successful relaunch. |
-| Where does the phone's onboarding stall? | After sign-in: waiting for the first computer, opening its session, the first message, the notification prompt. A sign-in that went through, by button, counted again under the account's sharing. Waits past a minute split into 1–5 min, 5–15 min, 15 min–1 h and over 1 h for the computer and the first message. Once per step per sign-in: `resumed` (reopened in a run that did not sign in), "Not you? Sign out", the address sent from the share sheet, a joining computer that wants its password or is offline | Stage totals per day, not a linked funnel. Subtract `resumed` from starts for fresh starts; an unmatched start is a closed app or a step still waiting. A resumed step's duration starts at the reopening. Signed-in sign-in counts are successes only; failures and cancels before an account remain the signed-out opt-in's. |
+| Where does the phone's onboarding stall? | After sign-in: waiting for the first computer, opening its session, the first message, the notification prompt. A sign-in that went through, by button, counted again under the account's sharing. Waits past a minute split into 1–5 min, 5–15 min, 15 min–1 h and over 1 h for the computer and the first message. Once per step per sign-in: `resumed` (reopened in a run that did not sign in), "Not you? Sign out", the address sent from the share sheet, a joining computer that wants its password or is offline | Stage totals per day, not a linked funnel. Subtract `resumed` from starts for fresh starts; an unmatched start is a closed app or a step still waiting. A resumed step's duration starts at the reopening. Signed-in sign-in counts are successes only; failures and cancels before an account remain the signed-out opt-in's, but a success is marked `retried` (a failed or cancelled try came first in that app run) or `switched` (another button was tried first). Phone reports carry release and iOS/Android, so every phone count also splits by those two margins (above 20 collector days); debug builds are not kept. A chosen sign-out sends what is queued first (up to 2 s), so "Not you? Sign out" reaches the totals. |
| Is measurement losing coverage? | Updated collector installation-days, pruned queues, full observation maps, unmatched app starts | Loss signals warrant caution. No signal does not prove complete collection. |
| How many people use Harness, and do they come back? | People active / working / new per day and per app, and D1/D2/D3/D7 returns (backend rollup of 10-day pseudonymous marks) | Sharing accounts only, staff excluded; an app open across midnight counts on both days, so prefer working returns. Not available before `PRODUCT_USAGE_SUBJECT_KEY` is set. |
diff --git a/docs/research/2026-10-14-mobile-app-tracking/index.html b/docs/research/2026-10-14-mobile-app-tracking/index.html
index 22243b25e..6b44323d9 100644
--- a/docs/research/2026-10-14-mobile-app-tracking/index.html
+++ b/docs/research/2026-10-14-mobile-app-tracking/index.html
@@ -317,7 +317,7 @@
<tr><td>5 · Notifications</td><td><code>notify_permission</code></td><td>The system prompt shows</td><td>Allow</td><td>—</td><td>Don't Allow (<code>unknown</code> when the OS gives no answer)</td></tr>
</table></div>
<div class="note">Each flow runs at most once per sign-in and app launch. These are counts of attempts, not of people: the daily totals have no identity to deduplicate them.
- Signing out clears the phone's unsent counts, so a step ended by signing out mostly shows as a start with no outcome rather than as <code>cancelled</code>.</div>
+ A chosen sign-out first sends what the phone has queued (up to 2 s), so a step ended by "Not you? Sign out" arrives as <code>cancelled</code> with its <code>not_you</code> mark.</div>
</div></div>
<h2>1. Welcome and sign-in</h2>
@@ -330,10 +330,12 @@
<tr><td>sign_in_email_*</td><td>"Continue with email", then the 4-digit code (<code>signInWithCode</code>). Sending the code is not counted</td></tr>
<tr><td>sign_in_scan_*</td><td>"QR code", then a computer's Add Phone code read by the camera (<code>signInWithScan</code>)</td></tr>
<tr><td>sign_in_*</td><td>The total of all four, as before</td></tr>
+ <tr><td>sign_in_retried</td><td>A sign-in that went through after a failed or cancelled try in the same app run</td></tr>
+ <tr><td>sign_in_switched</td><td>A sign-in that went through on another button than the first one tried</td></tr>
</table></div>
<p>Google and Apple were not counted at all before this change, so <code>sign_in</code> totals rise when it ships. A scan that fails and falls back to the emailed code counts as a failed scan; the code typed after it is its own email attempt.</p>
- <div class="note">These exist only for phones that ticked <b>Share setup and sign-in counts</b>, the one quiet line with ⓘ at the foot of every signed-out screen (not in these renders).
- It starts off on every launch, so expect small numbers. This is deliberate: before an account exists there is no other consent.</div></figcaption></figure>
+ <div class="note">Every outcome, failures and cancels included, exists only for phones that ticked <b>Share setup and sign-in counts</b> (<code>setup_phone_*</code>), the one quiet line with ⓘ at the foot of every signed-out screen; it starts off on every launch.
+ A sign-in that <b>went through</b> is counted again under the account's own sharing (<code>ui_phone_sign_in_*_ok</code>, the large population), with <code>retried</code> and <code>switched</code> saying how hard it was. People who never get in stay invisible: take installs and first opens from App Store Connect and Play Console as the denominator.</div></figcaption></figure>
<figure class="phone-pair"><div class="shots"><img src="img/03-code.jpg" alt="Check your email: the 4-digit code"></div>
<figcaption><div class="row"><span class="num">1b</span><span class="ttl2">What a failure carries</span></div>
<p>Only <code>failed</code>. The red reason under the picture ("Could not open the sign-in page…"), the email typed and the code never leave the phone. The old AA <code>reason</code> code is not sent either.</p></figcaption></figure>
@@ -345,8 +347,9 @@
<tr><th>Counter</th><th>When</th></tr>
<tr><td>computer_wait_started</td><td>The page shows, after a sign-in in this run or on a fresh phone, for an account with no computers</td></tr>
<tr><td>computer_wait_ok</td><td>The first computer appears on the account (the 5 s poll)</td></tr>
- <tr><td>computer_wait_cancelled</td><td>Signed out from here (rarely arrives: signing out drops the unsent counts)</td></tr>
- <tr><td>computer_wait_&lt;bucket&gt;</td><td>How long it took to install Harness and sign in on the computer: the step most likely to need <code>over_1m</code></td></tr>
+ <tr><td>computer_wait_cancelled</td><td>Signed out from here; <code>computer_wait_not_you</code> when it was "Not you? Sign out"</td></tr>
+ <tr><td>computer_wait_link_shared</td><td>The address sent to the computer from the share sheet</td></tr>
+ <tr><td>computer_wait_&lt;bucket&gt;</td><td>How long it took to install Harness and sign in on the computer. Past a minute it also splits into <code>1m_to_5m</code>, <code>5m_to_15m</code>, <code>15m_to_1h</code>, <code>over_1h</code></td></tr>
</table></div>
<p>Accounts that already had a computer skip this step, so it has no <code>started</code> for them.</p></figcaption></figure>
@@ -358,9 +361,10 @@
<tr><td>session_open_started</td><td>The join moment starts (a new computer, or the first ready one on the account)</td></tr>
<tr><td>session_open_ok</td><td>The hand-over: the computer's session opens, or one picked meanwhile in Find or from a notice</td></tr>
<tr><td>session_open_failed</td><td>"Waiting for its first session" passes 90 s</td></tr>
- <tr><td>session_open_cancelled</td><td>Signed out meanwhile (rarely arrives: signing out drops the unsent counts)</td></tr>
+ <tr><td>session_open_cancelled</td><td>Signed out meanwhile</td></tr>
+ <tr><td>session_open_blocked_password · blocked_offline</td><td>The joining computer wanted its password, or was offline by the account's word too</td></tr>
</table></div>
- <p>A computer that wants a password or is offline leaves the step running: its time then includes unlocking it.</p></figcaption></figure>
+ <p>A computer that wants a password or is offline leaves the step running, marked once: its time then includes unlocking it.</p></figcaption></figure>
<h2>4. The session</h2>
<figure class="phone-pair"><div class="shots"><div class="ph"><div class="sb"><span>9:41</span><span class="bat"></span></div><div class="island"></div>
@@ -405,7 +409,7 @@
<tr><td>notify_permission_unknown</td><td>The OS gave no answer, or the request failed</td></tr>
</table></div>
<p>To read the answer, <code>SystemNotices.requestPermission()</code> now returns the plugin's <code>bool?</code> instead of nothing. Settings ▸ Notifications and Focus's tips call it as before.</p>
- <div class="note">Android 12 and older show no prompt, so there the step can end <code>ok</code> with nothing on screen. Counts do not say iOS or Android apart.</div></figcaption></figure>
+ <div class="note">Android 12 and older show no prompt, so there the step can end <code>ok</code> with nothing on screen. Every count splits by iOS and Android (see Reading the numbers).</div></figcaption></figure>
<h2>Already counted, unchanged</h2>
<p class="sub">The phone flows from #1301/#1303 that the onboarding passes through.</p>
@@ -423,7 +427,9 @@
the four outcomes, <code>unmatchedStarts</code> and the duration buckets. The new flows appear there with no change, because the review reads the same vocabulary. Days are UTC; today is partial.</p>
<ul class="plain">
<li>Conversion between steps compares totals, not people: <code>session_open_started</code> ÷ <code>computer_wait_ok</code> is close to "joined, then went on", but nothing links the two counts.</li>
- <li>Sign-in rates describe only phones that ticked the box: a self-selected group, not all new users.</li>
+ <li>Sign-in failure rates describe only phones that ticked the box: a self-selected group. Successes, <code>retried</code> and <code>switched</code> cover every sharing account.</li>
+ <li><code>resumed</code> marks a step started in an app run that did not sign in (the app reopened mid-step). Subtract it from starts for fresh starts.</li>
+ <li>Every phone report carries its release and iOS/Android, so <code>usage:daily</code>'s <code>health.breakdowns</code> splits each <code>ui_phone_*</code> count by release and by platform: compare the release before and after a UI change. A margin appears above 20 collector days. Debug builds report as <code>development</code> and are not kept, but TestFlight builds are release builds and do count.</li>
<li>The web build of the same app counts under <code>ui_web_*</code>. Signed out, web sends nothing.</li>
</ul>
</div></div>
diff --git a/mobile/lib/measurement/onboarding_measurement.dart b/mobile/lib/measurement/onboarding_measurement.dart
index 945cc873c..89cb2654f 100644
--- a/mobile/lib/measurement/onboarding_measurement.dart
+++ b/mobile/lib/measurement/onboarding_measurement.dart
@@ -3,6 +3,12 @@ import 'product_measurement.dart';
/// Mirrors `PRODUCT_USAGE_ONBOARDING_MARKS` in backend/src/types/productUsage.ts, with the steps
/// each is listed under there ([flows]); another pairing would reject the whole report.
enum OnboardingMark {
+ /// A sign-in went through after an attempt in this app run failed or was cancelled.
+ retried('retried', {ProductFlow.signIn}),
+
+ /// A sign-in went through on another button than the first one tried in this app run.
+ switched('switched', {ProductFlow.signIn}),
+
/// The step started in an app run that did not sign in: reopened mid-step, not a new start.
resumed('resumed', {
ProductFlow.computerWait,
@@ -51,6 +57,19 @@ class OnboardingMeasurement {
final _marks = <(ProductFlow, OnboardingMark)>{};
final _marked = <(ProductFlow, OnboardingMark)>{};
bool _signedInThisRun = false;
+ ProductFlow? _firstMethod;
+ bool _troubled = false;
+
+ /// A sign-in attempt by [method] ended with [outcome]. Kept in RAM for this app run only: before
+ /// an account there is nobody's choice to ask, so it is counted — as [OnboardingMark.retried] or
+ /// [OnboardingMark.switched] — only with a sign-in that goes through ([signedIn]).
+ void attempted(ProductFlow method, ProductOutcome outcome) {
+ _firstMethod ??= method;
+ if (outcome == ProductOutcome.failed ||
+ outcome == ProductOutcome.cancelled) {
+ _troubled = true;
+ }
+ }
/// A sign-in by [method] went through after [took]. Counted under the account's own sharing — a
/// far larger group than the signed-out opt-in — as `sign_in` and the button, both ok.
@@ -58,6 +77,12 @@ class OnboardingMeasurement {
_signedInThisRun = true;
_signedIn[ProductFlow.signIn] = took;
_signedIn[method] = took;
+ if (_troubled) _marks.add((ProductFlow.signIn, OnboardingMark.retried));
+ if (_firstMethod != null && _firstMethod != method) {
+ _marks.add((ProductFlow.signIn, OnboardingMark.switched));
+ }
+ _firstMethod = null;
+ _troubled = false;
_admit();
}
@@ -110,6 +135,8 @@ class OnboardingMeasurement {
_seen.clear();
_marked.clear();
_signedInThisRun = false;
+ _firstMethod = null;
+ _troubled = false;
}
void _clearWaiting() {
diff --git a/mobile/lib/measurement/product_measurement.dart b/mobile/lib/measurement/product_measurement.dart
index 71dcd66e9..69aa4d2a6 100644
--- a/mobile/lib/measurement/product_measurement.dart
+++ b/mobile/lib/measurement/product_measurement.dart
@@ -65,6 +65,12 @@ class ProductMeasurement extends ChangeNotifier {
final DateTime Function() _now;
final String Function() _receipt;
bool signedOutSharing = false, choiceLoaded = false;
+
+ /// Which build reports: `{surface, release, platform, channel}`, as backend
+ /// `ProductUsageContext` takes it. Sent with the account's reports only, so the totals split by
+ /// release and by platform; a `development` build's reports are not kept. Null: no context.
+ Map<String, String>? context;
+ String? _coverageDay;
bool _disposed = false;
Object? _account;
bool? _enabled;
@@ -143,8 +149,31 @@ class ProductMeasurement extends ChangeNotifier {
_days.removeWhere((key, _) => key.startsWith('$channel:'));
_pending.remove(channel);
_active.removeWhere((_, value) => value == channel);
+ if (channel == 'ui') _coverageDay = null;
+ }
+
+ /// Sends what the account has queued before a sign-out discards it ([account]): a step ended by
+ /// signing out, and why. At most [within]; what is still queued then is lost as before.
+ Future<void> sendBeforeSignOut({
+ Duration within = const Duration(seconds: 2),
+ }) async {
+ final watch = Stopwatch()..start();
+ for (var round = 0; round < 3; round++) {
+ if (_disposed || !sharing || !_queued('ui') || watch.elapsed >= within) {
+ return;
+ }
+ try {
+ await flush().timeout(within - watch.elapsed);
+ } on TimeoutException {
+ return;
+ }
+ }
}
+ bool _queued(String channel) =>
+ _pending.containsKey(channel) ||
+ _days.keys.any((key) => key.startsWith('$channel:'));
+
/// [elapsed] is time the flow already ran before it could be counted; it lands in the duration.
void Function(ProductOutcome) begin(
ProductFlow flow, {
@@ -262,6 +291,12 @@ class ProductMeasurement extends ChangeNotifier {
);
final counters = _days.putIfAbsent('$channel:$day', () => {});
counters[metric] = min(1000, (counters[metric] ?? 0) + 1);
+ // One collector day per app run and UTC day: the backend shows a release or platform split
+ // only above a floor of these.
+ if (channel == 'ui' && context != null && _coverageDay != day) {
+ _coverageDay = day;
+ counters['health_${surface}_collector_days'] = 1;
+ }
_schedule();
}
@@ -330,6 +365,7 @@ class ProductMeasurement extends ChangeNotifier {
'day': key.split(':')[1],
'counters': batch,
if (channel == 'setup') 'consent': true else 'revision': _revision,
+ if (channel == 'ui' && context != null) 'context': context,
};
_pending[channel] = report;
}
diff --git a/mobile/lib/phone/privacy_shared_fields.dart b/mobile/lib/phone/privacy_shared_fields.dart
index 3bc0ef104..e4962161b 100644
--- a/mobile/lib/phone/privacy_shared_fields.dart
+++ b/mobile/lib/phone/privacy_shared_fields.dart
@@ -6,7 +6,9 @@ typedef _Field = ({String label, String text});
const List<_Field> _sent = [
(
label: 'Each report',
- text: 'UTC day, a random retry receipt, protocol and preference revisions.',
+ text:
+ 'UTC day, a random retry receipt, protocol and preference revisions; '
+ 'the app version and whether it runs on iOS or Android.',
),
(
label: 'Activity',
@@ -43,7 +45,8 @@ const List<_Field> _sent = [
label: 'Phone setup steps',
text:
'Waiting for a computer, opening its session, sending a first message, '
- 'answering the notification prompt: outcomes and duration buckets.',
+ 'answering the notification prompt: outcomes and duration buckets; '
+ 'whether a sign-in that went through came after a failed try or on another button.',
),
(label: 'Feedback', text: 'Only your selected task outcome or reason.'),
(
diff --git a/mobile/lib/state/app_state.dart b/mobile/lib/state/app_state.dart
index fd6cf2501..ea8b0275d 100644
--- a/mobile/lib/state/app_state.dart
+++ b/mobile/lib/state/app_state.dart
@@ -1,3 +1,4 @@
+import '../core/app_version.dart';
import '../core/test_run.dart';
import '../measurement/onboarding_measurement.dart';
import '../measurement/product_measurement.dart';
@@ -1126,9 +1127,35 @@ class AppNotifier extends ChangeNotifier {
sendSetupMeasurement(this.config.apiBaseUrl, report),
);
addListener(_syncProductMeasurement);
+ unawaited(_measurementContext());
_initDeviceLog();
}
+ /// Which build this phone's reports come from ([ProductMeasurement.context]): the public release
+ /// and the OS family, nothing that tells one phone from another. A debug build reports as
+ /// `development`, which the backend does not keep. Not the web, which has no such context.
+ Future<void> _measurementContext() async {
+ if (kIsWeb || kUnderTest) return;
+ var release = 'unknown';
+ try {
+ release = await runningAppVersion();
+ } catch (_) {}
+ if (_disposed) return;
+ productMeasurement.context = {
+ 'surface': 'phone',
+ // The backend refuses a whole report whose release is not a plain x.y.z.
+ 'release': RegExp(r'^(0|[1-9]\d{0,2})(\.(0|[1-9]\d{0,2})){2}$').hasMatch(release)
+ ? release
+ : 'unknown',
+ 'platform': switch (defaultTargetPlatform) {
+ TargetPlatform.iOS => 'ios',
+ TargetPlatform.android => 'android',
+ _ => 'other',
+ },
+ 'channel': kReleaseMode ? 'production' : 'development',
+ };
+ }
+
void _syncProductMeasurement() {
final scope =
!signingIn &&
@@ -1744,8 +1771,13 @@ class AppNotifier extends ChangeNotifier {
void Function(ProductOutcome) _measureSignIn(ProductFlow method) {
final finish = productMeasurement.beginEach([ProductFlow.signIn, method]);
final watch = Stopwatch()..start();
+ var done = false;
return (outcome) {
finish(outcome);
+ // Called again by each attempt's `finally`: only its first outcome is the attempt's.
+ if (done) return;
+ done = true;
+ onboardingMeasurement.attempted(method, outcome);
if (outcome == ProductOutcome.ok) {
onboardingMeasurement.signedIn(method, watch.elapsed);
}
@@ -1970,6 +2002,13 @@ class AppNotifier extends ChangeNotifier {
/// Everything a sign-out does, whoever asked for it. [reason] is what the welcome screen says
/// ([signedOutReason]): null when the person chose it.
Future<void> _endSession({String? reason}) async {
+ // Chosen by the person, the sign-out is itself a step's end ("Not you? Sign out"): end the steps
+ // it abandons, then send what is queued while the session can still send it — the queue goes
+ // with the account.
+ if (reason == null) {
+ onboardingMeasurement.reset();
+ await productMeasurement.sendBeforeSignOut();
+ }
// Signing out takes this phone's key out of the account's devices, while the sign-in still works
// to say so. Best effort, and brief.
if (_deviceLog case final log?) {
diff --git a/mobile/test/onboarding_measurement_test.dart b/mobile/test/onboarding_measurement_test.dart
index 0063f45c0..79790cfdc 100644
--- a/mobile/test/onboarding_measurement_test.dart
+++ b/mobile/test/onboarding_measurement_test.dart
@@ -228,6 +228,118 @@ void main() {
expect(counters(), isEmpty);
});
+ test(
+ 'a sign-in after a failed try on another button is retried and switched',
+ () async {
+ onboarding.attempted(ProductFlow.signInGoogle, ProductOutcome.cancelled);
+ onboarding.attempted(ProductFlow.signInEmail, ProductOutcome.ok);
+ onboarding.signedIn(ProductFlow.signInEmail, Duration.zero);
+ await signIn();
+ await usage.flush();
+ expect(
+ counters('ui_phone_sign_in_'),
+ allOf(
+ containsPair('ui_phone_sign_in_retried', 1),
+ containsPair('ui_phone_sign_in_switched', 1),
+ ),
+ );
+ },
+ );
+
+ test('a first sign-in that works is neither retried nor switched', () async {
+ onboarding.attempted(ProductFlow.signInApple, ProductOutcome.ok);
+ onboarding.signedIn(ProductFlow.signInApple, Duration.zero);
+ await signIn();
+ await usage.flush();
+ expect(
+ counters('ui_phone_sign_in_'),
+ isNot(contains('ui_phone_sign_in_retried')),
+ );
+ expect(
+ counters('ui_phone_sign_in_'),
+ isNot(contains('ui_phone_sign_in_switched')),
+ );
+ expect(
+ counters('ui_phone_sign_in_'),
+ containsPair('ui_phone_sign_in_ok', 1),
+ );
+ });
+
+ test('a sign-out sends the step it ended before the queue goes', () async {
+ signedInHere();
+ onboarding.start(ProductFlow.computerWait);
+ await signIn();
+ await usage.flush();
+ onboarding.mark(ProductFlow.computerWait, OnboardingMark.notYou);
+ onboarding.reset();
+ await usage.sendBeforeSignOut();
+ usage.account(null);
+ expect(counters(), containsPair('ui_phone_computer_wait_not_you', 1));
+ expect(counters(), containsPair('ui_phone_computer_wait_cancelled', 1));
+ });
+
+ test('without sending first, a sign-out loses what was queued', () async {
+ signedInHere();
+ onboarding.start(ProductFlow.computerWait);
+ await signIn();
+ await usage.flush();
+ onboarding.mark(ProductFlow.computerWait, OnboardingMark.notYou);
+ usage.account(null);
+ await usage.flush();
+ expect(counters(), isNot(contains('ui_phone_computer_wait_not_you')));
+ });
+
+ test(
+ 'the build context rides the account reports, with one collector day',
+ () async {
+ usage.context = {
+ 'surface': 'phone',
+ 'release': '1.0.3',
+ 'platform': 'ios',
+ 'channel': 'production',
+ };
+ signedInHere();
+ onboarding.start(ProductFlow.computerWait);
+ await signIn();
+ onboarding.end(ProductFlow.computerWait, ProductOutcome.ok);
+ await usage.flush();
+ expect(reports, isNotEmpty);
+ for (final report in reports) {
+ expect(report['context'], usage.context);
+ }
+ expect(counters(), containsPair('health_phone_collector_days', 1));
+ },
+ );
+
+ test('signed-out setup reports never carry the build context', () async {
+ final setup = <Map<String, dynamic>>[];
+ final guest =
+ ProductMeasurement(
+ surface: 'phone',
+ automatic: false,
+ now: () => DateTime.utc(2026, 10, 14, 12),
+ sendSetup: (r) async {
+ setup.add(r);
+ return {'accepted': true};
+ },
+ )
+ ..context = {
+ 'surface': 'phone',
+ 'release': '1.0.3',
+ 'platform': 'android',
+ 'channel': 'production',
+ };
+ addTearDown(guest.dispose);
+ await guest.setSignedOutSharing(true);
+ guest.begin(ProductFlow.signInGoogle)(ProductOutcome.ok);
+ await guest.flush();
+ expect(setup.single.containsKey('context'), isFalse);
+ expect(
+ (setup.single['counters'] as Map).keys,
+ isNot(contains('health_phone_collector_days')),
+ );
+ });
+
test('every mark is in the backend vocabulary under each step it names', () {
final vocabulary = File('../backend/src/types/productUsage.ts')
.readAsStringSync();