Skip to content

feat(ramps): add Unified Buy v2 analytics events#26374

Merged
amitabh94 merged 29 commits into
mainfrom
feat/ramps-unified-buy-v2-analytics
Feb 27, 2026
Merged

feat(ramps): add Unified Buy v2 analytics events#26374
amitabh94 merged 29 commits into
mainfrom
feat/ramps-unified-buy-v2-analytics

Conversation

@amitabh94

@amitabh94 amitabh94 commented Feb 20, 2026

Copy link
Copy Markdown
Contributor

Description

Add comprehensive analytics events to the Unified Buy v2 flow, covering every user interaction across Token Selection and Amount Input screens. Flow identity uses ramp_type only (e.g. 'UNIFIED BUY 2'); for a single dimension in Segment and Data Council.

Reason for change: Measure UB2 funnel conversion and drop-offs; compare UB2 vs UB1.
Improvement: 18 new events + enhanced existing events; screen viewed once per visit; Change provider only in Payment Selection modal.

Changes

  • 18 new events: Ramps Screen Viewed, Back Button Clicked, Network Filter Clicked, Token Searched, Settings Clicked, Setting Option Clicked, Payment Method Selector Clicked, Quick Amount Clicked, Change Provider Button Clicked, Provider Selected, Continue Button Clicked (KPI), Terms Consent Clicked, External Link Clicked, Close Button Clicked, Quote Error, Quote Error Tooltip Clicked, Unsupported Token Tooltip Clicked, Toast Button Clicked.
  • Existing enhanced: RAMPS_TOKEN_SELECTED and RAMPS_BUTTON_CLICKED accept ramp_type: 'UNIFIED BUY 2'.
  • Screens: TokenSelection, BuildQuote, PaymentSelectionModal (Change provider only).

Related PRs

Changelog

CHANGELOG entry: null

Related issues

Fixes: https://consensyssoftware.atlassian.net/browse/TRAM-3028

Manual testing steps

Feature: Unified Buy v2 analytics events

  Scenario: user completes token selection and amount input in UB2 flow
    Given Unified Buy v2 is enabled (MM_RAMPS_UNIFIED_BUY_V2_ENABLED=true) and user is on Buy from home

    When user opens Token Selection then searches token, filters by network, selects token, opens Amount Input, taps quick amount, opens payment selector, taps Change provider in Payment Selection modal, taps Settings, then taps Continue

    Then Segment debugger shows Ramps Screen Viewed (once per visit per screen), Ramps Token Searched, Ramps Network Filter Clicked, Ramps Token Selected with ramp_type UNIFIED BUY 2, Ramps Quick Amount Clicked, Ramps Payment Method Selector Clicked, Ramps Change Provider Button Clicked, Ramps Settings Clicked, Ramps Continue Button Clicked with no feature_flag_unified_buy_v2 in payloads

Screenshots/Recordings

Pre-merge author checklist

Pre-merge reviewer checklist

  • I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
  • I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

Note

Medium Risk
Adds/changes analytics instrumentation across multiple ramp screens and entry points, which is moderately risky due to potential schema regressions or event-volume changes (but no funds/auth logic is altered).

Overview
Adds Unified Buy v2 (UB2) analytics instrumentation across the ramps flow, introducing a new ramp_type value (UNIFIED_BUY_2) and a set of new MetaMetrics events (screen views, back/close, settings, quick amounts, provider/payment selection, external links, quote errors, tooltips, etc.).

Updates existing ramps events to match the new schema (notably renaming the RAMPS_BUTTON_CLICKED property from text to button_text) and wires UB2-aware ramp_type selection into multiple entry points (e.g., BalanceEmptyState, FundActionMenu, AccountsMenu, Card add-funds deposit).

Extends navigation header helpers to support an optional onBackPress callback so screens can track back navigation, and adjusts unit/smoke tests and snapshots accordingly.

Written by Cursor Bugbot for commit 2fb77db. This will update automatically on new commits. Configure here.

