# Add analytics to any site with one tag

> Add web analytics and session replay to any website by pasting a single script tag into your HTML head, with no cookies and zero configuration.

**To add analytics to your website, paste the snippet tag before the closing `</head>` tag on your pages.** Once installed, the tag immediately records pageviews, referrers, devices, and countries with no cookies and no stored IP addresses. You do not need to configure trackers or sign up for third-party scripts; everything flows to your project dashboard, the CLI, and your agents.

Here is how to set up the snippet, connect your domain, track custom events, and optionally record masked session replays.

## How to get your tag and place it in your HTML

If your project runs on our hosting, your environment already contains `NEXT_PUBLIC_VIBIZ_ANALYTICS_KEY` and `NEXT_PUBLIC_VIBIZ_ANALYTICS_URL`. The `analytics` resource is included by default whenever you initialize a full project.

You can inspect the tag snippet at any time using the CLI:

```bash
vibiz analytics snippet
```

The output gives you the exact script tag for your project:

```html
<script defer src="https://thelastapi.dev/v1/script.js" data-key="vz_pk_1234567890abcdef"></script>
```

Paste this line into your site's global layout or root HTML template, directly before the closing `</head>` tag. Because the script uses the `defer` attribute, it downloads in the background and will not block page rendering.

## Adding analytics to a site hosted elsewhere

You do not need to host your site with thelastapi to use its analytics. You can track a static site, a site running on another server, or an app built on any external platform.

### Step 1: Create an analytics-only project

Create a workspace with just the analytics resource attached:

```bash
vibiz init mysite --resources analytics
```

### Step 2: Register your domain

Our ingestion endpoints drop events sent from unknown origins to prevent spam and polluted data. If an event comes from an unregistered domain, the server rejects it with a `403 forbidden` error.

Register the external domain where your site answers:

```bash
vibiz domains add example.com --elsewhere
```

If your visitors also reach the site via `www.example.com`, add that domain as well. Once added, the collector accepts visits originating from those hostnames.

### Step 3: Paste the snippet

Run `vibiz analytics snippet` or visit the console under **Analytics ▸ Add it to any site**. Copy the script tag and paste it into your external site's `<head>` tag. As soon as you deploy the updated HTML, incoming visits will begin recording.

## How cookieless tracking works

The script does not set any cookies. Instead, it tracks visitors while respecting modern privacy standards.

A pseudorandom identifier stored in the browser's `localStorage` keeps a visitor counted as a single person across visits and network changes. If you do not want to use storage at all, add the `data-no-storage` attribute to your tag:

```html
<script defer src="https://thelastapi.dev/v1/script.js" data-key="vz_pk_1234567890abcdef" data-no-storage></script>
```

