Docs
Install the tracker
Peregrine needs one script tag on every page of your site. Sign up and add your domain first: the dashboard shows the tag with your domain already filled in.
<script defer src="https://justperegrine.com/js/peregrine.js" data-site="your-domain.com"></script>Keep it a plain <script> tag with defer, exactly as written. There is no npm package. The script is about 1.3 KB and loads without blocking the page.
Where it goes
Put it once, wherever your project renders the shared <head>:
| Project | File |
|---|---|
| Next.js, App Router | app/layout.tsx, inside <head> |
| Next.js, Pages Router | pages/_document.tsx, inside <Head> |
| Vite, React, Vue, plain HTML | index.html |
| Astro, SvelteKit, Nuxt | The base layout, or app.html in SvelteKit |
| WordPress | The theme header, or any plugin that inserts code into the head |
| Webflow, Framer, Carrd | Site settings, custom code in the head |
In Next.js, write it as a plain <script> element rather than next/script. A plain tag is the form the tracker is tested in, and it needs nothing from React.
Let a coding agent do it
If you use Claude Code, Cursor or a similar tool, paste this prompt into it instead. It adds the tag and also finds your checkout, which is the step that makes revenue attribution work. The dashboard shows the same prompt with your domain filled in.
Install Peregrine analytics on this project. The site's domain is your-domain.com.
1. Add this tag to the <head> of every page, exactly once, wherever this project renders shared <head> content (the root layout in Next.js App Router, pages/_document in the Pages Router, index.html in Vite, the base layout in Astro, SvelteKit or Nuxt, the theme header in WordPress):
<script defer src="https://justperegrine.com/js/peregrine.js" data-site="your-domain.com"></script>
Keep it a plain <script> tag with defer, src and data-site exactly as written. Do not npm-install, bundle or self-host it.
2. If this site sells anything, find how a buyer reaches checkout, so each sale is credited to the channel that brought the buyer. The tracker keeps a visitor id in localStorage and in a cookie named peregrine_vid.
- Plain <a href> links to Polar (polar.sh), Stripe (buy.stripe.com, checkout.stripe.com), Lemon Squeezy (*.lemonsqueezy.com) or Dodo Payments (checkout.dodopayments.com) are tagged automatically. Leave them as real links: a checkout opened with window.location or window.open from a click handler is not tagged.
- A checkout link on the site's own domain (for example buy.your-domain.com) is not recognised. Add data-checkout to the tag naming the host and that processor's reference parameter, e.g. data-checkout="buy.your-domain.com:checkout[custom][reference_id]". The parameter is reference_id for Polar, client_reference_id for Stripe, checkout[custom][reference_id] for Lemon Squeezy, metadata_reference_id for Dodo Payments.
- A checkout session created on the server must read the peregrine_vid cookie from the incoming request and attach it: metadata.reference_id for Polar, checkout_data.custom.reference_id for Lemon Squeezy, metadata.reference_id for Dodo Payments, client_reference_id for Stripe. If the cookie is missing, create the checkout as before.
3. Change nothing else. When you are done, list the files you changed and, for each checkout path you found, which of the three cases above it was and what you did.Single-page apps
Nothing extra to do. The tracker notices route changes made with the History API, which is what Next.js, React Router, Vue Router and SvelteKit use, and counts each one as a pageview.
Check that it works
- Open your site in a normal browser window.
- Go back to the dashboard. During setup it waits for that first pageview and moves on by itself. After setup, your visit shows under Right now.
Nothing showing up? Check these, in order:
- The domain matches.
data-sitemust be the domain you added in the dashboard.www.is ignored on both sides. Events for a domain nobody added are dropped without an error. - The page was served, not opened from disk. A
file://page sends nothing. Run a local server or check the deployed site. - It is not an automated browser. Playwright, Puppeteer and Selenium set
navigator.webdriver, and the tracker stays silent there on purpose. - An ad blocker is not blocking the script. Try a private window with extensions off.
Script attributes
| Attribute | What it does |
|---|---|
data-site | The domain you registered. Required. |
data-checkout | Checkout hosts the tracker would not recognise by itself, such as a checkout on your own domain. See revenue attribution. |
More docs
- Revenue attribution
- Goals and custom events
- Sale notifications on Telegram
- How channels are decided
- Bots and filtering
- What is collected
- Peregrine for Polar
- Peregrine for Lemon Squeezy
- Peregrine for Dodo Payments
Something missing? Write to us from the footer. Or see a real dashboard in the demo, or start a free trial.