feat(analytics-controller): add persisted event queue

packages/analytics-controller/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Optional persisted event queue support in `AnalyticsController`, disabled by default. ([#8797](https://github.com/MetaMask/core/pull/8797))
 - Optional `skipUUIDv4Check` on `AnalyticsPlatformAdapter` to allow non-UUIDv4 `analyticsId` strings when constructing `AnalyticsController` ([#8543](https://github.com/MetaMask/core/pull/8543))
 
 ### Changed

packages/analytics-controller/README.md

@@ -20,6 +20,7 @@ The AnalyticsController provides a unified interface for tracking analytics even
 | ------------- | --------- | --------------------------------------------- | --------- |
 | `analyticsId` | `string`  | UUIDv4 identifier (client platform-generated) | Yes       |
 | `optedIn`     | `boolean` | User opt-in status                            | Yes       |
+| `eventQueue`  | `object`  | Optional persisted delivery queue             | Yes       |
 
 ### Client Platform Responsibilities
 
@@ -37,6 +38,14 @@ When `isAnonymousEventsFeatureEnabled` is enabled in the constructor, events wit
 
 This allows sensitive data to be tracked anonymously while maintaining user identification for regular properties. When disabled (default), all properties are tracked in a single event.
 
+## Persisted Event Queue
+
+When `isEventQueuePersistenceEnabled` is enabled in the constructor, each final platform adapter payload is persisted until the adapter reports successful delivery through its callback.
+
+This feature is disabled by default. Client platforms that already rely on SDK-level persistence, such as MetaMask Mobile through `@segment/analytics-react-native`'s `storePersistor` option, should leave it disabled.
+
+Platforms without SDK-level persistence, such as MetaMask Extension, can enable it to replay queued payloads after restart. The queue stores the final adapter calls, so anonymous event splitting persists the identified and anonymous payloads separately.
+
 ## Lifecycle Hooks
 
 ### `onSetupCompleted`

packages/analytics-controller/package.json

@@ -55,12 +55,14 @@
   "dependencies": {
     "@metamask/base-controller": "^9.1.0",
     "@metamask/messenger": "^1.2.0",
-    "@metamask/utils": "^11.9.0"
+    "@metamask/utils": "^11.9.0",
+    "uuid": "^8.3.2"
   },
   "devDependencies": {
     "@metamask/auto-changelog": "^6.1.0",
     "@ts-bridge/cli": "^0.6.4",
     "@types/jest": "^29.5.14",
+    "@types/uuid": "^8.3.0",
     "deepmerge": "^4.2.2",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.5",