224-industries/form-attribution

Form Attribution

A lightweight, zero-dependency script that automatically captures marketing attribution data and injects it into forms as hidden fields.

| Resource | Link/URL | |------------|-------------------------------------------------------------------------------------------| | CDN URL| https://cdn.jsdelivr.net/npm/form-attribution@latest/dist/script.min.js | | Docs | https://form-attribution.flashbrew.digital/docs | | GitHub | https://github.com/Flash-Brew-Digital/form-attribution |

Basic Implementation

Add before the closing </body> tag:

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

The script automatically captures UTM parameters, stores them in sessionStorage, and injects hidden fields into all forms.

Configuration Options

Configure via data attributes on the script tag:

| Attribute | Default | Description | |-----------|---------|-------------| | data-storage | sessionStorage | sessionStorage, localStorage, or cookie | | data-field-prefix | "" | Prefix for hidden field names (e.g., attr_) | | data-extra-params | "" | Additional URL parameters to capture (comma-separated) | | data-exclude-forms | "" | CSS selector for forms to exclude | | data-click-ids | false | Capture ad platform click IDs (gclid, fbclid, etc.) | | data-debug | false | Enable debug panel overlay | | data-privacy | true | Respect GPC/DNT privacy signals | | data-storage-key | form_attribution_data | Custom storage key name |

Cookie-specific options (when 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 | lax, strict, or none |

What Gets Captured

URL Parameters (default): utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_id, ref

Metadata (automatic): landing_page, current_page, referrer_url, first_touch_timestamp

Click IDs (when data-click-ids="true"): gclid (Google), fbclid (Meta), msclkid (Microsoft), ttclid (TikTok), li_fat_id (LinkedIn), twclid (Twitter/X)

Common Configurations

With ad click ID tracking:

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

Cross-subdomain tracking (cookies):

<script src="https://cdn.jsdelivr.net/npm/form-attribution@latest/dist/script.min.js"
  data-storage="cookie"
  data-cookie-domain=".example.com"
  data-cookie-expires="90"
  data-click-ids="true" defer></script>

CRM field prefix:

<script src="https://cdn.jsdelivr.net/npm/form-attribution@latest/dist/script.min.js"
  data-field-prefix="lead_"
  data-click-ids="true" defer></script>

Exclude forms (e.g., search, login):

<script src="https://cdn.jsdelivr.net/npm/form-attribution@latest/dist/script.min.js"
  data-exclude-forms=".no-track, #login-form, [data-no-attribution]" defer></script>

JavaScript API

The library exposes a global FormAttribution object:

FormAttribution.getData();              // Get all captured data
FormAttribution.getParam('utm_source'); // Get specific parameter
FormAttribution.getForms();             // Get tracked forms
FormAttribution.clear();                // Clear stored data
FormAttribution.refresh();              // Re-inject into forms

Privacy

Respects Global Privacy Control (GPC) and Do Not Track (DNT) by default. When detected, no data is captured. Override with data-privacy="false".

References (references/*)

Platform-Specific Patterns

For implementation patterns specific to Webflow, HubSpot, WordPress, Marketo, and certain other platforms, see references/platforms.md.

FAQ

For common questions about compatibility, privacy, performance, and customization, see references/faq.md.