Futuristic Toast Example

Mouseprints Documentation

Overview

Mouseprints records and analyzes real user browsing sessions on your website. It visualizes click, scroll, and navigation behavior, helping you uncover UX obstacles, friction points, and valuable optimization opportunities.

Setup

Installation

After registering your site, add this script before </body> on every page:

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

How It Works

  • Mouseprints creates a privacy-respecting, pseudonymous ID for each browser and short-lived session.
  • User interactions (clicks, scrolls, typing, navigations, and more) are securely sent in short batches to your analytics dashboard.
  • Bots, rapid page reloads, and obvious non-human visitors are auto-filtered to keep your data clean.
  • Session data is only sent after your user's explicit consent (see Privacy, Consent & Cookie Banners).

Dynamic Site Identification

Your site_id is built directly into your script link by Mouseprints and does not need to be configured manually.

Captured Features

  • User clicks, taps, mouse movements, and scrolling behavior
  • Page loads, reloads, navigation (including single-page apps)
  • Viewport resizes and orientation changes
  • Form field entries (with strong masking to protect sensitive data)
  • Basic details: device, browser, referrer, page URL, and session timing

Automatic Bot Filtering

Automated traffic is detected based on inactivity, user agent, and minimal interaction, and is excluded from all your analytics.

Opting Out

Full Page Opt-Out

To fully disable Mouseprints recording for a given page, add data-mouseprints="off" to any element (typically the <body> tag):

index.html 
<body data-mouseprints="off">...</body>

If present anywhere in the page DOM, no events will be recorded for that visit.

Masking Individual Elements

To block Mouseprints from capturing or serializing specific elements, use mouseprints-ignore as an attribute or mouseprints-ignore="true":

index.html 
<div mouseprints-ignore>Sensitive content is never recorded.</div>
<input mouseprints-ignore="true" value="masked">
  • Both standalone mouseprints-ignore and mouseprints-ignore="true" forms are supported for compatibility.
  • These elements will be completely skipped from your Mouseprints replays and session data.
  • No data from ignored elements is ever sent or stored.
  • Use this to mask out chat widgets, dashboards, or sensitive custom UI in a way that cannot be bypassed by users.

Privacy, Consent & Cookie Banners

  • Consent is required for analytics: Mouseprints uses local storage IDs, and thus requires clear cookie/tracking consent for visitors covered by GDPR, ePrivacy, and CCPA.
  • When to show a cookie banner:
    • Display your consent banner as early as possible (ideally before analytics scripts load or fire).
    • Do not load or activate Mouseprints for users who refuse analytics cookies.
  • Built-in automatic cookie banner:
    • Add &cookie_banner=true to your script URL. Example:
      index.html 
      <script src="https://mouseprints.io/mouseprint.js?key=YOUR_API_KEY&cookie_banner=true" defer></script>
    • The banner appears at the bottom, always centered, and blocks session recording until accepted.
    • Customizing the banner:
      index.html 
      <script 
  src="https://mouseprints.io/mouseprint.js?key=YOUR_API_KEY&cookie_banner=true"
  data-banner-text="We use <span class='text-accent'>essential</span> cookies and <span class='text-accent'>analytical</span> cookies (Mouseprints) to help us improve your experience."
  data-accept-label="Accept Selected"
  data-banner-bg="#12151a"
  data-banner-border="#00ffee"
  data-banner-max-width="480px"
  data-button-bg="#00ffee"
  data-button-color="#115533"
  data-link-url="/privacy"
  data-link-label="Learn more"
  data-checkbox-color-border="#00ffee"
  data-checkbox-color-fill="#22ffd0"
  data-consent-text-color="#41ffe3"
  data-link-color="#00ffee"
  data-options="analytics"
  data-options-labels="Analytical"
  data-options-defaults="true"
  defer
