Set up Lantern in two lines

Install manually#

Add a site in the dashboard to get its data-site id; the install panel there shows these snippets with your id filled in. Pick your host:

const nextConfig = {
  async rewrites() {
    return [{ source: "/_p/:path*", destination: "https://api.visitlantern.com/:path*" }];
  },
};

import Script from "next/script";

// inside <body>
<Script src="/_p/script.js" data-site="site_xxxxxxxxxxxx" data-domain="yourdomain.com" strategy="afterInteractive" />

That's the whole setup. Deploy, open your site, and the visit shows up on the dashboard and the live globe within seconds.

Why a rewrite#

Ad blockers and privacy browsers (uBlock Origin, Brave, Safari's tracking protection) block scripts from known analytics domains. On sites with a technical audience that's often 20–40% of visitors, and they vanish from your numbers without any error.

The rewrite serves Lantern from yourdomain.com/_p, which is your own domain, so there's nothing to block. The script sends its events back through the same path, so the one rule covers both. Visitor locations stay accurate: your host forwards the visitor's IP, and Lantern uses it only to look up the city.

/_p is a suggestion; any unused path works if you change it in both the rewrite and the script's src.

Check it works#

After adding the site, the dashboard's install panel waits for your first pageview and confirms it. It also tells you whether the script is being served from your domain, so you know the rewrite works.

To check by hand, open your site with the browser's developer tools on the Network tab:

Goals & events#

Pageviews, sources, time on page and scroll depth are automatic. Track the moments that matter to your business as goals; they show up in the Goals card and on the live globe.

// Goals and custom events
pulse("track", "signup", { plan: "pro" })

// Tie the anonymous visitor to your user after sign-in
pulse("identify", user.id)

// Or without JavaScript: count clicks on any element
<button data-pulse-goal="signup_click" data-pulse-plan="pro">Sign up</button>

Event names are up to 120 characters; each event takes up to 30 properties with string, number or boolean values. To call pulse() before the script has loaded (for example, from inline code at the top of the page), add the queue stub first:

<script>window.pulse = window.pulse || function () { (pulse.q = pulse.q || []).push(arguments) };</script>

Identify users#

Visitors are anonymous. When someone signs in or signs up, call identify with your own user id. Their visits from then on carry that id, alongside the anonymous visitor id from before, so you can trace what first brought each customer.

pulse("identify", user.id, { plan: "pro" })

Use an internal id rather than an email address, so no personal data is sent to Lantern.

Revenue#

Record a payment from the browser, for example on your checkout success page:

pulse("revenue", 49, "USD", { plan: "pro" })

For payments confirmed on your server, pass pulse.visitorId() to your payment provider (for example as Stripe checkout metadata) so the payment can be tied back to the visit. Automatic Stripe attribution is on the roadmap.

Subdomains#

With data-domain="yourdomain.com" on the script (the install snippet includes it), the visitor id is stored in a cookie shared by all your subdomains. Someone who reads your blog on yourdomain.com and signs up on app.yourdomain.com is counted as one person with one source. Add the same script, with the same data-site, on every subdomain.

Single-page apps#

Client-side navigation in Next.js, React Router, Vue Router, SvelteKit and similar is tracked automatically: Lantern listens to the browser's history changes and records a pageview for each new URL. No router integration is needed.

AI crawlers#

GPTBot, ClaudeBot, PerplexityBot and other crawlers never run JavaScript, so the script can't see them. To find out which pages AI tools read, report crawler requests from your server. The install panel in the dashboard has a ready-made Next.js snippet with your site's secret; for other servers, send requests from crawler user agents to:

POST https://api.visitlantern.com/api/bot
Authorization: Bearer <your site's bot secret>
Content-Type: application/json

{ "ua": "<user-agent>", "url": "<full page URL>", "ip": "<client IP>" }

Up to 500 hits per request as a JSON array. Human user agents are ignored, so it's safe to over-send.

Script attributes#

JavaScript API#

Privacy & data#

• One first-party cookie, _pulse_vid, holds a random visitor id on your own domain. There are no third-party cookies and no tracking across other websites.
• IP addresses are used once, when the event arrives, to look up the city and network, and are never stored. Locations are approximate (mobile carriers in particular often resolve to a nearby city).
• Automated browsers are skipped, and known bots are kept out of visitor counts.
• Events are stored on Google Cloud in the United States.

IP geolocation by DB-IP

Troubleshooting#