Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(spaces): onboarding v2 PostHog funnel events (CUA-2292) (#5951)

cua-agents[bot]feafec648a40
diff --git a/apps/cua-spaces-desktop/src/bridge/telemetry.ts b/apps/cua-spaces-desktop/src/bridge/telemetry.ts
index 808346ca61..15147197cf 100644
--- a/apps/cua-spaces-desktop/src/bridge/telemetry.ts
+++ b/apps/cua-spaces-desktop/src/bridge/telemetry.ts
@@ -130,7 +130,8 @@ export function hostRecorded(raw: unknown): boolean {
export function leftWelcome(raw: unknown): boolean {
if (!raw || typeof raw !== "object") return false;
const s = raw as Record<string, unknown>;
- if (s.type === "onboarding-page") return !(s.page === "welcome" && s.action === "shown");
+ // Welcome being shown (the old `shown`, the funnel's `step_viewed`) is before the notice.
+ if (s.type === "onboarding-page") return !(s.page === "welcome" && (s.action === "shown" || s.action === "step_viewed"));
return s.type === "step" && s.step === "onboarding_skipped";
}
diff --git a/apps/cua-spaces-desktop/test/live-telemetry.test.ts b/apps/cua-spaces-desktop/test/live-telemetry.test.ts
index 40619936bc..5088dc0a69 100644
--- a/apps/cua-spaces-desktop/test/live-telemetry.test.ts
+++ b/apps/cua-spaces-desktop/test/live-telemetry.test.ts
@@ -136,6 +136,8 @@ describe("leaving Welcome", () => {
expect(leftWelcome({ type: "onboarding-page", page: "welcome", action: "shown", choice: "none" })).toBe(false);
expect(leftWelcome({ type: "step", step: "onboarding_shown", ok: true })).toBe(false);
expect(leftWelcome({ type: "feature", feature: "space_open" })).toBe(false);
+ expect(leftWelcome({ type: "onboarding-page", page: "welcome", action: "step_viewed", choice: "none" })).toBe(false);
+ expect(leftWelcome({ type: "onboarding-page", page: "welcome", action: "step_completed", choice: "none" })).toBe(true);
expect(leftWelcome({ type: "onboarding-page", page: "welcome", action: "completed", choice: "none" })).toBe(true);
expect(leftWelcome({ type: "onboarding-page", page: "signin", action: "shown", choice: "none" })).toBe(true);
expect(leftWelcome({ type: "step", step: "onboarding_skipped", ok: true })).toBe(true);
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge+Pages.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge+Pages.swift
index a5d9ceb54a..0748a4301d 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge+Pages.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge+Pages.swift
@@ -457,7 +457,10 @@ extension WebUIBridge {
static func leftWelcome(_ raw: Any) -> Bool {
guard let s = raw as? [String: Any] else { return false }
switch s["type"] as? String {
- case "onboarding-page": return !(s["page"] as? String == "welcome" && s["action"] as? String == "shown")
+ case "onboarding-page":
+ // Welcome being shown (`shown`, or the funnel's `step_viewed`) is before the notice.
+ let action = s["action"] as? String
+ return !(s["page"] as? String == "welcome" && (action == "shown" || action == "step_viewed"))
case "step": return s["step"] as? String == "onboarding_skipped"
default: return false
}
diff --git a/apps/cua-spaces-web/src/__tests__/first-run.test.tsx b/apps/cua-spaces-web/src/__tests__/first-run.test.tsx
index 791fc01540..a656b10aa7 100644
--- a/apps/cua-spaces-web/src/__tests__/first-run.test.tsx
+++ b/apps/cua-spaces-web/src/__tests__/first-run.test.tsx
@@ -139,6 +139,57 @@ describe.skipIf(!wasmBuilt)("the first run (real route, wasm core)", () => {
await waitFor(() => expect(calls.find((c) => c.op === "session.completeOnboarding")).toBeTruthy());
});
+ it("counts each screen viewed and finished, a skipped one, and Skip for now, as fixed words only", async () => {
+ const calls = await mount();
+ const funnel = () =>
+ calls
+ .filter((c) => c.op === "telemetry.track")
+ .flatMap((c) => (c.args as { signals: { type: string; page: string; action: string; choice: string }[] }).signals)
+ .filter((s) => s.type === "onboarding-page" && s.action.startsWith("step_"))
+ .map((s) => `${s.page} ${s.action}${s.choice === "none" ? "" : ` ${s.choice}`}`);
+ await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
+ click("[data-onboarding-primary]");
+ await waitFor(() => expect(heading()).toBe("Pick your agent."));
+ click("[data-onboarding-primary]");
+ await waitFor(() => expect(heading()).toBe("Connect your other devices."));
+ click("[data-first-run-secondary]");
+ await waitFor(() => expect(document.querySelector("[data-step]")?.getAttribute("data-step")).toBe("setup"));
+ click("[data-onboarding-later]");
+ await new Promise((r) => setTimeout(r, 300));
+ await waitFor(() =>
+ expect(funnel()).toEqual([
+ "welcome step_viewed",
+ "welcome step_completed",
+ "connect_agent step_viewed",
+ "connect_agent step_completed",
+ "sign_in step_viewed",
+ "sign_in step_skipped step",
+ "create_space step_viewed",
+ "create_space step_skipped later",
+ ]),
+ );
+ });
+
+ it("sends no funnel event while usage data is off", async () => {
+ const calls: Calls = [];
+ await testCore();
+ await mountApp("/onboarding", {
+ failsCreates: false,
+ listsGhost: false,
+ demo: { signedIn: false, onboarded: false },
+ intercept: (op, args) => {
+ calls.push({ op, args });
+ return undefined;
+ },
+ answer: (op, out) => (op === "settings.get" ? { ...(out as object), telemetry: { ...(out as { telemetry: object }).telemetry, enabled: false } } : out),
+ });
+ await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
+ click("[data-onboarding-primary]");
+ await waitFor(() => expect(heading()).toBe("Pick your agent."));
+ await new Promise((r) => setTimeout(r, 50));
+ expect(calls.some((c) => c.op === "telemetry.track")).toBe(false);
+ });
+
it("Back works from every step after Welcome, all the way to Welcome, keeping what was picked", async () => {
const calls = await mount();
await waitFor(() => expect(heading()).toBe("Your computers, shared by your team and its agents."));
diff --git a/apps/cua-spaces-web/src/bridge/first-run.ts b/apps/cua-spaces-web/src/bridge/first-run.ts
index 2b1892d333..249434e47c 100644
--- a/apps/cua-spaces-web/src/bridge/first-run.ts
+++ b/apps/cua-spaces-web/src/bridge/first-run.ts
@@ -36,7 +36,7 @@ import { useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore
import { BridgeContext } from "./BridgeProvider";
import type { CoreClient } from "./core";
import type { AgentSetupRow } from "./contracts/agents";
-import type { HostStatus } from "./contracts/host";
+import type { HostStatus, SignInFailure } from "./contracts/host";
import type {
CliInstallPlan,
FirstRunAgent,
@@ -425,6 +425,30 @@ export interface FirstRunUsage {
help: string | null;
}
+/** The usage data's name for each screen (`schema::FIRST_RUN_STEPS`). */
+export const FUNNEL_STEP: Record<FirstRunStep, string> = {
+ welcome: "welcome",
+ connect: "connect_agent",
+ cli: "terminal",
+ devices: "sign_in",
+ permissions: "permissions",
+ setup: "create_space",
+};
+
+/** When "Skip for now" was last pressed (the page may mount again as it leaves, under a second later). */
+let leftAtMs = 0;
+
+/** A sign-in's failure as the funnel's reason (`sign_in::error_kind`). */
+const SIGN_IN_REASON: Record<SignInFailure, string> = {
+ notConfirmed: "timeout",
+ declined: "permission_denied",
+ codeRejected: "unauthenticated",
+ offline: "transport",
+ serviceUnavailable: "http",
+ couldNotSave: "internal",
+ unknown: "other",
+};
+
const STEPS: FirstRunStep[] = ["welcome", "connect", "cli", "devices", "permissions", "setup"];
export interface FirstRunHook {
@@ -739,7 +763,42 @@ export function useFirstRun(active = true, pollMs = FIRST_RUN_POLL_MS): FirstRun
// The screens this run shows (the core's): the CLI's only while it is missing.
const shown = view.steps?.length ? view.steps : firstRunSteps(input);
const at = Math.max(shown.indexOf(view.step), 0);
- const forward = () => go(shown[Math.min(at + 1, shown.length - 1)]!);
+ const funnel = (action: string, detail = "none", of: FirstRunStep = view.step) => {
+ if (active && store) track(() => store.trackFirstRunStep(FUNNEL_STEP[of], action, detail));
+ };
+ const forward = (how: "completed" | "skipped" = "completed") => {
+ if (how === "completed") funnel("step_completed");
+ else funnel("step_skipped", "step");
+ go(shown[Math.min(at + 1, shown.length - 1)]!);
+ };
+
+ // Each screen is counted when it shows (once per arrival).
+ useEffect(() => {
+ // Leaving with "Skip for now" can mount the page again as it goes, within a second or two: not a view.
+ if (Date.now() - leftAtMs < 2_000) return;
+ if (active && store) track(() => store.trackFirstRunStep(FUNNEL_STEP[view.step], "step_viewed"));
+ }, [active, store, view.step]);
+
+ // A screen's failure is counted once each time it appears.
+ const signInPhase = session.data?.signIn;
+ const on = view.step;
+ const failure: { step: FirstRunStep; reason: string } | null =
+ on === "devices" && signInPhase?.kind === "failed"
+ ? { step: on, reason: SIGN_IN_REASON[signInPhase.reason ?? "unknown"] ?? "other" }
+ : on === "cli" && cli.state.error
+ ? { step: on, reason: "install_failed" }
+ : on === "connect" && (connectError || signInError)
+ ? { step: on, reason: "connect_failed" }
+ : (on === "devices" || on === "permissions" || on === "setup") && setupError
+ ? { step: on, reason: "setup_failed" }
+ : on === "setup" && extra.phase === "failed"
+ ? { step: on, reason: "create_failed" }
+ : null;
+ const failureKey = failure ? `${failure.step}:${failure.reason}` : "";
+ useEffect(() => {
+ if (failure) funnel("step_failed", failure.reason, failure.step);
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [failureKey]);
const setUpThisComputer = async () => {
if (!store || settingUp) return;
@@ -808,6 +867,7 @@ export function useFirstRun(active = true, pollMs = FIRST_RUN_POLL_MS): FirstRun
await spaces.cancelCreate(s.extraPendingId).catch(() => {});
writeFirstRun({ extraPendingId: null, extraOs: null });
} else if (id === "not-now") {
+ funnel("step_skipped", "step");
writeFirstRun({ extraNotNow: true });
} else if (id === "add") {
writeFirstRun({ extraNotNow: false, extraPendingId: null, extraOs: null });
@@ -844,9 +904,11 @@ export function useFirstRun(active = true, pollMs = FIRST_RUN_POLL_MS): FirstRun
switch (id) {
case "start":
case "continue":
+ forward();
+ break;
case "skip":
case "not-now":
- forward();
+ forward("skipped");
break;
case "install":
await cli.install();
@@ -878,11 +940,15 @@ export function useFirstRun(active = true, pollMs = FIRST_RUN_POLL_MS): FirstRun
refresh();
},
async finish() {
+ // "Not now" on the first Space card already counted that screen as skipped.
+ if (extra.phase !== "not-now") funnel("step_completed");
if (store) track(() => store.trackOnboardingFinished(telemetryState()));
await session.completeOnboarding(host?.configured ? "host" : "client");
writeFirstRun({ finishedLater: false, todosClosed: false });
},
later() {
+ funnel("step_skipped", "later");
+ leftAtMs = Date.now();
if (store) track(() => store.trackOnboardingSkipped(telemetryState()));
store?.cancelSignIn();
// The shell stops opening it (the sidebar offers it again).
diff --git a/apps/cua-spaces-web/src/bridge/store.ts b/apps/cua-spaces-web/src/bridge/store.ts
index 2f151b60c5..2af5e52ff1 100644
--- a/apps/cua-spaces-web/src/bridge/store.ts
+++ b/apps/cua-spaces-web/src/bridge/store.ts
@@ -335,6 +335,15 @@ export class BridgeStore {
void this.telemetry.track(seen);
}
+ /** One first-run funnel event (`cua_onboarding_step_*`, `cua_onboarding_skipped`):
+ * `step` is one of the app core's funnel steps, `action` `step_viewed`,
+ * `step_completed`, `step_failed` or `step_skipped`, `detail` the failure's
+ * reason or how it was skipped. Fixed words only; the host checks the
+ * switch again and fills the step's index, the version, OS and app version. */
+ trackFirstRunStep(step: string, action: string, detail = "none"): void {
+ void this.telemetry.track([{ type: "onboarding-page", page: step, action, choice: detail }]);
+ }
+
/** "Set up later": the first run left for now, on its current page. */
trackOnboardingSkipped(state: OnboardingFlowState): void {
void this.telemetry.track(telemetryOnboardingSkipped(this.core, state));
diff --git a/docs/content/docs/cua-sdk/concepts/telemetry-events.mdx b/docs/content/docs/cua-sdk/concepts/telemetry-events.mdx
index 86010a065c..f3d40b7c9c 100644
--- a/docs/content/docs/cua-sdk/concepts/telemetry-events.mdx
+++ b/docs/content/docs/cua-sdk/concepts/telemetry-events.mdx
@@ -38,6 +38,10 @@ Every event carries: `telemetry_schema_version`, `event_version`, `product`
| `cua_spacesd_session_deliveries` | `delivery_grant` (`present` or `absent`), `count` | Session deliveries with and without a Keyvault grant. |
| `cua_app_active` | `experiments_on` (the Cua Spaces experiments turned on in Settings, Experiments: `cua_volume`, `your_cloud`, `sharing` joined with `+`, or `none`), `ui_locale` (the Cua Spaces interface language: `en`, `zh-Hans`, `ko`, `pt-BR`, `ja`, `es`, or `other`; never a region or free text) | Daily and weekly active installs and retention: at most one per install per UTC day. Also installs per experiment, and which languages to ship. |
| `cua_onboarding_page` | `page` (`welcome`, `command_line`, `signin`, `agents`, `presentation`, `volume`, `this_machine`, `done`), `action` (`shown`, `completed`, `skipped`, `back`), `choice` (a fixed word such as `installed`, `signed_in`, `menu_bar_only`, `s3`, `host`, or `none`) | Which first-run page people leave on, and what they pick. |
+| `cua_onboarding_step_viewed` | `step` (`welcome`, `connect_agent`, `terminal`, `sign_in`, `permissions`, `create_space`), `step_index` (its position, 1 to 6), `onboarding_version` (2) | How many installs see each first-run screen. The OS and app version are the `os_family` and `product_version` every event carries. |
+| `cua_onboarding_step_completed` | `step`, `step_index`, `onboarding_version` | How many installs finish each first-run screen. |
+| `cua_onboarding_step_failed` | `step`, `step_index`, `onboarding_version`, `reason` (`timeout`, `cancelled`, `permission_denied`, `unauthenticated`, `transport`, `http`, `internal`, `install_failed`, `connect_failed`, `setup_failed`, `create_failed`, `other`) | Which first-run screens fail, and why. |
+| `cua_onboarding_skipped` | `step`, `step_index`, `onboarding_version`, `how` (`step`: that screen's own Skip or Not now; `later`: Skip for now, which leaves the whole first run) | Which screens people skip, and where they leave the first run. |
| `cua_space_wizard` | `action` (`opened`, `cancelled`, `submitted`) | How often a New Space is started and abandoned. |
| `cua_space_create_started` | `location`, `guest_os`, `kind`, `gpu` (GPU acceleration turned on) | Which Spaces are started, and how often with GPU acceleration. |
| `cua_space_create` | `location`, `guest_os`, `kind`, `outcome` (`ok`, `error`, or `cancelled` when Cancel was pressed while it was being created), `error_kind` ([kinds](/cua-sdk/concepts/telemetry-error-kinds)), `failed_phase` (the phase it failed or was cancelled in, or `none`), `stalled`, `time_bucket` (to ready, the failure, or cancel finishing), `gpu`, `retry_attempt` (`1` when the app ran the create a second time by itself after a passing failure, else `0`), `error_subclass` ([finer causes](/cua-sdk/concepts/telemetry-error-kinds#finer-causes), or `none`) | Space create success, failure and cancel rates, time to ready, which phase fails, and how often one automatic retry saves a create. Sent once per create, for its final outcome, so a retried create still counts once. |
diff --git a/libs/cua/crates/cua-spaces-app-core/src/telemetry.rs b/libs/cua/crates/cua-spaces-app-core/src/telemetry.rs
index b9c2bb7815..795e333c5b 100644
--- a/libs/cua/crates/cua-spaces-app-core/src/telemetry.rs
+++ b/libs/cua/crates/cua-spaces-app-core/src/telemetry.rs
@@ -63,11 +63,15 @@ pub enum TelemetrySignal {
/// A first-run page was shown or left (`cua_onboarding_page`).
OnboardingPage {
/// `welcome`, `signin`, `agents`, `presentation`, `volume`,
- /// `this_machine` or `done`.
+ /// `this_machine` or `done`; or, with a `step_*` action, one of
+ /// `schema::FIRST_RUN_STEPS` (`connect_agent`, `terminal`, ...).
page: String,
- /// `shown`, `completed`, `skipped` or `back`.
+ /// `shown`, `completed`, `skipped` or `back`; or `step_viewed`,
+ /// `step_completed`, `step_failed` or `step_skipped`, which send
+ /// `cua_onboarding_step_*` and `cua_onboarding_skipped`.
action: String,
- /// The page's answer as a fixed word, or `none`.
+ /// The page's answer as a fixed word, or `none`; for
+ /// `step_failed`, the reason (`timeout`, `install_failed`, ...).
choice: String,
},
/// The New Space panel (`cua_space_wizard`).
@@ -906,7 +910,13 @@ pub fn record(t: &cua_telemetry::Telemetry, signals: &[TelemetrySignal]) -> usiz
page,
action,
choice,
- } => events::onboarding_page(page, action, choice).map(|e| t.capture(e)),
+ } => if action.starts_with("step_") {
+ // The first run's funnel (`first_run_step`): its own events.
+ events::first_run_step(page, action, choice)
+ } else {
+ events::onboarding_page(page, action, choice)
+ }
+ .map(|e| t.capture(e)),
TelemetrySignal::SpaceWizard { action } => {
events::space_wizard(action).map(|e| t.capture(e))
}
@@ -1921,6 +1931,65 @@ mod tests {
);
}
+ /// A `step_*` onboarding-page signal sends the first-run funnel events
+ /// with the machine's OS and app version, and an old page still sends
+ /// `cua_onboarding_page`.
+ #[cfg(feature = "telemetry")]
+ #[test]
+ fn first_run_step_signals_record_the_funnel_events() {
+ use std::sync::Arc;
+ let home = tempfile::tempdir().unwrap();
+ let sink = Arc::new(cua_telemetry::sink::MemorySink::new());
+ let t = cua_telemetry::Telemetry::builder()
+ .env(|k| (k == "CUA_TELEMETRY_FORBID_NETWORK").then(|| "1".into()))
+ .home(home.path())
+ .sink(sink.clone())
+ .product("spaces_app", "0.12.0")
+ .foreground()
+ .build();
+ t.acknowledge_notice();
+ let sig = |page: &str, action: &str, choice: &str| TelemetrySignal::OnboardingPage {
+ page: page.into(),
+ action: action.into(),
+ choice: choice.into(),
+ };
+ let signals = [
+ sig("sign_in", "step_viewed", "none"),
+ sig("sign_in", "step_failed", "timeout"),
+ sig("sign_in", "step_completed", "none"),
+ sig("terminal", "step_skipped", "none"),
+ sig("welcome", "shown", "none"),
+ sig("/Users/alice", "step_viewed", "none"),
+ ];
+ assert_eq!(record(&t, &signals), 5, "the unknown step is dropped");
+ t.flush(std::time::Duration::from_secs(2));
+ let names: Vec<String> = sink
+ .events()
+ .iter()
+ .map(|e| e["event"].as_str().unwrap().to_string())
+ .filter(|n| n.starts_with("cua_onboarding"))
+ .collect();
+ assert_eq!(
+ names,
+ [
+ "cua_onboarding_step_viewed",
+ "cua_onboarding_step_failed",
+ "cua_onboarding_step_completed",
+ "cua_onboarding_skipped",
+ "cua_onboarding_page"
+ ]
+ );
+ let events = sink.events();
+ let failed = events
+ .iter()
+ .find(|e| e["event"] == "cua_onboarding_step_failed")
+ .unwrap();
+ assert_eq!(failed["properties"]["reason"], "timeout");
+ assert_eq!(failed["properties"]["step_index"], 4);
+ assert_eq!(failed["properties"]["product_version"], "0.12.0");
+ assert!(failed["properties"]["os_family"].is_string());
+ }
+
/// Every signal the parity flow derives is a valid event: each one is
/// queued on a client (none dropped by the schema), and no name, path,
/// email or bucket from the flow's inputs is in any payload.
diff --git a/libs/cua/crates/cua-spaces-ffi/src/app_core_types.rs b/libs/cua/crates/cua-spaces-ffi/src/app_core_types.rs
index 7861d63cb1..b39f480f4c 100644
--- a/libs/cua/crates/cua-spaces-ffi/src/app_core_types.rs
+++ b/libs/cua/crates/cua-spaces-ffi/src/app_core_types.rs
@@ -9585,11 +9585,15 @@ pub enum AppTelemetrySignal {
/// A first-run page was shown or left (`cua_onboarding_page`).
OnboardingPage {
/// `welcome`, `signin`, `agents`, `presentation`, `volume`,
- /// `this_machine` or `done`.
+ /// `this_machine` or `done`; or, with a `step_*` action, one of
+ /// `schema::FIRST_RUN_STEPS` (`connect_agent`, `terminal`, ...).
page: String,
- /// `shown`, `completed`, `skipped` or `back`.
+ /// `shown`, `completed`, `skipped` or `back`; or `step_viewed`,
+ /// `step_completed`, `step_failed` or `step_skipped`, which send
+ /// `cua_onboarding_step_*` and `cua_onboarding_skipped`.
action: String,
- /// The page's answer as a fixed word, or `none`.
+ /// The page's answer as a fixed word, or `none`; for
+ /// `step_failed`, the reason (`timeout`, `install_failed`, ...).
choice: String,
},
/// The New Space panel (`cua_space_wizard`).
diff --git a/libs/cua/crates/cua-telemetry/src/events.rs b/libs/cua/crates/cua-telemetry/src/events.rs
index 82f9f31c5a..479b35dde6 100644
--- a/libs/cua/crates/cua-telemetry/src/events.rs
+++ b/libs/cua/crates/cua-telemetry/src/events.rs
@@ -923,6 +923,35 @@ pub fn onboarding_page(page: &str, action: &str, choice: &str) -> Option<Event>
})
}
+/// One of the first-run funnel events: `step_viewed`, `step_completed`,
+/// `step_failed` (with `reason`) or `skipped` (with `how`, from the same
+/// last argument). None for a step, action or
+/// reason outside the vocabulary. `step_index` and `onboarding_version`
+/// come from the step, so a caller cannot send a wrong one.
+pub fn first_run_step(step: &str, action: &str, reason: &str) -> Option<Event> {
+ let step = pick(schema::FIRST_RUN_STEPS, step, "");
+ let name = match action.trim() {
+ "step_viewed" => event::ONBOARDING_STEP_VIEWED,
+ "step_completed" => event::ONBOARDING_STEP_COMPLETED,
+ "step_failed" => event::ONBOARDING_STEP_FAILED,
+ "step_skipped" => event::ONBOARDING_SKIPPED,
+ _ => return None,
+ };
+ let index = schema::FIRST_RUN_STEPS.iter().position(|s| *s == step)?;
+ let e = Event::new(name)
+ .s("step", step)
+ .n("step_index", index as u64 + 1)
+ .n("onboarding_version", schema::FIRST_RUN_VERSION);
+ Some(match name {
+ event::ONBOARDING_STEP_FAILED => e.s(
+ "reason",
+ pick(schema::FIRST_RUN_FAIL_REASONS, reason, "other"),
+ ),
+ event::ONBOARDING_SKIPPED => e.s("how", pick(schema::FIRST_RUN_SKIP_HOWS, reason, "later")),
+ _ => e,
+ })
+}
+
/// `cua_space_wizard`; None for an action outside the vocabulary.
pub fn space_wizard(action: &str) -> Option<Event> {
let a = pick(schema::WIZARD_ACTIONS, action, "");
diff --git a/libs/cua/crates/cua-telemetry/src/schema.rs b/libs/cua/crates/cua-telemetry/src/schema.rs
index 3ca2960b52..5cd2088872 100644
--- a/libs/cua/crates/cua-telemetry/src/schema.rs
+++ b/libs/cua/crates/cua-telemetry/src/schema.rs
@@ -402,6 +402,39 @@ pub const ONBOARDING_PAGES: &[&str] = &[
"this_machine",
"done",
];
+/// The first run's screens in the order the app shows them
+/// (`cua-spaces-app-core` `first_run`), as `cua_onboarding_step_*` and
+/// `cua_onboarding_skipped` name them. Its position (1 to 6) is the
+/// `step_index`, so a funnel keeps its order whichever screens a machine
+/// skips (no terminal screen once the CLI is installed, no permissions off a Mac).
+pub const FIRST_RUN_STEPS: &[&str] = &[
+ "welcome",
+ "connect_agent",
+ "terminal",
+ "sign_in",
+ "permissions",
+ "create_space",
+];
+/// Why a first-run screen failed (fixed words; never the message).
+pub const FIRST_RUN_FAIL_REASONS: &[&str] = &[
+ "timeout",
+ "cancelled",
+ "permission_denied",
+ "unauthenticated",
+ "transport",
+ "http",
+ "internal",
+ "install_failed",
+ "connect_failed",
+ "setup_failed",
+ "create_failed",
+ "other",
+];
+/// How a first-run screen was skipped: `step` (that screen's own Skip or
+/// Not now) or `later` (Skip for now, which leaves the whole first run).
+pub const FIRST_RUN_SKIP_HOWS: &[&str] = &["step", "later"];
+/// The version of the first run these events describe (`onboarding_version`).
+pub const FIRST_RUN_VERSION: u64 = 2;
/// What happened on a first-run page.
pub const PAGE_ACTIONS: &[&str] = &["shown", "completed", "skipped", "back"];
/// The answer a first-run page was left with (fixed words; `none` for a
@@ -613,6 +646,21 @@ pub const CLI_COMMANDS: &[&str] = include!("cli_commands.in");
// Common properties
// ---------------------------------------------------------------------------
+/// The first-run funnel events' own properties.
+const FIRST_RUN_PROPS: &[Prop] = &[
+ p("step", Kind::Enum(FIRST_RUN_STEPS), "The first-run screen."),
+ p(
+ "step_index",
+ Kind::Count { max: 6 },
+ "Its position, 1 to 6.",
+ ),
+ p(
+ "onboarding_version",
+ Kind::Count { max: 100 },
+ "The first run's version (2).",
+ ),
+];
+
/// Added to every event.
pub const COMMON: &[Prop] = &[
p(
@@ -755,6 +803,10 @@ pub mod event {
pub const SPACESD_SESSION_DELIVERIES: &str = "cua_spacesd_session_deliveries";
pub const APP_ACTIVE: &str = "cua_app_active";
pub const ONBOARDING_PAGE: &str = "cua_onboarding_page";
+ pub const ONBOARDING_STEP_VIEWED: &str = "cua_onboarding_step_viewed";
+ pub const ONBOARDING_STEP_COMPLETED: &str = "cua_onboarding_step_completed";
+ pub const ONBOARDING_STEP_FAILED: &str = "cua_onboarding_step_failed";
+ pub const ONBOARDING_SKIPPED: &str = "cua_onboarding_skipped";
pub const SPACE_WIZARD: &str = "cua_space_wizard";
pub const SPACE_CREATE: &str = "cua_space_create";
pub const SPACE_CREATE_STARTED: &str = "cua_space_create_started";
@@ -1228,6 +1280,76 @@ pub const EVENTS: &[EventSpec] = &[
],
purpose: "Onboarding funnel: which page people leave on, and what they pick on each.",
},
+ EventSpec {
+ name: event::ONBOARDING_STEP_VIEWED,
+ version: 1,
+ tier: Tier::Usage,
+ sample_rate: 1.0,
+ products: &["spaces_app"],
+ props: FIRST_RUN_PROPS,
+ purpose: "Onboarding v2 funnel: how many installs see each first-run screen. The OS and app version are the common os_family and product_version.",
+ },
+ EventSpec {
+ name: event::ONBOARDING_STEP_COMPLETED,
+ version: 1,
+ tier: Tier::Usage,
+ sample_rate: 1.0,
+ products: &["spaces_app"],
+ props: FIRST_RUN_PROPS,
+ purpose: "Onboarding v2 funnel: how many installs finish each first-run screen.",
+ },
+ EventSpec {
+ name: event::ONBOARDING_STEP_FAILED,
+ version: 1,
+ tier: Tier::Usage,
+ sample_rate: 1.0,
+ products: &["spaces_app"],
+ props: &[
+ p("step", Kind::Enum(FIRST_RUN_STEPS), "The first-run screen."),
+ p(
+ "step_index",
+ Kind::Count { max: 6 },
+ "Its position, 1 to 6.",
+ ),
+ p(
+ "onboarding_version",
+ Kind::Count { max: 100 },
+ "The first run's version (2).",
+ ),
+ p(
+ "reason",
+ Kind::Enum(FIRST_RUN_FAIL_REASONS),
+ "Why it failed, as a fixed word.",
+ ),
+ ],
+ purpose: "Onboarding v2 funnel: which first-run screens fail, and why.",
+ },
+ EventSpec {
+ name: event::ONBOARDING_SKIPPED,
+ version: 1,
+ tier: Tier::Usage,
+ sample_rate: 1.0,
+ products: &["spaces_app"],
+ props: &[
+ p("step", Kind::Enum(FIRST_RUN_STEPS), "The first-run screen."),
+ p(
+ "step_index",
+ Kind::Count { max: 6 },
+ "Its position, 1 to 6.",
+ ),
+ p(
+ "onboarding_version",
+ Kind::Count { max: 100 },
+ "The first run's version (2).",
+ ),
+ p(
+ "how",
+ Kind::Enum(FIRST_RUN_SKIP_HOWS),
+ "step: that screen's own Skip or Not now; later: Skip for now, which leaves the whole first run.",
+ ),
+ ],
+ purpose: "Onboarding v2 funnel: the screens people skip, and where they leave the first run with Skip for now.",
+ },
EventSpec {
name: event::SPACE_WIZARD,
version: 1,
diff --git a/libs/cua/crates/cua-telemetry/tests/privacy.rs b/libs/cua/crates/cua-telemetry/tests/privacy.rs
index 31be647c32..b1102b13bf 100644
--- a/libs/cua/crates/cua-telemetry/tests/privacy.rs
+++ b/libs/cua/crates/cua-telemetry/tests/privacy.rs
@@ -194,6 +194,8 @@ fn all_builders(s: &str) -> Vec<Event> {
events::onboarding_step(s, Outcome::Ok),
events::onboarding_page(s, "shown", "none"),
events::onboarding_page("welcome", s, "none"),
+ events::first_run_step(s, "step_viewed", "none"),
+ events::first_run_step("welcome", s, "none"),
events::space_wizard(s),
events::persistent_agent(s, Some(s), Outcome::Ok, Some(s)),
events::share(s, s, Outcome::Ok, "none", "none"),
@@ -214,6 +216,14 @@ fn all_builders(s: &str) -> Vec<Event> {
v.push(events::sign_in_failed(s));
// Known names with caller text wherever else a builder takes it.
v.push(events::onboarding_page("volume", "completed", s).unwrap());
+ for action in [
+ "step_viewed",
+ "step_completed",
+ "step_failed",
+ "step_skipped",
+ ] {
+ v.push(events::first_run_step("create_space", action, s).unwrap());
+ }
v.push(events::space_wizard("cancelled").unwrap());
v.push(events::persistent_agent("create", Some(s), Outcome::Error, Some(s)).unwrap());
v.push(events::share("share", s, Outcome::Ok, s, s).unwrap());
@@ -1258,6 +1268,32 @@ fn activation_builders_keep_vocabulary_and_coarsen_the_rest() {
assert_eq!(Outcome::from_word("/Users/alice"), Outcome::Error);
}
+/// The first-run funnel: the step fixes its index and version, a failure
+/// names a fixed reason, and caller text never gets through.
+#[test]
+fn first_run_funnel_events_carry_step_index_version_and_a_fixed_reason() {
+ let e = events::first_run_step("sign_in", "step_viewed", "none").unwrap();
+ assert_eq!(e.name, "cua_onboarding_step_viewed");
+ assert_eq!(e.props["step"], "sign_in");
+ assert_eq!(e.props["step_index"], 4);
+ assert_eq!(e.props["onboarding_version"], 2);
+ assert!(!e.props.contains_key("reason"));
+ let f = events::first_run_step("terminal", "step_failed", "/Users/alice").unwrap();
+ assert_eq!(f.name, "cua_onboarding_step_failed");
+ assert_eq!(f.props["step_index"], 3);
+ assert_eq!(f.props["reason"], "other");
+ let f = events::first_run_step("terminal", "step_failed", "install_failed").unwrap();
+ assert_eq!(f.props["reason"], "install_failed");
+ assert_eq!(
+ events::first_run_step("welcome", "step_skipped", "none")
+ .unwrap()
+ .name,
+ "cua_onboarding_skipped"
+ );
+ // An old-flow action is not a funnel event.
+ assert!(events::first_run_step("welcome", "shown", "none").is_none());
+}
+
/// Retention: one `cua_app_active` per install per UTC day, none while
/// off, and a new one the next day.
#[test]
diff --git a/libs/spaces-app-swift/Sources/CuaSpacesFFI/CuaSpacesFFI.swift b/libs/spaces-app-swift/Sources/CuaSpacesFFI/CuaSpacesFFI.swift
index 683a176ce5..199cc98882 100644
--- a/libs/spaces-app-swift/Sources/CuaSpacesFFI/CuaSpacesFFI.swift
+++ b/libs/spaces-app-swift/Sources/CuaSpacesFFI/CuaSpacesFFI.swift
@@ -59436,13 +59436,17 @@ public enum AppTelemetrySignal: Equatable, Hashable {
case onboardingPage(
/**
* `welcome`, `signin`, `agents`, `presentation`, `volume`,
- * `this_machine` or `done`.
+ * `this_machine` or `done`; or, with a `step_*` action, one of
+ * `schema::FIRST_RUN_STEPS` (`connect_agent`, `terminal`, ...).
*/page: String,
/**
- * `shown`, `completed`, `skipped` or `back`.
+ * `shown`, `completed`, `skipped` or `back`; or `step_viewed`,
+ * `step_completed`, `step_failed` or `step_skipped`, which send
+ * `cua_onboarding_step_*` and `cua_onboarding_skipped`.
*/action: String,
/**
- * The page's answer as a fixed word, or `none`.
+ * The page's answer as a fixed word, or `none`; for
+ * `step_failed`, the reason (`timeout`, `install_failed`, ...).
*/choice: String
)
/**