></script>
  • Attribute Reference (custom banners)
    • data-banner-text: Banner message (HTML, including links, allowed)
    • data-accept-label: Accept button text
    • data-banner-bg, data-banner-border, data-banner-max-width: Banner style
    • data-button-bg, data-button-color: Button background and text color
    • data-link-url, data-link-label: Privacy link and label for the banner
    • data-checkbox-color-border: Consent checkbox border color
    • data-checkbox-color-fill: Consent checkbox fill/check color
    • data-consent-text-color: Consent label text color
    • data-link-color: Link color inside banner
    • data-options, data-options-labels, data-options-defaults: Consent toggles
  • The banner will not show again if cookie_consent exists.
  • Custom/third-party banners: Only load Mouseprints if analytics consent is given:
    snippet.js 
    // Consent-callback example:
function onUserConsentsToAnalytics() {
  var script = document.createElement("script");
  script.src = "https://mouseprints.io/mouseprint.js?key=YOUR_API_KEY";
  script.defer = true;
  document.body.appendChild(script);
}

// Or:
function loadMouseprints() {
  if (!window.mouseprintsLoaded) {
    var script = document.createElement('script');
    script.src = "https://mouseprints.io/mouseprint.js?key=YOUR_API_KEY";
    script.defer = true;
    document.body.appendChild(script);
    window.mouseprintsLoaded = true;
  }
}
  • Input privacy: Mouseprints automatically masks all password, email, tel, number, or known credit card/government ID fields.
  • No data is sent before your user grants analytics consent. If a page has data-mouseprints="off", Mouseprints does not record regardless of consent.

Plans & Quotas

Your monthly quota is determined by your subscription plan. When your quota is reached, new sessions will not be recorded until it resets.

  • Free: 100 sessions/month — stored for 1 week
  • Starter: 500 sessions/month — stored for 2 weeks
  • Basic: 5,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

Sessions older than their retention period are automatically deleted. Please export important sessions for your own records if needed.

Once your monthly quota is exceeded, Mouseprints will stop recording new sessions until your next billing cycle. You may upgrade your plan at any time to restore functionality.

Dashboard & Insights

Get real-time and historical insights into your site's activity with a powerful analytics dashboard designed for clarity and depth.

  • Session Trends: View monthly usage, daily breakdowns, and traffic patterns by hour of day.
  • Click Heatmaps: Explore where users click and how they interact with each page.
  • Page-Level Analysis: Identify your most active pages and top exit pages.
  • Visitor Breakdown: See device types (mobile, desktop, tablet), user agents, and referrer statistics.
  • New vs Returning Users: Automatically detects returning visitors using browser fingerprints.
  • Session Metrics: Track session duration, event counts, and engagement quality per visit.
  • Geo Insights: Understand where your users are coming from with country, city, and region data.
  • Quota Monitoring: Visualize how close you are to your monthly session limit and avoid overages.
  • Per-Site Comparison: See session counts across all sites in your account to compare performance.
  • Top Referrers: Find out which sources are driving the most traffic.
  • Timeline Charts: Visualize traffic over the current month with interactive line graphs.

Authentication and private areas: Mouseprints does not record content behind login portals or password forms unless a session begins in a logged-in state. We respect user privacy and avoid capturing sensitive or restricted content by default.

UTM Campaign Tracking

Mouseprints automatically captures UTM parameters from URLs and associates them with session recordings. This helps you measure campaign performance with precision.

Captured UTM Parameters

  • utm_source - Where the traffic came from (e.g., google, newsletter)
  • utm_medium - Marketing medium (e.g., cpc, email, social)
  • utm_campaign - Name of the specific campaign (e.g., spring_sale_2025)
  • utm_term - Paid keyword tracking (if applicable)
  • utm_content - Distinguish similar ads/links in the same campaign

Campaign Performance Dashboard

Navigate to the Campaigns section in your dashboard to view:

  • Total sessions per UTM campaign
  • Average session duration
  • Unique visitors per campaign
  • Sparkline charts of recent session activity
  • Funnel paths and scroll depth breakdowns per campaign

Filtering & Sorting

You can filter campaigns by name, and sort by total sessions, average duration, or unique visitors for deeper analysis.

