Usage telemetry
Which anonymous usage events a Spaces app step means, and sending them.
Which anonymous usage events a Spaces app step means, and sending them.
These APIs are part of the Cua Spaces app export for building Spaces UIs. They are source-available under FSL-1.1-MIT and ship for Swift only (import CuaSpacesFFI); the Rust tab shows the cua-spaces-ffi crate they come from. The open source SDK packages for Python, TypeScript and Kotlin do not include them.
Each app_telemetry_* function takes a reducer step (the state before it and the action) and returns the AppTelemetrySignals it means: first-run pages, Space creates, Settings, Storage, sharing and enrollment, as fixed words only. app_telemetry_record sends them on the SDK's telemetry client, where every switch and the first-run notice apply. app_telemetry_start and app_telemetry_welcome_left hold the first events until the first run's Welcome page is left, with its usage-data switch deciding. What is sent: Telemetry and privacy.
AppTelemetrySignal enum#.feature(feature: String)
.step(step: String, ok: Bool)
.onboardingPage(page: String, action: String, choice: String)
.spaceWizard(action: String)
.spaceCreate(location: String, guestOs: String, kind: String, outcome: String, failedPhase: String, stalled: Bool, elapsedMs: UInt64, gpu: Bool)
.spaceCreateStarted(location: String, guestOs: String, kind: String, gpu: Bool)
.volumeSetup(surface: String, storage: String, addToFinder: Bool, mountMethod: String, outcome: String)
.share(action: String, role: String, outcome: String)
.appUpdate(action: String, channel: String, trigger: String)
.deviceEnroll(method: String, outcome: String)
.experiment(action: String, experiment: String)
.experimentsOn(experiments: [String])| Variant | Description |
|---|---|
Feature | A Spaces app feature was used (cua_spaces_feature_used). Fields: feature: String |
Step | An install or activation funnel step (cua_onboarding_step; first_* steps count once per install). Fields: step: String, ok: bool |
OnboardingPage | A first-run page was shown or left (cua_onboarding_page). Fields: page: String, action: String, choice: String |
SpaceWizard | The New Space panel (cua_space_wizard). Fields: action: String |
SpaceCreate | A Space create reached ready or failed (cua_space_create). Fields: location: String, guest_os: String, kind: String, outcome: String, failed_phase: String, stalled: bool, elapsed_ms: u64, gpu: bool |
SpaceCreateStarted | A Space create started (cua_space_create_started). Fields: location: String, guest_os: String, kind: String, gpu: bool |
VolumeSetup | A Cua Volume setting was saved (cua_volume_setup). Fields: surface: String, storage: String, add_to_finder: bool, mount_method: String, outcome: String |
Share | A Space was shared, unshared or its role changed (cua_share). Fields: action: String, role: String, outcome: String |
AppUpdate | An updater step (cua_app_update). Fields: action: String, channel: String, trigger: String |
DeviceEnroll | This device enrolled with the relay, or failed to (cua_device_enroll). Fields: method: String, outcome: String |
Experiment | An experiment was turned on or off in Settings, Experiments (cua_experiment). Fields: action: String, experiment: String |
ExperimentsOn | Which experiments are on now (no event of its own: the daily cua_app_active carries them as experiments_on). Fields: experiments: Vec<String> |
app_telemetry_creates#The events one step of the Spaces being created means, at now_ms
(call with the state before it).
func appTelemetryCreates(state: AppCreatesState, action: AppCreateAction, nowMs: Int64) -> [AppTelemetrySignal]| Parameter | Type | Default |
|---|---|---|
state | AppCreatesState | required |
action | AppCreateAction | required |
now_ms | i64 | required |
Returns Vec<AppTelemetrySignal>
app_telemetry_enroll#The events one step of the enroll sheet means.
func appTelemetryEnroll(state: AppEnrollState, action: AppEnrollAction) -> [AppTelemetrySignal]| Parameter | Type | Default |
|---|---|---|
state | AppEnrollState | required |
action | AppEnrollAction | required |
Returns Vec<AppTelemetrySignal>
app_telemetry_feature#A Spaces app feature (a fixed name).
func appTelemetryFeature(feature: String) -> [AppTelemetrySignal]| Parameter | Type | Default |
|---|---|---|
feature | String | required |
Returns Vec<AppTelemetrySignal>
app_telemetry_launched#The app started (app_launched).
func appTelemetryLaunched() -> [AppTelemetrySignal]Returns Vec<AppTelemetrySignal>
app_telemetry_onboarding#The events one first-run step means (call with the state before it).
func appTelemetryOnboarding(state: AppOnboardingState, action: AppOnboardingAction) -> [AppTelemetrySignal]| Parameter | Type | Default |
|---|---|---|
state | AppOnboardingState | required |
action | AppOnboardingAction | required |
Returns Vec<AppTelemetrySignal>
app_telemetry_onboarding_finished#"Start using Cua Spaces".
func appTelemetryOnboardingFinished(state: AppOnboardingState) -> [AppTelemetrySignal]| Parameter | Type | Default |
|---|---|---|
state | AppOnboardingState | required |
Returns Vec<AppTelemetrySignal>
app_telemetry_record#Records signals on the SDK's telemetry client (the switch, the notice
and the schema apply) and marks the day active. Returns how many events
were queued.
func appTelemetryRecord(signals: [AppTelemetrySignal]) -> UInt32| Parameter | Type | Default |
|---|---|---|
signals | Vec<AppTelemetrySignal> | required |
Returns u32
app_telemetry_share#The events one step of the Share sheet means.
func appTelemetryShare(input: AppShareInput, state: AppShareSheetState, action: AppShareSheetAction) -> [AppTelemetrySignal]| Parameter | Type | Default |
|---|---|---|
input | AppShareInput | required |
state | AppShareSheetState | required |
action | AppShareSheetAction | required |
Returns Vec<AppTelemetrySignal>
app_telemetry_start#The app started: attributes this process's events to spaces_app at
version, lets the app show the first-run notice itself (nothing is
sent before it has been shown once), and records app_launched (on a
first run, once the notice shows). Call once at launch, before the
first Cua. Returns whether the notice was already shown here.
func appTelemetryStart(version: String) -> Bool| Parameter | Type | Default |
|---|---|---|
version | String | required |
Returns bool
app_telemetry_storage#The events one step of Settings, Storage means.
func appTelemetryStorage(input: AppStorageInput, state: AppStorageState, action: AppStorageAction) -> [AppTelemetrySignal]| Parameter | Type | Default |
|---|---|---|
input | AppStorageInput | required |
state | AppStorageState | required |
action | AppStorageAction | required |
Returns Vec<AppTelemetrySignal>
app_telemetry_welcome_left#The first run left Welcome with its usage-data switch at on: writes
the machine's setting when it changed (the same as Settings and cua telemetry off), then records that the notice was shown. Nothing is
queued or sent before; with the switch off, nothing after either.
func appTelemetryWelcomeLeft(on: Bool) throws| Parameter | Type | Default |
|---|---|---|
on | bool | required |
Raises CuaError