Add 18 new event enum values and TypeScript interfaces for
comprehensive Unified Buy v2 analytics tracking. Instrument
TokenSelection and BuildQuote screens with:
- Screen viewed events
- Token search (debounced)
- Network filter clicks
- Quick amount pill selection
- Payment method selector clicks
- Change provider button clicks
- Continue button clicked (KPI)
- Settings button clicks
- Unsupported token tooltip clicks

Update existing RAMPS_TOKEN_SELECTED to include ramp_type
differentiation for UB2 phase comparison.

Remaining screens (NativeFlow, Checkout, Order Details, modals)
will be instrumented in follow-up commits.

Co-authored-by: Cursor <cursoragent@cursor.com>
@github-actions

Copy link
Copy Markdown
Contributor

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

@metamaskbot metamaskbot added the team-money-movement issues related to Money Movement features label Feb 20, 2026
amitabh94 and others added 2 commits February 20, 2026 16:52
Flow identity uses ramp_type only (e.g. UNIFIED BUY 2) for Segment and Data Council.
Update PR description to state ramp_type-only; see pr_26374_body.md for body copy.

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@sonarqubecloud

Copy link
Copy Markdown

Quality Gate Failed Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

Co-authored-by: Cursor <cursoragent@cursor.com>
@amitabh94 amitabh94 force-pushed the feat/ramps-unified-buy-v2-analytics branch from 998158b to 640cb83 Compare February 24, 2026 00:57
amitabh94 and others added 4 commits February 23, 2026 21:35
…ildQuote lints

- Remove feature_flag_unified_buy_v2 from all ramp analytics events in TokenSelection and BuildQuote
- Use UnifiedRampRoutingType.AGGREGATOR for ramp_routing fallback
- Use userRegion.regionCode for region (Country has isoCode, not code)
- Remove redundant useCallback deps and unused useRampsUnifiedV2Enabled in BuildQuote

Co-authored-by: Cursor <cursoragent@cursor.com>
Use UNIFIED_BUY_2 and UNIFIED_BUY (underscored) to match the segment
schema enum values. Updates event payloads, TypeScript types, and tests.

Co-authored-by: Cursor <cursoragent@cursor.com>
Resolve merge conflict in BuildQuote.tsx: keep analytics tracking
for RAMPS_PAYMENT_METHOD_SELECTOR_CLICKED with main's simplified
callback structure.

Add analytics tracking to new V2 order details screens:
- OrderDetails: RAMPS_SCREEN_VIEWED on mount
- OrderContent: RAMPS_EXTERNAL_LINK_CLICKED on provider link press
- DepositOrderDetails: RAMPS_SCREEN_VIEWED on mount
- Checkout: RAMPS_SCREEN_VIEWED + RAMPS_CLOSE_BUTTON_CLICKED

Co-authored-by: Cursor <cursoragent@cursor.com>
Add RAMPS_SCREEN_VIEWED to native flow screens (Verify Identity,
Enter Email, OTP Code) for both V2 and Deposit paths.

Add RAMPS_BACK_BUTTON_CLICKED via navbar onClose callbacks for
all screens: Verify Identity, Enter Email, OTP Code, Order Details.

Add RAMPS_TERMS_CONSENT_CLICKED to Verify Identity screens.

Add RAMPS_EXTERNAL_LINK_CLICKED to Verify Identity link handlers.

Add RAMPS_SETTING_OPTION_CLICKED to Settings modal options
(View Order History, Contact Support, Log Out).

Add RAMPS_PROVIDER_SELECTED to ProviderSelectionModal.

Add RAMPS_CHANGE_PROVIDER_BUTTON_CLICKED to TokenNotAvailableModal.

Add RAMPS_QUOTE_ERROR to BuildQuote when quote fetch fails.

Add RAMPS_CLOSE_BUTTON_CLICKED to OrderDetails close button.

Made-with: Cursor
@github-actions github-actions Bot added size-L and removed size-M labels Feb 25, 2026
- Track payment method selection (RAMPS_PAYMENT_METHOD_SELECTED) in
  PaymentSelectionModal when user picks a method like Apple Pay