Untracked Traffic

Sessions that don't include UTM parameters are grouped under Untracked.

User Funnels

Mouseprints auto-detects user funnels from recorded navigation paths during each session. Funnels show the most common page transitions users take, helping you understand conversion journeys or drop-off points.

  • Automatically extracted from click/navigation events
  • Includes counts and associated sessions
  • Viewable in the Campaigns tab when UTM data is present
  • Sessions are clickable to replay specific paths

Funnel analysis can be filtered by campaign, helping correlate user flow with marketing efforts.

AI Insights

For Pro and Enterprise plans, Mouseprints uses OpenAI-powered models to analyze your recent session recordings and highlight:

  • Rage clicks: Unusually fast or repeated click patterns suggesting frustration
  • Dead clicks: Clicks that result in no visible change
  • Scroll drop-off: Where users stop reading a page
  • User funnels: The most common navigation journeys
  • Click ranking: Which elements earn the most clicks or taps

Frequency: Each type of AI analysis can be refreshed once every 24 hours per site.

Interpret with care: AI summarizes patterns found in session logs, but may occasionally surface noise, outliers, or false positives. Use results as a guide, not as absolute truth.

Heatmaps

The Heatmaps section lets you visually analyze where users click on specific pages of your site. You can access it from the Heatmaps tab in your site dashboard.

  • Click heatmaps are generated from actual user session data
  • Each heatmap is rendered over a full-page screenshot of the live page
  • Heat intensity reflects the frequency and distribution of user clicks
  • Only pages with recorded clicks will appear in the heatmap list
  • All clicks from matching page URLs are aggregated to generate the heatmap

Page List

The index view displays a list of all pages with recorded click activity. For each page, you'll see the domain and path. Click on any entry to view its corresponding heatmap.

Shared Heatmaps

You can generate a public view link for any heatmap using the Share button. These links allow non-logged-in users to view a specific heatmap. Access can be revoked at any time using the Unshare button.

Screenshot Rendering

Heatmaps are overlaid on screenshots taken in real time using a headless browser. This means the page must be publicly accessible; Mouseprints cannot render pages behind authentication or firewalls.

Data Storage & Format

  • Each session is stored as a single JSON file, grouped by site and user in your account.
  • All session files include a session ID, key metadata, and the detailed interaction timeline.
  • Session metadata (event counts, durations, referrer) is also indexed in the database for fast access and dashboard reporting but is never shared with third parties.

Security

  • All data is encrypted in transit (HTTPS) and secure on our servers.
  • Masking of sensitive fields is strictly enforced client-side before any data is sent.
  • Only account holders and designated team members can view session data for your sites.
  • No cross-domain tracking, fingerprinting, or resale of behavioral data.
  • Mouseprints supports regulatory compliance (GDPR, ePrivacy Directive, CCPA) provided your site displays proper consent banners as required in your region.

Sharing

You may choose to generate share links for specific session recordings or heatmaps. Anyone with the link can view the shared content, even if they are not logged in.

  • Session Sharing — Share a full session replay with timeline, meta info, and playback controls.
  • Heatmap Sharing — Share a visual heatmap for a specific page, including the overlay and screenshot.

All shared links can be revoked from your dashboard at any time. Shared heatmaps and sessions do not expose any private or password-protected content.

Session API

The frontend script transmits session event batches to Mouseprints using your site credentials and anonymized browser/session identifiers. Mouseprints verifies, filters, and safely records all data on your behalf. Please contact support if you need special API integrations.

About Input Masking

Our script will mask any input identified as a password, email, telephone number, or credit card field (when marked with standard HTML attributes).

API Access: Private Data Endpoints

For programmatic access to your site's session data and AI-powered analytics, use the authenticated API. All endpoints require an API key.

  • Get a live or historical feed of session metadata
  • Download raw session JSON files
  • Query AI-generated behavioral summaries

Authentication

Supply your site's API key in the header of every request:
Authorization: Bearer your-private-api-key-here

