Docs · Install

Install /v1.js.

One script tag on your site. No build step. Under 8 KB gzipped. Captures referral clicks, sets a first-party cookie, and — optionally — renders an in-product "Refer a friend" button for logged-in customers.

1. Grab your merchant handle

Your merchant handle is the identifier the widget uses to attribute clicks back to your program. It's visible on the dashboard, right under the install snippet — look for Your merchant handle. It's a short slug that looks something like lineary-a8f2.

2. Drop in the script

Paste one of the snippets below into your site. The widget loads asynchronously, so it won't block your page render.

Next.js (recommended)

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://yourherd.co/v1.js"
          data-merchant="YOUR_MERCHANT_SLUG"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Works with both the App Router and Pages Router. The afterInteractive strategy keeps the widget out of your critical rendering path.

Plain HTML / any framework

<!-- at the bottom of <body> on every page -->
<script
  src="https://yourherd.co/v1.js"
  data-merchant="YOUR_MERCHANT_SLUG"
  defer
></script>

Works in Astro, Remix, SvelteKit, Rails, Django, Laravel, Webflow — anywhere you can drop a <script> into a layout that renders on every page.

WordPress

Either paste the plain-HTML snippet into your theme's footer.php (before </body>), or use a plugin like Insert Headers and Footers and paste it in the footer slot. Avoid caching plugins that strip third-party scripts; whitelist yourherd.co if needed.

3. (Optional) Turn on the in-product share button

If you're rendering the script in a logged-in context and you know the signed-in customer's email, pass it as data-customer-email. The widget will lazy-mount a small "Refer a friend" button in the bottom-right corner of your app — only after the user's first interaction with the page.

<!-- inside your logged-in layout (server-rendered) -->
<script
  src="https://yourherd.co/v1.js"
  data-merchant="YOUR_MERCHANT_SLUG"
  data-customer-email="{{ current_user.email }}"
  defer
></script>

The email is hashed before it leaves the page; we use it to match the customer to an advocate record and generate their personal share link.

Verify it's working

Open your site in a fresh browser tab.
Open dev-tools → Network. Filter for v1.js and confirm the request succeeds.
Visit any page on your site with ?r=TEST on the URL.
Check dev-tools → Application → Cookies. You should see a herd_ref cookie set to TEST.
Refresh /app/referrals in your dashboard — the click should appear within seconds.

Troubleshooting

The script loads but I don't see clicks. Check that data-merchant matches your handle exactly — a typo or trailing space will cause the click POST to 404 silently. The handle is case-sensitive.

The cookie isn't being set. Safari's Intelligent Tracking Prevention will block third-party cookies. The widget uses a first-party cookie scoped to your own domain, so this shouldn't happen in practice — but confirm you're loading the script from the same origin as your site, not inside an iframe.

Something else. Email hello@yourherd.co with a link to a page the script is loaded on and a screenshot of your dev-tools Network tab. We respond fast.

With the widget installed, share your first link. Any ?r=TOKEN visit from a customer now flows through attribution → conversion → reward → payout automatically. Head back to the dashboard to see clicks land live.