feat(analytics): multi-provider (Firebase+Matomo), queueing with persistence, standardized events

[CharlVS]

feat(analytics): multi-provider (Firebase+Matomo), queueing with persistence, standardized events

@KomodoPlatform/qa Jump to the bottom of this message for testing info; but I still suggest reading below for additional context.

Overview

• Introduces Analytics v2 with a unified repository that can fan out events to multiple providers in parallel.
• Adds optional Matomo provider alongside Firebase, gated by runtime flags and disabled automatically when config is absent or analytics are disabled (CI/privacy).
• Implements robust queueing and persistence to prevent event loss across restarts and during provider initialization/disable periods.
• Standardizes event names and parameters; extends coverage in DEX, Bridge, Wallet Withdraw, Market Maker Bot, NFTs, Settings, and UI telemetry.

Key changes

• Multiple providers behind a single interface
  • New interface lib/bloc/analytics/analytics_api.dart.
  • Providers: FirebaseAnalyticsApi and MatomoAnalyticsApi.
  • Orchestration and fan-out: lib/bloc/analytics/analytics_repo.dart registers Firebase always; registers Matomo only when both MATOMO_URL and MATOMO_SITE_ID are provided; enforces ANALYTICS_DISABLED and CI gating via lib/shared/constants.dart.
• Provider initialization, activation, and retries
  • Each provider handles initialize/activate/deactivate/retry with up to 3 retries and debug logging. Firebase skips unsupported platforms (Linux).
• Queueing and persistence
  • Providers maintain their own queues; repository delegates queueing.
  • Firebase: periodic persistence to SharedPreferences and restore on startup; flush on activation.
  • Matomo: uses matomo_tracker persistent dispatch; queues in-memory when disabled and flushes on activation. Optional visit-scoped custom dimension for platform.
• Matomo provider (optional)
  • Config via --dart-define and lib/shared/constants.dart: MATOMO_URL, MATOMO_SITE_ID, optional MATOMO_PLATFORM_DIMENSION_ID.
  • Initialization enforces trailing slash; disables self when config missing; respects ANALYTICS_DISABLED and CI. Adds optional X-KW-KEY header from FEEDBACK_API_KEY if present.
  • Sends events using EventInfo with category derived from event name; numeric value inferred from common keys.
