Skip to content

Tracking options

Each site has one script, and you never need to change it. To track more than pageviews and custom events, you turn on options in the dashboard or through your agent. There's no code to change and nothing to deploy.

Tracked by default

With every option off, the script sends:

  • Pageviews: one for each distinct URL, including navigations in single-page apps. The URL's fragment is ignored unless you turn on Hash routes.
  • Time on page: how long the page was visible, from when it was shown until it was hidden or closed.
  • Custom events: anything you send with nl.track() (see Custom events).

Each pageview includes the page's URL, its referrer, the width of the browser window and the script's version. Our server then adds the browser, operating system and device type from the user agent, and the country, region and city from the request. See Privacy for exactly what we store about a visitor.

Options

Every option is off until you turn it on.

OptionWhat it addsName in MCP
Page speedCore Web Vitals from real visits, shown in Speedvitals
ErrorsUncaught errors and unhandled promise rejections, with their stack traceserrors
Console errorsconsole.error calls as well (requires Errors)console_errors
Session replayRecords a share of sessionsreplay
Sessions recordedThe share of sessions to record, from 0.01 to 1 (default 0.1)replay_share
Mask all textMasks all text and media in recordings, not only form inputsmask_all_text
Outbound linksClicks on links to other sites, and file downloadslinks
Hash routesTracks each #/ route as its own pagehash

Changing options

  • In the dashboard: go to your site's Settings → Collect. The Errors and Replays views also offer to turn their option on if nothing has been collected yet.
  • From your agent: use the MCP tool update_site with the names in the table. For example, ask your agent to "turn on session replay for 25% of sessions".

Changes reach your site within five minutes. The settings are part of your site's script, and browsers fetch a fresh copy within that time.

Page speed

The script measures LCP, INP, CLS, FCP and TTFB the same way Chrome's own field data does. It reports them for every page load and, in Chromium browsers that support it, for every single-page app navigation too. Each report names the element responsible for LCP, INP and the largest layout shift. If something new has been measured when the page is hidden, the page load sends an updated report, and only its latest report counts.

Errors

The script reports uncaught errors and unhandled promise rejections, plus any errors you catch yourself and report with nl.error(err, props). If you also turn on Console errors, it reports console.error calls too. Many libraries log through console.error, so expect more errors with this on.

  • Each Error object is reported only once, however it reaches the script.
  • If the same error happens again within 60 seconds, the repeats are sent together as one report with a count.
  • Each page load sends at most 30 error reports.
  • Errors from browser extensions, ResizeObserver loop notices and Script error. messages from cross-origin scripts are ignored.

To label errors with your release, add data-release to the script tag:

<script defer src="https://app.nanolytics.dev/s/pk_….js" data-release="2026.11.16"></script>

See Errors for how errors are grouped.

Session replay

The script records the share of sessions you choose. Each session is either recorded in full or not at all. Anything people type is always masked in the browser, and with Mask all text on, all text and media are masked too. Sessions aren't recorded if the visitor has withdrawn consent, if their browser sends a Global Privacy Control signal, or if the browser is controlled by automation. See Session replay.

When a visitor clicks a link, the script sends one of two custom events. The prop url holds the link's URL without its query string or fragment.

  • download: a link to a file, detected by its extension (.pdf, .zip, .dmg, .csv, .mp4 and others) or by its download attribute, on any host.
  • outbound: a link to another host. Note that www.example.com and example.com count as different hosts.

Middle clicks are tracked; right clicks aren't. A download is never also counted as an outbound click.

Hash routes

Turn this on if your app uses hash-based routing. A URL like /#/users/1?tab=2 is then tracked as the page /users/1?tab=2. Any query string on the page itself, such as campaign tags, is kept alongside the route's.

404 pages

Only your site knows when a page doesn't exist. If you have a static not-found page, add data-ext="404" to its script tag:

<script defer src="https://app.nanolytics.dev/s/pk_….js" data-ext="404"></script>

If your app renders its own not-found route, call nl.track('404') there instead. Either way, you get a custom event named 404. Its url prop is the missing page, and if the browser provides one, its referrer prop is the page with the broken link.