Sessions

A session is one recording — the full stream of events between a user opening your app and their last interaction.

Lifecycle

Stage	Trigger
Start	First `init()` call after a fresh page load, or after 30 min of idle
Active	While the user is interacting (clicks, scrolls, taps)
Paused	When the tab backgrounds or the app suspends
End	30 min of inactivity, or explicit `stop()` call

The timeout is configurable per project via sessionTimeoutMs in init().

Session ID

Every session has its own ID, stored in memory (not persisted across page reloads). You can read it at runtime:

const { sessionId } = useGalacha();
// => "sess_01HK8Z2M7F3Y4Q9R3B7KJX5PM2"

On a hard page reload, a new session starts. On a soft SPA navigation (React Router, Next.js <Link>, etc.), the same session continues.

Session vs Visitor

	Session	Visitor
Lifetime	30 min of idle	Forever (until `localStorage` clears)
Persistence	Memory only	`localStorage`
Reset on reload?	Yes	No
Reset on logout?	No (unless you call `stop()`)	No

A single visitor can own many sessions. The dashboard groups them under the same visitor ID, so you can follow a single user across weeks.

Ending a session manually

You rarely need to. The most common reason is a logout flow where you want the current user's session to close cleanly before the next user signs in:

// React / Next.js
const { stop } = useGalacha();
 
function handleLogout() {
  stop();
  // clear tokens, redirect, etc.
}

Heads up: stop() tears down the recorder. To start recording again, you need to reload the page or re-mount the <GalachaProvider>. If you expect the same tab to log a new user back in, skip the stop() call and let identify() retag the session instead.

Idle detection

The SDK watches user input — mousemove, scroll, click, keypress, touch — and resets the idle timer on each. If nothing happens for sessionTimeoutMs (default 30 min), the next event triggers a new session.

<GalachaProvider
  projectKey="..."
  sessionTimeoutMs={15 * 60 * 1000}  // shorter sessions
/>

Custom event on session start?

Not supported in the public API. The session starts silently. If you need a hook, subscribe to ready from useGalacha():

const { ready, sessionId } = useGalacha();
 
useEffect(() => {
  if (ready) analytics.track("galacha_session_start", { sessionId });
}, [ready, sessionId]);