supasecret

Analytics Documentation

Technical overview of Space Hunter's anonymous analytics system

Overview

Space Hunter collects anonymous usage analytics to help us understand how the app is used and improve the user experience. All data collection is completely anonymous and optional.

This page provides technical details for developers who want to understand exactly what data is sent to our servers.

How to Disable Analytics

You can disable anonymous analytics at any time in the app:

  1. Open Space Hunter
  2. Go to Settings
  3. Navigate to Advanced tab
  4. Toggle off Enable anonymous analytics

Once disabled, the app will no longer send any analytics events to our servers.

Technical Details

API Endpoint

All analytics events are sent via POST request to our API endopint

Request Format

Events are sent as JSON with the following structure:

{
  "session_id": "uuid",
  "event_type": "string",
  "timestamp": "ISO8601",
  "app_version": "string",
  "os_version": "string",
  "license_tier": "free|trial|pro",
  "data": {} | null
}

Server-Side Data Collection

In addition to the app-provided fields, the server automatically captures:

  • ip_address - Your IP address (used for geolocation, not stored for tracking)
  • country_code - Two-letter country code derived from your IP (e.g., "US", "GB", "DE")

Session ID

The session_id is a randomly generated UUID that is created when the app launches.

  • A new session ID is generated every time you launch Space Hunter
  • The session ID is not stored between launches
  • It cannot be used to identify you or track you across sessions
  • It exists only to correlate events within a single app session

Event Types

Space Hunter sends the following event types:

1. app_launched

Sent when Space Hunter is launched.

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "app_launched",
  "timestamp": "2025-01-15T14:32:10Z",
  "app_version": "1.0.0",
  "os_version": "15.2.0",
  "license_tier": "free",
  "data": null
}

2. scan_started

Sent when a file system scan begins.

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "scan_started",
  "timestamp": "2025-01-15T14:32:15Z",
  "app_version": "1.0.0",
  "os_version": "15.2.0",
  "license_tier": "free",
  "data": null
}

3. scan_completed

Sent when a file system scan completes successfully.

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "scan_completed",
  "timestamp": "2025-01-15T14:32:25Z",
  "app_version": "1.0.0",
  "os_version": "15.2.0",
  "license_tier": "free",
  "data": {
    "total_size_mb": 44339,
    "categories_found": [
      "Language Files",
      "Log Files",
      "Downloads",
      "Trash",
      "Chrome Cache",
      "Firefox Cache",
      "Homebrew Cleanup",
      "Docker Cleanup",
      "Rust Cargo Cache",
      "Go Module Cache",
      "Node Modules",
      "Python Envs",
      "PHP Packages",
      "Xcode Build Cache",
      "Gradle Cache"
    ],
    "duration_seconds": 1719
  }
}

Data fields:

  • total_size_mb - Total size of cleanable files found (in megabytes)
  • categories_found - Array of file category names discovered during scan
  • duration_seconds - How long the scan took (in seconds)

4. cleanup_started

Sent when a cleanup operation begins.

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "cleanup_started",
  "timestamp": "2025-01-15T14:33:00Z",
  "app_version": "1.0.0",
  "os_version": "15.2.0",
  "license_tier": "free",
  "data": {
    "categories": ["Node Modules", "Docker Cleanup"],
    "total_size_mb": 1500
  }
}

Data fields:

  • categories - Array of categories selected for cleanup
  • total_size_mb - Planned deletion size (in megabytes)

5. cleanup_completed

Sent when a cleanup operation finishes.

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "cleanup_completed",
  "timestamp": "2025-01-15T14:33:15Z",
  "app_version": "1.0.0",
  "os_version": "15.2.0",
  "license_tier": "free",
  "data": {
    "categories": ["Node Modules", "Docker Cleanup"],
    "total_size_mb": 1450,
    "success": true
  }
}

Data fields:

  • categories - Array of categories that were cleaned
  • total_size_mb - Actual deleted size (in megabytes)
  • success - Whether the operation completed successfully

6. license_upgraded

Sent when a user activates a license.

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "license_upgraded",
  "timestamp": "2025-01-15T14:35:00Z",
  "app_version": "1.0.0",
  "os_version": "15.2.0",
  "license_tier": "pro",
  "data": {
    "from_tier": "free",
    "to_tier": "pro"
  }
}

Data fields:

  • from_tier - Previous license tier
  • to_tier - New license tier

7. quota_limit_reached

Sent when a free user hits the 10GB cleanup quota.

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "quota_limit_reached",
  "timestamp": "2025-01-15T14:40:00Z",
  "app_version": "1.0.0",
  "os_version": "15.2.0",
  "license_tier": "free",
  "data": null
}

8. settings_opened

Sent when the settings window is opened.

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "settings_opened",
  "timestamp": "2025-01-15T14:45:00Z",
  "app_version": "1.0.0",
  "os_version": "15.2.0",
  "license_tier": "free",
  "data": null
}

9. error_occurred

Sent when an error occurs in the application.

Example payload:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "error_occurred",
  "timestamp": "2025-01-15T14:50:00Z",
  "app_version": "1.0.0",
  "os_version": "15.2.0",
  "license_tier": "free",
  "data": {
    "error_type": "scan_failed",
    "error_message": "Permission denied"
  }
}

Data fields:

  • error_type - Category of the error
  • error_message - Sanitized error description (no personally identifiable information)

Data Retention

Analytics data is stored in our database for analysis and product improvement purposes. We retain this data indefinitely as it contains no personally identifiable information.

IP addresses and country codes are used only for aggregate statistics (e.g., "How many users are from the US?") and cannot be used to identify individual users due to the random session IDs.

Privacy Commitment

  • No personal information is collected (no names, emails, or file paths)
  • No tracking across sessions - session IDs are regenerated on each launch
  • Completely optional - you can disable analytics at any time
  • Transparent - this page documents exactly what we collect
  • Used only for product improvement - never sold or shared with third parties

Questions?

If you have questions about our analytics system or data collection practices, please contact us at [email protected].