fix: only fire APP_OPENED on background → active transition

[vinnyhoward]

Description

When the QR scanner on iPhone prompts the user to grant camera access, iOS transitions the app to inactive (not background). If the user taps "Cancel" on the permission dialog, the app returns to active, which was incorrectly triggering the App Opened analytics event.

The fix tightens the condition in AppStateEventListener to only fire APP_OPENED when transitioning from background → active, which represents the user genuinely re-opening the app. Transitions from inactive → active (system dialogs, incoming calls, etc.) are now correctly ignored.

Changelog

CHANGELOG entry:null

Related issues

Fixes: https://consensyssoftware.atlassian.net/browse/TMCU-256

Manual testing steps

Feature: App Opened analytics event

  Scenario: user dismisses camera permission dialog from QR scanner
    Given the user has not granted camera access to MetaMask
    And the user is on any screen in the app

    When user taps the QR scanner icon
    And the iOS camera permission dialog appears
    And user taps "Cancel" on the dialog

    Then the App Opened analytics event is NOT fired

  Scenario: user opens the app from the background
    Given the user has backgrounded the app

    When user returns to the app from the app switcher or home screen

    Then the App Opened analytics event IS fired

Screenshots/Recordings

Screen.Recording.2026-03-30.at.11.08.20.AM.mov

Before

Observe that the app opened event fires after pressing cancel

Screen.Recording.2026-03-30.at.11.08.20.AM.mov

After

Observe that the app opened event does not fire after pressing cancel

Screen.Recording.2026-03-30.at.11.22.19.AM.mov

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

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

Low Risk
Low risk: narrows when the APP_OPENED analytics event is emitted and adds targeted tests, with no changes to auth, funds, or persistence logic.

Overview
Prevents false-positive APP_OPENED analytics by only triggering the event when the app transitions from background to active, ignoring inactive → active transitions (e.g., iOS permission dialogs/calls).

Updates app-state tracking to preserve background across the iOS intermediate inactive state so the subsequent active transition still counts as an app open. Tests are adjusted to include explicit background setup and new cases covering background → inactive → active, repeated active, and inactive → active not firing.

^{Written by Cursor Bugbot for commit 302c59c. This will update automatically on new commits. Configure here.}

[github-actions]

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.

[cursor]

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.}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.64%. Comparing base (e2bb36a) to head (a5410aa).
⚠️ Report is 28 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff            @@
##             main   #27463    +/-   ##
========================================
  Coverage   82.63%   82.64%            
========================================
  Files        4854     4859     +5     
  Lines      125092   125393   +301     
  Branches    27919    28069   +150     
========================================
+ Hits       103376   103637   +261     
+ Misses      14600    14594     -6     
- Partials     7116     7162    +46     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

✅ E2E Fixture Validation — Schema is up to date
17 value mismatches detected (expected — fixture represents an existing user).
View details

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: None (no tests recommended)
• Selected Performance tags: None (no tests recommended)
• Risk Level: low
• AI Confidence: 90%

click to see 🤖 AI reasoning details

E2E Test Selection:
The changes are a targeted bug fix in AppStateEventListener.ts that corrects when the APP_OPENED analytics event fires:

1. Before: APP_OPENED fired on any transition to 'active' state (including from 'inactive', e.g., when dismissing system permission dialogs)
2. After: APP_OPENED only fires when transitioning from 'background' to 'active', with special iOS handling to preserve 'background' state through the intermediate 'inactive' state

Why no E2E tags are needed:

• This is a pure analytics/event-firing fix with no UI changes
• No navigation, controller, or user-facing flow changes
• The core deeplink processing behavior is preserved (still fires when returning from background)
• The fix makes behavior more correct by eliminating false positive APP_OPENED events
• Comprehensive unit tests cover all the new scenarios (iOS background→inactive→active, system dialog inactive→active)
• The change is isolated to AppStateEventListener.ts which handles app state transitions internally
• No shared components (TabBar, Modals, Confirmations, Browser) are affected

Risk assessment: Low - well-tested unit-level fix that corrects analytics event firing logic without changing any user-visible behavior or E2E-testable flows.

Performance Test Selection:
The change only affects when the APP_OPENED analytics event fires (state transition logic). It does not impact UI rendering, data loading, account/network lists, critical user flows, or app startup performance. No performance tests are warranted.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud