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

# Install the browser script

> Add agentrail-browser to your pages with one tag, choose which calls carry the page's trace, and decide when behaviour and the fingerprint are turned on.

The browser script records the steps a person, or an agent driving a browser, takes on your pages: page views, your pages' calls to your own services, and WebMCP tool calls. It is one line in your pages' `<head>`.

An agent that never runs JavaScript never loads the script. To see those, add the [edge](https://agentrail.co/docs/guides/journeys-edge.md) too.

## Add the tag

**1. Open Set up**

An Admin opens **Journeys**, selects **Set up** and chooses **Browser script**. If you are in **Settings · Journeys**, use **Add the browser script**.

**2. Name the source**

Enter a **Name**, such as "Marketing site", and select **Create source**.

**3. Add your API's origins**

Under **Your API's origins**, list any other origins your pages call. Agentrail adds them to the tag. See [Calls to your own services](#calls-to-your-own-services).

**4. Paste the tag**

Copy the **Browser script tag** into the `<head>` of your site's layout, so it loads on every page.

The tag looks like this:

```html theme={null}
<script async src="https://<collector>/agentrail.js" data-key="ajp_…"></script>
```

The key in the tag is public, because it sits in your page. It can only send this source's steps.

The source moves from **Waiting for its first event** to **Receiving** in **Settings · Journeys** once a page has loaded.

## Tag attributes

| Attribute | What it does |
| - | - |
| `data-key` | The source's public key. Required. |
| `data-first-party` | Other origins whose calls carry the page's trace, separated by commas, such as `https://api.example.com`. |
| `data-query-allowlist` | The query parameters a recorded path keeps, separated by commas. Every other parameter is dropped from what is recorded. |
| `data-behaviour="on"` | Records how the page is used. Off unless you add it. See [Behaviour and the fingerprint](#behaviour-and-the-fingerprint). |
| `data-fingerprint="on"` | Reads the tab's fingerprint, once a tab. Off unless you add it. See [Behaviour and the fingerprint](#behaviour-and-the-fingerprint). |
| `data-session-idle` | Seconds without a request after which a visitor's session ends. The default is 1800, which is 30 minutes. |
| `data-session-domain` | The domain a session is shared across, such as `example.com`. By default, a session stays on the page's host. |
| `data-collector` | The collector's full address, such as `https://<collector>/ingest/browser`, when it is not where the script came from. |

`data-behaviour` and `data-fingerprint` take effect only with the value `on`.

## Calls to your own services

Each call a page makes to its own origin, or to an origin in `data-first-party`, carries the page's trace in a `traceparent` header and is recorded. That is how a page view joins the API call it made: when your API is also a source, the trace proves the two belong together.

* A call to any other origin goes as your page made it, and is not recorded.
* A call that already carries a `traceparent`, such as one from your own tracer, keeps it and is not recorded.

> [!WARNING]
>
> `traceparent` is a custom header, so a browser checks with your API before a call from another origin carries it. Add `traceparent` to your API's allowed CORS request headers before you list its origin, or the browser will block your pages' calls to it.

## Behaviour and the fingerprint

The tag records page views, calls and WebMCP tool calls as soon as it loads. Behaviour and the fingerprint are separate, and each stays off until you turn it on.

**Behaviour** is how a page is used: pointer movement, clicks, key presses, scrolling and focus, with their timing and position. It never includes what was typed, pasted or chosen, or which key was pressed. See [What Agentrail records](https://agentrail.co/docs/guides/journeys-data.md#behaviour).

Turn it on when you want to know who drove a page. It is what **Driver** on a journey is read from: a page view with no behaviour shows no driver, so an agent in an ordinary browser that names nothing can only be told from a person this way. Add `data-behaviour="on"`, and check that your site's privacy notice covers it.

**The fingerprint** identifies a visitor's browser, so turn it on only for a visitor who has consented. Journeys shows nothing from it today, so you lose nothing by leaving it off.

To turn it on, render `data-fingerprint="on"` only once your site's consent banner or cookie says yes. A visitor who consents part-way through a page is fingerprinted from their next page load.

## The session

The session is a cookie, `agentrail_session`. The edge sets it, and on a site with no edge the script sets it the same way. It holds a generated id and nothing about the visitor. It ends after 30 minutes without a request, and a day after it began.

On a site with the edge, give both the same idle timeout and domain.

## Bundle it yourself

If your site bundles its own scripts, install the package and start it once a page, as early as you can:

```sh theme={null}
npm install agentrail-browser
```

```js theme={null}
import { start } from 'agentrail-browser';

start({
  key: 'ajp_…',
  collector: 'https://<collector>/ingest/browser',
  firstParty: ['https://api.example.com'],
});
```

The options match the tag's attributes: `firstParty`, `queryAllowlist`, `behaviour: true`, `fingerprint: true`, `sessionIdleTimeout` and `sessionCookieDomain`. `service` names the service on each step, and defaults to the page's host. `onError` is told of every call the collector refused or never got; otherwise the page's console is warned.

For what the script sends, see [What Agentrail records](https://agentrail.co/docs/guides/journeys-data.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.