Get started

Quick start

Add a site, install the browser part and the server part, and see your first agent visit.

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 in PARLOX_SECRET_KEY on 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:

Terminal
npx parlox init

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

Terminal
npm install @parlox/browser
Entry file
import { 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):

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

Terminal
npm install @parlox/server
middleware.ts (in src/ when the app uses one; proxy.ts in Next.js 16)
import { 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:

.env
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:

Terminal
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