# Clerion documentation, complete

Every page of the Clerion docs in one file. Each section is also served on its own at the address beside it.

- [Clerion documentation](https://getclerion.com/docs.md)
- [Quickstart](https://getclerion.com/docs/quickstart.md)
- [Install on your platform](https://getclerion.com/docs/install.md)
- [Import your history](https://getclerion.com/docs/import-history.md)
- [Check your installation](https://getclerion.com/docs/check-installation.md)
- [Custom events](https://getclerion.com/docs/custom-events.md)
- [Revenue by source](https://getclerion.com/docs/revenue-by-source.md)
- [Exit question](https://getclerion.com/docs/exit-question.md)
- [Rage clicks](https://getclerion.com/docs/rage-clicks.md)
- [Deploy markers](https://getclerion.com/docs/deploy-markers.md)
- [MCP server](https://getclerion.com/docs/mcp.md)
- [Script tag](https://getclerion.com/docs/script-tag.md)
- [JavaScript API](https://getclerion.com/docs/javascript-api.md)
- [Configuration options](https://getclerion.com/docs/configuration.md)
- [Consent banner](https://getclerion.com/docs/consent-banner.md)
- [Dashboard filters](https://getclerion.com/docs/filters.md)
- [Export and data retention](https://getclerion.com/docs/export-and-retention.md)

---

# Clerion documentation

> How to set up Clerion, track what matters on your site, and use every feature: install, custom events, revenue by source, exit question, deploys, rage clicks, MCP.

Clerion is website intelligence for AI founders: web analytics, AI-assistant traffic, conversions and revenue by source, SEO and AI-readiness, speed and errors from one script tag. It finds the patterns in the data, ranks what changed and tells you the fix. These docs cover how to set it up and how each feature works.

New here? Start with the [Quickstart](https://getclerion.com/docs/quickstart): an account, one line in your site's head, and the dashboard fills in from your first visitor.

## Getting started

| Page | What it covers |
|---|---|
| [Quickstart](https://getclerion.com/docs/quickstart) | Create an account, paste the snippet, read the first briefing. |
| [Install on your platform](https://getclerion.com/docs/install) | Where the line goes on WordPress, Shopify, Webflow, Squarespace, Wix, Next.js and the rest. |
| [Import your history](https://getclerion.com/docs/import-history) | Bring Google Analytics 4 history across, so the briefing has something to say on day one. |
| [Check your installation](https://getclerion.com/docs/check-installation) | Confirm visits are arriving, and what to do when they are not. |

## Tracking

| Page | What it covers |
|---|---|
| [Custom events](https://getclerion.com/docs/custom-events) | Count signups, purchases and anything else with one call or one attribute. |
| [Revenue by source](https://getclerion.com/docs/revenue-by-source) | See which source brings paying customers, ChatGPT included. |

## Visitor insight

| Page | What it covers |
|---|---|
| [Exit question](https://getclerion.com/docs/exit-question) | Ask visitors about to leave a page why, once, from five answers. |
| [Rage clicks](https://getclerion.com/docs/rage-clicks) | Find the elements people click again and again. |

## Releases

| Page | What it covers |
|---|---|
| [Deploy markers](https://getclerion.com/docs/deploy-markers) | Mark each deploy from CI and see what it did to errors and conversion. |

## Integrations

| Page | What it covers |
|---|---|
| [MCP server](https://getclerion.com/docs/mcp) | Let Claude, Cursor or any MCP client read your analytics. |

## Reference

| Page | What it covers |
|---|---|
| [Script tag](https://getclerion.com/docs/script-tag) | Every attribute the snippet reads. |
| [JavaScript API](https://getclerion.com/docs/javascript-api) | The methods on `window.clerion`. |
| [Configuration options](https://getclerion.com/docs/configuration) | Every option when you start the tracker yourself. |
| [Consent banner](https://getclerion.com/docs/consent-banner) | Optional, one tag, remembers the visitor's choice. |
| [Dashboard filters](https://getclerion.com/docs/filters) | Click to filter, and filters in the page address. |
| [Export and retention](https://getclerion.com/docs/export-and-retention) | CSV or JSON out, how long data is kept, how to delete it. |

## Copy a page

Every page has a Copy page as Markdown button, and is served as plain Markdown at its address plus `.md`. The whole manual is one file at [/docs/everything.md](https://getclerion.com/docs/everything.md), for pasting into an assistant.

---

Source: https://getclerion.com/docs (Clerion docs, Getting started). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Quickstart

> Create an account, paste one script tag, optionally import your Google Analytics history, and read the first briefing. About a minute, no cookie banner.

Create an account, paste one script tag into your site's head, and the dashboard fills in from your first visitor. There is no cookie banner to add, no event plan to write, and nothing is charged for 14 days.

## Before you start

You need an email address you can confirm a link on, and somewhere to paste one line into your site's head. If you have a Google Analytics 4 export, keep it nearby: [Import your history](https://getclerion.com/docs/import-history) reads it into the new dashboard. Every account starts on the 14-day trial at Growth level, with every feature on.

## 1. Create your account

[Sign up](https://app.getclerion.com/signup) with email and a password, or with Google, then confirm the link we email you. Pick a plan and add a card. The exact amount and the date it would be charged are shown before you confirm, and cancelling inside the 14 days charges nothing.

Vesper, a worked example store, is on the account from day one, so there is a full dashboard and a real briefing to read before your own site has data.

## 2. Paste the snippet

Copy the tag from your dashboard and paste it once inside the head of every page you want counted. The version below has placeholders; the copy in your dashboard carries your real key and site id.

```html
<script
  src="https://api.getclerion.com/sdk/clerion-analytics.js"
  data-api-key="YOUR_API_KEY"
  data-website-id="YOUR_WEBSITE_ID"
></script>
```

It loads deferred, so it never slows the page, and it sets no cookies. Where exactly it goes depends on your platform: see [Install on your platform](https://getclerion.com/docs/install).

## 3. Read the first briefing

Open the Overview. With an import, Clerion writes a briefing straight away. Without one, it works from your first visitor and gets sharp once it has about a week of data, rather than guessing from a day of noise. Every claim in a briefing clicks through to the sessions behind it.

To confirm visits are arriving, see [Check your installation](https://getclerion.com/docs/check-installation).

## What is tracked automatically

Nothing below needs configuration.

| Area | What is counted |
|---|---|
| Traffic | Pageviews, sessions, visitors, entry and exit pages, referrers, campaigns and site search. |
| Behaviour | Clicks, scroll depth, active time, forms, outbound links and file downloads. |
| AI assistants | Referrals from ChatGPT, Perplexity, Claude, Gemini and Copilot as their own channel. |
| Speed | Load time, first paint and time to interactive, scored against Core Web Vitals. |
| Errors | JavaScript exceptions and console errors, grouped by page and severity, with the visitor's last actions. |
| Frustration | [Rage clicks](https://getclerion.com/docs/rage-clicks): three or more fast clicks on one element. |
| SEO | Titles, headings, meta tags, canonicals, Open Graph and schema on every page, for the site audit. |
| Bots | Crawlers detected and excluded from your numbers, and never counted toward billing. |

## Next steps

- Count the moments that matter to you with [Custom events](https://getclerion.com/docs/custom-events).
- See which channel brings customers with [Revenue by source](https://getclerion.com/docs/revenue-by-source).
- Mark releases from CI with [Deploy markers](https://getclerion.com/docs/deploy-markers).

---

Source: https://getclerion.com/docs/quickstart (Clerion docs, Getting started). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Install on your platform

> Where the Clerion snippet goes on WordPress, Shopify, Webflow, Squarespace, Wix, Next.js and React, and any other site, plus Tag Manager and Content Security Policy.

Clerion needs one line in the head of every page you want counted. It works on any site that lets you add to its HTML head. Copy the line from your dashboard; it carries your real key and site id.

## Plain HTML

Paste it anywhere inside `<head>` on every page. It loads deferred, so it never slows the page.

## WordPress

Paste it into your theme's `header.php` just before `</head>`, or use any header-scripts plugin if you would rather not touch theme files. A child theme is the safer home, since a parent theme update can overwrite `header.php`.

## Shopify

Open Online Store, Themes, Edit code, then `layout/theme.liquid`, and paste it just before `</head>`. It loads on every storefront page your theme controls.

## Webflow

Go to Project settings, Custom code, paste it into Head code, then publish. Webflow applies it site-wide, so one paste covers every page.

## Squarespace

Use Settings, Advanced, Code injection, Header. It applies to every page.

## Wix

Use Settings, Custom code, and add it to Head on all pages.

## Next.js and React

Put it in your root layout's head, or render it with `next/script` using the `afterInteractive` strategy:

```tsx
import Script from "next/script";

<Script
  src="https://api.getclerion.com/sdk/clerion-analytics.js"
  data-api-key="YOUR_API_KEY"
  data-website-id="YOUR_WEBSITE_ID"
  strategy="afterInteractive"
/>
```

Client-side route changes are counted as pageviews, so a single-page app behaves like any other site. Vue, Nuxt, Svelte and other frameworks work the same way: one tag in the document head.

## Anything else

Framer, Ghost, Astro, Hugo, Laravel, Rails, Django and hand-written HTML all work. If you can add one line to the head, you can run Clerion.

## Google Tag Manager

You can load Clerion through Tag Manager, but we would rather you did not. Ad blockers block the tag manager itself on a large share of devices, so loading Clerion through it hands back the accuracy you installed Clerion to get. Paste the line directly instead.

## Content Security Policy

Only a strict CSP needs a change. Allow the Clerion script source and its collection endpoint in your `script-src` and `connect-src` directives. The exact hosts are shown with your snippet in the dashboard.

## One snippet per page

Keep the line on each page once. Two copies on a page count every visit twice; see [Check your installation](https://getclerion.com/docs/check-installation) if your numbers look too high.

---

Source: https://getclerion.com/docs/install (Clerion docs, Getting started). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Import your history

> Bring your Google Analytics 4 history into Clerion during setup, so the first briefing has something true to say on day one. Parsed in your browser, never uploaded.

Importing is optional. Export your reports from Google Analytics 4 and drop the file in during setup, and Clerion writes its first briefing as soon as the import lands, instead of waiting for a week of new data.

## Import from Google Analytics 4

1. In Google Analytics 4, export your reports as CSV.
2. In Clerion's setup, drop the file in when it asks for your history.
3. The imported days appear on the Overview chart as their own hatched series, and the briefing reads them.

## What is sent

The file is parsed in your browser and never leaves your machine. Only aggregates and capped top lists are sent to Clerion: up to about two years of daily totals and ten years of monthly totals, with the top pages and sources.

| Detail | |
|---|---|
| Imports per site | One. A new import replaces the old one. |
| Deleting | An import can be deleted whenever you want. |
| Visitor data | None. Only daily and monthly totals and capped top lists. |

## Coming from another tool

Exports from Plausible, Fathom, Matomo, Simple Analytics and Umami are recognised. From those or anything else, ask priority support inside the app and we bring the history across for you.

## How the briefing uses it

Imported history is shown and read alongside what Clerion tracks itself. The briefing says which claims come from imported history and which from live tracking, and never mixes the two in one comparison.

---

Source: https://getclerion.com/docs/import-history (Clerion docs, Getting started). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Check your installation

> Confirm Clerion is counting visits, watch events in the console with debug mode, and fix the two common problems: nothing arriving, or numbers too high.

The quickest check is to visit your own site in another tab. The live pulse on the dashboard updates every 30 seconds, so your visit shows up almost at once.

## Watch events in the console

Add `data-debug="true"` to the snippet and the browser console logs each batch of events as it is sent, a few seconds after the last one, along with any error the tracker hits:

```html
<script src="https://api.getclerion.com/sdk/clerion-analytics.js"
  data-api-key="YOUR_API_KEY" data-website-id="YOUR_WEBSITE_ID"
  data-debug="true"></script>
```

Remove it when you are done; it changes nothing that is counted.

## Nothing is arriving

| Check | Why |
|---|---|
| The snippet is inside `<head>` on the page you loaded | A page without it is not counted. |
| It is not loaded through a tag manager | Ad blockers block tag managers, and the tag never runs. |
| Your browser is not set to ignore you | Clerion does not count visits from browsers with Global Privacy Control or Do Not Track turned on. |
| You did not opt your own device out | Running `localStorage.setItem('clerion_ignore', 'true')` in the console leaves that browser uncounted on purpose. Remove the key to be counted again. |

Still nothing? Ask Clerion in the app and the AI walks through the likely causes with you. Priority support is one panel away.

## Numbers are too high

The snippet is probably on a page twice, for example once in the theme and once from a plugin. Keep one per page, remove the duplicate, and counts settle from the next visitor onward.

## Leave your own visits out

Run this once in the browser console on each device you use, on your own site:

```js
localStorage.setItem("clerion_ignore", "true");
```

Visits from that browser are no longer counted. Automated browsers, such as link previewers and crawlers driving headless Chrome, are never counted either.

---

Source: https://getclerion.com/docs/check-installation (Clerion docs, Getting started). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Custom events

> Record a signup, purchase or any conversion with one call or one HTML attribute, attach a value and currency, and read completions, conversion rate and revenue on the Custom events page.

A custom event in Clerion is one line of JavaScript or one HTML attribute. Call `window.clerion.trackEvent("signup")` when the thing you care about happens, or put `data-track-event="signup"` on the button that triggers it. Every event name Clerion does not already track becomes a goal on its own, with uniques, completions, conversion rate and summed value on the Custom events page. There is nothing to define in the dashboard first.

This page covers the two ways to send an event, how to attach revenue, what the Custom events page shows, the limits, and the mistakes that make counts look wrong.

## Before you start

The one-line snippet must already be on the page. It creates the tracker as `window.clerion` once the page has loaded, and everything below uses that object. If you have not installed it yet, [set up Clerion](https://getclerion.com/docs/quickstart) first.

Pageviews, sessions, clicks, scroll depth, forms, outbound links, file downloads and Core Web Vitals are collected without any of this. Custom events are for the moments that mean something specific to your product: a signup, a trial start, a purchase, a plan upgrade, a feature used for the first time.

## Send an event from JavaScript

Call `trackEvent` with a name and, optionally, an object of details.

```js
window.clerion.trackEvent("signup");

window.clerion.trackEvent("purchase", {
  value: 49,
  currency: "USD",
  plan: "starter",
});
```

The name is the goal. Keep it short, lowercase, and stable, in the style of the built-in names: `signup`, `trial_start`, `purchase`, `upgrade`, `waitlist_join`. Renaming an event later starts a new goal; the old one keeps its history under the old name.

Everything in the second argument is stored with the event and comes back in exports. Three keys have meaning in the dashboard:

| Key | What it does |
|---|---|
| `value` | Added to the goal's summed value. `orderValue` and `revenue` are accepted as aliases. Numbers or numeric strings. |
| `currency` | Shown next to the value. If a goal sees more than one currency, the most common one is displayed. |
| `path` | Overrides the page the event is attributed to. By default it is the current page. |

Clerion adds the page, referrer, device, UTM parameters, landing page, language and timezone to every event itself, so you do not need to send them.

### Fire it at the right moment

Send the event when the conversion has actually happened, not when the user clicks the button that starts it. For a signup, that is the page after the form succeeds, or the success callback of your request:

```js
async function submitSignup(form) {
  const res = await fetch("/api/signup", { method: "POST", body: new FormData(form) });
  if (res.ok) window.clerion.trackEvent("signup", { plan: form.plan.value });
}
```

### Make sure the tracker exists

The snippet creates `window.clerion` when the DOM is ready. Code that runs earlier, such as an inline script above the snippet, will find it undefined. Two safe patterns:

```js
// Only fire if the tracker is present. Nothing breaks if it is not.
window.clerion?.trackEvent("signup");

// Or wait for the page to load first.
window.addEventListener("load", () => window.clerion.trackEvent("signup"));
```

In a single-page app, call `trackEvent` from the same place you handle the result of the action. Route changes are already counted as pageviews.

### In React, Next.js or another framework

The tracker is a global, so call it from wherever the outcome is known. In a React component:

```tsx
async function onSubmit(form: SignupForm) {
  const res = await fetch("/api/signup", { method: "POST", body: JSON.stringify(form) });
  if (res.ok) window.clerion?.trackEvent("signup", { plan: form.plan });
}
```

In Next.js the snippet goes in the root layout with `next/script` (see [Install on your platform](https://getclerion.com/docs/install)); the call above is unchanged. Route changes are counted as pageviews on their own.

For TypeScript, declare the global once:

```ts
// clerion.d.ts
declare global {
  interface Window {
    clerion?: {
      trackEvent(name: string, details?: Record<string, unknown>): void;
      trackPageView(path?: string, details?: Record<string, unknown>): void;
      setConsentStatus(granted: boolean): void;
    };
  }
}
export {};
```

## Send an event from HTML

For a click you want to count, add an attribute to the element. No JavaScript needed.

```html
<a href="/pricing" data-track-event="pricing_click">See pricing</a>

<button data-track-event="demo_request" data-track-data='{"source":"hero"}'>
  Book a demo
</button>
```

When the element is clicked, Clerion records an event with that name. Anything in `data-track-data` must be valid JSON; it is stored under `customData` with the event. The element's tag, id, classes and position are recorded as well; its text is not, because page copy is content, not analytics.

Use this for clicks. For anything that depends on a result, such as a form succeeding or a payment completing, use the JavaScript call so you count the outcome rather than the attempt.

## Read the results

Open the site in Clerion and go to Behavior, then Custom events. Every custom event name appears as a row in All events, with:

- **Uniques.** Sessions in which the event fired at least once.
- **Completions.** Total times it fired.
- **Conversion rate.** Uniques divided by all sessions in the selected date range.
- **Value.** The sum of `value` across completions, with the currency.

The list respects the date range and every filter on the dashboard, so clicking a country, a referrer or a page filters the goals to those sessions too. That is how you compare the conversion rate of visitors from ChatGPT against visitors from search.

Under the table, the Where paying customers came from card uses the same values. Each payment is credited to the source of the visit it came from, with visitors, payers, pay rate and revenue per source. [Revenue by source](https://getclerion.com/docs/revenue-by-source) covers how it is counted.

Events arrive within seconds. The tracker batches events and sends them five seconds after the last one, or immediately when the page is hidden or closed, and the dashboard's live figures refresh every 30 seconds.

## Names that will not become goals

Clerion's own event names are excluded from All events because they describe behaviour rather than conversions. Do not reuse them for your own events:

`page_view`, `page_details`, `session_start`, `session_end`, `scroll_depth`, `click`, `time_on_page`, `error`, `outbound_link`, `file_download`, `performance`, `site_details`, `form_focus`, `form_submit`, `product_view`, `add_to_cart`, `remove_from_cart`, `checkout_start`, `search`, `banner_click`, `category_click`, `filter_apply`, `sort_change`, `wishlist_add`, `wishlist_remove`, `rage_click`, `exit_answer`.

The commerce names in that list have their own helpers and feed the ecommerce funnel instead:

```js
window.clerion.trackProductView(productId, productName, { price: 89 });
window.clerion.trackAddToCart(productId, productName, quantity, price);
window.clerion.trackCheckoutStart(products, orderValue);
window.clerion.trackSearch(query, resultCount);
```

The funnel view reports sessions to product views to cart adds to checkouts, with the conversion rate at each step. A completed purchase is not a built-in name, so track it as a custom event with a value.

## Limits

- Details on one event are capped at 5 KB. Larger payloads are rejected with a 413 and the event is not stored.
- Strings are truncated at 500 characters, arrays at 50 items, nesting at 5 levels, and keys at 100 characters.
- Up to 100 events per batch. The tracker manages batching for you.
- Do not put personal data in event details. Clerion stores no personal data by default, and your events should keep it that way. A plan name is fine; an email address is not.

## When the numbers look wrong

**The goal does not appear.** Check the name is not on the built-in list above, and that `window.clerion` existed when you called it. Add `data-debug="true"` to the snippet and the browser console logs each batch of events as it is sent.

**Completions are higher than uniques by a lot.** The event fires more than once per session, often because it is attached to a click rather than a result, or the page it fires on is reloaded. Move the call to the success path.

**Counts are lower than you expect.** If you initialise the tracker yourself with a `samplingRate` below 1, custom events are dropped for visitors outside the sample. Leave sampling at the default of 100 percent for anything you count as a conversion. Also check for ad blockers on your own devices when testing; the snippet is rarely blocked, but a blocked test session is a common false alarm.

**Value is missing.** Send `value` as a number, not a formatted string like `"$49.00"`. Numeric strings such as `"49"` are accepted; anything with a currency symbol is ignored.

## Questions

### Do I need to create the goal in the dashboard first?
No. Any event name that is not one of Clerion's built-in names appears the first time it arrives.

### Can I track revenue?
Yes. Pass `value` and `currency` in the event details. All events sums the value per event and shows the currency next to it, and the Where paying customers came from card shows which sources brought those payers.

### Does this work without a cookie banner?
Yes. Custom events are recorded in cookieless mode like everything else. No personal data is attached to them.

### Can I filter conversions by traffic source?
Yes. Click any referrer, country, page or device in the dashboard and the list narrows to those sessions, so you can see the conversion rate for visitors from ChatGPT, search or a campaign side by side. Plans and limits are at [/pricing](https://getclerion.com/pricing), and the wider setup is covered in the [Quickstart](https://getclerion.com/docs/quickstart).

---

Source: https://getclerion.com/docs/custom-events (Clerion docs, Tracking). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Revenue by source

> Send a value with the event that means someone paid, and Clerion shows visitors, payers, pay rate and revenue for each source, AI assistants included.

Clerion shows which traffic source brings paying customers once your site sends one custom event with a value at the moment someone pays, for example `window.clerion.trackEvent("purchase", { value: 49, currency: "USD" })`. The Custom events page then has a card called Where paying customers came from, with visitors, payers, pay rate and revenue for every source, ChatGPT and the other assistants included. There is nothing to switch on in the dashboard.

[Revenue by source in Clerion: the cursor runs down the sources to chatgpt.com, the one with the highest pay rate, then down to why visitors left the checkout](/product/clips/customers.mp4 "clip")

## Before you start

The Clerion snippet must be on every page a buyer passes through, including the page where the payment is confirmed. If it is not installed yet, [set up Clerion](https://getclerion.com/docs/quickstart) first.

You need one event that fires when money actually changes hands: a purchase, a subscription started, an upgrade. If you already send that event without a value, add the value and the card fills in from then on.

## Send the payment event with a value

Fire the event on the confirmation page, or in the success callback of your checkout, and pass the amount:

```js
window.clerion.trackEvent("purchase", {
  value: 49,
  currency: "USD",
});
```

For a subscription, send the first payment:

```js
window.clerion.trackEvent("subscription_started", { value: 29, currency: "USD", plan: "growth" });
```

The amount can sit in `value`, `orderValue` or `revenue`, as a number or a numeric string such as `"49"`. A formatted string like `"$49.00"` is ignored. If one site takes more than one currency, the card shows the one seen most often, and amounts are summed as they arrive, without conversion.

On a confirmation page that is rendered after the payment, read the amount from the page and send it once:

```html
<!-- /thank-you, rendered by your server with the order in it -->
<script>
  window.addEventListener("load", () => {
    window.clerion?.trackEvent("purchase", { value: 49, currency: "USD", order: "A1042" });
  });
</script>
```

In a React or Next.js app, send it from the success state, once:

```tsx
useEffect(() => {
  if (order.status === "paid") window.clerion?.trackEvent("purchase", { value: order.total, currency: order.currency });
}, [order.status]);
```

If your checkout is hosted elsewhere, for example by a payment provider, send the event on the page the provider returns the buyer to. Include the amount yourself; Clerion does not read it from the provider.

You can also use the HTML attribute instead of JavaScript. The full reference for events is in [How to track custom events and conversions in Clerion](https://getclerion.com/docs/custom-events).

## Read the card

Open your site, go to Behavior, then Custom events, and scroll below All events. Where paying customers came from lists every source that sent visitors in the selected period:

| Column | What it means |
|---|---|
| Source | Where the visitor came from: an assistant such as chatgpt.com or perplexity.ai, a referring site, or Direct. |
| Visitors | People who arrived from that source in the period. On the cookie-free setup each visit counts on its own. |
| Paid | How many of them sent an event with a value above zero. |
| Pay rate | Paid as a share of Visitors. |
| Revenue | The sum of their payments, in the site's most common currency. |

The bar behind each source is its share of the period's revenue. The source at the top is the one that brought the most money, which is often not the one that brought the most visitors.

The same figures reach your briefing and Ask Clerion. A question such as "which channel brings paying customers?" is answered from them.

## How a payment is credited

Clerion credits each payment to a source in one of two ways, depending on whether it can recognise the visitor on a later visit.

| Your setup | Who a payment is credited to |
|---|---|
| Default, cookie-free (no consent banner) | The source of the visit in which the payment happened. Clerion keeps no identifier between visits, so a visitor who came from ChatGPT on Monday and paid after typing your address on Friday counts under Direct. |
| Consent banner on, and the visitor accepted | The source of that visitor's first visit in the selected period, across visits, for up to a year after they accepted. |

Assistants are recognised even when they hide the referrer, from links tagged with `utm_source`, `ref` or `source` naming the assistant. Other tagged links, such as a newsletter, are counted by their referrer here; their full breakdown is under Campaigns.

## Limits

| Limit | What it means for you |
|---|---|
| First touch inside the period | A customer whose first visit was before the selected range is credited to their first visit inside it. Widen the range to look further back. |
| Payments in the browser only | The payment has to be sent from a page with the snippet. Clerion does not connect to Stripe or another provider, so it shows what your events report, not MRR, churn or refunds. |
| A page view is needed | A payment from someone with no page view in the period has no source to credit, and is left out of the card. |
| Very busy sites | The card reads up to 150,000 events per site for the range. Above that it says so, and a shorter range can bring it back. |

## If the card says to pass a value

The card shows a hint instead of a table when no event in the period carried a value above zero. Check three things:

1. The event fires after the payment succeeds, not when the buy button is clicked.
2. The amount is a number or a plain numeric string, not `"$49.00"`.
3. The page that fires it has the snippet, and the event shows up in the All events table above.

## Questions

### Does this work without a cookie banner?

Yes. On the default cookie-free setup each payment is credited to the source of the visit it happened in. The consent banner only adds following a visitor across visits.

### Can I see ChatGPT revenue on its own?

Yes. chatgpt.com, perplexity.ai, claude.ai, gemini.google.com and the other assistants each have their own row, with their own pay rate and revenue.

### Why does Direct have so much revenue?

On the cookie-free setup, people who come back by typing your address or from a bookmark to pay count as Direct, because the visit that paid had no referrer. Turning on the consent banner credits accepted visitors to their first visit instead.

### Is this the same as the value in the All events table?

The total is the same money. All events sums it per event name; this card splits it by where the payers came from.

---

Source: https://getclerion.com/docs/revenue-by-source (Clerion docs, Tracking). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Exit question

> Add one attribute to the Clerion snippet and visitors about to leave a page you choose are asked why, once, from five answers. Set up, read and limits.

To ask visitors why they leave, add `data-exit-question` to your Clerion snippet with the pages you care about, for example `data-exit-question="/pricing,/signup"`. When a visitor on one of those pages moves to leave, after at least five seconds there, a small card asks "Before you go, what stopped you?" with five answers. Each visitor is asked once per page, and the answers appear on the Custom events page and in your briefing.

[Clerion's Custom events page: revenue by source, then the answers visitors gave for leaving the checkout, led by too expensive](/product/clips/customers.mp4 "clip")

## Before you start

The Clerion snippet must already be on the pages you want to ask on. If it is not, [set up Clerion](https://getclerion.com/docs/quickstart) first. The question uses the snippet that is already there; there is no second script.

Pick the pages where leaving costs you something: pricing, signup, checkout, a product page that gets traffic and few sales. Asking on every page tells you less, because a visitor reading your blog and leaving is usually done, not stuck.

## Add the attribute

Add `data-exit-question` to the script tag you pasted, with the paths separated by commas:

```html
<script src="https://api.getclerion.com/sdk/clerion-analytics.js"
  data-api-key="cle_..." data-website-id="site_..."
  data-exit-question="/pricing,/signup"></script>
```

Keep your own `data-api-key` and `data-website-id`; only the last attribute is new. Paths match like this:

| You write | It asks on |
|---|---|
| `/pricing` | Exactly /pricing |
| `/docs/*` | Every page whose path starts with /docs/ |
| `*` | Every page |

In Next.js, the same attribute goes on the `Script`:

```tsx
<Script
  src="https://api.getclerion.com/sdk/clerion-analytics.js"
  data-api-key="YOUR_API_KEY"
  data-website-id="YOUR_WEBSITE_ID"
  data-exit-question="/pricing,/signup"
  strategy="afterInteractive"
/>
```

Publish the change. There is nothing to turn on in the dashboard.

## What the visitor sees

A small white card in the bottom right corner with the question and five answers:

- Too expensive
- Not sure what it does
- Missing a feature
- Something broke
- Just looking

One click sends the answer and the card thanks them and closes. The close button or the Escape key dismisses it without an answer.

It appears when the pointer leaves the window through the top, which is what people do on the way to the tab bar or the back button, and only after five seconds on the page, so nobody is asked on arrival.

## Read the answers

Open your site, go to Behavior, then Custom events. The card Why visitors left lists each page that has answers, with how many people answered and the share of each answer, most common first.

When one answer dominates a page, it usually explains the drop-off there better than any metric. Too expensive on pricing is a pricing conversation; Not sure what it does on pricing is a copy problem on the pages before it.

The answers also reach your briefing and Ask Clerion, so "why do people leave the pricing page?" is answered with what visitors said.

## Limits

| Limit | What it means for you |
|---|---|
| Desktop only | Phones have no leaving gesture to read, so phone visitors are never asked. |
| Once per visitor per page | Remembered in the visitor's browser. A dismissed card counts as asked. If the browser blocks storage, the visitor is not asked at all. |
| Five fixed answers | There is no free text, which keeps it to one click and keeps the answers comparable. |
| Only when tracking runs | Visitors with Global Privacy Control or Do Not Track on, or who declined the consent banner, are not asked. |
| Not a goal | Answers are recorded as `exit_answer`, which never shows up as a custom event or a conversion. |

## If nobody is being asked

1. Check the attribute is on the script tag the page really loads, and the path matches the page exactly, including any trailing part such as `/pricing/annual`.
2. Test on a desktop browser: stay on the page for five seconds, then move the pointer up past the top of the window.
3. If you were asked once already in that browser, you will not be asked again. Try a private window.

## Questions

### Does the exit question need a cookie banner?

No. It stores one small marker in the visitor's browser so they are not asked twice, and records the answer as an anonymous event, like the rest of Clerion.

### Can I change the question or the answers?

Not yet. The wording is fixed so answers mean the same thing across pages and sites.

### Does it slow the page down?

No. The card is built only when it is shown, from the snippet already on the page.

### Can I ask on a single-page app?

Yes. The path is read when the pointer leaves, so client-side navigation is followed, and the five-second wait starts again after each page change.

---

Source: https://getclerion.com/docs/exit-question (Clerion docs, Visitor insight). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Rage clicks

> Clerion records three or more fast clicks on one element as a rage click, with no setup. Where to see them, how they are counted and what to fix.

Clerion finds rage clicks with no setup. When a visitor clicks the same element three or more times, each click within 0.7 seconds of the last, the snippet records one rage click with the page and the element. You see them on the Errors page in a card called Rage clicks, by page and element, with how many bursts and how many visits.

[Clerion's Rage clicks card: span.delivery-option on the checkout, clicked in 41 bursts across 33 visits, above the gallery image on the wool overcoat](/product/clips/rage-clicks.mp4 "clip")

## Before you start

The Clerion snippet must be on the page. If it is, rage clicks are already being recorded: the snippet is served by Clerion, so every site picked this up without a change. If it is not installed, [set up Clerion](https://getclerion.com/docs/quickstart) first.

## Read the card

Open your site, go to Observability, then Errors, and scroll below the event log to Rage clicks:

| Column | What it means |
|---|---|
| Element | The element that was clicked, as a short CSS selector: its tag, its id after `#`, and up to two classes after `.`. The page is beside it. |
| Bursts | How many times someone clicked it three or more times in a row. |
| Sessions | How many different visits did it. Rows are sorted by this. |

The briefing and Ask Clerion see the same rows, so "what frustrates visitors on checkout?" is answered with the element.

## How a rage click is counted

| Rule | Detail |
|---|---|
| Three clicks | Three or more clicks on the same element, each within 0.7 seconds of the one before, make one burst. Ten clicks in a row are still one burst. |
| Any element | Images, labels, plain text and icons count, not only links and buttons. That is how an element that looks clickable and does nothing shows up. |
| The element itself | The exact element under the pointer is recorded, so a click on the icon inside a button names the icon. |
| Not sampled like clicks | Ordinary clicks are sampled to keep traffic light; bursts are not, so every one is counted. |
| Not a goal | Bursts are recorded as `rage_click`, which never shows up as a custom event or a conversion. |

## What to do with a rage click

Most rows fall into one of three cases:

1. **It looks clickable and is not.** An image in a product gallery, a price, a card with a hover effect. Make it do what people expect, or stop it looking like a control.
2. **It is clickable and too slow.** A button that waits on the network with no sign it heard the click. Show that it is working at once, and disable it until it finishes.
3. **It is broken.** A control that throws a script error. Check the event log on the same page for an error at the same spot.

## Make the elements easy to name

A selector such as `div.card` is hard to place on a busy page. Give the elements people interact with an `id` or a meaningful class, for example `button#apply-coupon` or `span.delivery-option`, and the card names them in a way you can find in your code.

## Limits

| Limit | What it means for you |
|---|---|
| From now on | Bursts are recorded from the day the updated snippet reached your site. There is no history before that. |
| Only when tracking runs | Visitors with Global Privacy Control or Do Not Track on, or who declined the consent banner, are not counted. |
| Twelve rows | The card lists the twelve elements with the most visits. |
| Very busy sites | The card reads up to 150,000 events per site for the range. Above that it says so, and a shorter range can bring it back. |

## Questions

### Do I need to turn rage clicks on?

No. The snippet already records them on every site.

### Does this record what visitors type or read?

No. Only the element's tag, id and classes, and where on the page the click landed. No text from the page and no form contents.

### What is the difference between a rage click and a dead click?

A rage click is repeated clicking on one element. A dead click is a single click that does nothing. Clerion records rage clicks; an element that keeps getting rage-clicked is usually a dead click people tried more than once.

### Why is the same element listed on two pages?

The card counts by page and element together, so a header button that frustrates people on two pages appears on both.

---

Source: https://getclerion.com/docs/rage-clicks (Clerion docs, Visitor insight). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Deploy markers

> One call at the end of your deploy job, and Clerion sets each deploy's error rate and conversion against the day before. GitHub Actions and any CI.

To mark a deploy in Clerion, add one HTTP call to the end of your deploy job: a POST to `https://api.getclerion.com/api/v1/deploys` with your Clerion key and your site id. The Errors page then shows each deploy with its error rate and conversion rate for the 24 hours before against the 24 hours after, and the briefing can name the deploy behind a change.

[Clerion's Deploys card: the cursor goes to New delivery step, then across to its error rate rising from 1% to 6.2% and conversion falling from 3.4% to 2.1%](/product/clips/deploys.mp4 "clip")

## Before you start

You need two things from the dashboard:

| What | Where to find it |
|---|---|
| Your key | Your model, in the sidebar. It starts with `clm_` and is the same key Claude and Cursor use. Available on Growth, Business and during the trial. |
| Your site id | The `data-website-id` value in your snippet, or the part of the dashboard address that starts with `site_`. |

Store the key as a secret in your CI, never in the repository. Anyone holding it can read your analytics through the MCP server.

## Send the call

From any shell or CI step:

```bash
curl -X POST https://api.getclerion.com/api/v1/deploys \
  -H "Authorization: Bearer $CLERION_KEY" \
  -H "Content-Type: application/json" \
  -d '{"websiteId":"site_...","label":"v1.8"}'
```

The body takes three fields:

| Field | Required | What it does |
|---|---|---|
| `websiteId` | Yes | The site the deploy belongs to. |
| `label` | No | What shipped, up to 80 characters: a version, a branch, a commit. Shown in the dashboard and named by the briefing. |
| `deployedAt` | No | An ISO time within the last week, if the call is sent after the fact. Defaults to now. |

A successful call returns `200` with the deploy as recorded.

### GitHub Actions

Add the key as a repository secret called `CLERION_KEY`, then add a last step to the job that deploys:

```yaml
- name: Mark the deploy in Clerion
  if: success()
  run: |
    curl -fsS -X POST https://api.getclerion.com/api/v1/deploys \
      -H "Authorization: Bearer ${{ secrets.CLERION_KEY }}" \
      -H "Content-Type: application/json" \
      -d "{\"websiteId\":\"site_...\",\"label\":\"${GITHUB_REF_NAME} ${GITHUB_SHA::7}\"}"
```

`if: success()` keeps a failed deploy from being marked. `-f` makes the step fail loudly if the key is wrong, so you notice.

### GitLab CI

```yaml
deploy:
  script:
    - ./deploy.sh
    - >
      curl -fsS -X POST https://api.getclerion.com/api/v1/deploys
      -H "Authorization: Bearer $CLERION_KEY"
      -H "Content-Type: application/json"
      -d "{\"websiteId\":\"site_...\",\"label\":\"$CI_COMMIT_REF_NAME $CI_COMMIT_SHORT_SHA\"}"
```

Add `CLERION_KEY` as a masked CI variable.

### A deploy script, marking the real time

If your deploy finishes a while after the command runs, record the time it went live:

```bash
#!/bin/sh
set -e
./release.sh
AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -fsS -X POST https://api.getclerion.com/api/v1/deploys \
  -H "Authorization: Bearer $CLERION_KEY" -H "Content-Type: application/json" \
  -d "{\"websiteId\":\"site_...\",\"label\":\"$(git rev-parse --short HEAD)\",\"deployedAt\":\"$AT\"}"
```

### From Node

```js
await fetch("https://api.getclerion.com/api/v1/deploys", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.CLERION_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ websiteId: "site_...", label: process.env.RELEASE_TAG }),
});
```

### Other CI and hosts

Any system that can run a command after a deploy can send the same `curl`: GitLab CI, CircleCI, Bitbucket Pipelines, or a deploy script on your own server. Put it after the step that makes the new version live, not after the build, so the time marks when visitors started getting it.

## Read the Deploys card

Open your site, go to Observability, then Errors, and scroll below the event log. Each deploy in the selected period has one row:

| Column | What it means |
|---|---|
| Deploy | Your label and the time it was recorded. |
| Sessions | Visits in the 24 hours before, then the 24 hours after. |
| Error rate | The share of those visits that hit at least one JavaScript error, before and after, with the change in points. |
| Conversion | The share of visits that sent any custom event, before and after, with the change in points. |

A change for the worse is marked in red. A deploy less than six hours old shows as still settling and is not judged, because a few hours of traffic are too few to read.

The briefing and Ask Clerion see the same rows. When a drop starts on the day of a deploy and that deploy moved errors or conversion, the briefing names it.

## Limits

| Limit | What it means for you |
|---|---|
| A paid plan | The key exists on Growth, Business and the trial. On Starter there is no key to send. |
| 24 hours each side | Two deploys on the same day share some of those hours, so their numbers overlap. |
| Conversion means any custom event | It is the share of visits that sent one, not one goal in particular. |
| 50 deploys per range | The card lists up to 50 deploys in the selected period. |
| Very busy sites | The card reads up to 150,000 events per site for the range. Above that it says so, and a shorter range can bring it back. |

## If the call fails

| Response | Cause |
|---|---|
| `401` | The key is missing, mistyped, or was replaced in Your model. Copy the current one. Replacing the key stops the old one everywhere at once. |
| `404` | The site id is not a site on the account that owns the key. |
| `400` | `websiteId` is missing, or `deployedAt` is more than a week away from now. |

## Questions

### Does marking a deploy change my analytics?

No. It adds a row to the Deploys card and a fact for the briefing. Visits, events and errors are counted exactly as before.

### Can I mark a deploy by hand?

Yes. The same `curl` from a terminal works; give it a label such as `pricing page copy`.

### Is the key safe to put in CI?

As a CI secret, yes. It reads analytics and records deploys, and cannot change or delete anything else. If it leaks, replace it in Your model and every copy stops working.

### Which deploys should I mark?

Production only. Preview and staging deploys get no real traffic, so their before and after would be empty.

---

Source: https://getclerion.com/docs/deploy-markers (Clerion docs, Releases). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# MCP server

> Connect Claude, Cursor or any MCP client to your Clerion analytics: seven read-only tools, with a key or OAuth. On Growth, Business and in every trial.

Clerion runs an MCP server at `https://api.getclerion.com/mcp`. Connect Claude, Cursor or any client that speaks MCP over HTTP, and it reads your traffic, pages, locations, devices, errors and speed as seven read-only tools. It returns aggregates only, never visitor rows, and nothing in it can change or delete anything. It is included on Growth and Business and in every trial.

## Connect a client

1. In the Clerion dashboard, open **Your model**. It shows a command for clients that take a key, the address for Claude's connector, and your key with **Replace key** beside it.
2. Add Clerion to your client:

| Client | How |
|---|---|
| claude.ai, Claude Desktop, Cowork | Open Customize, then Connectors, choose Add custom connector, paste `https://api.getclerion.com/mcp`, and approve when Claude sends you to Clerion. |
| Claude Code | Run the command shown on the Your model screen in your terminal. |
| Cursor and other clients that take a key | Add an HTTP MCP server at `https://api.getclerion.com/mcp` with an `Authorization` header of `Bearer` and your key. |

### Claude Code

Paste the command from Your model. It has this shape, with your own key:

```bash
claude mcp add --transport http clerion https://api.getclerion.com/mcp \
  --header "Authorization: Bearer clm_..."
```

### Cursor

Add the server to `.cursor/mcp.json` in your project, or the global one:

```json
{
  "mcpServers": {
    "clerion": {
      "url": "https://api.getclerion.com/mcp",
      "headers": { "Authorization": "Bearer clm_..." }
    }
  }
}
```

### Any other client

Point it at `https://api.getclerion.com/mcp` over HTTP with an `Authorization: Bearer clm_...` header, or, if it supports OAuth, add the address alone and approve the connection when it sends you to Clerion.

3. Ask the question you would have opened the dashboard for. The model calls the tools it needs and writes the answer with the numbers in it.

## Tools

| Tool | What it returns |
|---|---|
| `clerion_list_sites` | The sites on the account, with the `websiteId` every other tool takes. |
| `clerion_traffic_summary` | Visitors, sessions, pageviews, bounce rate and session length, with the daily trend. |
| `clerion_top_pages` | The most visited pages, with views and unique visitors per path. |
| `clerion_locations` | Sessions and pageviews by country and city. |
| `clerion_devices` | Sessions by device type, with each type's share. |
| `clerion_errors` | JavaScript errors: how many fired, how many are distinct, which hit the most visitors. |
| `clerion_speed` | Load time, first contentful paint and time to interactive, with the sample size. |

## What a question looks like

Ask the way you would ask a colleague. The model picks the tools:

> Where did visitors leave last week?

The client calls `clerion_list_sites` for the site id, then `clerion_top_pages` for the week, and answers with the pages and their figures. Follow up in the same conversation:

> Which three SEO fixes should I make this week?

It reads the pages and the analytics together and lists three.

## Your key

The key starts with `clm_`. The same key sends [Deploy markers](https://getclerion.com/docs/deploy-markers) from CI. **Replace key** retires the old key and every OAuth connection at once, everywhere, on the next request.

Tool calls are database reads: they do not count against your AI allowance, and Clerion does not see the question or the answer.

More on why and how: [Clerion's MCP server](https://getclerion.com/mcp).

---

Source: https://getclerion.com/docs/mcp (Clerion docs, Integrations). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Script tag

> Every attribute the Clerion snippet reads: the key and site id, the API address, auto-tracking, debug mode, turning tracking off, and the exit question.

The snippet configures itself from attributes on its own `<script>` tag. Only the key is required; the copy in your dashboard already carries the key and the site id.

```html
<script
  src="https://api.getclerion.com/sdk/clerion-analytics.js"
  data-api-key="YOUR_API_KEY"
  data-website-id="YOUR_WEBSITE_ID"
></script>
```

## Attributes

| Attribute | Value | What it does |
|---|---|---|
| `data-api-key` | Your tracking key, starting `cle_` | Required. Without it the snippet does nothing. |
| `data-website-id` | Your site id, starting `site_` | The site the visits belong to. |
| `data-api-url` | A URL | Where events are sent. Defaults to the API on the host the script was loaded from; leave it unset. |
| `data-auto-track` | `false` | Turns off automatic tracking: no pageviews, clicks, scroll, forms, speed, errors, rage clicks or exit question. Session starts and what you send with the [JavaScript API](https://getclerion.com/docs/javascript-api) are still recorded. |
| `data-debug` | `true` | Logs each batch of events to the browser console as it is sent, and any tracker error. See [Check your installation](https://getclerion.com/docs/check-installation). |
| `data-disabled` | `true` | Turns tracking off entirely, for a staging site that shares the template. |
| `data-exit-question` | Paths, comma-separated | Asks visitors leaving those pages why. `/pricing` matches one page, `/docs/*` every page under it, `*` every page. See [Exit question](https://getclerion.com/docs/exit-question). |

## In Next.js

```tsx
import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html><body>{children}
      <Script src="https://api.getclerion.com/sdk/clerion-analytics.js" data-api-key="YOUR_API_KEY" data-website-id="YOUR_WEBSITE_ID" strategy="afterInteractive" />
    </body></html>
  );
}
```

## Every other option

Sampling, batching, the session timeout, which automatic events to record and the consent settings are not attributes. Start the tracker yourself to set them: see [Configuration options](https://getclerion.com/docs/configuration).

## What the snippet does not need

No cookie and no consent banner: Clerion counts visits without setting cookies. The one cookie it knows is the visitor's choice, and only if you turn on the optional consent banner. No event plan: everything in [What is tracked automatically](https://getclerion.com/docs/quickstart#what-is-tracked-automatically) is on by default.

## Privacy signals

The snippet honours Global Privacy Control and Do Not Track. A visitor with either turned on is not tracked, and the exit question is never shown to them.

---

Source: https://getclerion.com/docs/script-tag (Clerion docs, Reference). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# JavaScript API

> The methods on window.clerion: trackEvent for custom events and revenue, trackPageView for manual pageviews, and the commerce helpers that feed the ecommerce funnel.

The snippet creates the tracker as `window.clerion` once the page has loaded. Everything below is optional: pageviews, clicks, scroll, forms, speed, errors and rage clicks are tracked without any code.

Code that may run before the tracker exists should guard the call:

```js
window.clerion?.trackEvent("signup");
```

## trackEvent

```js
window.clerion.trackEvent(name, details);
```

Records a custom event. Every name Clerion does not use itself appears on the Custom events page the first time it arrives. `details` is optional; three keys have meaning in the dashboard:

| Key | What it does |
|---|---|
| `value` | Summed per event, and read by [Revenue by source](https://getclerion.com/docs/revenue-by-source). `orderValue` and `revenue` are accepted as aliases. A number or a numeric string. |
| `currency` | Shown next to the value. |
| `path` | Overrides the page the event is attributed to. |

```js
window.clerion.trackEvent("purchase", { value: 49, currency: "USD", plan: "starter" });
```

The full guide, with the HTML attribute alternative and the reserved names, is [Custom events](https://getclerion.com/docs/custom-events).

Attribute an event to a different page than the one it fired on, for example a modal that lives on every page:

```js
window.clerion.trackEvent("demo_request", { path: "/book-a-demo" });
```

For TypeScript, declare the global once; the declaration is in [Custom events](https://getclerion.com/docs/custom-events#in-react-nextjs-or-another-framework).

## trackPageView

```js
window.clerion.trackPageView(path, details);
```

Records a pageview by hand. Rarely needed: the first pageview and every client-side route change are counted automatically. `path` defaults to the current page.

## Commerce helpers

These record the built-in commerce events that feed the ecommerce funnel, product view to cart to checkout.

| Method | Records |
|---|---|
| `trackProductView(productId, productName, { category, price })` | `product_view` |
| `trackAddToCart(productId, productName, quantity, price, size)` | `add_to_cart`. `quantity` defaults to 1. |
| `trackRemoveFromCart(productId, productName, quantity, price)` | `remove_from_cart` |
| `trackCheckoutStart(products, orderValue)` | `checkout_start` |
| `trackSearch(query, resultsCount)` | `search` |
| `trackCategoryClick(categoryName)` | `category_click` |
| `trackBannerClick(bannerIndex, details)` | `banner_click` |
| `trackWishlistAdd(productId, productName, details)` | `wishlist_add` |
| `trackWishlistRemove(productId, productName)` | `wishlist_remove` |
| `trackFilterApply(filterType, filterValue, appliedFilters)` | `filter_apply` |
| `trackSortChange(field, order)` | `sort_change`. `order` defaults to `asc`. |

A completed purchase is not a built-in name. Send it with `trackEvent` and a value, so it counts as revenue.

## Consent

```js
window.clerion.setConsentStatus(true);
```

Records the visitor's choice, as Clerion's optional consent banner does. With consent given, Clerion keeps a visitor id for up to a year, which lets [Revenue by source](https://getclerion.com/docs/revenue-by-source) follow a visitor across visits. `setConsentStatus(false)` removes it, and that browser is not tracked on later visits. Without a choice, Clerion runs cookie-free and counts each visit on its own.

## Limits on details

| Limit | Value |
|---|---|
| Size | 5 KB per event. Larger payloads are rejected and the event is not stored. |
| Strings | Truncated at 500 characters. |
| Arrays | 50 items. |
| Nesting | 5 levels. |
| Keys | 100 characters. |

Do not put personal data in event details. A plan name is fine; an email address is not.

---

Source: https://getclerion.com/docs/javascript-api (Clerion docs, Reference). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Configuration options

> Every option the Clerion tracker accepts when you start it yourself: what is tracked, sampling, batching, the session timeout, consent and the exit question.

The script tag starts the tracker with its defaults, and those defaults suit almost every site. When you need to change one, load the script with `data-disabled="true"` so the tag does not start a tracker, then start your own:

```html
<script src="https://api.getclerion.com/sdk/clerion-analytics.js" data-disabled="true"></script>
<script>
  window.addEventListener("load", () => {
    window.clerion = new ClerionAnalytics({
      apiKey: "YOUR_API_KEY",
      websiteId: "YOUR_WEBSITE_ID",
      trackScroll: false,
      exitQuestion: ["/pricing"],
    });
  });
</script>
```

Assign it to `window.clerion` so [custom events](https://getclerion.com/docs/custom-events) and the rest of the [JavaScript API](https://getclerion.com/docs/javascript-api) work as documented. Start exactly one tracker per page.

## Required

| Option | What it is |
|---|---|
| `apiKey` | Your tracking key, starting `cle_`. The tracker throws without it. |
| `websiteId` | Your site id, starting `site_`. |

## What is tracked

All on by default.

| Option | Default | What it controls |
|---|---|---|
| `autoTrack` | `true` | Everything below, plus pageviews and session starts. `false` records only what you send yourself. |
| `trackClicks` | `true` | Clicks on links and buttons, with the element's tag, id and classes. Never its text. |
| `trackScroll` | `true` | Scroll depth, at the thresholds below. |
| `scrollDepthThresholds` | `[25, 50, 75, 100]` | The depths, in percent, at which a scroll event is recorded. |
| `trackForms` | `true` | Form focus and submit, by form id or name. Never the values. |
| `trackOutbound` | `true` | Clicks on links to other sites, with the destination. |
| `trackFileDownloads` | `true` | Clicks on links to files such as PDFs and images. |
| `trackPerformance` | `true` | Load time and Core Web Vitals. |
| `trackErrors` | `true` | JavaScript errors and console errors, with the visitor's last actions. |
| `exitQuestion` | `[]` | Paths on which leaving visitors are asked why. See [Exit question](https://getclerion.com/docs/exit-question). |

Rage clicks are recorded whenever `autoTrack` is on; there is no switch for them alone.

## Sending

| Option | Default | What it controls |
|---|---|---|
| `enableBatching` | `true` | Events are queued and sent together, five seconds after the last one, or at once when the page is hidden or closed. `false` sends each event as it happens. |
| `heartbeatInterval` | `120000` | Milliseconds between flushes of anything still queued. Two minutes. |
| `sessionTimeout` | `1800000` | Milliseconds of inactivity after which the next action starts a new session. Thirty minutes. |
| `apiUrl` | derived | Where events are sent. Derived from the script's own address; leave it unset. |

## Sampling

Leave these at their defaults for anything you count as a conversion.

| Option | Default | What it controls |
|---|---|---|
| `samplingRate` | `1.0` | The share of visitors whose events are recorded. Errors, session starts and ends, and pageviews are always recorded. Custom events and rage clicks are not, so a rate below 1 undercounts them. |
| `detailedEventsSamplingRate` | `0.1` | For visitors who are sampled, the share of clicks, scroll depths and form focuses that are kept. Keeps high-volume events light. |

## Consent and privacy

| Option | Default | What it controls |
|---|---|---|
| `requireConsent` | `true` | Whether a recorded refusal stops tracking. With the [consent banner](https://getclerion.com/docs/consent-banner), a visitor who clicks Reject is not tracked. |
| `allowWithoutConsent` | `true` | Before a visitor has chosen, track the session without keeping anything between visits. |
| `consentCookieName` | `clerion_consent` | The cookie the banner writes and the tracker reads. |
| `consentCookieExpiry` | `365` | Days a choice, and the visitor id that comes with acceptance, are kept. |
| `ignorePrivacySignals` | `false` | Global Privacy Control and Do Not Track stop tracking. Set `true` only with your own legal basis for it. |

## Debugging

| Option | Default | What it controls |
|---|---|---|
| `debug` | `false` | Logs each batch of events to the console as it is sent, and any tracker error. |
| `sourceMapUrl` | `null` | Where the tracker can fetch source maps to resolve error stack traces. |
| `enableSourceMapResolution` | `true` | Whether it tries. |

## From the script tag

The tag itself reads only `data-api-key`, `data-website-id`, `data-api-url`, `data-auto-track`, `data-debug`, `data-disabled` and `data-exit-question`. Every other option needs the pattern at the top of this page. See [Script tag](https://getclerion.com/docs/script-tag).

---

Source: https://getclerion.com/docs/configuration (Clerion docs, Reference). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Consent banner

> Clerion needs no consent banner. If your policy wants one anyway, one script tag shows it, loads the tracker, and keeps a visitor id only for people who accept.

Clerion sets no cookies and stores no personal data, so it needs no consent banner and none is shown by default. Some teams want one anyway, for their own policy or because other scripts on the site need it. Clerion's banner is one script tag that shows the banner, loads the tracker itself, and remembers the visitor's choice.

## Add it

Replace the normal snippet with the banner's. Use the copy from your dashboard; it carries your key and site id.

```html
<script
  src="https://api.getclerion.com/sdk/clerion-consent-banner.js"
  data-api-key="YOUR_API_KEY"
  data-website-id="YOUR_WEBSITE_ID"
  data-theme="auto"
></script>
```

Do not keep the plain snippet as well: the banner starts the tracker, and two trackers count every visit twice.

## What each choice does

| The visitor | What Clerion does |
|---|---|
| Has not chosen yet | Tracks the visit without keeping anything between visits. Nothing is written to the browser. |
| Clicks Accept | Writes the `clerion_consent` cookie and keeps a visitor id for a year, so [Revenue by source](https://getclerion.com/docs/revenue-by-source) can follow them across visits. |
| Clicks Reject | Writes the cookie as a refusal. That browser is not tracked, now or on later visits, until the cookie expires. |

The choice lasts 365 days. Settings reopens the banner so a visitor can change it.

## Appearance

Optional attributes on the same tag:

| Attribute | Values | Default |
|---|---|---|
| `data-theme` | `light`, `dark`, `auto` (follows the visitor's system) | `light` |
| `data-position` | `bottom`, `top` | `bottom` |
| `data-accent-color` | Any CSS colour, for buttons and links | `#007acc` |
| `data-font-family` | A CSS font stack; `inherit` uses your site's font | System font |
| `data-border-radius` | Button corner radius in pixels | `4` |
| `data-title` | The banner's heading | We use cookies and analytics |
| `data-description` | The sentence under it | A short line about privacy-friendly analytics |
| `data-privacy-url` | A link to your privacy policy | None |

```html
<script src="https://api.getclerion.com/sdk/clerion-consent-banner.js"
  data-api-key="YOUR_API_KEY" data-website-id="YOUR_WEBSITE_ID"
  data-theme="dark" data-accent-color="#0066CC" data-font-family="inherit"
  data-title="One cookie, your call"
  data-description="We count visits without tracking you. Accept to help us tell returning readers from new ones."
  data-privacy-url="https://yoursite.com/privacy"></script>
```

## Your own banner

If you already have a consent tool, keep it and tell Clerion the result:

```js
window.clerion.setConsentStatus(true);  // accepted
window.clerion.setConsentStatus(false); // rejected
```

Call it when your banner records a choice. The tracker writes the same cookie and behaves exactly as above. Load the normal snippet in this case, not the banner's.

## Questions

### Does the banner make Clerion set cookies?

One: the visitor's choice, under the name `clerion_consent`. Acceptance also stores a visitor id in the browser. Neither exists unless the banner, or your own call to `setConsentStatus`, is in use.

### Does rejecting break anything on my site?

No. The tracker stops; the page is unaffected.

---

Source: https://getclerion.com/docs/consent-banner (Clerion docs, Reference). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Dashboard filters

> Click any row to filter the whole dashboard to those visitors. Filters live in the page address, so a filtered view can be shared, bookmarked or built by hand.

Click any row in any table, a country, a source, a page, a device, and the whole dashboard narrows to those visitors: every number, chart, funnel and the user flow. Click the row again to clear it. Filters across different dimensions combine, so "mobile" and "United States" together show mobile visitors from the United States.

## Exclude instead

Hold Alt (Option on a Mac) while clicking a row, or use the hide control that appears when you hover it, to hide those visitors instead of showing only them. Exclusions stack: several countries can be hidden at once. The filter bar reads each active filter back in plain words.

## Filters in the address

Active filters are written into the page address as `f`, a JSON list of dimension and value pairs:

```text
https://app.getclerion.com/analytics/site_...?f=[["device","mobile"],["country","United States"]]
```

A value starting with `!` excludes:

```text
?f=[["source","!newsletter"]]
```

Copy the address to share the exact view, bookmark it, or build one in a script.

| Dimension | Example values |
|---|---|
| `page` | `/pricing` |
| `source` | `chatgpt.com`, `google.com`, `direct` |
| `country`, `region`, `city` | `Germany`, `Bavaria`, `Munich` |
| `language`, `timezone` | `en-US`, `Europe/Berlin` |
| `device` | `mobile`, `desktop`, `tablet` |
| `browser`, `os`, `screen` | `Safari`, `iOS`, `390x844` |
| `isp` | The visitor's network provider |
| `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term` | Whatever your links carry |

One value per dimension, except exclusions, which can be several.

## What filters apply to

Everything that counts visitors: the numbers at the top, the chart, every breakdown, custom events and the funnel, user flow, and the briefing's figures when you ask a question with a filter on. The site graph keeps every page visible, but its traffic numbers follow the filter.

## From Ask Clerion

Press ⌘K and type a filter in your own words, such as "mobile visitors from the United States". Clerion turns it into the same filters. Start with "not" to exclude: "not visitors from the newsletter".

---

Source: https://getclerion.com/docs/filters (Clerion docs, Reference). The whole manual as one file: https://getclerion.com/docs/everything.md


---

# Export and data retention

> Export your events as CSV or JSON from Settings, how long each plan keeps raw data, and how to delete it.

Your data is yours. Export it as CSV or JSON whenever you like, and delete a site or your whole account from Settings.

## Export

Open Settings, then Export. Pick the site, the date range and the format.

| | |
|---|---|
| Formats | CSV, or JSON. |
| Rows | One per event: its type, time, page, referrer, device, country and the details you sent with it. |
| Paging | Up to 1,000 rows per page; a larger range comes as several files. |
| Range | Any dates inside your plan's history window. |

Exported rows carry no personal data, because none is stored: no IP addresses, no raw user agents, no names.

## How long raw data is kept

Raw events, the rows behind every number, are kept for your plan's history window and then deleted automatically. The dashboard's date picker shows the same window.

| Plan | Raw events kept |
|---|---|
| Solo | 90 days |
| Starter | 1 year |
| Growth, and the trial | About 13 months |
| Business | 2 years |

Imported history from Google Analytics is separate: it is stored as daily and monthly totals and kept until you replace or delete the import. See [Import your history](https://getclerion.com/docs/import-history).

## Deleting data

| To delete | Where |
|---|---|
| One site and all its events | Settings, the site's row, Delete. The tracking key stops working; re-adding the same address later revives it. |
| Visits from your own network | Settings, the site's row, the option to ignore localhost and private networks, with a button to remove what was already collected. |
| Your account and everything in it | Settings, Account, Delete account. |

Deletion is immediate in the dashboard and permanent.

## Questions

### Can I export from a script?

The dashboard's export calls the same endpoint it would show you; there is no separate public API for it yet. For reading figures from code, use the [MCP server](https://getclerion.com/docs/mcp), which serves aggregates to any client.

### Does the AI keep a copy?

No. The model receives aggregate statistics for the question at hand and keeps nothing. Briefings are stored with your account and deleted with it.

---

Source: https://getclerion.com/docs/export-and-retention (Clerion docs, Reference). The whole manual as one file: https://getclerion.com/docs/everything.md