feat(analytics-controller): add optional event fragments for journey-scoped properties

[gauthierpetetin]

Explanation

Clients currently re-derive the same analytics properties for every event in a signature or transaction confirmation. That duplication is easy to get wrong and hard to keep consistent as more UI pieces contribute to the same journey.

This adds optional event fragments to AnalyticsController, disabled by default via isEventFragmentsEnabled. A fragment is a persisted bag of properties and sensitiveProperties that any part of a client can write to while a journey is in progress:

• Funnel. Declare initialEvent, successEvent, and failureEvent. Creation can emit the initial event, and finalizeEventFragment emits success or failure.
• Property bag. Declare no event names. The client reads the fragment back with getEventFragmentById when it emits its own event.

Emission goes through trackEvent, so consent gating, anonymous event splitting, the pre-consent queue, and geolocation enrichment all apply. Accumulation uses that same consent gate: fragments are only stored while the user is opted in, or while they are undecided and the pre-consent queue is enabled. eventFragments is persisted but excluded from state logs, debug snapshots, and UI, matching the other analytics queues.

This is not a breaking change. Clients must opt in with the constructor flag.

References

N/A

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed
• I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Made with Cursor

[cursor]

Current version of PR was reviewed by /review-bugbot on Sep 1, 19:46 GMT+2. It flagged 0 findings.

^{Bugbot on commit 9b468c3 is skipped.}

[Copilot]

Pull request overview

Adds an optional “event fragments” feature to @metamask/analytics-controller, allowing clients (when opted-in via isEventFragmentsEnabled) to persist and update journey-scoped analytics property bags and optionally emit initial/success/failure events through the existing trackEvent pipeline and consent gating.

Changes:

• Introduces AnalyticsEventFragment* types and exports them from the package public API.
• Extends AnalyticsController state, metadata, messenger methods, and implementation to support fragment lifecycle (create/upsert/update/get/delete/finalize) with consent-aware reconciliation on init.
• Adds selectors + comprehensive tests, and documents the feature in the README/changelog.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/analytics-controller/src/selectors.ts	Adds selectors for reading all fragments and a fragment by ID.
packages/analytics-controller/src/selectors.test.ts	Adds unit tests for the new selectors.
packages/analytics-controller/src/index.ts	Exposes event fragment types and new controller method action types from the public entrypoint.
packages/analytics-controller/src/EventFragment.types.ts	Defines the event fragment data model and option/payload types.
packages/analytics-controller/src/AnalyticsController.ts	Implements fragment storage, reconciliation on init, consent gating integration, and lifecycle methods.
packages/analytics-controller/src/AnalyticsController.test.ts	Adds extensive tests covering fragment behavior, consent gating, persistence, and messenger exposure.
packages/analytics-controller/src/AnalyticsController-method-action-types.ts	Adds messenger action type definitions for fragment lifecycle methods.
packages/analytics-controller/README.md	Documents the new feature and its usage patterns.
packages/analytics-controller/CHANGELOG.md	Adds an Unreleased entry describing the new feature.

Suppressed comments (3)

packages/analytics-controller/src/AnalyticsController.ts:541

• mergeEventFragmentContext returns { ...base, ...override }, but base/override are AnalyticsContext | undefined. Coalesce to {} before spreading to avoid TypeScript errors and make the intent explicit.

  return { ...base, ...override };

packages/analytics-controller/src/AnalyticsController-method-action-types.ts:101

• The getEventFragmentById action-type JSDoc omits the consent gate, but the handler returns undefined when capture is not allowed (opted out, or undecided without pre-consent queue). Align the docs with the implementation to avoid consumer confusion.

 * @returns The fragment, or `undefined` when no fragment has that ID or the
 * event fragments feature is disabled.
 */

packages/analytics-controller/src/AnalyticsController.ts:1629

• finalizeEventFragment is a logged no-op when the feature is disabled or consent gating disallows capture, so the @throws doc should note that a missing fragment will not throw in those ignored-call states.

   * @throws Error if no fragment has that ID.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

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

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