Ryan Howard

Pavlo Samsonov

<p>Track the complete customer journey from first click to conversion with referral and Google Ads attribution data captured in your WordPress forms.</p>
<h3>Overview</h3>
<p>Form Attribution Tracking is a WordPress plugin that automatically captures and stores complete attribution data from Google Ads campaigns (and other traffic sources) directly in form submissions. This enables you to connect specific leads back to their originating campaigns, keywords, and ads in Google Ads for accurate conversion tracking and ROI measurement.</p>
<p>The plugin uses first-touch attribution, meaning it captures the visitor’s original traffic source on their first visit and maintains that data through their entire journey until they convert via a form submission.</p>
<h3>Key Features</h3>
<h3>Complete Google Ads Attribution Data</h3>
<p>Automatically captures 8 attribution fields for every form submission:</p>
<ul>
<li><strong>Attribution Source</strong> – Traffic source (google, facebook, direct, etc.)</li>
<li><strong>Attribution Medium</strong> – Traffic medium (cpc, organic, referral, etc.)</li>
<li><strong>Attribution Campaign</strong> – Campaign name from utm_campaign</li>
<li><strong>Attribution Term</strong> – Keyword from utm_term</li>
<li><strong>Attribution Content</strong> – Ad variation from utm_content</li>
<li><strong>Google Click ID (GCLID)</strong> – Direct link to the specific Google Ads click</li>
<li><strong>Landing Page</strong> – The first page the visitor landed on</li>
<li><strong>First Click Timestamp</strong> – When the visitor first arrived</li>
</ul>
<h3>Google Ads Conversion Tracking</h3>
<p>The Google Click ID (GCLID) field enables you to:<br />
– Import conversions directly back into Google Ads<br />
– Connect form submissions to specific ad clicks<br />
– Measure true campaign ROI based on actual leads/sales<br />
– Track the complete path from ad click to conversion<br />
– Attribute conversions to the exact keyword and ad that drove them</p>
<h3>Smart Tracking Technology</h3>
<ul>
<li><strong>First-Touch Attribution</strong> – Captures original source, not last-click</li>
<li><strong>Cookie Persistence</strong> – Maintains attribution data across multiple sessions (configurable 1-365 days)</li>
<li><strong>JavaScript + PHP Fallback</strong> – Dual-layer tracking ensures data capture even if JavaScript is disabled</li>
<li><strong>Dynamic Form Support</strong> – Mutation observer watches for forms loaded via AJAX</li>
<li><strong>UTM Parameter Detection</strong> – Automatically parses and stores all UTM parameters</li>
<li><strong>Intelligent Source Categorization</strong> – Recognizes and categorizes traffic from Google, Facebook, LinkedIn, and 15+ other platforms</li>
</ul>
<h3>Universal Form Plugin Support</h3>
<p>Works seamlessly with:<br />
– <strong>Gravity Forms</strong><br />
– <strong>Fluent Forms</strong><br />
– <strong>Formidable Forms</strong></p>
<p>Modular architecture makes it easy to extend to other form plugins.</p>
<h3>Comprehensive Admin Dashboard</h3>
<ul>
<li><strong>Statistics Dashboard</strong> – View submission counts, attribution source distribution, and recent activity</li>
<li><strong>Form Management</strong> – See which forms have attribution tracking and bulk-add fields to all forms</li>
<li><strong>Debug Mode</strong> – Browser console logging for troubleshooting</li>
<li><strong>Flexible Configuration</strong> – Customize cookie duration and auto-add behavior</li>
</ul>
<h3>How It Works</h3>
<h3>Data Capture Flow</h3>
<ol>
<li>
<p><strong>Visitor Arrives</strong> – When someone visits your site, the JavaScript tracking code immediately captures:</p>
<ul>
<li>All UTM parameters from the URL</li>
<li>Google Click ID (GCLID) if present</li>
<li>HTTP referrer to determine traffic source</li>
<li>Current page URL as landing page</li>
<li>Current timestamp</li>
</ul>
</li>
<li>
<p><strong>Attribution Stored</strong> – All data is packaged as JSON and stored in a first-party cookie with your configured expiration (default 30 days)</p>
</li>
<li>
<p><strong>First-Touch Persistence</strong> – If the visitor returns multiple times before converting, the original attribution data is preserved (not overwritten)</p>
</li>
<li>
<p><strong>Form Submission</strong> – When the visitor fills out a form, the tracking code automatically:</p>
<ul>
<li>Reads the stored attribution data</li>
<li>Populates hidden fields in the form</li>
<li>Submits with the complete attribution chain</li>
</ul>
</li>
<li>
<p><strong>PHP Fallback</strong> – If JavaScript fails to populate fields, the PHP integration captures attribution server-side before form processing</p>
</li>
</ol>
<h3>Integration with Google Ads</h3>
<p>To enable conversion imports in Google Ads:</p>
<ol>
<li>Forms will capture the GCLID parameter automatically from your ad URLs</li>
<li>Export your form submissions (including attribution fields) as CSV</li>
<li>In Google Ads, navigate to Tools <span aria-hidden="true" class="wp-exclude-emoji">→</span> Conversions <span aria-hidden="true" class="wp-exclude-emoji">→</span> Uploads</li>
<li>Create a conversion action using the GCLID field to match conversions</li>
<li>Upload your leads with timestamps and GCLIDs</li>
<li>Google Ads will attribute the conversions to the exact campaigns, ad groups, keywords, and ads that generated them</li>
</ol>
<p>This creates a closed feedback loop between your ad spend and actual business results.</p>
<h3>Configuration</h3>
<h3>Settings</h3>
<p>Access settings via <strong>Form Attribution Tracking <span aria-hidden="true" class="wp-exclude-emoji">→</span> Settings</strong>:</p>
<ul>
<li><strong>Auto-add to new forms</strong> – Automatically adds all 8 attribution fields when new forms are created</li>
<li><strong>Cookie Duration</strong> – How long to preserve first-touch attribution data (1-365 days, default 30)</li>
<li><strong>Debug Mode</strong> – Enables detailed logging in browser console for troubleshooting</li>
</ul>
<h3>Managing Existing Forms</h3>
<p>Use the <strong>Manage Forms</strong> tab to:<br />
– View all forms and their attribution tracking status<br />
– Bulk-add attribution fields to all existing forms with one click<br />
– See which forms already have tracking enabled</p>
<h3>Statistics</h3>
<p>The <strong>Statistics</strong> tab provides:<br />
– Total submissions tracked across all forms<br />
– Breakdown of traffic sources (Google, Facebook, Direct, etc.)<br />
– Recent form submissions with their attribution data<br />
– Forms-with-tracking count</p>
<h3>Usage</h3>
<h3>For Marketers</h3>
<p>Once installed and configured, the plugin works automatically. Every form submission will include complete attribution data that you can:</p>
<ul>
<li>Export to CSV and upload to Google Ads for conversion tracking</li>
<li>Analyze in your CRM to understand which campaigns drive the best leads</li>
<li>Use to calculate true cost-per-lead and ROI by campaign</li>
<li>Review to optimize your landing pages and ad targeting</li>
</ul>
<h3>For Developers</h3>
<h4>JavaScript API</h4>
<p>The plugin exposes a global API for programmatic access:</p>
<pre><code>`javascript
</code></pre>
<p>// Get full attribution data object<br />
const attribution = window.FormAttributionTracking.getAttributionData();<br />
// Returns: { utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, landing_page, timestamp }</p>
<p>// Get just the traffic source (legacy method)<br />
const source = window.FormAttributionTracking.getReferralSource();</p>
<p>// Manually trigger form field population<br />
window.FormAttributionTracking.populateFormFields();</p>
<p>// Access configuration<br />
const config = window.FormAttributionTracking.config;<br />
    `</p>
