JavaScript SDK

The UserSesh tracker is a lightweight JavaScript SDK that auto-captures analytics, session recordings, and heatmaps. No build step required.

Installation

Script tag (any website)

Add this to your HTML <head>:

<script
  src="https://usersesh.com/tracker.js"
  data-site-id="YOUR_SITE_ID"
  async
></script>

Next.js (App Router)

Add to app/layout.tsx inside <head>:

import Script from "next/script";

<Script
  src="https://usersesh.com/tracker.js"
  data-site-id="YOUR_SITE_ID"
  strategy="afterInteractive"
/>

Next.js (Pages Router)

Add to pages/_document.tsx or pages/_app.tsx inside <Head>:

<script src="https://usersesh.com/tracker.js" data-site-id="YOUR_SITE_ID" async></script>

Vue / Nuxt

For Vite + Vue, add to index.html. For Nuxt, add to nuxt.config using app.head.script.

<script src="https://usersesh.com/tracker.js" data-site-id="YOUR_SITE_ID" async></script>

SvelteKit

Add to src/app.html inside <head>.

Astro

Add to your base layout component (src/layouts/Layout.astro) inside <head>.

npm package (React)

npm install usersesh
import { UserSesh } from "usersesh";

// In your root component:
<UserSesh siteId="YOUR_SITE_ID" />

Configuration

Configure the tracker with data-* attributes on the script tag:

AttributeRequiredDescription
data-site-idYesYour site ID from the dashboard
data-api-endpointNoCustom API endpoint. Defaults to the script's origin.
data-debugNoSet to "true" for verbose console logging
data-idle-timeoutNoIdle timeout in seconds. Default: 60
data-track-consoleNoSet to "true" to track console.error calls

Auto-Tracked Data

Once installed, the tracker automatically captures the following with zero code:

Sessions & Page Views

Session start/end, duration, idle detection, page URL changes, SPA navigation (pushState/replaceState/popstate).

Clicks

Every click with element tag, selector, text content, and position. Includes data-track, data-analytics, and data-testid attributes when present.

Scroll Depth

Fires events at 25%, 50%, 75%, and 90% scroll milestones.

Rage Clicks

3+ clicks within 50px in under 1 second. Indicates broken buttons or confusing UX.

Errors

Runtime JavaScript errors, unhandled promise rejections, and optionally console.error calls.

Web Vitals

FCP (First Contentful Paint), LCP (Largest Contentful Paint), TTFB (Time to First Byte), CLS (Cumulative Layout Shift).

Session Recordings

Full DOM replay including mutations, mouse movement, clicks, scrolls, and input events. PII is auto-masked.

Heatmaps

Click positions (relative %), mouse movement, and scroll depth data. Batched every 15 seconds.

UTM & Ad Click IDs

Captures utm_source, utm_medium, utm_campaign, etc. Also captures gclid (Google), fbclid (Meta), twclid (X/Twitter), li_fat_id and li_ed (LinkedIn), ttclid (TikTok), and more.

Device Info

Browser, OS, device type, screen resolution, and viewport size.

API Reference

The SDK exposes its API on window.usersesh (also available as window.AnalyticsTracker).

usersesh.track(eventName, properties?)

Track a custom business event with optional properties.

usersesh.track("signed_up", { method: "google" });
usersesh.track("feature_used", { feature: "export", format: "csv" });
usersesh.track("cta_clicked", { name: "hero-signup", location: "hero" });
ParamTypeDescription
eventNamestringEvent name. Use snake_case.
propertiesobjectOptional key-value pairs attached to the event.

See Events & Identification for best practices.

usersesh.conversion(options)

Track a revenue or conversion event. Used for ad platform ROAS matching.

usersesh.conversion({ event: "purchase", revenue: 49.99, currency: "USD" });
usersesh.conversion({ event: "signup", revenue: 0 });
usersesh.conversion({
  event: "trial_start",
  revenue: 0,
  metadata: { plan: "pro", source: "pricing" }
});
OptionTypeDescription
eventstringConversion event name (e.g. "purchase", "signup")
revenuenumberRevenue amount. Use 0 for free conversions.
currencystringISO currency code. Default: "USD"
metadataobjectOptional extra data (plan, source, etc.)

See Conversion Tracking for full details.

usersesh.identify(userId, traits?)

Link the current session to a known user. Call this after login or signup.

usersesh.identify("user_123", {
  email: "jane@example.com",
  name: "Jane Doe",
  plan: "pro",
  created_at: "2024-01-15"
});
ParamTypeDescription
userIdstringUnique user identifier from your system
traitsobjectOptional user properties (email, name, plan, etc.)

usersesh.people.set(properties)

Update user properties without changing identity. Useful for updating plan, role, or other profile data after the initial identify call.

usersesh.people.set({ plan: "enterprise", seats: 25 });

usersesh.reset()

Clear the current user identity. Call this when the user logs out.

usersesh.reset();

usersesh.getVisitorId()

Returns the anonymous visitor ID (generated on first visit, persisted in localStorage).

const visitorId = usersesh.getVisitorId(); // "v_abc123..."

usersesh.getUserId()

Returns the identified user ID set via identify(), or null if not identified.

const userId = usersesh.getUserId(); // "user_123" or null

usersesh.setRecordingEnabled(enabled)

Programmatically enable or disable session recording. Useful for consent flows.

// Disable recording until user consents
usersesh.setRecordingEnabled(false);

// User clicks "Accept"
usersesh.setRecordingEnabled(true);

usersesh.isIdle()

Returns whether the user is currently idle (no mouse/keyboard activity for the idle timeout period).

if (!usersesh.isIdle()) {
  // User is active
}

Privacy & PII Masking

The tracker automatically masks sensitive data in session recordings:

  • Password inputs are never recorded
  • Email addresses are auto-detected and masked
  • Phone numbers are auto-detected and masked
  • Credit card numbers are auto-detected and masked

Next steps