Configuration

Full reference for all options accepted by haya.init().

Signature

haya.init(projectId: string, config?: Partial<HayaConfig>): void

Parameter	Type	Required	Description
projectId	string	Yes	Your SDK key from the Haya dashboard
config	Partial<HayaConfig>	No	Feature flags and settings (see below)

---

All options

haya.init('YOUR_SDK_KEY', {
  // ── Features ────────────────────────────────────
  sessionReplay: false,       // Record DOM replay (first 40s per session)
  heatmaps: true,             // Collect click + scroll data for heatmaps

  // ── Auto-tracking ────────────────────────────────
  autoTrack: {
    clicks: true,             // Track every click
    scrolls: true,            // Track scroll depth
    pageviews: true,          // Track page loads + SPA navigation
  },
  trackMousemove: false,      // Track mouse position (high volume — off by default)

  // ── Privacy ──────────────────────────────────────
  maskInputs: true,           // Mask all input values in replays
  ignoreSelectors: [],        // CSS selectors to exclude from tracking

  // ── Transport ────────────────────────────────────
  endpoint: 'https://api.usehaya.io/api/v1/analytics/events',
  flushInterval: 3000,        // ms between batch sends (default: 3s)
  flushSize: 50,              // Flush early when buffer hits this count

  // ── Replay ───────────────────────────────────────
  replayMaxDuration: 40,      // Max seconds of replay to record per session

  // ── Debug ────────────────────────────────────────
  debug: false,               // Log SDK activity to console
});

---

Option details

sessionReplay

Type: boolean Default: false

Enables rrweb-based DOM recording. Records the first replayMaxDuration seconds of each session. Replays can be watched in the Haya dashboard under Sessions.

Replay recording automatically stops after replayMaxDuration seconds — regular event tracking continues indefinitely.

---

heatmaps

Type: boolean Default: true

Enables click coordinate and scroll depth collection used to render heatmaps in the dashboard. Requires autoTrack.clicks and autoTrack.scrolls to also be enabled.

---

autoTrack

Type: object

Controls which browser interactions are captured automatically.

Key	Default	Tracks
clicks	true	Click position, target element, page URL
scrolls	true	Scroll depth as % of page height
pageviews	true	Initial load + pushState/popstate navigation

---

trackMousemove

Type: boolean Default: false

Tracks mouse cursor position at 100ms intervals. Generates high event volume — only enable if you specifically need cursor tracking data.

---

maskInputs

Type: boolean Default: true

When true, all <input>, <textarea>, and <select> values are replaced with *** in session replays. The field interactions (focus, blur, submit) are still tracked, just not the values.

:::warning Recommended: keep this on Always keep maskInputs: true in production unless you have a specific reason to disable it. It prevents accidental capture of passwords, credit card numbers, and personal data. :::

---

ignoreSelectors

Type: string[] Default: []

An array of CSS selectors. Elements matching these selectors will not be tracked or included in replays.

haya.init('YOUR_SDK_KEY', {
  ignoreSelectors: ['.haya-ignore', '#sensitive-widget', '[data-no-track]'],
});

You can also call haya.ignore(selector) before init() as an alternative.

---

endpoint

Type: string Default: https://api.usehaya.io/api/v1/analytics/events

The URL where events are sent. Override this only if you are self-hosting the Haya backend on your own domain.

---

flushInterval

Type: number (ms) Default: 3000

How often the SDK sends buffered events to the backend. Lower values mean more real-time data but more network requests. The minimum effective value is 1000.

---

flushSize

Type: number Default: 50

When the event buffer reaches this count, the SDK flushes immediately without waiting for the next interval. Prevents memory buildup on pages with very high click rates.

---

replayMaxDuration

Type: number (seconds) Default: 40

Maximum seconds of session replay recorded per session. Recording stops automatically when this limit is reached. Regular event tracking (clicks, scrolls, etc.) continues indefinitely after the replay cap.

---

debug

Type: boolean Default: false

Logs SDK activity to the browser console — initialization, event captures, batch flushes, errors. Useful during development.

You can also toggle debug mode at runtime:

haya.setDebug(true);