Quick start
Add a site, install the browser part and the server part, and see your first agent visit.
On this page
From nothing to your first agent visit. Each step links to the page with the details.
1. Add your site
Create an account at app.parlox.io and add your site by its domain. You get two keys:
- a public key (
pk_…) for the browser part. It is safe in the browser: it can only send data, never read any; - a secret key (
sk_parlox_…) for the server part, with access "Crawler reports only". It is shown once, so copy it now. It goes inPARLOX_SECRET_KEYon your server, never in browser code or in git.
The site's settings also show a verification token for PARLOX_VERIFY_TOKEN, which proves you own the domain (Verifying the domain). More on the kinds of key: Keys and access.
2. The fastest route: the wizard
For Next.js, Vite React, Express or Hono, run this in your project and follow it:
npx parlox initIt signs you in, lets you pick the site, shows every change as a diff before it writes anything, adds the browser part and the server part, and on a linked Vercel project sets the key for you. The install wizard says what it changes and how to undo it. If you used it, skip to step 5.
3. Add the browser part
With a build step (React, Next.js, Vue, any bundler), install the package and start it once:
npm install @parlox/browserimport { init } from "@parlox/browser";
init({ publicKey: "pk_…" });React and Next.js can render <ParloxAnalytics publicKey="pk_…" /> from @parlox/browser/react in the root layout instead (The npm package).
Without a build step (Shopify themes, WordPress, plain HTML), paste the pinned tag into the <head> of every page (The pinned script tag):
<script async src="https://gateway.parlox.io/sdk/1.0.3/parlox.js" integrity="sha384-naJsIFbLpeBsYg6qCN51Tt54BEFhO4MDhTMmrGP4Ja/nXjrfUziCot/3mHbhqCb+" crossorigin="anonymous" data-key="pk_…"></script>4. Add the server part
Fetchers never run JavaScript, so only your server sees them. On Next.js, Express, Hono and other Node or edge servers, install @parlox/server and add one line; on any other stack, send one HTTP call per automated request (The server part). Next.js, for example:
npm install @parlox/serverimport { withParlox } from "@parlox/server/next";
export default withParlox();
export const config = {
// Pages, robots.txt, llms.txt, sitemaps and the ownership check; not static assets or API routes.
matcher: ["/((?!_next/static|_next/image|api/|favicon.ico|.*\\.(?:png|jpe?g|gif|svg|webp|avif|ico|css|js|map|woff2?)$).*)"],
};Set the two variables on your host:
PARLOX_SECRET_KEY=sk_parlox_…
PARLOX_VERIFY_TOKEN=…Behind nginx, pass the client's address to your app (Behind nginx). A site whose built files are served as they are, by nginx or a static host, gets no server part, except on Vercel, where Routing Middleware fills that role. The browser part still sees people and browser agents; here is what it cannot see.
5. Deploy and check
Deploy, then ask for a page the way ChatGPT's fetcher would:
curl -A "ChatGPT-User/1.0" https://your-site.example/Within about ten seconds the site's dashboard shows a visit from ChatGPT. It is labelled self-declared, not verified: the request came from your machine, not from one of OpenAI's published addresses (How a visitor is identified).
On a site with no server part (built files served by nginx or a static host), this request reaches no Parlox code and nothing appears: check with a normal browser visit instead.
Then open your site in a normal browser: a person's visit appears too.
6. Next steps
- Verify the domain. Collection does not wait for it, but the weekly page checks and the control map do.
- Send cart and checkout events and purchases from your server, so each visit shows what it led to.
- Read what is collected before you go live.