Skip to content

feat: working matomo analytics (test environment) #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 5, 2025

Conversation

nikitalokhmachev-ai
Copy link
Collaborator

@nikitalokhmachev-ai nikitalokhmachev-ai commented Jun 2, 2025

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
    Copy link
    Collaborator Author

    image

    @pr-agent-monadical
    Copy link

    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);
      }
    }

    @nikitalokhmachev-ai nikitalokhmachev-ai linked an issue Jun 2, 2025 that may be closed by this pull request
    @Shrinks99 Shrinks99 merged commit d3ab23b into main Jun 5, 2025
    0 of 3 checks passed
    @Shrinks99 Shrinks99 deleted the nikita-matomo-analytics branch June 5, 2025 05:29
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Projects
    None yet
    Development

    Successfully merging this pull request may close these issues.

    Analytics
    2 participants