Set up with your agent

Open Connect agent in the dashboard, choose Copy setup prompt, and paste it into your coding agent. You do not need to add the site first. The agent works out the domain your project is served from, finds that site in your workspace or creates it, installs tracking, and tests its MCP connection. The dashboard confirms when events arrive. Keep the prompt private: it contains access keys.

The prompt names no site, so the same one works in every project in your workspace. There are no IDs or keys to substitute manually. If the agent cannot tell your production domain, or finds a site that looks like the same product under a slightly different hostname, it asks you before creating anything. It places the tracker in the shared layout and checks for a duplicate installation. Deploy the resulting changes to begin collecting visits. Custom conversions still need explicit events.

Manual installation

Create an account at the dashboard and add a site. Its id is listed under Workspaces. Put it in this tag and place the tag in your site's shared layout.

<script defer src="https://app.stepmetrics.co/t.js" data-site="YOUR_SITE_ID"></script>

The site id is public by design. It grants write-only access: it can add events and never read them. Reading requires an API key, which is stored only as a sha256 hash.

Script tag options

The one cookie

The tracker sets one first-party cookie, stepmetrics_id, on your site's own host. It holds a random id and nothing about the visitor. It is there so a later visit from the same browser can be counted as a return, for the returning visitors figures. It lasts 400 days, the longest a browser keeps a cookie, and is renewed on each visit. Safari keeps a cookie set by a script for at most 7 days, so there a browser that stays away longer than a week is counted as new when it returns. It is SameSite=Lax, Secure on https, and never sent to any other domain, ours included.

To run without it, add data-cookieless to the script tag: no cookie is written, no id is sent, and one an earlier tag left is removed. Separately, the visitorCookie setting on the site decides whether an id that arrives is stored; turned off, it is dropped on arrival. Your daily visitor counts do not use the cookie and are the same either way.

The device fingerprint

Alongside the cookie, the tracker reads what the device reports about itself and sends it with each visit: screen size, colour depth and pixel ratio, time zone, languages, platform, processor cores, memory, touch support, graphics card, which of a list of common fonts are installed, and a hash of how the device draws a test image. From the details that stay the same between visits it makes one id, the fingerprint. Nothing is stored on the device for it.

The fingerprint recognises a visitor whose cookie was blocked, cleared or has expired, including Safari's 7-day limit. It is a likely match, not an exact one: two identical devices with the same settings have the same fingerprint. So the Visitors page keeps it apart from the cookie. A visitor with no cookie is listed by device, and a new cookie on a device seen before is marked Likely returning rather than Returning. The returning visitors figures use the cookie only.

It is on by default. Add data-no-fingerprint to the script tag to stop it being sent, or turn off the visitorFingerprint setting to drop it on arrival. Whether your visitors must agree to it first depends on where they are, and is yours to decide: if you use a consent tool, load the StepMetrics tag through it.