Events

Server-side /analyze succeeded.

Mirror of the iOS `analysis_completed` from the server perspective. Useful when the client event is dropped (offline, queue drain, etc.) — the server still records the success.

No properties.

Server-side /analyze threw.

Mirror of `analysis_failed` from the server perspective.

No properties.

Server deduped a duplicate analyze request.

A client retried a request the server had already serviced; the dedupe layer returned the cached result instead of re-calling Gemini.

No properties.

User-action that needs a system permission — fires before we touch the system API.

Fires regardless of whether the OS prompt actually appears (an already-granted or already-denied status fires this too, with `initial_status` set accordingly). Pair with `permission_resolved` — which only fires when `initial_status` was `not_determined` — to compute prompt-conversion rates.

User responded to the system permission prompt.

Only fires when the preceding `permission_requested` had `initial_status == not_determined` — i.e. the OS prompt actually appeared. `latency_ms` is a proxy for prompt friction (a long delay is a user reading the rationale carefully). `limited` photo access counts as granted.

Catches Settings.app permission flips — the only signal iOS gives us post-prompt.

Fires on app foreground when the current status differs from what we cached on the previous run. Suppressed on first launch (no baseline to diff against — that run only seeds the cache).

User tapped the camera's record button.

Fires the moment `AVCaptureMovieFileOutput.startRecording` is called — the user is committed to a take. Pair with `record_completed` for the capture-completion rate and `record_cancelled` to bucket the drop-off cause.

A clip was successfully captured and is about to flow into the trim flow.

Fires from the AVCaptureFileOutputRecordingDelegate's `didFinishRecordingTo` callback when `error == nil`. `hit_max_cap` flags takes that auto-stopped at the duration cap rather than being stopped by the user.

User dismissed the camera screen without a usable take.

`was_recording: true` is a mid-take bail (informative on recording-quality friction); `was_recording: false` is a 'decided not to record after opening the camera' signal — more likely a permission or preview issue.

User tapped the FAB's 'Import from Photos' item.

Measures intent at the front of the import funnel. Pair with `import_completed` to compute drop-off through the Photos picker → confirm sheet flow.

No properties.

A clip the user picked from Photos is now in the local library.

One event per clip (staged + confirmed). `size_bytes` is best-effort — dropped on permission errors so a stat failure does NOT drop the whole event.

Import couldn't complete.

Fires when either every staged clip failed (PHPicker / file-copy errors) or the confirm pass dropped clips from the accepted set.

Unified 'a clip joined the library' event — both acquisition paths fire it.

Lets the dashboard answer 'of all clips in the library, what % came from each source × speed combination' with a single GROUP BY query. Imports report `speed: unknown` until we wire a `PHAsset.mediaSubtypes.videoHighFrameRate` probe.

A trim export landed.

Fires once `AVAssetExportSession` completes — one event whether the clip went straight to analyze (online) or got diverted to the offline queue. Pair with `record_completed` to see the 'captured → trimmed → analyzed' funnel.

User tapped the Analyze CTA on a clip.

Fires BEFORE the prep / transcode / pose pipeline kicks in — `analysis_started` covers the later moment when the actual /analyze network call goes out. The gap between this event and `analysis_started` captures prep-stage drop-off.

User tapped 'Cancel analysis' inside the ProcessingSheet.

Distinct from the swipe-down dismiss (which keeps the analyze running in the background). `percent` distinguishes 'bailed at 5%, impatient' from 'bailed at 80%, network stall'.

User tapped Retry in the ProcessingSheet failure UI.

Fires on the user-tap, not on the success/failure of the retry itself. `recoverable` mirrors the failure's `isRecoverable` so the dashboard can answer 'of recoverable failures, what % actually retry'.

The /analyze network call has gone out.

Anchors the actual server-roundtrip in the funnel. Earlier than this, `analyze_tapped` captures intent; later, `analysis_completed` / `analysis_failed` captures the outcome.

Gemini returned and Firestore wrote successfully.

End-of-funnel success event for the analyze path. `latency_ms` and `findings_count` are the headline quality signals.

/analyze threw.

Both the failure reason (short, low-cardinality bucket) and the recoverability flag are captured so the dashboard can split user-facing failures from queue-able transient ones.

User deleted a clip from the review screen.

`status` distinguishes 'deleted a failed clip' (strong negative — analysis didn't help) from 'deleted an analyzed clip' (could be tidying, sharing complete, etc.). Fired up-front so the event lands even if a cleanup branch throws.

Library feed shell appeared on screen.

Per-screen visit count; useful for "how often do users return to browse."

No properties.

User flicked to a new clip in the immersive vertical feed.

Highest-volume event in the taxonomy — one per page change.

User tapped into a clip's review screen from the library grid.

Distinguishes "scrolled past it" from "actually engaged with it."

User opened a past clip's findings sheet.

Counts how often users *open the collection* of findings for a clip — pair with `finding_viewed` (one event per individual finding card) to measure the open→drill-in funnel.

User paged onto an individual finding card.

Distinguishes "opened the findings sheet" from "actually read individual findings."

User tapped "Tell me more" on a specific finding.

Fires only on the open transition, not the collapse. Pair with `findings_viewed` to measure depth of engagement.

/explain returned successfully.

Pairs with `finding_explain_requested` for the open→resolution funnel. `latency_ms` is the user's actual wait.

/explain threw.

Cancellations are excluded (user-driven teardown). `reason` shares the analyze-failure vocabulary.

User completed a horizontal scrub gesture on a clip player.

Fires once per drag, on gesture end, only when the gesture actually committed to horizontal-scrub. Summed `duration_ms` is total scrub time per user.

User created a new player roster entry.

Fires only on the new-player path (edits are not roster growth).

User flipped the active player in the switcher menu.

Gated on an actual transition — re-tapping the already-active player is a no-op. The denominator is 'user opened the switcher AND picked a different player'.

User archived a player — v1's user-facing delete.

Archive keeps the player's clips visible under 'All players' with an archived badge. True hard-delete is a separate settings action that isn't wired yet; if/when it ships, `player_removed` will join this taxonomy.

User assigned tags to a clip.

Empty sport/action are kept as empty strings rather than dropped so dashboards can distinguish 'user cleared the tag' from 'user never set one.'

User tapped a provider button on the welcome screen.

Fired before the `AuthService` call goes out so the per-provider denominator includes attempts that fail or get cancelled. Provider strings match FirebaseAuth `providerID` values for clean joins with `signed_in` and `sign_in_failed`.

`AuthService` threw a non-cancel error.

Cancels (`AuthError.userCancelled`) are filtered out — a user dismissing the Apple/Google sheet doesn't count as a failure. Reason is the `AuthError` case name (low cardinality so dashboards can group by failure mode without parsing message strings).

Fresh sign-in resolved.

Fires after FirebaseAuth's state-change listener observes a new uid. Fired AFTER `Analytics.setUserID` so the event itself is attributed to the new uid.

Sign-out completed.

Fires BEFORE `clearIdentity` so the event itself is still attributed to the user who just signed out, not to nobody.

No properties.

App entered the foreground.

Covers cold launches and background-to-foreground resumes. The `was_cold` property distinguishes the two so dashboards can split fresh starts from quick resumes. Pair with `app_backgrounded` to derive session length downstream.

App moved to the background.

Fires exactly once per "user left the app" transition. Pair with the most-recent `app_opened` to bound a session.

No properties.