Add tracking to a website

One script tag records pageviews, including route changes in single-page apps, and shows a consent banner. Works with any framework.

Prerequisites

• A web property and its key. See Get a project key.
• A privacy page on the site. The banner links to /privacy unless you set data-privacy-url.

1. Add the script

Paste before </body>, replacing <project key>:

<script src="https://analyticsapi.specvista.com/api/v1/sdk.js" data-api-key="<project key>" async></script>

Next.js App Router, in app/layout.tsx:

import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <footer>
          <a href="#" data-sa-consent-settings>Cookie and analytics settings</a>
        </footer>
        <Script src="https://analyticsapi.specvista.com/api/v1/sdk.js" data-api-key={process.env.NEXT_PUBLIC_SA_API_KEY} strategy="afterInteractive" />
      </body>
    </html>
  );
}

A web key is public by design, so a NEXT_PUBLIC_ variable or a literal key are both fine.

Without a key: if the property's domain is set, leave out data-api-key. The script then identifies the site by its hostname, with www. ignored.

Expected result: the page loads sdk.js with status 200, and a request to https://analyticsapi.specvista.com/api/v1/ingest returns 202.

2. Understand consent

Until a visitor chooses, and after Only essential, the script sends one pageview per route change with only the path, the referrer host, the device type and consent: "essential". These still count as pageviews in reports. Custom events and identify calls are dropped. After Accept analytics and personalisation, the script:

• stores a first-party visitor id in localStorage["sa_aid"] and the cookie _sa_aid, and a session id in sessionStorage;
• sends full events with the URL, referrer, browser, operating system, screen size, language, time zone and UTM parameters;
• adds a hashed browser fingerprint, built from canvas and font measurements, to help join visits;
• adds an _sa_x parameter to links that go to other domains registered on the same account, so a visitor moving between your sites is counted once.

Mention these in your privacy policy.

Let visitors change their choice: give any element data-sa-consent-settings, for example a footer link labelled "Cookie and analytics settings".

3. Send custom events and identify people

window.saTrack?.("checkout.completed", { plan: "pro" });
window.saIdentify?.("user_123", { email: "person@example.com", name: "Ada" });

Both only send once the visitor has accepted. The functions exist only after sdk.js has run, and calls made earlier are not queued, so use ?.. In React, call them from client components ("use client") or event handlers. For TypeScript, declare them once, for example in types/specvista.d.ts:

declare global {
  interface Window {
    saTrack?: (event: string, properties?: Record<string, unknown>) => void;
    saIdentify?: (userId: string, traits?: Record<string, unknown>) => void;
    saConsent?: { open: () => void; choice: () => "full" | "essential" | null };
  }
}
export {};

Name events object.action in lower case. Never put passwords, payment details, messages or other free text in properties.

Other globals: window.saConsent.open() reopens the banner and window.saConsent.choice() returns "full", "essential" or null. Each change fires a sa:consent event on window with detail.choice.

4. Confirm success

1. Open the site in an ordinary browser window, not a headless or automated one. Events are stored within seconds.
2. Open the property in the dashboard. While no event has arrived, the page says the property has not sent an event yet and checks again every 5 seconds.
3. Or, with a bearer token, call GET /api/v1/analytics/{projectId}/overview and check that total is above 0. See Read reports.

Common errors