# 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