Pimms analytics script is a lightweight (~1kb), open-source client-side tracking library that handles conversion attribution automatically. It detects click IDs, injects tracking parameters into third-party embeds, and stores attribution cookies — all with a single script tag.
This guide covers every configuration option available in @getpimms/analytics, from basic setup to advanced reverse proxy configurations for ad-blocker bypass.
1. Quick start
Add this single script tag to your site's <head>:
<script
defer
src="https://cdn.pimms.io/analytics/script.detection.js"
data-domains='{"outbound": "tally.so,cal.com"}'>
</script>Replace the outbound domains with the third-party services you use (e.g. tally.so, cal.com, buy.stripe.com).
Using a custom PIMMS domain? Add it to the list:
<script
defer
src="https://cdn.pimms.io/analytics/script.detection.js"
data-domains='{"refer": "go.yourdomain.com", "outbound": "tally.so,cal.com"}'>
</script>2. Available script bundles
All scripts are available via CDN at https://cdn.pimms.io/analytics/.
For most integrations, use script.detection.js. It gives you everything in one script tag.
3. Domain configuration (data-domains)
Configure domains and features via a single JSON object passed as data-domains:
<script
defer
src="https://cdn.pimms.io/analytics/script.detection.js"
data-domains='{
"refer": "go.example.com",
"site": "site.example.com",
"outbound": "tally.so,cal.com,buy.stripe.com",
"embed": {
"attributes": ["data-tally-src", "data-cal-link"]
},
"thank-you": "https://pim.ms/your-thank-you-link"
}'>
</script>Outbound domains
When outbound is configured, all <a> links whose href matches one of the listed domains automatically get ?pimms_id=... appended. This enables cross-domain tracking without manual URL changes.
Embed support
The embed extension auto-appends pimms_id to embed widget attributes and inside <iframe srcdoc="..."> content, for any URL matching an outbound domain.
Default target attributes: data-cal-link and data-tally-src
To add custom attributes:
<script
defer
src="https://cdn.pimms.io/analytics/script.detection.js"
data-domains='{
"outbound": "tally.so,cal.com",
"embed": {
"attributes": ["data-tally-src", "data-cal-link", "data-custom-src"]
}
}'>
</script>Thank-you page tracking
When enabled, the script fires a one-time GET fetch to a PIMMS short link on pages under /thanks/. This triggers a conversion event server-side.
The fetch fires once per /thanks/* path per browser session (deduplicated via sessionStorage).
4. Automatic ID detection
The detection bundle automatically replaces placeholder values in links to official integrations:
It also replaces any existing pimms_id=1 placeholders in links with the real pimms_id value.
Forward to same-domain links
To append pimms_id to all same-domain links as well:
<script
defer
src="https://cdn.pimms.io/analytics/script.detection.js"
data-forward-all="true">
</script>5. Attribution model
Choose which touchpoint receives conversion credit:
<script
defer
src="https://cdn.pimms.io/analytics/script.detection.js"
data-attribution-model="first-click">
</script>6. Cookie options
Customize the cookie behavior for tracking:
<script
defer
src="https://cdn.pimms.io/analytics/script.detection.js"
data-cookie-options='{"expiresInDays": 60}'>
</script>7. Anti ad-blocker: reverse proxy setup
Ad-blockers may block requests to cdn.pimms.io or api.pimms.io. Set up a reverse proxy to route tracking through your own domain.
Step 1: Proxy the script
Route the script through your domain so it's not blocked.
Next.js (next.config.js):
module.exports = {
async rewrites() {
return [
{
source: "/_proxy/pimms/script.js",
destination: "https://cdn.pimms.io/analytics/script.detection.js",
},
];
},
};Vercel (vercel.json):
{
"rewrites": [
{
"source": "/_proxy/pimms/script.js",
"destination": "https://cdn.pimms.io/analytics/script.detection.js"
}
]
}Step 2: Proxy the API
Route tracking API calls through your domain:
Next.js (next.config.js):
module.exports = {
async rewrites() {
return [
{
source: "/_proxy/pimms/script.js",
destination: "https://cdn.pimms.io/analytics/script.detection.js",
},
{
source: "/_proxy/pimms/track/:path",
destination: "https://api.pimms.io/track/:path",
},
];
},
};Vercel (vercel.json):
{
"rewrites": [
{
"source": "/_proxy/pimms/script.js",
"destination": "https://cdn.pimms.io/analytics/script.detection.js"
},
{
"source": "/_proxy/pimms/track/:path",
"destination": "https://api.pimms.io/track/:path"
}
]
}Step 3: Update the script tag
Point to your proxy instead of the CDN:
<script
defer
src="/_proxy/pimms/script.js"
data-api-host="/_proxy/pimms">
</script>8. React / Next.js integration
Install the npm package as an alternative to the CDN script tag:
npm install @getpimms/analyticsBasic setup:
import { Analytics as PimmsAnalytics } from "@getpimms/analytics/react";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
<PimmsAnalytics
domainsConfig={{
refer: "go.example.com",
outbound: "tally.so,cal.com",
}}
/>
</html>
);
}With reverse proxy:
<PimmsAnalytics
apiHost="/_proxy/pimms"
scriptProps={{ src: "/_proxy/pimms/script.js" }}
domainsConfig={{
refer: "go.example.com",
outbound: "tally.so,cal.com",
}}
/>With custom options:
<PimmsAnalytics
attributionModel="first-click"
cookieOptions={{ expiresInDays: 60 }}
domainsConfig={{
refer: "go.example.com",
outbound: "tally.so,cal.com",
}}
/>9. Standalone scripts
These scripts work independently (no base tracking required):
script.expose.js
Reads pimms_id from cookies or URL and exposes it as window.pimms_id. Useful for server-side integrations or custom tracking code.
<script src="https://cdn.pimms.io/analytics/script.expose.js"></script>
<script>
console.log(window.pimms_id);
</script>script.inject-form.js
Injects a hidden <input name="pimms_id"> into all <form> elements on the page. Watches for dynamically added forms via MutationObserver.
<script src="https://cdn.pimms.io/analytics/script.inject-form.js"></script>Use this alongside script.detection.js on sites with native forms (Framer, Webflow, WordPress/Elementor) to automatically capture pimms_id in form submissions.
10. Full example
A complete script tag with detection, outbound domains, embed support, thank-you page, custom attribution, and cookie settings:
<script
defer
src="https://cdn.pimms.io/analytics/script.detection.js"
data-domains='{
"refer": "go.example.com",
"site": "site.example.com",
"outbound": "tally.so,cal.com,buy.stripe.com",
"thank-you": "https://pim.ms/your-thank-you-link"
}'
data-attribution-model="last-click"
data-cookie-options='{"expiresInDays": 60}'
data-query-param="via">
</script>This single tag enables: click tracking, outbound link tracking, embed support for Tally/Cal.com, automatic ID detection for Stripe/Cal.com/iClosed, thank-you page conversion callbacks, and custom attribution settings.
FAQs
Is the Pimms analytics script open source?
Yes! The script is fully open source and available on GitHub. You can audit the code, contribute, or fork it for your own use.
How large is the script?
The script is approximately 1kb gzipped, making it one of the lightest analytics scripts available. It has zero impact on your site's performance.
Does the script work with Single Page Applications (SPAs)?
Yes. The script handles route changes in SPAs automatically. For React/Next.js apps, use the npm package for the best integration experience.
Can I use multiple script bundles together?
Yes! script.expose.js and script.inject-form.js are standalone and can be used alongside script.detection.js. For example, use script.detection.js for tracking and script.inject-form.js for form field injection on the same page.
It starts here
If you made it this far, it's time to grab 10 free links.
10 smart links included • No credit card
