Sight / docs

Install and verify tracking

Agent installation

After OAuth, ask your agent to call get_tracking_setup (pass project_id — from list_projects — when the account has more than one project). It returns the project name, its domain allowlist, an install-only collection key, and the exact snippet to add. The agent configures the integration for you.

The collection key starts with pk_. It can record events; it cannot read analytics or manage the account. OAuth tokens never belong in your site.

The snippet

<script defer src="https://cdn.usesight.dev/s.js" data-key="pk_..."></script>
<noscript><img src="https://cdn.usesight.dev/t.gif?k=pk_..." width="1" height="1" alt="" /></noscript>

s.js is one immutable, keyless file — the key rides on data-key, so it is cached once and served from the CDN, never re-fetched per key. Events are sent to https://api.usesight.dev by default; set data-api to override (only needed for self-hosting). Add it to your shared layout/template so it runs on every page.

window.sight.track("name", { any: "props" }) records a custom event.

Allowed domains

Because the collection key is public, set the project's allowed domains to the hostname(s) your site is served from — a bare example.com also covers www and subdomains. Events whose Origin/Referer don't match are dropped, so a copied key can't attribute traffic elsewhere. Edit the list in Dashboard → Setup → Allowed domains, or have your agent call set_project_domains. An empty list accepts any origin.

This stops honest reuse of a leaked key; a caller that forges request headers can still send events (limited by rate limiting instead).

Check the first visit

  1. Finish installing the integration.
  2. Open a page on your actual site.
  3. Open Dashboard → Setup. Sight checks incoming traffic every ten seconds.
  4. Look for Traffic received, or ask your agent to call get_live_visitors.

A traffic check confirms event ingestion. OAuth/MCP connectivity is a separate connection.

AI crawler traffic

Most crawlers do not execute JavaScript. Use a server middleware or proxy integration to forward the original User-Agent. Browser-only tracking does not promise complete crawler coverage.

Manual installation

Manual setup remains available under Dashboard → Setup. Prefer the install-only key supplied through authorized MCP. Older examples use legacy sk_ keys; those have broader permissions and should not be confused with OAuth access tokens.