thelastapi
Get started free

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.

On this page 7 sections

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:

Terminal
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:

Terminal
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:

Terminal
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.

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:

JavaScript
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:

TypeScript
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:

JavaScript
vibiz('identify', user.id);

When they log out, clear the identity:

JavaScript
vibiz('identify', null);

Adding session replay without extra code

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

Terminal
vibiz add replay

Or, if starting from scratch:

Terminal
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:

JavaScript
vibiz('replay', 'start');

To stop recording in that browser session:

JavaScript
vibiz('replay', 'stop');

For a deeper dive into masking configurations, see our guide on session replay for a 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:

Terminal
vibiz analytics --period 7d

To view error-related session recordings:

Terminal
vibiz replays --errors --period 7d

From the API

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

Terminal
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?".

Common error codes

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

Status codeError codeReasonNext step
401unauthorizedThe data-key in your script tag is missing or incorrect.Verify the key from vibiz analytics snippet.
403forbiddenThe request origin does not match an added domain.Run vibiz domains add <domain> --elsewhere.
400invalid_requestThe event payload exceeds 8 KB or 30 properties.Reduce custom event properties to scalar values.
429rate_limitedTraffic 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. Create your account at 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.