Documentation

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

Data Attributes

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>

Storage Options

Choose where attribution data is persisted between page loads:

Session Storage (default)

Data persists for the browser session only.

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

Local Storage

Data persists until explicitly cleared.

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

Cookies

Data accessible server-side and can span subdomains.

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

Cookie Settings

When using data-storage="cookie", additional options are available:

Example: Cross-Subdomain Tracking

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

Privacy Controls

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.

Disable Privacy Signal Detection

If you need to disable privacy signal detection (not recommended):

<script src="/dist/script.min.js" data-privacy="false"></script>

Click ID Tracking

Enable automatic capture of ad platform click IDs:

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

When enabled, the following parameters are automatically tracked:

Debug Panel

The debug panel provides a visual interface for inspecting attribution data, viewing tracked forms, and monitoring activity in real-time.

Enabling the Debug Panel

Add data-debug="true"to the script tag:

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

Features

• Data Tab: View all captured UTM parameters and metadata
• Forms Tab: See all forms on the page and their injection status (click to highlight)
• Log Tab: Real-time activity log with timestamps
• Copy: Export attribution data as JSON to clipboard
• Clear: Remove all stored attribution data
• Refresh: Re-inject data into all forms

The panel can be minimized, dragged to reposition, and its state persists across page reloads.

JavaScript API

Form Attribution exposes a global FormAttribution object for programmatic access to attribution data and control.

Methods

Properties

Events

Example Usage

// Wait for initialization
FormAttribution.on('onReady', ({ data, config }) => {
  console.log('Attribution ready:', data);
});

// Get all attribution data
const data = FormAttribution.getData();
console.log(data);
// { utm_source: 'google', utm_medium: 'cpc', ... }

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

// Get tracked forms
const forms = FormAttribution.getForms();
forms.forEach(form => {
  // Status: 'Injected' (has data), 'Ready' (no data yet), or 'Excluded'
  const status = form.excluded ? 'excluded' : form.injected ? 'injected' : 'ready';
  console.log(form.name, status);
});

// Clear data (useful for testing)
FormAttribution.clear();

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

// Access current config
console.log(FormAttribution.config.storage); // 'sessionStorage'

// Remove a callback
const myHandler = ({ data }) => console.log('Captured:', data);
FormAttribution.on('onCapture', myHandler);
// Later...
FormAttribution.off('onCapture', myHandler);

Captured Parameters

URL Parameters (default)

Metadata (automatically captured)

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

Storage Fallbacks

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