feat: working matomo analytics (test environment)

[nikitalokhmachev-ai]

User description

Implemented matomo analytics (for now, in my own matomo environment). #39

Once Chase provides me with the credentials, I will change the URL and SITE_ID.

---

PR Type

Enhancement

---

Description

• Implemented Matomo analytics with opt-out capability

• Added event tracking for user actions

• Created archive size monitoring system

• Added analytics toggle in settings

---

Changes walkthrough 📝

Relevant files

Enhancement

matomo.ts Core Matomo analytics implementation                                          src/matomo.ts Created new file for Matomo analytics integration Implemented persistent user ID generation and storage Added analytics opt-out functionality Created trackEvent function for sending events to Matomo +130/-0  events.ts Event tracking system implementation                                          src/events.ts Created new file with event tracking functions Implemented tracking for page views, archiving, torrents Added functions for tracking settings changes Created archive size tracking functionality +58/-0    bg.ts Background tracking integration                                                    src/ext/bg.ts Added archive size tracking functionality Implemented periodic size checking (every 5 minutes) Added event tracking for archiving start/stop Added message handler for Matomo tracking requests +74/-0    settings-page.ts Analytics settings UI implementation                                          src/settings-page.ts Added analytics toggle in settings UI Implemented analytics opt-out functionality Added event tracking for settings changes Updated settings UI with analytics explanation +35/-0    recorder.ts Archive event tracking integration                                              src/recorder.ts Added page archiving event tracking Integrated with onPageArchived event Added page size tracking +11/-0    argo-archive-list.ts Page view tracking integration                                                      src/argo-archive-list.ts Added page click tracking Integrated with onPageClicked event +2/-0      sidepanel.ts Torrent creation tracking                                                                src/sidepanel.ts Added torrent creation tracking Integrated with onTorrentCreated event +3/-0

---

Need help?

Type /help how to ... in the comments thread for any questions about PR-Agent usage.

Check out the documentation for more information.

[nikitalokhmachev-ai]

[pr-agent-monadical]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 39 - Partially compliant Compliant requirements: Implement analytics with Matomo Allow users to opt out of tracking in settings Track specific events: Torrent created Page archived Settings (# of blocked URLs, screenshots enabled, cookies enabled, localstorage enabled) Page clicked (viewed) Total archive size Non-compliant requirements: Self-hosted Matomo (currently using test environment) Requires further human verification: Verify that the analytics data is being properly received in the Matomo dashboard Confirm that the opt-out functionality completely stops all tracking

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🧪 No relevant tests

🔒 Security concerns Sensitive information exposure: The implementation tracks URLs of archived pages and sends them to Matomo. While this is expected for analytics, it's important to ensure users understand that their browsing history (in the form of archived URLs) is being sent to a third-party service. The opt-out option helps mitigate this concern, but the PR should ensure that when analytics is disabled, no data is sent to Matomo.

⚡ Recommended focus areas for review Hardcoded Credentials The Matomo URL and Site ID are hardcoded in the file. As mentioned in the PR description, these will need to be updated with the proper credentials once provided. const MATOMO_URL = "https://argo-chrome-test.matomo.cloud/matomo.php"; const SITE_ID = "2"; Debug Logging All event tracking functions include console.log statements that should be removed or disabled in production to avoid cluttering the console. export async function onPageClicked(pageUrl: string): Promise<void> { console.log("onPageClicked called with URL:", pageUrl); await trackEvent("Archive", "ViewPage", pageUrl); } // Track when a torrent is created for sharing export async function onTorrentCreated(numPages: number): Promise<void> { console.log("onTorrentCreated called with pages:", numPages); await trackEvent("Sharing", "TorrentCreated", `${numPages} pages`); } // Track when a page is successfully archived export async function onPageArchived( pageUrl: string, pageSize?: number, ): Promise<void> { console.log("onPageArchived called:", pageUrl, pageSize); await trackEvent("Archive", "PageArchived", pageUrl); // If page size is provided, track it separately if (pageSize !== undefined) { await trackEvent("Archive", "PageSize", `${Math.round(pageSize / 1024)}KB`); } } // Track settings changes export async function onSettingsChanged( settingName: string, value: string | boolean | number, ): Promise<void> { console.log("onSettingsChanged:", settingName, value); await trackEvent("Settings", settingName, String(value)); } // Track total archive size export async function trackArchiveSize(totalSizeBytes: number): Promise<void> { const sizeMB = Math.round(totalSizeBytes / (1024 * 1024)); console.log("trackArchiveSize:", sizeMB, "MB"); await trackEvent("Archive", "TotalSize", `${sizeMB}MB`); } // Track when archiving starts export async function onArchivingStarted(pageUrl: string): Promise<void> { console.log("onArchivingStarted:", pageUrl); await trackEvent("Archive", "Started", pageUrl); } // Track when archiving stops export async function onArchivingStopped( reason: string = "manual", ): Promise<void> { console.log("onArchivingStopped:", reason); await trackEvent("Archive", "Stopped", reason); } Performance Concern The checkAndTrackArchiveSize function is called frequently and may impact performance, especially with the 5-minute interval timer that runs continuously. async function checkAndTrackArchiveSize() { try { const collId = await getLocalOption("defaultCollId"); if (!collId) return; const coll = await collLoader.loadColl(collId); if (!coll?.store?.getAllPages) return; const pages = await coll.store.getAllPages(); // @ts-expect-error any const totalSize = pages.reduce((sum, page) => sum + (page.size || 0), 0); const sizeDiff = totalSize - lastTrackedTotalSize; if ( sizeDiff > 10 * 1024 * 1024 || (totalSize > 0 && lastTrackedTotalSize === 0) ) { await trackArchiveSize(totalSize); lastTrackedTotalSize = totalSize; } } catch (error) { console.error("Error tracking archive size:", error); } }