peregrine
DocsDemoGet started

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

ProjectFile
Next.js, App Routerapp/layout.tsx, inside <head>
Next.js, Pages Routerpages/_document.tsx, inside <Head>
Vite, React, Vue, plain HTMLindex.html
Astro, SvelteKit, NuxtThe base layout, or app.html in SvelteKit
WordPressThe theme header, or any plugin that inserts code into the head
Webflow, Framer, CarrdSite 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

  1. Open your site in a normal browser window.
  2. 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-site must 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

AttributeWhat it does
data-siteThe domain you registered. Required.
data-checkoutCheckout 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.

peregrine
DemoDocsIntegrationsCompareUTM builderSign in
© 2026
TermsPrivacyDPA

Contact us

Something is broken or wrong

hello@justperegrine.com
Featured onFeatured on DanielLaunchesLaunched on LaunchPanda