- Track change provider click from PaymentSelectionModal
- Track info tooltip click on Order Details (Processing Info)
- Track support link click from ProcessingInfoModal
- Update RampsPaymentMethodSelected type to accept UNIFIED_BUY_2

Made-with: Cursor
…event

Replace RAMPS_EXTERNAL_LINK_CLICKED with RAMPS_INFO_TOOLTIP_CLICKED
for the order details info icon, since it opens an in-app modal
rather than an external link.

Made-with: Cursor
- Add onBackPress callback to getRampsBuildQuoteNavbarOptions
- Fire RAMPS_BACK_BUTTON_CLICKED from BuildQuote (Amount Input)
- Fire RAMPS_BACK_BUTTON_CLICKED from Checkout (Aggregator Checkout)

Made-with: Cursor
The back arrow is rendered even with showBack: false since showClose
defaults to true in getDepositNavbarOptions.

Made-with: Cursor
Use a ref guard so RAMPS_SCREEN_VIEWED fires only once per screen
mount in BuildQuote and TokenSelection, preventing duplicate events
when rampRoutingDecision changes during navigation to Checkout.

Made-with: Cursor
@amitabh94 amitabh94 added the no-changelog no-changelog Indicates no external facing user changes, therefore no changelog documentation needed label Feb 26, 2026
- Remove explicit `= undefined` default from getRampsOrderDetailsNavbarOptions
  onClose param to fix TS type narrowing issue
- Widen TokenNetworkFilterBar setNetworkFilter prop type to accept plain
  callback since the component only calls it with direct values
- Fix useAnalytics mock in TokenSelection and OrderContent tests to export
  named trackEvent via arrow wrapper (avoids Jest hoisting timing issue)
- Mock useDebouncedValue in TokenSelection tests to prevent async cleanup
  issues during test teardown
- Update TokenSelection snapshots

Made-with: Cursor
…reateEventBuilder

Replace Ramp-specific trackRampsEvent calls with the shared useAnalytics
hook and createEventBuilder pattern across all 17 Unified Buy v2 source
files. Remove redundant per-file useAnalytics mocks from test files since
the global testSetup.js already provides this mock. Remove analytics
assertion test cases that only tested implementation wiring.

Made-with: Cursor
@github-actions github-actions Bot added size-XL and removed size-L labels Feb 27, 2026
…y-v2-analytics

Made-with: Cursor

# Conflicts:
#	app/components/UI/Ramp/Views/Checkout/Checkout.tsx
@amitabh94 amitabh94 marked this pull request as ready for review February 27, 2026 05:56
@amitabh94 amitabh94 requested review from a team as code owners February 27, 2026 05:56
Comment thread app/components/UI/Ramp/Views/Checkout/Checkout.tsx
Comment thread app/components/UI/Ramp/Views/TokenSelection/TokenSelection.tsx
Comment thread app/components/UI/Ramp/Views/TokenSelection/TokenSelection.tsx Outdated
- Gate TokenSelection analytics on isV2UnifiedEnabled flag (HIGH: v2
  events were firing for v1 users)
- Add hasTrackedScreenViewRef guard to Checkout screen viewed (MED:
  event could fire multiple times)
- Prevent token search re-firing on network filter change by tracking
  previous search string
- Update E2E test to expect UNIFIED_BUY_2 when v2 flag is enabled
- Remove duplicate useRampsUnifiedV2Enabled hook call in TokenSelection

Made-with: Cursor
Comment thread app/components/UI/Ramp/Views/Modals/ProcessingInfoModal/ProcessingInfoModal.tsx Outdated
Comment thread app/components/UI/Ramp/Views/BuildQuote/BuildQuote.tsx
- Wrap new URL() in try-catch in ProcessingInfoModal to prevent crash on malformed URLs
- Add ref guard to quote error event to prevent duplicate firing on dependency changes

Made-with: Cursor
Comment thread app/components/UI/Ramp/Views/OrderDetails/OrderContent.tsx Outdated
Move new URL() out of the try block that opens the browser so a
malformed provider URL does not prevent the link from opening.

Made-with: Cursor
… Segment PR feedback

