Form Attribution

A lightweight, zero-dependency script that automatically captures and passes the referrer, UTM parameters, ad click IDs, and more to your forms as hidden fields.

Try the Script Builder | View Documentation

Features

• Zero dependencies - Runs entirely on native browser APIs with no external libraries
• Automatic capture - Records UTM parameters, referrer URL, landing page, timestamp and more without manual setup
• Persistent storage - Maintains attribution data across sessions using intelligent storage fallbacks
• Form injection - Automatically adds hidden fields to every form on the page
• Dynamic form support - Monitors the DOM via MutationObserver to handle forms added after page load
• First-touch attribution - Retains original attribution data even when users return later
• Privacy-respecting - Complies with Global Privacy Control (GPC) and Do Not Track (DNT) preferences
• XSS-safe - Sanitizes all injected values to prevent cross-site scripting attacks
• Debug panel - Visual overlay for inspecting attribution data, forms, and activity in real-time
• JavaScript API - Programmatic access via window.FormAttribution for custom integrations

Quick Start

Add the script to your website before the closing </body>tag:

<script src="https://cdn.jsdelivr.net/npm/form-attribution@latest/dist/script.min.js"></script>

That's it! The script will automatically:

1. Capture common URL parameters and metadata (e.g. landing page)
2. Store the data in the user's browser temporarily
3. Inject hidden fields into all forms on the page

Parameters Captured

URL Parameters (default)

Parameter	Description
utm_source	Traffic source (e.g., google, newsletter)
utm_medium	Marketing medium (e.g., cpc, email)
utm_campaign	Campaign name
utm_term	Paid search keywords
utm_content	Content variant for A/B testing
utm_id	Campaign ID
ref	Referrer tracking parameter

Metadata (automatically captured)

Parameter	Description
landing_page	First page URL visited
current_page	Current page URL (where form was submitted)
referrer_url	Document referrer
first_touch_timestamp	ISO 8601 timestamp of first visit

Click ID Parameters (when data-click-ids="true")

Parameter	Platform
gclid	Google Ads
fbclid	Meta Ads
msclkid	Microsoft Advertising
ttclid	TikTok Ads
li_fat_id	LinkedIn Ads
twclid	Twitter/X Ads

Configuration

Configure the script by adding optional data attributes to the script tag:

<script src="/dist/script.min.js"
  data-storage="localStorage"
  data-field-prefix="attr_"
  data-extra-params="gclid,fbclid"
  data-exclude-forms=".no-track"
  data-debug="true">
</script>

Options

Attribute	Default	Description
data-storage	sessionStorage	Storage method: sessionStorage, localStorage, or cookie
data-field-prefix	""	Prefix for hidden field names (e.g., attr_ creates attr_utm_source)
data-extra-params	""	Comma-separated list of additional URL parameters to capture
data-exclude-forms	""	CSS selector for forms to exclude from injection
data-storage-key	form_attribution_data	Custom key name for stored data
data-debug	false	Enable console logging and debug panel
data-privacy	true	Set to "false" to disable GPC/DNT privacy signal detection
data-click-ids	false	Set to "true" to automatically capture ad platform click IDs

Cookie Options

When using data-storage="cookie":

Attribute	Default	Description
data-cookie-domain	""	Cookie domain (e.g., .example.com)
data-cookie-path	/	Cookie path
data-cookie-expires	30	Expiration in days
data-cookie-samesite	lax	SameSite policy: lax, strict, or none

Usage Examples

Use localStorage for Longer Persistence

<script src="/dist/script.min.js"
  data-storage="localStorage">
</script>

Use Cookies for Cross-Subdomain Tracking

<script src="/dist/script.min.js"
  data-storage="cookie"
  data-cookie-domain=".example.com"
  data-cookie-expires="90">
</script>

Exclude Specific Forms

<script src="/dist/script.min.js"
  data-exclude-forms=".login-form, [data-no-attribution]">
</script>

Add Field Prefix for CRM Compatibility

<script src="/dist/script.min.js"
  data-field-prefix="lead_">
</script>

Script Builder

Use the interactive Script Builder tool to generate a configured script tag with a visual interface.

Storage Fallback Chain

The script uses intelligent fallbacks when a storage type isn't available:

Requested	Fallback Chain
localStorage	localStorage → sessionStorage → cookie → memory
sessionStorage	sessionStorage → cookie → memory
cookie	cookie → memory

Privacy

By default, the script respects user privacy preferences:

• Global Privacy Control (GPC) - Disables tracking when navigator.globalPrivacyControl is true
• Do Not Track (DNT) - Disables tracking when DNT is enabled

When privacy signals are detected, no data is captured or stored. You can override this behavior by setting data-privacy="false" on the script tag.

JavaScript API

Form Attribution exposes a global FormAttribution object for programmatic access:

// Get all attribution data
const data = FormAttribution.getData();

// Get a specific parameter
const source = FormAttribution.getParam('utm_source');

// Get tracked forms with their status
const forms = FormAttribution.getForms();

// Clear all stored data
FormAttribution.clear();

// Re-inject data into forms
FormAttribution.refresh();

// Register event callbacks (supports multiple listeners)
FormAttribution.on('onReady', ({ data, config }) => {
  console.log('Attribution ready:', data);
});

// Remove a callback
FormAttribution.off('onCapture', myHandler);

Available Methods

Method	Returns	Description
getData()	Object|null	Get all captured attribution data
getParam(name)	string|null	Get a specific parameter value
getForms()	Array	Get list of forms with their status
clear()	void	Clear all stored attribution data
refresh()	void	Re-inject data into all forms
on(event, cb)	Object	Register event callback (chainable)
off(event, cb)	Object	Unregister a callback (chainable)

Events

Event	Payload	Description
onReady	{ data, config }	Fired when initialization is complete
onCapture	{ data }	Fired when new data is captured
onUpdate	{ data }	Fired when data is updated

Debug Panel

Enable the debug panel by adding data-debug="true" to the script tag:

<script src="/dist/script.min.js" data-debug="true"></script>

The debug panel provides:

• Data Tab - View all captured UTM parameters and metadata
• Forms Tab - See all forms and their injection status (click to highlight)
• Log Tab - Real-time activity log with timestamps
• Actions - Copy data to clipboard, clear storage, refresh forms

The panel is draggable, collapsible, and its state persists across page reloads. Uses Shadow DOM for style isolation.

Note: Remove data-debug before deploying to production.

Injected Fields

Hidden fields are injected with the following attributes:

<input type="hidden"
  name="utm_source"
  value="google"
  data-form-attribution="true"
  data-form-attribution-managed="true">

• Existing hidden fields with matching names are updated (no duplicates created)
• User-visible form fields are never modified
• All values are HTML-entity encoded for XSS protection

Development

Prerequisites

• Node.js
• pnpm

Setup

pnpm install

Commands

pnpm test                         # Run Playwright tests (Chromium, Firefox, WebKit)
pnpm exec playwright test --ui    # Run tests with interactive UI
pnpm check                        # Lint with Biome
pnpm fix                          # Auto-fix lint issues

Browser Support

Built on standard browser APIs with graceful fallbacks for broad compatibility:

• URL API — Parses query parameters
• MutationObserver — Detects dynamically added forms
• Web Storage API — Persists data via sessionStorage and localStorage
• CookieStore API — Falls back to document.cookie for older

Documentation

Complete documentation is available at https://form-attribution.flashbrew.digital/docs.

License

Apache-2.0

---

Built by Ben Sabic at Flash Brew Digital | GitHub