feat: forward allowlisted Segment events to Braze [GE-165] [GE-190]

[baptiste-marchand]

Description

Enables Braze events tracking via Segment’s device-mode pipeline by adding a custom BrazePlugin that identifies users via MetaMask profileId, forwards only allowlisted track events and identify traits via the Braze SDK.

Allowlisted events are managed on LaunchDarkly with a feature flag, so that we can update them without having to do a new release

A custom BrazePlugin was used instead of Segment's one for 2 reasons:

• to use a different ID in Segment and Braze events. Segment identify calls use the Metametrics ID, while we needed to use the profile ID in Braze. The base plugin was instead copying Segment's ID for Braze
• to fix an issue with Segment's destinations that their support team wasn't able to help with considering our constraints.

Changelog

CHANGELOG entry:

Related issues

Fixes: https://consensyssoftware.atlassian.net/browse/GE-165

Manual testing steps

Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]

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.

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
Changes the analytics pipeline and remote-config-driven allowlisting, which can affect what data is sent to Braze and when. Incorrect flag values or identity syncing issues could lead to dropped/extra analytics events or misattribution.

Overview
Routes Braze tracking through Segment device-mode by introducing a custom BrazePlugin destination plugin that gates track events and identify traits behind configurable allowlists and a profileId guard, and adds support for forwarding language/flush calls to the native Braze SDK.

Updates the public Braze API (app/core/Braze/index.ts) to manage a singleton plugin, set/clear Braze identity on sign-in/sign-out, keep Braze language in sync with locale changes, and validate/apply allowlists from a new remote feature flag.

Wires the plugin into analytics initialization by extending createPlatformAdapter to accept optional Segment plugins, subscribing analytics-controller-init.ts to remote feature flag updates (and an initial fetch), and adds a new init messenger plus Jest/test/mocks and feature-flag registry entries to support this behavior.

^{Reviewed by Cursor Bugbot for commit e248adf. Bugbot is set up for automated code reviews on this repo. 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.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 85.71429% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.24%. Comparing base (15470f4) to head (0e43f0b).
⚠️ Report is 34 commits behind head on main.

Files with missing lines	Patch %	Lines
...ne/controllers/analytics-controller/BrazePlugin.ts	74.46%	10 Missing and 2 partials ⚠️
app/core/Braze/index.ts	96.42%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #28805      +/-   ##
==========================================
+ Coverage   82.20%   82.24%   +0.03%     
==========================================
  Files        5017     5030      +13     
  Lines      131659   132129     +470     
  Branches    29381    29496     +115     
==========================================
+ Hits       108228   108663     +435     
- Misses      16083    16099      +16     
- Partials     7348     7367      +19     

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

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

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

^{Reviewed by Cursor Bugbot for commit 3a2e67f. Configure here.}

[samir-acle]

LGTM, great work.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeIdentity, SmokeWalletPlatform
• Selected Performance tags: None (no tests recommended)
• Risk Level: medium
• AI Confidence: 78%

click to see 🤖 AI reasoning details

E2E Test Selection:
The PR refactors the Braze analytics integration by introducing a new BrazePlugin Segment destination, moving useBrazeIdentity hook, and wiring up the AnalyticsController init messenger. Key impacts:

1. Identity/sign-in flow: useBrazeIdentity now also calls clearBrazeUser() on sign-out (new behavior). This hook is used in useIdentityEffects which is called in Nav/Main/index.js — the main navigation component. This affects every user session's sign-in/sign-out lifecycle.

2. Engine initialization: AnalyticsController init now uses a real getAnalyticsControllerInitMessenger (replacing noop) and subscribes to RemoteFeatureFlagController:stateChange. This is a change to Engine startup behavior.

3. E2E guards in place: Both setBrazeUser() and clearBrazeUser() have isE2E guards that return early, so Braze SDK calls won't execute during E2E tests. The testSetup.js adds proper mocks for the new Braze SDK methods.

4. No UI changes: No visual components were modified, so most feature-specific tests are not impacted.

SmokeIdentity is selected because the changes directly touch the identity sign-in/sign-out flow (useBrazeIdentity, useIdentityEffects), account syncing infrastructure, and the profile ID management that underpins identity features.

SmokeWalletPlatform is selected because it covers wallet lifecycle analytics tracking (new wallet creation, SRP import events) and the analytics controller initialization changes could affect how analytics events are tracked during wallet lifecycle events. It also covers multi-SRP architecture which intersects with the identity changes.

Other tags (SmokeConfirmations, SmokeTrade, etc.) are not selected because the changes are analytics infrastructure with proper E2E guards, and don't touch transaction flows, network management, or other feature-specific code paths.

Performance Test Selection:
The changes are analytics infrastructure (Braze plugin, identity hooks, Engine messenger wiring). They don't affect UI rendering, list components, data loading performance, or critical user flow timing. The BrazePlugin is a Segment destination plugin that runs asynchronously and is no-op in E2E. No performance-sensitive code paths are modified.

View GitHub Actions results

[github-actions]

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

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[ccharly]

LGTM for accounts (not tested)

[Cal-L]

platform files lgtm!