With `data-no-storage` active, the server relies on a daily-salted hash to calculate daily uniqueness. Under this mode, a visitor who returns tomorrow is counted as a new visitor. To understand the differences in measurement detail, read our guide on [cookieless web analytics](https://thelastapi.dev/blog/cookieless-web-analytics).

Geographic data comes from local IP geolocation lookups performed immediately when the request hits our collector. The raw IP address is discarded and never written to storage.

## Tracking custom events and user identity

Beyond standard pageviews, the client script exposes a simple `vibiz` helper function on the `window` object.

### Custom events

To capture user actions like clicks, upgrades, or downloads, pass the event name and an object with scalar properties:

```js
vibiz('event', 'Signup', { plan: 'pro' });
```

Payloads must be scalar JSON up to 8 KB, containing at most 30 properties. Automated bots are filtered and dropped before processing.

If you prefer to record business events from your backend API instead of the browser, use `@vibiz/app`:

```ts
import { vibiz } from '@vibiz/app';

await vibiz.user(session.userId).track('Upgraded', {
  properties: { plan: 'pro' }
});
```

Development API keys do not write to production analytics logs, keeping test traffic out of your real totals.

### Identifying signed-in users

When a visitor signs in to your application, call `identify` to associate their past and future visits across devices into one visitor profile:

```js
vibiz('identify', user.id);
```

When they log out, clear the identity:

```js
vibiz('identify', null);
```

## Adding session replay without extra code

You can capture visual replays alongside metrics by attaching the `replay` resource to your project:

```bash
vibiz add replay
```

Or, if starting from scratch:

```bash
vibiz init mysite --resources analytics,replay
```

Once the resource is present, the script tag automatically starts recording sessions without requiring you to update your frontend markup.

Every session is recorded by default and masked directly inside the visitor's browser before upload:
- Password, card, and one-time code fields are never captured.
- Form inputs appear as typed, but text resembling credit card numbers or IBANs anywhere on the page is replaced with mask characters.
- Query parameters are stripped from URLs.
- You can manually mask custom containers with `data-vibiz-mask` or prevent recording of specific elements with `data-vibiz-sensitive`.

If you operate in jurisdictions requiring explicit consent before recording, set `require_consent: true` via the API or CLI configuration. The recorder will wait until your code explicitly calls:

```js
vibiz('replay', 'start');
```

To stop recording in that browser session:

```js
vibiz('replay', 'stop');
```

For a deeper dive into masking configurations, see our guide on [session replay for a small site](https://thelastapi.dev/blog/session-replay-small-site).

## Reading your metrics and troubleshooting

You can query your traffic data using the CLI or via simple HTTP requests.

### From your terminal

To view traffic over the past week:

```bash
vibiz analytics --period 7d
```

To view error-related session recordings:

```bash
vibiz replays --errors --period 7d
```

### From the API

You can pull aggregate totals, top pages, referrers, and device breakdowns using standard JSON requests:

```bash
curl "https://thelastapi.dev/v1/projects/prj_123/analytics?period=7d" \
  -H "Authorization: Bearer $VIBIZ_API_KEY"
```

The response includes:
- `totals` and `timeseries`
- `top_pages`
- `sources` (such as Google, ChatGPT, or Direct)
- `countries` and `devices`
- `events`

### Monitoring and health checks

If you manage multiple projects, you can inspect high-level traffic drops and JavaScript error spikes across all of them in console ▸ **Mission Control** or with `vibiz health`. The system checks each project hourly. If pageviews fall over 60% below their 7-day average, or if session replays detect a sudden spike in errors or dead clicks, the project flags an amber warning. Learn more about running automated checks in [ask your agent "how is my site doing?"](https://thelastapi.dev/blog/ask-agent-how-is-my-site-doing).

### Common error codes

If an analytics payload fails, check the HTTP response code returned by the ingestion endpoint:

| Status code | Error code | Reason | Next step |
| --- | --- | --- | --- |
| `401` | `unauthorized` | The `data-key` in your script tag is missing or incorrect. | Verify the key from `vibiz analytics snippet`. |
| `403` | `forbidden` | The request origin does not match an added domain. | Run `vibiz domains add <domain> --elsewhere`. |
| `400` | `invalid_request` | The event payload exceeds 8 KB or 30 properties. | Reduce custom event properties to scalar values. |
| `429` | `rate_limited` | Traffic or replay chunks exceeded current limits. | Read the `Retry-After` header and back off. |

To inspect complete configuration options, visit the [Analytics and replay docs](https://thelastapi.dev/docs/analytics). Create your account at [thelastapi.dev/start](https://thelastapi.dev/start) to start building.

## Frequently asked questions

### Does the analytics script slow down page loading?

No. The script uses the `defer` attribute, meaning it downloads in parallel with the document and executes only after HTML parsing is complete.

### Do I need a cookie banner to use this analytics snippet?

By default, the script stores a random string in `localStorage` rather than setting cookies, and raw IP addresses are never kept. You can also add `data-no-storage` to use daily-salted hashing instead, but you should verify your local regulatory requirements.

### How much does analytics and session replay cost?

Analytics events and session replay recordings cost $0 to record. Replay storage costs $0.023 per GB-month with the default margin (+20% today), and sessions are retained for 30 days by default.

### What happens if I forget to add my domain before deploying the tag?

Requests sent from unrecognized domains are rejected with an HTTP `403 forbidden` status code. Once you run `vibiz domains add example.com --elsewhere`, the domain is immediately permitted to send data.

---

Published 2026-11-15 · https://thelastapi.dev/blog/add-analytics-any-site-one-tag
