feat(analytics): screen.viewed consolidation (#2883)

[piyalbasu]

TL;DR

Part of the cross-platform analytics refactor (#2883). This collapses every screen-load event (previously named "loaded screen: X") into a single canonical event screen.viewed, carrying screen_name, flow, surface, and step (where a screen is a sub-step). No non-screen (domain/action) event is renamed or touched — those are handled in a follow-up change.

screen_name is derived deterministically from the existing legacy string (part after "loaded screen: ", trimmed, lowercased, each run of non-alphanumeric chars → a single _). Because both platforms already use identical legacy strings, this yields cross-platform-consistent names automatically. surface comes from the foundation's getSurface() via the common context.

⚠️ This PR stacks on the unmerged feat/analytics-schema-foundation-spec (the property-model foundation). Base is that branch, not master. Review/merge the foundation PR first.

🤖 Opened unattended by an automated agent. Decisions were made autonomously and documented below — the screen_name reconciliation checklist in particular needs a human pass against the RFC's canonical screen catalog before this ships.

What changed

New machinery (extension/src/helpers/metrics.ts)

• emitScreenViewed(screenName, props?) — emits screen.viewed with screen_name + optional flow/step + any preserved extra props. Undefined flow/step are dropped from the payload. surface/schema_version/etc. are attached by the existing buildCommonContext (from the property-model foundation).
• toScreenName(legacy) — the deterministic legacy→canonical derivation (documented + unit-tested against the documented examples).
• Flow union type: onboarding | send | swap | signing | assets | settings | discovery | security | history.
• METRIC_NAMES.screenViewed = "screen.viewed" added.

Cutover (hard — each screen emits ONLY screen.viewed, never both)

• popup/metrics/views.ts: routeToEventName (route → legacy name) refactored into routeToScreen (route → { screen_name, flow, step? }) as the single source of truth. The navigate handler emits screen.viewed, preserving the extra props on grant-access / add-token / sign-transaction / sign-auth-entry / sign-message (domain, subdomain, sidebarMode, number_of_operations, operationTypes).
• popup/views/Send/index.tsx & popup/views/Swap/index.tsx: step→legacy-name maps became step→screen-def maps.
• popup/components/swap/SwapAmount/index.tsx, popup/views/DisplayBackupPhrase/index.tsx, popup/components/manageAssets/TrustlineError/index.tsx, popup/metrics/discover.ts: cut over to emitScreenViewed.
• popup/constants/metricsNames.ts: removed all now-dead "loaded screen: X" constants (verified unreferenced). Non-screen names left intact.
• config/jest/setupTests.tsx: added emitScreenViewed to the global helpers/metrics mock so screen-rendering component tests keep passing.

Tests

• helpers/metrics.test.ts: toScreenName derivation + emitScreenViewed (event name, screen_name/flow/surface, extra-prop passthrough, step, and the no-legacy-name guarantee).
• popup/metrics/views.test.ts (new): route→screen mapping, preserved props, completion-screen step, the untouched non-screen modify-asset-list event, and that every route maps and never yields a loaded screen: name.

Decisions made autonomously

• Scope = ALL screen-load emit sites, not just views.ts. This covers every emit that currently fires a loaded screen: X event. Beyond the navigate handler, that included the Send/Swap step maps, SwapAmount set-max, DisplayBackupPhrase, TrustlineError, and discover.trackDiscoverViewed. All cut over.
• Completion/success screens use a step property, not bespoke events: account_creator_finished, recover_account_success, account_migration_migration_complete → step: "success".
• ROUTES.manageAssetsListsModifyAssetList left untouched. Its route navigation already emitted a non-screen action event ("manage asset list: modify asset list"), not a "loaded screen:" event, so per scope it is preserved verbatim (special-cased in the handler; its constant kept).
• SwapAmount set-max click historically fired "loaded screen: swap amount" on a button click (a pre-existing oddity). Behavior preserved, just renamed to screen.viewed / swap_amount. Flagged here; re-classifying it as an action event belongs to a follow-up change.
• Debug/integration-test screens kept emitting screen.viewed (debug, integration_test) — their removal is a follow-up change.
• screen_name uses the mechanical value, not a hand-polished catalog name, even where it reads awkwardly (send_payment_amount, add_fund, account_migration_migration_complete). See the reconciliation checklist.
• flow assignment is best-effort judgment; omitted where nothing fit (account, view_public_key_generator, debug, integration_test, wallets).
• Sub-step granularity for Send/Swap lives in screen_name (e.g. send_payment_amount), so step was reserved for terminal completion markers rather than duplicating the step name.

📋 screen_name reconciliation checklist — every name produced (reconcile against the RFC canonical screen catalog)

Mechanically derived. Tick once confirmed against the RFC catalog; flagged rows are the likely rename candidates.

screen_name	flow	step	source	note
welcome	onboarding		views
account	—		views	home view; no flow assigned
account_history	history		views
add_account	onboarding		views
import_account	onboarding		views
connect_wallet	onboarding		views
connect_wallet_plugin	onboarding		views
connect_device	onboarding		views
add_token	signing		views	+domain/subdomain/sidebarMode
sign_message	signing		views	+domain/subdomain/sidebarMode
sign_transaction	signing		views	+domain/subdomain/sidebarMode/number_of_operations/operationTypes
review_authorization	signing		views
sign_auth_entry	signing		views	+domain/subdomain/sidebarMode
grant_access	signing		views	+domain/subdomain/sidebarMode
mnemonic_phrase	onboarding		views
confirm_mnemonic_phrase	onboarding		views
unlock_account	security		views
verify_account	security		views
account_creator_finished	onboarding	success	views	⚠️ completion screen; catalog name?
account_creator	onboarding		views
recover_account	onboarding		views
recover_account_success	onboarding	success	views	completion screen
display_backup_phrase	security		views + DisplayBackupPhrase
unlock_backup_phrase	security		DisplayBackupPhrase
settings	settings		views
preferences	settings		views
security	security		views
manage_connected_apps	settings		views	flow could be security
about	settings		views
view_public_key_generator	—		views	⚠️ awkward legacy name ("view public key generator")
debug	—		views	debug screen
integration_test	—		views	test screen
send_payment	send		views
add_collectibles	assets		views
manage_assets	assets		views
search_asset	assets		views
asset_visibility	assets		views
add_asset_manually	assets		views	⚠️ vs catalog add_asset?
swap	swap		views
manage_network	settings		views
add_network	settings		views
edit_network	settings		views
network_settings	settings		views
leave_feedback	settings		views
manage_assets_lists	assets		views	flow could be settings
account_migration	security		views	flow judgment call
account_migration_review_migration	security		views
account_migration_mnemonic_phrase	security		views
account_migration_confirm_migration	security		views
account_migration_migration_complete	security	success	views	⚠️ double "migration" in legacy string
advanced_settings	settings		views
auto_lock_timer	security		views
add_fund	assets		views	⚠️ singular; legacy "add fund" typo → add_funds?
wallets	—		views
confirm_sidebar_request	signing		views
send_payment_select_asset	send		Send step	⚠️ vs catalog send_select_asset?
send_payment_amount	send		Send step	⚠️ vs catalog send_amount?
send_payment_confirm	send		Send step	⚠️ vs catalog send_confirm?
send_payment_to	send		Send step	⚠️ vs catalog send_destination?
swap_confirm	swap		Swap step
swap_to_asset	swap		Swap step
swap_amount	swap		Swap step + SwapAmount set-max
swap_amount_review	swap		Swap step
swap_from_asset	swap		Swap step
trustline_error	assets		TrustlineError
discover	discovery		discover.ts

Verification

Run from repo root (see environment note below):

• npx tsc --noEmit -p extension/tsconfig.json → clean (exit 0).
• npx jest extension/src/helpers/metrics.test.ts extension/src/popup/metrics/views.test.ts → 42 passed.
• Affected component/module tests (Send, Swap, SwapAmount, DisplayBackupPhrase, TrustlineError, send.test.ts, views/__tests__/Send.test.tsx) → all passing (pre-existing Swap.test.tsx skips are unchanged, not introduced here).
• prettier --check on all touched files → clean after formatting.

Environment note: this branch was prepared in a sandbox where the yarn@4 corepack binary download (repo.yarnpkg.com) is blocked by egress policy, so dependencies were installed with npm --ignore-scripts and the commits use --no-verify. Verification steps above were run manually with npx in place of the husky pre-commit hook (webpack/prettier/i18next); the hook itself was not exercised. CI should run the normal yarn toolchain.

---

Generated by Claude Code

[github-actions]

PR Preview build is ready: https://github.com/stellar/freighter/releases/tag/untagged-f066e36e5606759d3651 (SDF collaborators only — install instructions in the release description)

[CassioMG]

do we have this same event on mobile? If not, should we add it there or remove it from here to keep parity?

[piyalbasu]

Good catch — no, mobile doesn't have a swap: amount percentage set event, and I'd introduced it only on this side. I've reworked it to match mobile instead.

TL;DR: Mobile fires the shared send payment: set max action event on the Max tap only (and reuses that same event on both send and swap). The extension's Send screen already did exactly that; only the Swap screen diverged — I'd coined a new swap: amount percentage set event that fired on every percentage tap. I've dropped that new event and pointed the swap Max tap at the same shared send payment: set max, gated on 100%. Now all four call sites (ext send, ext swap, mobile send, mobile swap) emit one consistent event. Partial-tap (25/50/75) telemetry is gone — it was net-new and single-platform; if we want it, it should be added deliberately to both platforms in the action-events follow-up.

---

Details

Before (this PR): the swap handler emitted emitMetric(METRIC_NAMES.swapAmountPercentageSet, { percentage: pct }) on all of 25/50/75/100.

After: if (pct === 100) { emitMetric(METRIC_NAMES.sendPaymentSetMax); } — the swap: amount percentage set constant is removed, and the telemetry test now asserts partial taps emit nothing while the Max tap emits send payment: set max (and still no screen.viewed).

Mobile parity (both max-only, shared event):

• Swap: https://github.com/stellar/freighter-mobile/blob/7ab58d969c382eea9ec79d42e1b60b28c1aa2451/src/components/screens/SwapScreen/screens/SwapAmountScreen.tsx#L441-L442
• Send: https://github.com/stellar/freighter-mobile/blob/7ab58d969c382eea9ec79d42e1b60b28c1aa2451/src/components/screens/SendScreen/screens/TransactionAmountScreen.tsx#L464-L467

One caveat worth flagging: send payment: set max firing on a swap screen is semantically off — it says "send payment" but it's a swap. Mobile already lives with this, so matching it keeps us consistent today, but a properly-named shared set max event is a good candidate for the action-events follow-up so both platforms rename together. I'll note it on the RFC.

[CassioMG]

should we make this screen_name: string; like we have on mobile?

[piyalbasu]

I'd lean toward keeping it as-is here, but happy to align if we want literal shape-parity — the two are structured differently on purpose.

TL;DR: On the extension, screen_name isn't an optional prop — it's a required positional argument to emitScreenViewed(screenName, props), so it can't be omitted or mistyped. ScreenViewedProps is deliberately just the extra stuff that rides alongside it (flow, step, passthrough). Folding screen_name into that interface would actually make it structurally optional (the interface has a [key: string]: unknown index signature and callers pass props = {}), i.e. weaker than what we have. If the goal is cross-platform code that reads the same, I'm glad to restructure to a single-object signature to match mobile — just want to flag it's a slight typing downgrade, so I'd only do it for the consistency, not for safety.

---

Details

Current shape:

export const emitScreenViewed = (
  screenName: string,                 // required, positional — cannot be dropped
  props: ScreenViewedProps = {},      // the *extra* props only
) => { ... body = { screen_name: screenName, ...props } ... };

export interface ScreenViewedProps {
  flow?: Flow;
  step?: Step;
  [key: string]: unknown;
}

Adding screen_name: string to ScreenViewedProps only helps if we also collapse the signature to emitScreenViewed(props). As long as screenName stays a separate required arg, a screen_name field on the props type would be dead (never read) or contradictory.

Call sites already lean on the positional shape — e.g. Send/Swap destructure the catalog entry and pass the name explicitly: const { screen_name, ...props } = screen; emitScreenViewed(screen_name, props);.

So the options are:

1. Keep as-is (my lean): required positional screenName + extras interface — strongest typing.
2. Match mobile's shape: change to emitScreenViewed({ screen_name, flow, step, ... }) with screen_name: string required on the type. Reads the same as mobile; costs a small refactor of the ~7 call sites and is marginally weaker only if we keep the index signature.

Which do you prefer? If (2), I'll make it required on the interface (no ?) so we don't lose the guarantee.

[CassioMG]

step coverage is asymmetric with mobile — confirm this is intentional

The step vocabulary (confirm | processing | success) matches mobile (stellar/freighter-mobile#937), and both platforms emit confirm on the send/swap confirm screens. But the applied set differs:

step	Extension (this PR)	Mobile (#937)
confirm	✅ send/swap confirm	✅ send/swap confirm
success	✅ account_creator_finished (this line), recover_account_success, account_migration_migration_complete	❌ none
processing	❌ none	✅ send_payment_processing

A cross-platform funnel keyed on step: "success" will see extension-only data, and one keyed on step: "processing" will see mobile-only data. The migration/completion success screens are genuinely extension-specific, but worth confirming: does the extension send/swap flow have an in-flight state that should carry step: "processing" to match mobile's send_payment_processing? Flagging the same question on both PRs so step coverage is decided together.

[piyalbasu]

Good flag — closed the processing gap in f4c36fd.

TL;DR: The extension now emits send_payment_processing (flow: "send", step: "processing") when a send submission goes in-flight, matching mobile — so a cross-platform step: "processing" funnel now has extension data. Scoped to send only (mobile emits no swap-processing event, so adding one here would be new single-platform drift). The success steps stay extension-only by design — they're dedicated completion routes mobile renders without a screen.

---

Details

Why an effect, not a step/route. Unlike mobile — where send_payment_processing is a navigable screen — the extension's in-flight state is an internal render state of the confirm screen (submitStatus === PENDING → SendingTransaction inside the shared SubmitTransaction), still on send_payment_confirm. There's no route/step to hang it on, so it's emitted from a submitStatus effect in Send/index: fires once when status → PENDING, guard resets when the status clears so a retried submission re-emits. Test added in Send.test.tsx.

https://github.com/stellar/freighter/blob/f4c36fd2/extension/src/popup/components/InternalTransaction/SubmitTransaction/index.tsx#L373-L380

Swap left alone (deliberate). Mobile has a SwapProcessingScreen UI but emits no analytics for it — there's no swap-processing event on mobile. Adding one on the extension would reintroduce the exact single-platform drift this refactor is removing. If we want processing coverage for swap, that's a both-platforms addition (extension + a mobile change on #937) — happy to open it if you'd like.

success asymmetry is a real catalog difference, not tagging drift. The three step: "success" screens are dedicated routes (onboarding completion + account-migration complete); mobile's flows don't have equivalent screens.

[piyalbasu]

Cross-linking the mobile side: the parity this thread assumes is now real on both ends.

TL;DR: When the table above was written, mobile declared send_payment_processing in its catalog but never actually emitted it — no route or component fired it, so a step: "processing" funnel would have been empty on mobile. That's now fixed in stellar/freighter-mobile#937 (commit 6f81a5e2): mobile emits send_payment_processing (flow: "send", step: "processing") once when its processing screen mounts, which is send-only and once-per-submission — same semantics as the extension's PENDING effect here. So the processing stage is genuinely symmetric now, and success stays extension-only by design (mobile has no dedicated completion screens — those are action events, and there's no account-migration flow). No further change needed on this PR.

[CassioMG]

should we rename it to SCREEN_BY_ROUTE for consistency with SWAP_SCREEN_BY_STEP and SEND_SCREEN_BY_STEP?

[piyalbasu]

Done — renamed routeToScreen → SCREEN_BY_ROUTE in 398a9dc, matching SEND_SCREEN_BY_STEP / SWAP_SCREEN_BY_STEP.