Mouseprints Documentation

Overview

Mouseprints is a lightweight session recording and behavior analytics service. It tracks user interactions like clicks, scrolls, inputs, and DOM activity, allowing you to understand how visitors engage with your website.

Setup

Installation

After registering a site, embed the following script before the closing </body> tag of your HTML:

<script src="https://mouseprints.io/mouseprint.js?key=YOUR_API_KEY" defer></script>

How It Works

The script generates a unique browser and session ID per visitor. Sessions are streamed in batches to Mouseprints' servers. Only active sessions are recorded — idle or bot-like traffic is ignored automatically.

Recorded Features

  • Mouse movements and scrolling
  • Viewport resizing and orientation changes
  • Clicks, form input (non-sensitive only)
  • DOM changes and mutations
  • Exit page and interaction heatmaps
  • Device and browser info
  • Session duration and activity score

Mouseprints masks all fields that appear to contain emails, passwords, or phone numbers by default.

Bot Detection

Sessions without interaction, with suspicious user agents, or with missing metadata are discarded automatically to reduce noise from crawlers and bots.

Plans & Quotas

Your monthly quota determines how many sessions can be recorded across all sites:

  • Free: 50 sessions/month — stored for 1 week
  • Basic: 3,000 sessions/month — stored for 1 month
  • Pro: 50,000 sessions/month — stored for 6 months
  • Enterprise: 1,000,000 sessions/month — stored for 2 years

Once your quota is exceeded, new sessions are dropped until your next billing cycle begins.

Note: Older sessions beyond the storage duration are automatically and permanently deleted. Be sure to export any critical sessions before they expire.

Dashboard & Insights

The dashboard shows live and historical analytics for each of your sites:

  • Total and recent session counts
  • Heatmaps by page
  • Device and browser usage
  • Top referrers and pages
  • Session duration and drop-off timing
  • Time-based activity graphs

Important: Mouseprints cannot bypass login forms, authentication gates, or private dashboards. This means heatmaps (and some session replays) will not reflect content or behavior that occurs behind a login screen unless the user was already logged in during the session. Pages protected by authentication are effectively invisible to the recorder.

AI Insights

Pro and Enterprise plans include experimental AI-powered analysis tools. These models review your recent session data to highlight:

  • Rage clicks: Repetitive or frustrated clicking behavior
  • Dead clicks: Clicks that don't trigger interaction
  • Scroll drop-off: Where users stop scrolling
  • User funnels: Automatically detected multi-step flows
  • Click ranking: Most clicked elements per page

Note: AI results are generated using heuristics and large language models. They are helpful for guidance but may contain inaccuracies or false positives. Use them to support — not replace — your own UX judgment.

Limit: Each analysis type can be refreshed once every 24 hours per site.

Data Storage

Each session is stored as a JSON file under a per-user and per-site folder. Metadata like duration, referrer, and device are stored in a database for quick access. Sessions are persisted unless manually deleted via the dashboard.

Security & Privacy

  • All data is transmitted over HTTPS and stored securely.
  • Input masking prevents accidental capture of sensitive information.
  • Only you (the site owner) can access session recordings unless shared.
  • We do not track users across domains or share session data with third parties.

Session Sharing

Each session has a unique URL that can be copied and shared. Shared sessions can be viewed by anyone with the link, even if they aren't logged in.

Session API

The snippet sends batched session events to /api/session-record. Each request includes metadata, event payloads, and the current session ID. The server verifies authenticity, filters bots, and stores the session in your site folder.