• Event schema and coverage
  • Standardized snake_case event names and parameters across categories.
  • Extended events and wiring: DEX maker/taker confirmation, Bridge confirmation, Wallet Withdraw, NFTs (gallery/transfer), Market Maker Bot (setup/trade/error), Settings theme selection, searchbar input, and UI telemetry.
  • See lib/analytics/analytics_factory.dart, lib/analytics/events/*, and updates in lib/views/* such as:
    • lib/views/dex/simple/confirm/maker_order_confirmation.dart
    • lib/views/dex/simple/confirm/taker_order_confirmation.dart
    • lib/views/bridge/bridge_confirmation.dart
    • lib/views/wallet/coin_details/withdraw_form/withdraw_form.dart
• Flags, gating, and docs
  • Runtime defines in lib/shared/constants.dart: ANALYTICS_DISABLED, CI, MATOMO_URL, MATOMO_SITE_ID, MATOMO_PLATFORM_DIMENSION_ID.
  • Docs updated: docs/ANALYTICS.md, new docs/MATOMO_SETUP.md, docs/FIREBASE_SETUP.md.
• CI and platform
  • macOS plugin registrant updated; pubspec.yaml adds matomo_tracker.
  • Minor workflow/action adjustments.

Developer notes (build flags)

• Disable analytics entirely (applies to all providers):

--dart-define=ANALYTICS_DISABLED=true

• CI environment (implicitly disables analytics in code):

--dart-define=CI=true

• Enable Matomo (requires both):

--dart-define=MATOMO_URL=https://your-matomo.example.com/
--dart-define=MATOMO_SITE_ID=1

• Optional: set a Matomo visit-scoped platform dimension:

--dart-define=MATOMO_PLATFORM_DIMENSION_ID=12

Notes:

• Matomo remains disabled when MATOMO_URL or MATOMO_SITE_ID is missing. Ensure MATOMO_URL ends with a trailing slash (as required by matomo_tracker).
• Firebase Analytics is not initialized on Linux.

Scope

• 40 files changed, 2196 insertions, 1277 deletions.
• Major areas: lib/bloc/analytics/*, lib/analytics/analytics_factory.dart, lib/analytics/events/*, lib/shared/constants.dart, DEX/Bridge/Withdraw/NFT/MMB views, docs, workflows, and macOS registrant.

No breaking changes

• Default behavior unchanged without Matomo flags; Firebase continues to work as before.
• Analytics can be disabled via settings and runtime flags; no PII added; event updates are additive.

Testing (QA)

1. Basic app-wide smoke testing to confirm the event hooks haven't broken the actual events.
2. Ensure that the events are being logged for Google Analytics and Matomo either by viewing the console requests (filter kwa.komodoplatform.com for Matomo, not sure about URL for Google Analytics), or (preferably) viewing the events in Matomo and Firebase. @gcharang, please set up @smk762 with access to Matomo.

It's not realistic to test all 45 analytics events (file), but it may be sufficient to monitor the logged events post-release. When we have time, we can do a thorough scrub of all analytics to ensure they are always firing when they should, exactly once - no more and no less.

---

Note

Introduce unified analytics with Firebase+Matomo, robust queueing/persistence, runtime/CI gating, and standardized event instrumentation across DEX, Bridge, Wallet, NFTs, MMB, Settings, and UI.

• Analytics:
  • Architecture: Add AnalyticsApi interface and unified AnalyticsRepository to fan out events to multiple providers.
  • Providers: Implement FirebaseAnalyticsApi and optional MatomoAnalyticsApi (registered via flags); both support activate/deactivate/retry.
  • Queueing/Persistence: Provider-level queues; Firebase persists via SharedPreferences; Matomo uses persistent dispatch; flush on activation.
  • Runtime Gating: Add ANALYTICS_DISABLED and CI flags; optional MATOMO_URL, MATOMO_SITE_ID (and platform dimension) in shared/constants.dart.
• Event Schema & Coverage:
  • Standardize event names/params (snake_case; asset/network/hd_type/failure_reason, etc.).
  • Wire events in DEX (maker/taker), Bridge, Withdraw, NFTs (gallery/transfer), Market Maker Bot (setup/trade/error), Settings theme, searchbar, HD address, data sync, performance.
• Docs:
  • Update docs/ANALYTICS.md, docs/FIREBASE_SETUP.md; add docs/MATOMO_SETUP.md with flags and setup guidance.
• Build/CI:
  • Add Matomo inputs and analytics-disable behavior to build/action workflow; integration runner passes CI flags to disable analytics in tests.
• Deps/Platform:
  • Add matomo_tracker (and related plugin registrations); minor macOS registrant/project updates.
• Misc:
  • Add unit test scaffold for AnalyticsRepository.

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch add/enhanced-analytics-v2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Visit the preview URL for this PR (updated for commit c3551a3):

https://walletrc--pull-2932-merge-7y966wuu.web.app

_{(expires Wed, 08 Oct 2025 15:43:18 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: f66a4ff03faa546f12f0ae5a841bd9eff2714dcc}

[chatgpt-codex-connector]

Codex Review: Here are some suggestions.

Reply with @codex fix comments to fix any unresolved comments.

About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you open a pull request for review, mark a draft as ready, or comment "@codex review". If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex fix this CI failure" or "@codex address that feedback".

[smk762]

Confirmed dashboard detects app, though upon browsing I noticed a few instances of Oops… there was a problem during the request. and very little else - most pages showed "no data" - though there was some. Perhaps it just needs to be populated more?

Approving as there is enough data to confirm the linkage, and general smoke test of standard wallet/dex ops function as expected.

If further confirmation testing is required regarding the "no data", please let me know.

[gcharang]

@smk762 there was a permissions issue and I fixed it. please check again, the data should populate

[gcharang]

the view_asset, swap_initiated, asset_enabled, swap_success events should mention the actual names of the assets @CharlVS

[CharlVS]

Thanks, @gcharang I'll have a look. It should be receiving exactly the same data as the other provider.

[CharlVS]

@cursoragent, check for issues where event parameters are not being included in the events logged by Matomo.

[cursor]

I've enhanced the Matomo analytics tracking by modifying how events are labeled, ensuring that event parameters are now captured and displayed as the event's name (label) in Matomo. This provides more detailed and contextual information directly within the analytics interface.

• I modified the trackEvent method in lib/bloc/analytics/matomo_analytics_api.dart to set the EventInfo.name property using a newly formatted label derived from event parameters, rather than just the event's action.
• I implemented a new private helper method, _formatEventLabel, within lib/bloc/analytics/matomo_analytics_api.dart. This method takes a map of event parameters and converts them into a sorted, semicolon-separated string (e.g., key1=value1; key2=value2) for use as the event label.

---

 

_{Learn more about Cursor Agents}

[smk762]

@smk762 there was a permissions issue and I fixed it. please check again, the data should populate

Thanks - confirmed I dont see the error boxes any more. There's still a few places with "no data", but I can see new things too like the events table. Just took a little VPN tour around a few countries, which soon after were visible on the map.

My prior approval remains in effect, otherwise let me know if anything else specific to look for.