- Rename text to button_text for Ramps Button Clicked (all call sites)
- Rename text to external_link_description for Ramps External Link Clicked
- FundActionMenu v2: button_text Buy (not Add funds); Sell unchanged
- Card add funds: button_text Fund with cash to match visible label
- Update tests for new property names

Made-with: Cursor
@amitabh94 amitabh94 requested a review from a team as a code owner February 27, 2026 19:14
Comment thread app/components/UI/Ramp/Deposit/types/analytics.ts
… type

Align interface with Segment schema and call sites (ProcessingInfoModal, OrderContent, VerifyIdentity).

Made-with: Cursor
@github-actions

Copy link
Copy Markdown
Contributor

🔍 Smart E2E Test Selection

  • Selected E2E tags: SmokeRamps
  • Selected Performance tags: None (no tests recommended)
  • Risk Level: medium
  • AI Confidence: 90%
click to see 🤖 AI reasoning details

E2E Test Selection:
This PR is focused on adding comprehensive analytics tracking for the Unified Buy v2 (on-ramp) flow. The changes include:

  1. New Analytics Events: Added 19 new analytics events in MetaMetrics.events.ts for tracking user interactions in the Unified Buy v2 flow (screen views, button clicks, errors, tooltips, etc.)

  2. Ramp Component Updates: Multiple Ramp-related components have been updated to track analytics events:

    • BuildQuote.tsx, TokenSelection.tsx, Checkout.tsx, OrderDetails.tsx, OrderContent.tsx
    • Native flow screens (EnterEmail.tsx, OtpCode.tsx, VerifyIdentity.tsx)
    • Various modals (PaymentSelection, ProviderSelection, Settings, TokenNotAvailable, ProcessingInfo)
  3. Analytics Hook Migration: Components are migrating from the old useAnalytics hook to the new centralized useAnalytics from useAnalytics/useAnalytics

  4. Property Renaming: Changed text to button_text in analytics properties across multiple components

  5. E2E Test Update: The test file onramp-unified-buy.spec.ts was updated to expect UNIFIED_BUY_2 instead of UNIFIED_BUY for the ramp_type property

  6. Entry Point Updates: Components like AccountsMenu, FundActionMenu, BalanceEmptyState, and AddFundsBottomSheet were updated to use the new ramp_type

The changes are primarily analytics-focused and don't fundamentally change the user-facing functionality, but they do touch the Ramps flow extensively. The SmokeRamps tag is the appropriate choice as it covers:

  • On-ramp flows with mocked regional settings
  • Deep link navigation into buy flows
  • Limits validation and handling

No other tags are needed because:

  • The changes don't affect confirmations/transactions (SmokeConfirmations)
  • The changes don't affect wallet platform features (SmokeWalletPlatform)
  • The changes don't affect accounts management (SmokeAccounts)
  • The changes are isolated to the Ramps feature area

Performance Test Selection:
This PR is focused on analytics tracking for the Ramps feature. The changes add event tracking calls throughout the Ramp components but do not modify UI rendering, data loading patterns, state management, or any performance-critical paths. The analytics calls are lightweight (just sending events) and won't impact app performance. No performance tests are needed.

View GitHub Actions results

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Comment thread app/components/UI/Ramp/Views/TokenSelection/TokenSelection.tsx

@vinnyhoward vinnyhoward left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

UX owned files LGTM

@amitabh94 amitabh94 enabled auto-merge February 27, 2026 20:37
@amitabh94 amitabh94 added this pull request to the merge queue Feb 27, 2026
Merged via the queue into main with commit 1ae46b5 Feb 27, 2026
90 of 91 checks passed
@amitabh94 amitabh94 deleted the feat/ramps-unified-buy-v2-analytics branch February 27, 2026 21:21
@github-actions github-actions Bot locked and limited conversation to collaborators Feb 27, 2026
@metamaskbot metamaskbot added the release-7.69.0 Issue or pull request that will be included in release 7.69.0 label Feb 27, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

no-changelog no-changelog Indicates no external facing user changes, therefore no changelog documentation needed release-7.69.0 Issue or pull request that will be included in release 7.69.0 size-XL team-money-movement issues related to Money Movement features

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants