> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexclave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Explore events, session replays, and SQL queries in your project's analytics dataset

The Analytics app gives you direct access to your project's analytics dataset in Hexclave. You can inspect raw event tables, run ClickHouse SQL queries, and watch session replays to debug real user behavior.

## Overview

Analytics is organized into four areas in the dashboard:

* **Tables**: Browse rows across tables (events, users, contact channels, and more) with sorting, search, and incremental loading
* **Queries**: Run and save reusable ClickHouse SQL queries
* **Replays**: Watch session replays and filter by user, team, duration, activity window, and click count
* **Clickmaps**: See which elements get clicks on your pages

See [Replays & Clickmaps](https://docs.hexclave.com/guides/apps/analytics/replays-and-clickmaps.md) for the full guide to session replays and clickmaps.

## How Analytics Works

Hexclave records analytics events and replay chunks, then exposes them through the Analytics app for read-only querying and investigation.

User activity in your app flows into Hexclave event ingestion, which stores data in ClickHouse. This data powers the Tables view, the SQL query runner, and the Session replay UI.

Analytics isn't only client events. Hexclave also exposes product data from the rest of your project — users, contact channels, teams, permissions, email outbox, and more — in the same read-only ClickHouse dataset, so you can join product state with behavior in one place. See [Queries & Tables](https://docs.hexclave.com/guides/apps/analytics/queries-and-tables.md) for the full table list.

### What Gets Tracked

Hexclave collects both client-side and server-side analytics events:

* **Client-side events**: browser interaction events like `$page-view` and `$click`
* **Server-side events**: currently `$token-refresh` and `$sign-up-rule-trigger`

## Enabling the Analytics App

To use analytics in your project:

1. Open your Hexclave dashboard
2. Go to **Apps**
3. Open **Analytics**
4. Click **Enable**

## Quick Start

1. Enable Analytics in your Hexclave dashboard (**Apps -> Analytics**)
2. Initialize Hexclave on your frontend with `HexclaveClientApp`/`HexclaveProvider` and a persistent `tokenStore` (e.g. `"cookie"`, or `"nextjs-cookie"` in Next.js)
3. Call `hexclaveClientApp.initAnalytics()` on every page you want to track (see [Tracking every page](#tracking-every-page))
4. Sign in with a real user session
5. Open the app and navigate/click around
6. Check **Analytics -> Tables** to confirm events are arriving

SDK analytics capture and session replay recording are **on by default** once the Analytics app is enabled — you do not need to set `analytics.enabled` or `analytics.replays.enabled` unless you want to opt out (pass `analytics: { enabled: false }` or `analytics: { replays: { enabled: false } }`).

After setup, Hexclave automatically captures client-side `$page-view` and `$click` events.

See [Replays & Clickmaps](https://docs.hexclave.com/guides/apps/analytics/replays-and-clickmaps.md) to tune replay privacy or opt out.

### Filtering automatic events

Use `analytics.sanitizeEvent` to transform automatic `$page-view` and `$click` events before the SDK buffers them. Return `null` to discard an event. Use `analytics.ignoreClickSelector` to exclude clicks on matching elements and their descendants.

```ts theme={null}
import { HexclaveClientApp } from "@hexclave/js";

const app = new HexclaveClientApp({
  projectId: "your-project-id",
  publishableClientKey: "your-publishable-client-key",
  tokenStore: "cookie",
  analytics: {
    ignoreClickSelector: ".no-analytics",
    sanitizeEvent(event) {
      if (event.event_type === "$click") return null;
      return { ...event, data: { path: event.data.path } };
    },
    replays: { enabled: false },
  },
});
```

The sanitizer only filters automatic browser events, not session replay recordings or server-side events. Configure replay masking/blocking separately, or disable replay recording as in the example. To stop all SDK-managed analytics capture, set `analytics.enabled` to `false` when constructing the app.

Construct apps with a sanitizer in the client runtime. Functions cannot be serialized across a server/client boundary; the SDK rejects JSON serialization of a sanitizer rather than silently dropping it.

When using an external-auth token store, the SDK skips analytics and replay uploads while signed out instead of creating an anonymous Hexclave user. Later uploads can resume once the external provider supplies a valid session.

### Tracking every page

The client app only records analytics on pages where it is loaded in the browser. If your app only imports `hexclaveClientApp` on pages that use authentication, every other page goes untracked.

To avoid this, call `initAnalytics()` at the top level of a client-side module that every page loads, such as your root layout or entry file:

```ts theme={null}
import { hexclaveClientApp } from "./hexclave/client";

hexclaveClientApp.initAnalytics();
```

In Next.js, the root layout is a server component, so do the call in a client component that you render from `app/layout.tsx`:

```tsx src/components/hexclave-analytics.tsx theme={null}
"use client";

import { hexclaveClientApp } from "@/hexclave/client";

hexclaveClientApp.initAnalytics();

export function HexclaveAnalytics() {
  return null;
}
```

`initAnalytics()` doesn't start anything itself, because capture already starts when the client app is created. Calling it makes sure that the module that creates the client app is loaded on that page.

To catch setup mistakes early, `initAnalytics()` throws if your client app is configured so that it never records analytics: when you pass `analytics: { enabled: false }` or `automaticSideEffects: false`, or when `tokenStore` is `null`. If the Analytics app is not enabled on your project, the SDK logs an error as soon as the first upload is rejected. If you've turned off analytics on purpose, remove the `initAnalytics()` call.

## Tables

The **Tables** screen is the fastest way to inspect recent analytics records.

* Opens on `events` by default; pick other tables from the sidebar
* Built-in ordering and client-side search
* Relative/absolute timestamp display toggle
* Row detail dialog for inspecting full JSON payloads

Use this view when you need to quickly answer "what just happened?" without writing SQL.

## Queries

The **Queries** screen is a ClickHouse SQL workspace for deeper analysis.

* Run read-only SQL queries with a timeout budget
* Query the users and analytics tables
* Save reusable queries into folders
* Re-run saved queries with one click
* Edit and overwrite saved query definitions

## Session Replays

The **Replays** screen helps you move from "an event happened" to "what the user actually saw."

* Filter sessions by user, team, duration, recency, and click count
* Play back multi-tab sessions
* Control playback speed
* Optionally skip inactive ranges
* Jump across click/page-view timeline markers

Use replays when metrics alone are not enough to explain user behavior.

### Replay recording in the SDK

Session replay recording is **enabled by default** once Analytics is on and your client app uses a persistent token store. You can tune privacy or opt out via the `analytics.replays` options:

```ts theme={null}
import { HexclaveClientApp } from "@hexclave/js";

export const hexclaveClientApp = new HexclaveClientApp({
  // ...your existing client app options
  tokenStore: "cookie", // use "nextjs-cookie" in Next.js
  analytics: {
    replays: {
      // Optional. Defaults to true when the Analytics app is enabled; set to false to opt out.
      enabled: true,
      // Optional. Defaults to true.
      maskAllInputs: true,
    },
  },
});
```

`maskAllInputs` defaults to `true`, so form fields are masked unless you explicitly disable it. For the full set of privacy controls, playback, and clickmaps, see [Replays & Clickmaps](https://docs.hexclave.com/guides/apps/analytics/replays-and-clickmaps.md).

### Disabling Analytics Capture in the SDK

SDK-managed analytics capture is enabled by default. You can disable it by disabling the Analytics app in the config or dashboard. If you don't want the SDK to collect any analytics data at all but would like to keep the Analytics app enabled, you can also pass `analytics: { enabled: false }` when creating your client app:

```ts theme={null}
import { HexclaveClientApp } from "@hexclave/js";

export const hexclaveClientApp = new HexclaveClientApp({
  // ...your existing client app options
  tokenStore: "cookie", // use "nextjs-cookie" in Next.js
  analytics: { enabled: false },
});
```

This stops the SDK from sending `$page-view` and `$click` events. If you'd rather keep analytics, enable the Analytics app in your dashboard (**Apps -> Analytics**) instead.

## Best Practices

1. **Use Tables for quick incident triage**: the Tables UI is the fastest way to inspect recent rows (events, users, and more) without writing SQL.
2. **Use Queries for repeatable analysis**: save important SQL in folders, and scope queries with filters/`LIMIT` so they stay within result and timeout limits.
3. **Use Replays for behavioral debugging**: start from an event pattern, then inspect matching session replays to understand what users actually did.
4. **Use Clickmaps for UI friction and attention**: overlay click counts on your live pages to see whether a flow takes unnecessary clicks, whether a control looks interactable, or how variants compare in an A/B test. Clicks are tied to DOM elements (not pixel coordinates), so a marker in the middle of a button does not mean the user clicked the middle of that button. See [Replays & Clickmaps](https://docs.hexclave.com/guides/apps/analytics/replays-and-clickmaps.md).
5. **Keep replay privacy defaults on**: leave `maskAllInputs` enabled unless you have a specific reason and a data-handling policy for unmasked inputs.