Description

This is PR 3 of the GE-217 push pre-prompt rollout.

This PR mounts the push notification onboarding pre-prompt from Nav/Main and wires the production flow for the two currently supported startup variants:

• push_permission: shown to eligible users who have not granted OS push permission or do not yet have notification preferences.
• marketing_consent: shown to eligible existing users with push notifications enabled but marketing notification preferences disabled.

The prompt resolver now gates display on notification runtime eligibility, completed onboarding, the default-on feature flag, one-time “shown” storage, OS push permission status, Authenticated User Storage notification preferences, and pending social-login marketing-consent backfill. AUS preference reads stay behind the runtime gate, and resetting the developer “push pre prompt shown” flag does not immediately reopen the prompt until the app is restarted.

This PR also adds shared notification preference helpers used by Settings and startup onboarding, background enablement for the push pre-prompt path, marketing notification preference updates, toast copy, and MetaMetrics/identify instrumentation for pre-prompt actions, OS prompt responses, marketing consent, and push notification enablement.

Changelog

CHANGELOG entry: Added a startup prompt for eligible users to enable push notifications.

Related issues

Fixes: GE-217

Manual testing steps

Feature: Push notification startup pre-prompt

  Scenario: eligible user sees the push permission pre-prompt
    Given notifications are enabled for the build
    And the user is eligible for the push permission pre-prompt
    And the push pre-prompt has not already been shown

    When the user launches the app
    Then the push notification onboarding sheet is shown

    When the user taps "Yes"
    Then the native push permission prompt is requested
    And the startup surface is completed
    And notifications are enabled in the background

  Scenario: eligible user dismisses the push permission pre-prompt
    Given notifications are enabled for the build
    And the user is eligible for the push permission pre-prompt
    And the push pre-prompt has not already been shown

    When the user launches the app
    And the user taps "Not now"
    Then the push notification onboarding sheet closes
    And the startup surface is completed

  Scenario: existing user sees the marketing consent pre-prompt
    Given notifications are enabled for the build
    And the user already has notification preferences
    And the user has not enabled marketing consent
    And the push pre-prompt has not already been shown

    When the user launches the app
    Then the marketing consent onboarding sheet is shown

    When the user confirms marketing consent
    Then marketing consent is enabled
    And the startup surface is completed    

Manual Testing Steps

Preconditions

• Use a build with the notifications feature flag enabled.
• Use a device/simulator where OS notification permissions can be reset.
• After seeing either pre-prompt once, go to Settings > Developer options and tap Reset push pre prompt shown, then fully kill and reopen the app before testing another prompt.
• To force a clean first-run state, delete the app from the device and install it again.
• To test update behavior, do not delete the app. Install/update the PR build over an existing installed build so app data is preserved.

Flow 1: New User / Push Permission Pre-Prompt

Setup

1. Delete the app from the device.
2. Install the PR build.
3. If needed, reset OS notification permission for MetaMask from device settings.
4. Open the app and complete onboarding with a new wallet or imported wallet.
5. Keep marketing consent disabled during onboarding if the option is shown.
6. Finish onboarding and land in the wallet.

Steps

1. Confirm the push notification pre-prompt appears after onboarding.
2. Confirm the sheet explains push notifications and personalized updates.
3. Tap Not now.
4. Confirm the sheet closes.
5. Confirm a toast appears saying notifications can be enabled later in Settings > Notifications.
6. Go to Settings > Developer options and tap Reset push pre prompt shown.
7. Fully kill and reopen the app.
8. Confirm the push notification pre-prompt appears again.
9. Tap Yes.
10. Confirm the native OS push notification prompt appears.
11. Tap Allow.
12. Confirm the sheet closes.
13. Confirm a success toast appears.
14. Go to Settings > Notifications.
15. Confirm notifications are enabled.
16. Confirm the relevant notification categories, including marketing/updates, are enabled where available.

Also Verify

• Repeat the Yes path and tap Don’t Allow on the OS prompt.
• Confirm the app does not crash.
• Confirm the sheet closes and the user sees guidance to enable notifications later in settings.

Flow 2: Existing User / App Update With Push Enabled But Marketing Consent Disabled

Setup

1. Start from an existing installed app with a completed wallet.
2. Do not delete the app.
3. Enable push notifications from Settings > Notifications.
4. Disable marketing consent from Settings > Security & Privacy > Data collection for marketing.
5. Install/update to the PR build over the existing app.
6. Open the app and unlock the wallet.
7. If the prompt was already seen, use Settings > Developer options > Reset push pre prompt shown, then fully kill and reopen the app.

Steps

1. Confirm the existing-user marketing consent pre-prompt appears.
2. Confirm the prompt asks for personalized/marketing updates.
3. Tap Not now.
4. Confirm the sheet closes.
5. Confirm marketing consent remains disabled.
6. Confirm push notifications remain enabled.
7. Reset push pre prompt shown in Developer options.
8. Fully kill and reopen the app.
9. Confirm the existing-user marketing consent prompt appears again.
10. Tap Confirm.
11. Confirm the sheet closes.
12. Confirm a success toast appears.
13. Go to Settings > Security & Privacy.
14. Confirm Data collection for marketing is enabled.
15. Go to Settings > Notifications.
16. Confirm Updates and Rewards / marketing notification preferences are enabled.

Flow 3: Existing User / App Update With Marketing Consent Enabled But Push Disabled

Setup

1. Start from an existing installed app with a completed wallet but push not enabled (also not denied)
2. Do not delete the app.
3. Enable marketing consent from Settings > Security & Privacy > Data collection for marketing.
4. Disable push notifications from device OS settings or Settings > Notifications.
5. Install/update to the PR build over the existing app.
6. Open the app and unlock the wallet.
7. Reset push pre prompt shown in Developer options if needed, then fully kill and reopen.

Steps

1. Confirm the push permission pre-prompt appears.
2. Tap Yes.
3. Confirm the native OS notification prompt appears.
4. Tap Allow.
5. Confirm notifications are enabled.
6. Confirm marketing consent remains enabled.

Regression Checks

• The pre-prompt should only show once per install/session unless reset from Developer options.
• Resetting push pre prompt shown should not immediately reopen the prompt until the app is restarted.
• Deleting and reinstalling the app should allow the new-user flow to be tested again.
• Updating the app without deleting it should preserve user state and trigger the correct existing-user flow.
• Users with both push notifications and marketing consent already enabled should not see either pre-prompt.

Screenshots/Recordings

Before

After

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.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

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.