Note: Data is always private to your site. API keys can access only the sessions/analyses for their associated site. Rate limits apply. For security best practices, never expose your API key on public frontends or client JavaScript.

Endpoints

GET /api/v1/sessions

Returns a paginated list of your site's sessions.
Query params: page (default: 1), per_page (default: 50, max: 100) 

GET /api/v1/sessions?page=1&per_page=50

Returns:

{
  "sessions": [
    {
      "id": "abc123",
      "filename": "1685.json",
      "started_at": "2024-06-02T13:58:03Z",
      "duration": 320,
      "user_agent": "...",
      "name": null,
      "shared": false,
      "deleted": false
    }
  ],
  "page": 1,
  "per_page": 50
}

Rate limit: 60/minute.

GET /api/v1/sessions/<session_id>

Returns metadata for a single session (only if it belongs to your site).

GET /api/v1/sessions/abc123

Returns: 404 if not found or unauthorized.

{
  "id": "abc123",
  "filename": "1685.json",
  "started_at": "...",
  "duration": 320,
  "user_agent": "...",
  "name": null,
  "shared": false,
  "deleted": false
}

GET /api/v1/sessions/<session_id>/file

Download or view the raw JSON file for a specific session.
Query params: download=1 (forces a file download) 

GET /api/v1/sessions/abc123/file
GET /api/v1/sessions/abc123/file?download=1

Returns:

  • application/json: parsed session data
  • 403: session does not belong to your site
  • 404: file not found
Rate limit: 30/minute.

POST /api/v1/upload_session

Upload a single session recording to your site.
Headers: Authorization: Bearer <api_key>
Form fields:

  • session (file, required): .json file of the session
  • session_prefix (string, optional): optional name prefix

POST /api/v1/upload_session
Authorization: Bearer abc123
Content-Type: multipart/form-data

Returns:

  • 200: { success: true, session_id: "...", filename: "..." }
  • 400: validation error
  • 401: invalid API key
  • 403: quota exceeded
Rate limit: 100/minute.

GET /api/v1/ai_analysis

List all AI-generated behavioral analyses for your site.
Query params: page & per_page 

GET /api/v1/ai_analysis?page=1&per_page=50

Returns:

{
  "ai_analysis": [
    {
      "id": "xyz789",
      "analysis_type": "summary",
      "session_count": 20,
      "summary": "Visitors tend to...",
      "created_at": "2024-06-02T13:45:00Z"
    }
  ],
  "page": 1,
  "per_page": 50
}

Rate limit: 60/minute

GET /api/v1/ai_analysis/<analysis_id>

Get full result for one AI analysis. 

GET /api/v1/ai_analysis/xyz789

Returns: 404 if not found or unauthorized.

{
  "id": "xyz789",
  "analysis_type": "summary",
  "session_count": 20,
  "summary": "Visitors tend to...",
  "raw": {...},
  "created_at": "2024-06-02T13:45:00Z"
}

GET /api/v1/health

Health check endpoint. No authentication required. 

GET /api/v1/health

Returns: {"status": "ok"}

Errors

  • 401: Missing or invalid API key
  • 403: Access denied for this site
  • 404: Not found
  • 429: Rate limited

Best practices

  • Keep your API key safe - never publish it client-side
  • Use HTTPS at all times
  • Rotate credentials periodically if compromised

Content Security Policy (CSP)

If your site uses CSP headers, ensure Mouseprints is allowed:

script-src 'self' https://mouseprints.io;
  connect-src 'self' https://mouseprints.io;
  img-src 'self' data:;

Adjust policies as needed for additional features such as screenshot rendering or 3rd-party analytics.

Browser Support

Mouseprints supports all modern browsers:

  • Chrome (latest 2 versions)
  • Firefox (latest 2 versions)
  • Safari 13+
  • Edge (Chromium-based)
  • Mobile Safari & Chrome

Internet Explorer is not supported. Recording accuracy may vary on older or non-standard browsers.