<h4>JavaScript Events</h4>
<p>Listen for when attribution data is populated:</p>
<pre><code>`javascript
</code></pre>
<p>window.addEventListener(‘attributionDataPopulated’, function(event) {<br />
    console.log(‘Attribution captured:’, event.detail.attribution);<br />
    console.log(‘Fields populated:’, event.detail.fieldsCount);<br />
});<br />
    `</p>
<h4>PHP Hooks and Filters</h4>
<p>Extend or customize the plugin:</p>
<pre><code>`php
</code></pre>
<p>// Add custom form plugin integration<br />
add_filter(‘attribution_tracking_integrations’, function($integrations) {<br />
    $integrations[‘CustomForms’] = new CustomFormsIntegration();<br />
    return $integrations;<br />
});</p>
<p>// React to integration initialization<br />
add_action(‘attribution_tracking_integration_initialized’, function($integration_name) {<br />
    error_log(“Attribution tracking initialized for: ” . $integration_name);<br />
});</p>
<p>// Hook into debug logging<br />
add_action(‘form_referral_source_debug_log’, function($message, $context, $source) {<br />
    error_log(“[$source] $message: ” . print_r($context, true));<br />
}, 10, 3);<br />
    `</p>
<h3>Attribution Field Names</h3>
<p>The plugin creates these hidden fields in your forms:</p>
<ul>
<li><code>attribution_source</code> – Traffic source identifier</li>
<li><code>attribution_medium</code> – Marketing medium</li>
<li><code>attribution_campaign</code> – Campaign name</li>
<li><code>attribution_term</code> – Keyword/search term</li>
<li><code>attribution_content</code> – Ad content variation</li>
<li><code>attribution_gclid</code> – Google Ads Click ID</li>
<li><code>attribution_landing_page</code> – First page visited</li>
<li><code>attribution_timestamp</code> – ISO 8601 timestamp of first visit</li>
</ul>
<p>All fields are automatically populated by JavaScript and have PHP fallbacks.</p>
<h3>Traffic Source Detection</h3>
<p>The plugin intelligently categorizes traffic sources:</p>
<h3>UTM Parameters (Highest Priority)</h3>
<p>If UTM parameters are present in the URL, they are captured exactly as provided.</p>
<h3>Known Platforms (Automatic Categorization)</h3>
<p>The plugin recognizes and categorizes referrers from:<br />
– Google (google.com, google.co.uk, etc.)<br />
– Facebook (facebook.com, fb.com, m.facebook.com)<br />
– Twitter/X (twitter.com, x.com, t.co)<br />
– LinkedIn (linkedin.com, lnkd.in)<br />
– YouTube (youtube.com, youtu.be)<br />
– Instagram (instagram.com)<br />
– TikTok (tiktok.com)<br />
– Pinterest (pinterest.com, pin.it)<br />
– Reddit (reddit.com)<br />
– Bing (bing.com)<br />
– Yahoo (yahoo.com)<br />
– DuckDuckGo (duckduckgo.com)</p>
<h3>Generic Referrals</h3>
<p>For unlisted referrers, the clean hostname is stored (e.g., “example.com”)</p>
<h3>Direct Traffic</h3>
<p>When no referrer or UTM parameters are present, traffic is marked as “direct”</p>
<h3>Troubleshooting</h3>
<h3>Attribution Data Not Being Captured</h3>
<ol>
<li><strong>Enable Debug Mode</strong> in plugin settings</li>
<li>Open browser console (F12) and check for “[Referral Source]” log messages</li>
<li>Verify cookies are enabled in the browser</li>
<li>Check that JavaScript is not being blocked</li>
</ol>
<h3>Fields Not Populating in Forms</h3>
<ol>
<li>Enable Debug Mode and check console for “Field populated” messages</li>
<li>Verify the form fields exist (check Manage Forms tab)</li>
<li>Test with a fresh browser/incognito window</li>
<li>Check that the form HTML includes the expected hidden field names</li>
</ol>
<h3>Forms Not Showing in Dashboard</h3>
<ol>
<li>Verify your form plugin (Gravity Forms, Fluent Forms, or Formidable Forms) is active</li>
<li>Check that you have forms created in that plugin</li>
<li>Look for PHP errors in debug.log if WP_DEBUG is enabled</li>
</ol>
<h3>GCLID Not Being Captured</h3>
<ol>
<li>Verify your Google Ads URLs include the {gclid} parameter</li>
<li>Use Google’s Campaign URL Builder to test: https://ga-dev-tools.google/campaign-url-builder/</li>
<li>Check that cookies are working (GCLID is stored in the attribution cookie)</li>
<li>Enable Debug Mode to see what parameters are being captured</li>
</ol>
<h3>Extending the Plugin</h3>
<h3>Adding Support for Other Form Plugins</h3>
<p>Create a new integration class:</p>
<pre><code>`php
</code></pre>
<p><?php<br />
namespace FormAttributionTracking\Integrations;</p>
<p>use FormAttributionTracking\Abstracts\AbstractFormIntegration;</p>
<p>class CustomFormPluginIntegration extends AbstractFormIntegration<br />
{<br />
    public function isAvailable(): bool {<br />
        return class_exists(‘CustomFormPlugin’);<br />
    }</p>
<pre><code>public function getName(): string {
    return 'Custom Form Plugin';
}

public function getVersion(): string {
    return '1.0.0';
}

protected function registerHooks(): void {
    // Hook into your form plugin's save/render events
    add_action('custom_form_save', [$this, 'onFormSaved'], 10, 2);
}

public function addReferralSourceField(int $formId): bool {
    // Implement logic to add hidden fields to forms
}

public function removeReferralSourceField(int $formId): bool {
    // Implement logic to remove hidden fields
}

public function hasReferralSourceField(int $formId): bool {
    // Check if form has attribution fields
}

public function getAllForms(): array {
    // Return array of all forms
}
</code></pre>
<p>}<br />
    `</p>
