Setup flow

Setup docs

Add the tracking script to your site and visitorlens will start collecting visits, page performance, and events. Each site uses its own public key.

Create a site

Add a site in the dashboard and copy its public key.

Install script

Place the tracking script in the page head or before the closing body tag.

Verify collection

Open your site once and confirm the visit in realtime or visit details.

Track events

Report forms, buttons, copies, outbound links, and other key actions.

Install tracking script

Place this snippet on the pages you want to track. Use your own site public key in production.

<script defer
  src="https://cdn.visitorlens.app/visitorlens.js"
  data-endpoint="https://t.visitorlens.app/collect"
  data-site="vl_pub_demo">
</script>

Script options

Use data attributes on the script tag to control the site key, endpoint, automatic pageviews, and debug output.

data-site="vl_pub_demo"
data-endpoint="https://t.visitorlens.app/collect"
data-auto="true"
data-debug="false"

Report custom events

Keep event names stable. Use properties for context such as plan, source page, or button location.

visitorlens.track("signup");
visitorlens.track("purchase", {
  plan: "pro",
  source_page: "/contact"
});

Debug mode

Temporarily enable data-debug so the script prints send status in the browser console. Turn it off after verification.

<script defer
  src="https://cdn.visitorlens.app/visitorlens.js"
  data-endpoint="https://t.visitorlens.app/collect"
  data-site="vl_pub_demo"
  data-debug="true">
</script>

Verify setup

Before launch, open the page once and confirm app health, Worker, and database paths from the console or local checks.

npm run check:health -- https://your-domain.com
npm run check:tracking-script
npm run check:collector-security
npm run check:remote-collector

Default collect endpoint

The script reports to the visitorlens collection endpoint by default and can later use your own domain.

https://t.visitorlens.app/collect

Setup notes

Start with core pages, then add events gradually.
Use lowercase event names with underscores.
Do not send personal data such as phone numbers or email addresses in event properties.
The public key can be exposed in the browser. The service_role key must stay in Worker Secrets.