> For the complete documentation index, see [llms.txt](https://docs.fullsession.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fullsession.io/7.-recording-rules-and-element-tracking.md).
# 7. Recording Rules & Element Tracking
So far you've been *watching* what FullSession captures. This chapter is about *configuring* it — controlling which pages are recorded, naming and watching the elements that matter to your business, and sending the custom events that show up in the player and power funnels. These settings live in two places: **Settings → Privacy Rules** (what gets recorded) and **Settings → Element Tracking** (which elements you measure). Custom events are added in your site's code.
***
### 7.1 What You Can Configure (Overview)
Before diving in, here's the lay of the land. FullSession separates three related concerns
| Setting | Where | Controls |
| -------------------------------- | --------------------------- | ------------------------------------------------------------------------------ |
| **Page recording rules** | Settings → Privacy Rules | Which **pages/URLs** are recorded (section 7.2) |
| **Element recording rules** | Settings → Privacy Rules | Which **elements are masked or excluded** for privacy (section 7.3) |
| **Named Elements & Watch Rules** | Settings → Element Tracking | Which **elements you measure** in reports, heatmaps, and funnels (section 7.4) |
| **Custom events** | Your website code | Business actions sent via `FUS.event(...)` (section 7.5) |
> **Page rules vs. element rules** — *page* rules decide whether a whole page is recorded at all; *element* recording rules decide whether specific elements on a recorded page are masked or hidden. They work together.
***
### 7.2 Page Recording Rules
By default, FullSession records your site's pages. **Page recording rules** let you change that — either to *exclude* specific pages you don't want recorded, or to record *only* a chosen set of pages.
These are configured under **Settings → Privacy Rules → Page recording rules**.
#### The two modes
A single site-level toggle determines what your rule list *means*:
| Mode | Behavior |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Record all except listed pages** (default) | Every page is recorded **except** the ones your rules match — the list acts as an **exclusion list**. |
| **Exclude all pages** (record only listed) | **No** page is recorded **except** the ones your rules match — the list acts as an **allowlist**. |
So the same rule list flips purpose depending on the mode. Switch to **Exclude all pages** when you want a tightly scoped recording (e.g. only your signup funnel); leave it off when you want to record broadly and only carve out a few sensitive pages.
#### Creating a page rule
1. Click **Create Page Rule**.
2. In the **page** field, paste any URL — *"Put any url and we'll extract the path!"* FullSession extracts just the path (and strips trailing slashes), so you can paste a full address and it figures out the path for you.
3. Choose the matching options:
* **Ignore Query Parameters** — match the path regardless of any `?query=...` string. Turn this on when the same page has many query-string variants you want treated as one.
* **Include sub-paths** — match the path *and everything beneath it*. With this on, a rule for `/account` also covers `/account/settings`, `/account/billing`, and so on.
4. Save.
#### How matching works
Page rules match the **literal path**, refined by the two checkboxes above. Importantly:
> **There are no wildcards or regular expressions.** Matching is the path itself, optionally with query parameters ignored and/or sub-paths included. To cover a whole section of your site, use **Include sub-paths** rather than a `*` pattern.
#### Common recipes
| Goal | Mode | Rule(s) |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------- |
| Never record account pages | Record all except | `/account` with **Include sub-paths** on |
| Ignore checkout query-string noise | Record all except | `/checkout` with **Ignore Query Parameters** on |
| Record only the signup funnel | Exclude all pages | `/`, `/pricing`, `/signup` (add **Include sub-paths** where needed) |
#### Test your rules
After saving, browse the affected pages in an incognito window and confirm in the **Sessions** list (\[Chapter 5 — Sessions]) that the right pages do (and don't) appear. A few minutes of testing prevents weeks of missing — or unwanted — data.
> **Related privacy controls** in the same panel include **IP Address Collection** (on/off) and a **Total Session Length Recording Rule** that caps how long a single session is recorded. See \[Chapter 21 — Privacy, Security & Compliance].
***
### 7.3 Element Recording Rules (Masking & Exclusion)
Where page rules decide *which pages* record, **element recording rules** decide whether specific *elements* on a recorded page are captured, masked, or hidden — the core of protecting sensitive content. These live under **Settings → Privacy Rules → Element recording rules**.
#### What a rule does
Each rule targets elements by **CSS selector** and applies one of three actions:
| Action | Effect |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Exclude** | Fully block the element from recording — it isn't captured at all. |
| **Mask** | Capture the element's presence but hide its **content** (e.g. show that a field exists without recording what was typed). |
| **Unmask** | Explicitly *re-enable* capture for something inside a masked region — an exception to a broader mask. |
Each rule also has a **scope** — **Live Sessions** (active, applied to new sessions) or **No Sessions (inactive)** (the rule exists but isn't applied) — plus optional **notes** and an **exception selector**.
#### Built-in protections
FullSession ships with sensible defaults already in place, so common sensitive fields are protected out of the box — including **password fields** (`input[type=password]`), **hidden inputs** (`input[type=hidden]`), and **credit-card fields** (`[autocomplete*=cc-]`). You can add your own rules for anything else specific to your site.
> This section is a summary; masking, privacy, and compliance are covered in full in \[Chapter 21 — Privacy, Security & Compliance].
***
### 7.4 Element Tracking: Named Elements & Watch Rules
To *measure* the specific elements that matter — your CTAs, nav links, key buttons — use **Element Tracking** under **Settings → Element Tracking**. There are two complementary tools.
#### Named Elements (Labels)
A **Named Element** attaches a human-readable name to an element (or group of elements), so it appears clearly in **click reports** and **funnels** instead of as a raw selector.
A named element consists of:
* **Name** — the friendly label (e.g. *"Hero CTA – Start trial"*).
* **Description** — optional context.
* **Selectors** — one or more **CSS selectors** identifying the element(s).
> *"Assign human-readable names to tracked elements so they appear clearly in click reports and funnels."*
Use named elements whenever you want a specific element to be recognizable in your analytics — they turn `button.btn-primary.cta-xl` into *"Start trial."*
#### Watch Rules
A **Watch Rule** tells FullSession to **log and surface interactions** on specific elements across **all** recorded sessions — feeding heatmaps and element-level reporting.
> *"Define rules to log and surface interactions on specific elements across all recorded sessions."*
A watch rule consists of:
* **Name** and optional **description**.
* A **selector definition** that targets the element by any combination of:
* **Element/tag** (e.g. `button`)
* **ID**
* **Classes**
* An optional **parent relationship** — match only when the element sits under a given parent, either as a **direct** child or **any** descendant.
This structured targeting lets you be as broad ("all buttons with class `cta`") or as precise ("the `Apply` button directly inside the `coupon-form`") as you need.
#### How tracked elements feed reports
* **Named Elements** provide the labels that make click data and funnel steps readable.
* **Watch Rules** identify which elements' interactions are logged and surfaced — these power **element heatmaps** and the interaction reporting in \[Chapter 8 — Heatmaps].
#### Selectors are entered as text
> **There is no visual point-and-click element picker.** Named Elements and Watch Rules are defined by entering **CSS selectors** (or the structured selector definition). To get a reliable selector, inspect the element in your browser's developer tools and copy a stable selector.
**Tips for durable selectors:**
* Prefer a stable **id** or a dedicated attribute over auto-generated class names.
* Avoid deep, brittle chains like `div > div > div:nth-child(3) > button` — they break when your layout shifts.
* Coordinate with engineering to add stable hooks (e.g. a consistent class or attribute) to important elements.
> **Tip** — if a tracked element's click metrics suddenly drop to zero, a markup change likely broke its selector. Update the selector in the Named Element or Watch Rule.
***
### 7.5 Custom Events with `FUS.event`
A **custom event** is a named action meaningful to *your* product — *purchase*, *plan upgraded*, *search performed*. Custom events appear in the session player's events list (\[Chapter 6, section 6.3]) and are the building blocks of funnels, segments, and insight cards.
> **Custom events are code-only.** There is no UI for creating "no-code" custom events from a click or page visit — you send them from your website code with `FUS.event(...)`. (To *measure clicks* on an element without code, use a **Watch Rule** / **Named Element**, section 7.4.)
#### The method
```javascript
window.FUS.event(eventName, eventData);
```
* **`eventName`** *(string, required)* — the event name.
* **`eventData`** *(object, required)* — a **non-empty** object of properties whose values are strings or numbers.
```javascript
window.FUS.event('purchase', { amount_real: 99.99, product: 'Widget' });
```
#### Validation rules
FullSession validates every event and **rejects invalid ones** (it throws a descriptive error listing what's wrong), so getting the format right matters:
| Rule | Detail |
| -------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Event name is a string** | Required. |
| **No hyphens in the event name** | `'user-action'` is rejected — use `'user_action'`. |
| **`eventData` is a non-empty object** | An empty object `{}` or an array `[]` is rejected. |
| **No hyphens in property keys** | `{'event-type': ...}` is rejected. |
| **Values are strings or numbers only** | No booleans, objects, or arrays as values. |
| **Default type is string** | A key with no type suffix is treated as a **string** — passing a number to it is rejected. |
| **`_str` suffix → string** | A key ending in `_str` is validated as a string. |
| **`_real` suffix → number** | A key ending in `_real` is validated as a (finite) number. |
| **Numbers must be finite** | `Infinity` and `NaN` are rejected. |
#### The `_str` / `_real` convention
This is the part teams most often miss: because the **default value type is string**, you must use the **`_real` suffix** to send a number.
```javascript
// ✅ VALID
window.FUS.event('purchase', { amount_real: 99.99, product: 'Widget' });
window.FUS.event('login', { username_str: 'john' });
// ⛔ INVALID
window.FUS.event('user-action', {}); // hyphen in event name (and empty data)
window.FUS.event('action', { 'event-type': 'click' }); // hyphen in a key
window.FUS.event('action', {}); // empty eventData
window.FUS.event('action', []); // eventData is an array
window.FUS.event('purchase', { amount: 99.99 }); // number sent to a string-typed key — use amount_real
```
In that last example, `amount` has no suffix, so FullSession expects a string and rejects the number — the error even suggests using `amount_real`. Switching to `amount_real: 99.99` makes it valid.
#### Naming events well
Your event names appear across the player, funnels, segments, and dashboards, so name them deliberately:
* Use **clear, human names** — `purchase`, `plan_upgraded`, `search_performed`.
* Use a **consistent style** (and remember: **underscores, never hyphens**).
* **Don't rename** an event after collecting data — it splits your history.
* Keep a **shared list** of event names so teammates reuse rather than duplicate them.
#### What custom events unlock
Once events are flowing, you can:
* See them in the **session player** events list (\[Chapter 6]).
* Build **funnels** from them (\[Chapter 12 — Funnels]).
* Define **segments** around them (\[Chapter 11 — Segments]).
* Chart them as **insight cards** (\[Chapter 10 — Insights & Cards]).
> **The big picture** — **page recording rules** decide which pages record (literal paths, with ignore-params and include-sub-paths, switched between exclude-list and allowlist modes); **element recording rules** mask or exclude sensitive elements; **Named Elements and Watch Rules** (CSS selectors, no visual picker) decide which elements you measure in heatmaps and funnels; and **custom events** — sent only via `FUS.event` with the `_str`/`_real`, no-hyphen, non-empty rules — translate your interactions into business actions.
***
> **Next up:** \[Chapter 8 — Heatmaps] takes the Named Elements and Watch Rules you configured here and visualizes them in aggregate — showing where visitors click, how far they scroll, and which tracked elements draw the most interaction.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.fullsession.io/7.-recording-rules-and-element-tracking.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.