<p>Register your integration:</p>
<pre><code>`php
</code></pre>
<p>add_filter(‘attribution_tracking_integrations’, function($integrations) {<br />
    $integrations[‘CustomFormPlugin’] = new CustomFormPluginIntegration();<br />
    return $integrations;<br />
});<br />
    `</p>
<h3>Architecture</h3>
<p>The plugin uses a clean, modern PHP 8+ architecture:</p>
<pre><code>`
</code></pre>
<p>src/<br />
├── Contracts/<br />
│   └── FormIntegrationInterface.php    # Interface all integrations must implement<br />
├── Abstracts/<br />
│   └── AbstractFormIntegration.php     # Base class with common functionality<br />
├── Integrations/<br />
│   ├── GravityFormsIntegration.php     # Gravity Forms support<br />
│   ├── FluentFormsIntegration.php      # Fluent Forms support<br />
│   └── FormidableFormsIntegration.php  # Formidable Forms support<br />
├── Views/<br />
│   └── admin-page.php                  # Admin dashboard template<br />
└── Plugin.php                          # Main plugin orchestration class<br />
    `</p>
<h3>Privacy & Compliance</h3>
<p>This plugin stores first-party cookies to maintain attribution data. Consider these compliance aspects:</p>
<ul>
<li><strong>Cookie Duration</strong>: Configurable 1-365 days (default 30)</li>
<li><strong>Data Stored</strong>: Marketing attribution data only (no PII)</li>
<li><strong>First-Party Cookies</strong>: Data stays on your domain</li>
<li><strong>User Control</strong>: Respects browser cookie settings</li>
<li><strong>GDPR</strong>: Consider adding cookie consent notices per your requirements</li>
<li><strong>Data Retention</strong>: Attribution data is only stored in form submissions per your form plugin’s data retention policies</li>
</ul>
<h3>Support & Contributing</h3>
<p>For bug reports, feature requests, or contributions:</p>
<ul>
<li>Plugin Author: Ryan Howard</li>
<li>Website: https://www.ryanhoward.dev</li>
<li>Text Domain: form-attribution-tracking</li>
</ul>
<h3>License</h3>
<p>This plugin is licensed under the GPL v2 or later.</p>


