Ferrous-Solitaire/docs/analytics-validation.md

Analytics Validation Runbook

Ferrous Solitaire currently has two analytics paths:

• Native desktop/Android gameplay events use solitaire_engine::AnalyticsPlugin and solitaire_data::MatomoClient.
• Hosted web pages include Matomo page-view snippets in solitaire_server/web/*.html.

The Bevy /play WASM canvas does not emit the native gameplay events because AnalyticsPlugin is intentionally gated out on wasm32; it depends on the native Tokio/reqwest stack.

Native Matomo Validation

Use this when a deployed Matomo instance and a native build are available.

1. Configure settings.json with a Matomo URL and site ID:

   {
     "analytics_enabled": true,
     "matomo_url": "https://analytics.example.com",
     "matomo_site_id": 1
   }
   

2. Launch the native app and open Settings.

3. Confirm the Privacy section appears and "Share usage data" is ON.

4. Start a new confirmed game.

5. Win or forfeit the game.

6. Unlock an achievement if practical, or use an existing achievement path that is easy to trigger in a test profile.

7. Wait at least 60 seconds, or close after the win/forfeit path has fired its immediate flush.

8. In Matomo, confirm the following custom events arrived:

   Category	Action	Name
   Game	Start	classic, zen, challenge, time_attack, or difficulty
   Game	Won	empty
   Game	Forfeit	empty
   Achievement	Unlocked	achievement id

Web/WASM Decision

Keep the current split unless the project explicitly needs in-canvas gameplay events for /play.

Current behavior:

• /, /play-classic, /account, /leaderboard, and /replays emit Matomo page views through the hosted HTML snippets.
• /play hosts the Bevy canvas but does not emit gameplay events from the engine.
• The browser Content-Security-Policy already allows the deployed Matomo host for scripts, images, and connections.

If gameplay events are needed on /play, add a small wasm32-only analytics bridge instead of trying to compile the native plugin:

• keep the same event contract as native (Game / Start, Game / Won, Game / Forfeit, Achievement / Unlocked);
• read Settings::analytics_enabled, matomo_url, and matomo_site_id;
• send through browser APIs or the existing _paq queue;
• keep the Settings opt-in behavior identical to native;
• add Playwright coverage that stubs Matomo and verifies emitted payloads.