🧭 React UTM Tracker

Lightweight, privacy-compliant React library for capturing and managing UTM parameters easily.

✨ Features

✅ Automatically detects and stores UTM parameters (utm_source, utm_medium, utm_campaign, etc.)
✅ Lightweight — <5 KB gzipped, no external dependencies
✅ Privacy-safe (Secure; SameSite=Lax cookies, consent-aware)
✅ Works with any React app (React 17+)
✅ Easy to integrate — just wrap your app with <UTMProvider>
✅ Customizable capture keys, expiry, and consent control
✅ API utilities: useUTM() and deleteUTMCookie()

🚀 Installation

# npm
npm install react-utm-tracker

# yarn
yarn add react-utm-tracker

# pnpm
pnpm add react-utm-tracker

⚡ Quick Start

1️⃣ Wrap your app with the provider

import { UTMProvider } from "react-utm-tracker";
import MainApp from "./MainApp";

function App() {
  return (
    <UTMProvider>
      <MainApp />
    </UTMProvider>
  );
}

export default App;

2️⃣ Access UTMs anywhere in your app

import { useUTM } from "react-utm-tracker";

function Dashboard() {
  const utm = useUTM();

  return (
    <div>
      <h3>User UTM Data</h3>
      <pre>{JSON.stringify(utm, null, 2)}</pre>
    </div>
  );
}

3️⃣ Clear UTM cookies when needed

import { deleteUTMCookie } from "react-utm-tracker";

function LogoutButton() {
  return (
    <button onClick={() => deleteUTMCookie()}>
      Clear All UTM Data
    </button>
  );
}

⚙️ Configuration (Props for <UTMProvider>)

| Prop | Type | Default | Description | | ----------------- | ----------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------ | | captureParams | string[] | ['utm_source','utm_medium','utm_campaign','utm_term','utm_content'] | Whitelisted URL parameters to capture. | | cookieExpiryDays| number | 30 | Number of days before cookies expire. | | requireReferrer | boolean | false | Capture UTMs only if the visitor came from another referrer. | | requireConsent | boolean | false | Enables GDPR-style consent check; no cookies are set until granted.| | consentGiven | boolean | true | Whether user consent has been granted (used with requireConsent).|

🧩 Example – Full Custom Configuration

Here's an example of how to implement a consent banner and customize the provider.

import { useState } from 'react';
import { UTMProvider, useUTM, deleteUTMCookie } from "react-utm-tracker";

// A simple banner to get user consent
function ConsentBanner({ onAccept }) {
  return (
    <div className="consent-banner">
      <p>We use cookies to track marketing performance.</p>
      <button onClick={onAccept}>Accept</button>
    </div>
  );
}

export default function App() {
  const [consent, setConsent] = useState(false);

  return (
    <>
      {!consent && <ConsentBanner onAccept={() => setConsent(true)} />}
      <UTMProvider
        captureParams={['utm_source', 'utm_medium', 'utm_campaign']}
        cookieExpiryDays={14}
        requireReferrer={true}
        requireConsent={true}
        consentGiven={consent}
      >
        <MainApp />
      </UTMProvider>
    </>
  );
}

function MainApp() {
  const utm = useUTM();

  return (
    <div>
      <h2>Captured UTMs:</h2>
      <pre>{JSON.stringify(utm, null, 2)}</pre>
      <button onClick={() => deleteUTMCookie(['utm_source'])}>
        Delete Only utm_source
      </button>
    </div>
  );
}

🔧 API Reference

🧱 UTMProvider

The main provider component that wraps your app and automatically detects UTMs from the URL.

<UTMProvider
  captureParams={['utm_source', 'utm_campaign']}
  cookieExpiryDays={30}
  requireReferrer={false}
  requireConsent={true}
  consentGiven={cookieConsent}
>
  {children}
</UTMProvider>

🪣 useUTM()

A React hook that returns an object of the stored UTM key-value pairs.

const utm = useUTM();

console.log(utm);
/*
{
  utm_source: "google",
  utm_medium: "cpc",
  utm_campaign: "spring_sale"
}
*/

🧹 deleteUTMCookie(names?: string[])

A utility function to delete UTM cookies.

| Usage | Description | | --------------------------------- | -------------------------------------------- | | deleteUTMCookie() | Deletes all UTM cookies set by this library. | | deleteUTMCookie(['utm_source']) | Deletes only the specified UTM cookies. |

Cookies are removed securely with path=/; SameSite=Lax; Secure.

🛡️ Privacy & Compliance

✅ GDPR-ready: No cookies are set until consent is given when using requireConsent={true}.
✅ CCPA/LGPD: Supports user-initiated data deletion via deleteUTMCookie().
✅ Security: Cookies are set with Secure and SameSite=Lax flags by default.
✅ Transparency: All cookies created by this library are prefixed with utm_ for easy identification.

📦 Storage & Persistence

• Default storage: Cookies.
• Each cookie name is the same as the UTM parameter (e.g., utm_source, utm_medium).
• Expiry is controlled via the cookieExpiryDays prop on the provider.

🧠 Common Use-Cases

• Persist UTM parameters across a user's session to attribute sign-ups or purchases.
• Send UTM data with form submissions to your backend.
• Forward UTM data to analytics, CRM, or payment provider payloads.
• Attribute marketing campaign effectiveness in custom internal dashboards.
• Respect user privacy regulations out-of-the-box with consent management.

🧪 Local Testing

If you have cloned the repository and want to test it locally:

1. Install dependencies:

   npm install

2. Build the library:

   npm run build

3. Navigate to the test application:

   cd test-app
   npm run dev

4. Then open the following URL in your browser to see the UTM parameters captured:

   👉 http://localhost:<your-localhost-port>/?utm_source=google&utm_medium=cpc&utm_campaign=demo

📜 License

MIT © 2025 Debangan Paul Chowdhury

Feel free to use, modify, and distribute.

❤️ Contributing

Contributions, issues, and feature requests are welcome! Please feel free to open issues or pull requests on the GitHub repository.