@redactable/marketing-attribution-capture

Lightweight, dependency-free browser snippet that captures first-touch marketing attribution (UTM params, ad click IDs, and external referrer) into a first-party cookie.

• No dependencies, ~3 KB unminified.
• Writes the first-touch record once per visitor and never overwrites it.
• Ignores internal referrers and visitors that have already onboarded.
• Works as a plain <script> tag, via a CDN, or as an ESM/CommonJS import.

Install

npm install @redactable/marketing-attribution-capture

Usage

1. Drop-in <script> (auto-runs on load)

<script src="https://unpkg.com/@redactable/marketing-attribution-capture/marketing-attribution-capture.js"></script>

Or, if you bundle the file yourself, copy it from node_modules/@redactable/marketing-attribution-capture/marketing-attribution-capture.js.

2. ESM / bundlers

Importing the package auto-runs capture() in the browser (it is a no-op in non-browser environments such as SSR), and also exposes the function so you can control timing or override config:

import { capture } from '@redactable/marketing-attribution-capture';

// Re-run after a consent banner is accepted, with custom config:
capture({ cookieDomain: '.example.com', firstTouchKey: 'attr_first' });

3. CommonJS

const { capture } = require('@redactable/marketing-attribution-capture');
capture();

What gets stored

A JSON object (URL-encoded) is written to the first-touch cookie (default rd_attr_first, 180-day TTL):

{
  "landing_url": "https://www.redactable.com/?utm_source=google&gclid=abc",
  "referrer": "https://www.google.com/",
  "ts": "2026-06-26T20:45:00.000Z",
  "utm_source": "google",
  "gclid": "abc"
}

Tracked params include UTM (utm_*), Redactable UTM aliases (rd_u_*), and ad click IDs (gclid, gbraid, wbraid, msclkid, gad_source, gad_campaignid, fbclid, via). The cookie is only written when at least one marketing signal (a tracked param or an external referrer) is present.

Options

| Option | Default | Description | | ------------------ | ---------------------- | ----------------------------------------------------------------- | | cookieDomain | '.redactable.com' | Cookie domain attribute. | | firstTouchKey | 'rd_attr_first' | Cookie name for the first-touch record. | | cookieTtlDays | 180 | Cookie lifetime in days. | | onboardedKey | 'rd_onboarded' | If this cookie exists, capture is skipped. | | trackedParams | UTM + click IDs | Query params recorded when present. | | internalHosts | Redactable hostnames | Referrers from these hosts are ignored. | | isConsentGranted | () => true | Consent gate; capture is skipped when it returns false. |

capture(options) returns the touch object it wrote, or null when nothing was written.

License

MIT