Form Attribution Tracking

Track the complete customer journey from first click to conversion with referral and Google Ads attribution data captured in your WordPress forms.

Crelora

<p><a href="https://onelence.com" rel="nofollow ugc">OneLence</a> is a marketing decision layer that helps teams understand which channels, campaigns, creators, affiliates, and customer journeys actually contribute to growth—so decisions are based on evidence, not guesswork.</p>
<p><strong>OneLence Connect</strong> is the official WordPress integration for the OneLence platform. It sends reliable server-side attribution and conversion data from your WordPress site into your OneLence workspace, including WooCommerce activity, with less data loss from ad blockers and browser restrictions.</p>
<p>Once connected, your WordPress data becomes part of the broader OneLence decision workflow: attribution, channel evaluation, conversion analysis, reinvestment decisions, and growth prioritization.</p>
<p>This plugin is focused on reliable data collection and delivery for OneLence. Reporting, decision workflows, and strategic insights happen inside your OneLence workspace.</p>
<p><strong>What you get</strong></p>
<ul>
<li><strong>More reliable attribution</strong> with server-side tracking and reduced data loss</li>
<li><strong>WooCommerce conversion tracking</strong> with automatic retry handling when delivery fails</li>
<li><strong>Consent-aware tracking</strong> compatible with popular CMPs and OneLence Consent</li>
<li><strong>Hybrid tracking mode</strong> that combines server reliability with browser SDK capabilities without duplicate page views</li>
<li><strong>No-code event setup</strong> using the Events tab with visual selectors and rule builders</li>
<li><strong>Diagnostics and validation tools</strong> in wp-admin, including Test Connection before launch</li>
<li><strong>Reliable inputs for OneLence decisions</strong> about channels, campaigns, creators, affiliates, and growth priorities</li>
</ul>
<p><strong>What you need</strong></p>
<ul>
<li>A <a href="https://onelence.com" rel="nofollow ugc">OneLence account</a> (<a href="https://onelence.com/pricing" rel="nofollow ugc">free trial available</a>)</li>
<li>Use <strong>Connect to OneLence</strong> in the plugin dashboard—your site is linked and credentials are configured automatically</li>
</ul>
<p>Works on any WordPress site, including WooCommerce stores, SaaS sites, landing pages, content-driven brands, and lead-generation websites.</p>
<p>WooCommerce support is optional but fully supported for order and conversion tracking.</p>
<p><strong>Learn more</strong></p>
<ul>
<li><a href="https://onelence.com" rel="nofollow ugc">OneLence — marketing decision layer</a></li>
<li><a href="https://onelence.com/docs/integrations/start-integration/website-builder-setup/wordpress" rel="nofollow ugc">WordPress setup guide</a></li>
<li><a href="https://onelence.com/docs/integrations/start-integration" rel="nofollow ugc">Integrations overview</a></li>
</ul>
<h3>External services</h3>
<p>This plugin connects to external services. Data is only sent when tracking is enabled and your consent settings allow it.</p>
<h4>OneLence ingestion API</h4>
<p>Used to deliver server-side attribution events and WooCommerce conversions to your OneLence workspace.</p>
<ul>
<li><strong>What is sent:</strong> page URLs, visitor identifiers (<code>olm_vid</code>), UTM and attribution parameters, event names and configured properties, WooCommerce order metadata when store tracking is enabled, and optional user email on login for identify events.</li>
<li><strong>When:</strong> on page views, configured events, conversions, and related server-side actions according to your tracking mode and consent mode.</li>
<li><strong>Where:</strong> <code>https://ingest.onelence.com</code></li>
<li><strong>Provider:</strong> Crelora / OneLence — <a href="https://onelence.com/terms-of-service" rel="nofollow ugc">Terms of Service</a>, <a href="https://onelence.com/privacy-policy" rel="nofollow ugc">Privacy Policy</a></li>
</ul>
<h4>Mark browser SDK (Hybrid / JS-only modes)</h4>
<p>Used for client-side tracking when Hybrid or JS-only tracking modes are enabled.</p>
<ul>
<li><strong>What is sent:</strong> analytics and attribution data configured in the plugin, including page views and custom events, subject to your CMP and consent settings.</li>
<li><strong>When:</strong> after consent is granted (or immediately when no CMP is detected and your consent mode allows it).</li>
<li><strong>Where:</strong> the Mark SDK bundled inside this plugin (<code>assets/js/mark.browser.umd.js</code>). No third-party script host is used on WordPress.org builds.</li>
<li><strong>Provider:</strong> Crelora / OneLence — <a href="https://onelence.com/terms-of-service" rel="nofollow ugc">Terms of Service</a>, <a href="https://onelence.com/privacy-policy" rel="nofollow ugc">Privacy Policy</a></li>
</ul>
<h4>Connect to OneLence (setup)</h4>
<p>Used when an administrator clicks <strong>Connect to OneLence</strong> in wp-admin to link the WordPress site to a OneLence workspace.</p>
<ul>
<li><strong>What is sent:</strong> OAuth/session tokens and site metadata required to obtain API credentials.</li>
<li><strong>When:</strong> during the administrator-initiated connect flow.</li>
<li><strong>Where:</strong> OneLence web properties under <code>onelence.com</code></li>
<li><strong>Provider:</strong> Crelora / OneLence — <a href="https://onelence.com/terms-of-service" rel="nofollow ugc">Terms of Service</a>, <a href="https://onelence.com/privacy-policy" rel="nofollow ugc">Privacy Policy</a></li>
</ul>
<h4>OneLence Consent (optional separate plugin)</h4>
<p>Not required. If installed, OneLence Connect reads consent signals from that plugin and may forward optional coverage metrics when forwarding is enabled in settings.</p>
<ul>
<li><strong>What is sent:</strong> consent state required for tracking decisions and optional lightweight coverage metrics when forwarding is enabled.</li>
<li><strong>When:</strong> while visitors interact with the consent banner and when forwarding is enabled.</li>
<li><strong>Where:</strong> local WordPress installation (OneLence Consent plugin). Download: <a href="https://onelence.com/consent/download" rel="nofollow ugc">onelence.com/consent/download</a></li>
<li><strong>Provider:</strong> Crelora / OneLence — <a href="https://onelence.com/terms-of-service" rel="nofollow ugc">Terms of Service</a>, <a href="https://onelence.com/privacy-policy" rel="nofollow ugc">Privacy Policy</a></li>
</ul>
<h3>Privacy</h3>
<ul>
<li><strong>Cookies:</strong> <code>olm_vid</code> (visitor identity) and <code>olm_utm</code> (attribution parameters). These are set according to your consent mode and detected CMP.</li>
<li><strong>Consent:</strong> OneLence Connect reads consent signals from your CMP; it does not replace your cookie banner. Optional <strong>OneLence Consent</strong> is available as a separate plugin.</li>
<li><strong>WordPress tools:</strong> Personal data export is registered with WordPress privacy tools. Use <strong>Keep Data on Uninstall</strong> in Tracking settings if you want plugin options retained after uninstall.</li>
<li><strong>Policy:</strong> <a href="https://onelence.com/privacy-policy" rel="nofollow ugc">OneLence privacy policy</a></li>
</ul>
<h3>For developers</h3>
<p>OneLence Connect exposes WordPress hooks for custom integrations, including:</p>
<ul>
<li><code>onelco_should_track</code></li>
<li><code>onelco_event_payload</code></li>
<li><code>onelco_conversion_payload</code></li>
<li><code>onelco_visitor_id</code></li>
<li><code>onelco_event_sent</code></li>
<li><code>onelco_conversion_sent</code></li>
<li><code>onelco_load_mark_sdk</code></li>
</ul>
<p>Custom conversions can use:</p>
<ul>
<li><code>ONELCO_Tracker::track_custom_conversion()</code></li>
<li><code>onelco_track_custom_conversion</code> action</li>
</ul>
<p>Full integration reference:</p>
<p><a href="https://onelence.com/docs/integrations/start-integration/website-builder-setup/wordpress" rel="nofollow ugc">WordPress setup docs</a></p>


OneLence Connect for WordPress

Connect WordPress to OneLence for reliable attribution, cleaner marketing signals, and clearer decisions about what deserves more investment.

Form Attribution Tracking vs OneLence Connect for WordPress