Referral Source Tracking for WPForms

How do I enable the plugin?

After purchasing Referral Source Tracking for WPForms, you’ll need to install the plugin on your WordPress website. Let’s walk through that process.

Step 1: Installation

Log in to your WordPress website and navigate to Plugins > Add Plugin > Upload Plugin > Install the zip file and activate it.

Step 2: Register the Plugin

On the left hand navigation, navigate to WPForms > Referral Tracking.

Enter your license key and activate it.

Step 3: Enable the Feature

After activating your license, a “General” tab will appear in the Referral Tracking settings page, click it and click “Save Changes”.

That’s it! Now referral source tracking will be active on any existing forms or new forms you create.

---

Feature Details

Sources it Detects

We capture the referrer URL when one is available and store it on the entry. We also apply friendly labels for common platforms so the source is easy to understand at a glance.

Here’s the list of sources that are labeled when detected:

• Google: Google Ads, Google Organic, Gemini
• Microsoft/Bing: Microsoft Ads, Bing Organic
• Facebook: Facebook Ads, Facebook Organic
• LinkedIn: LinkedIn Ads, LinkedIn Organic
• X (Twitter): X Ads, X Organic
• Reddit: Reddit Ads, Reddit Organic
• TikTok: TikTok Ads, TikTok Organic
• Pinterest: Pinterest Ads, Pinterest Organic
• Snapchat: Snapchat Ads, Snapchat Organic
• Other Search Engines: Yahoo, DuckDuckGo, Yandex
• AI Assistants (when available): ChatGPT, Perplexity, Microsoft Copilot, Claude, Grok, DeepSeek
• Email Platforms (campaign tracking): Mailchimp, Constant Contact, Salesforce Pardot, HubSpot
• Direct and Unknown are used when appropriate.
• Custom sources can be added too!

UTM Parameters it Captures

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content
• utm_id

Click IDs Captured

• gclid
• gbraid
• wbraid
• msclkid
• li_fat_id
• rdt_cid
• ttclid
• pin_cid
• snap_cid
• mc_cid
• mc_eid
• dclid

---

Smart Tags

{pb_ref_source} – the detected referral source label (defaulting to “Unknown” when the visit couldn’t be classified).

{pb_ref_params} – full string of captured referral parameters (UTMs and other query vars kept together).

{pb_ref_referrer} – browser referrer that brought the visitor to the site.

{pb_ref_utm_id} – captured utm_id.

{pb_ref_utm_source} – captured utm_source.

{pb_ref_utm_medium} – captured utm_medium.

{pb_ref_utm_campaign} – captured utm_campaign.

{pb_ref_utm_term} – captured utm_term.

{pb_ref_utm_content} – captured utm_content.

{pb_ref_clid} – the first detected click ID (gclid, fbclid, msclkid, etc.).

---

Translations

This plugin is fully translation-ready. You can translate it into any language using the free Loco Translate plugin or any other WordPress translation tool.

Default language: English (en_US)

---

FAQs

Does it work with WPForms Lite?

Yes. Referral tracking capture and Smart Tag processing work with WPForms Lite. However, WPForms Lite has limited entry management UI compared to Pro — entry list columns, the single-entry referral tracking sidebar, and CSV export integration require WPForms Pro.

Can I export the data?

Yes. Tracking values are included in WPForms CSV exports. All referral fields (source, referrer, UTMs, click ID, and more) are added as export columns automatically.

What exactly does the plugin capture?

We capture common attribution fields and store them alongside each WPForms entry, including UTM parameters (source, medium, campaign, term, content), Click IDs (gclid, msclkid, gbraid/wbraid, etc.), the original referrer URL, and related landing-page context so you can clearly see where each lead came from.

Can I add custom sources?

Yes! Whether it’s a referral site, affiliate partnership etc, you can add custom sources with clear labels.

Where is the referral data saved?

In your WordPress database in a dedicated plugin table linked to WPForms entries. We do not send conversions or events to ad platforms.

Is this first-touch or last-touch attribution?

This plugin focuses on first-touch attribution by storing the original referrer and campaign parameters that brought the visitor to your site (within the retention window).

How long does it remember a visitor’s attribution data?

The retention window is 7 days. If a visitor submits a form within 7 days of their first tracked visit, the original attribution values will be applied to the entry.

Does it work with caching/CDNs?

Usually, yes. Tracking runs client-side, so most caching/CDN setups work fine. If you use aggressive script optimization (minify/deferral), exclude the plugin scripts below and test a submission:

• /wp-content/plugins/pb-wpforms-referral-tracking/assets/dist/js.cookie.min.js
• /wp-content/plugins/pb-wpforms-referral-tracking/assets/js/front-end.js

Does it work with AJAX-enabled WPForms?

Yes. It works with AJAX forms (WPForms default) and standard submissions.

Can I track more than one form?

Yes. It works across all your WPForms—each submission saves its own attribution values to that entry.

Does this replace GA4 / Google Ads conversion tracking?

No. This plugin doesn’t fire pixels or send conversion events to GA4 or ad platforms. It stores attribution data inside the WPForms entry, so your team can see lead source data directly in WordPress and exports.

Does it collect personal data?

By default, it captures attribution data (UTMs, gclid, referrer URLs). It does not capture additional PII by default. Your form fields and any parameters included in URLs are controlled by your site and marketing setup.

Is it GDPR/CCPA compliant?

It can be used in a GDPR/CCPA-friendly way. The plugin stores attribution data alongside your entries and doesn’t transmit events to ad platforms. You’re responsible for consent/legitimate interest and proper disclosure for your specific setup.

Does it work with a WordPress Multisite network?

TL;DR

• Unlimited license: enable Network Mode once; one key can manage every subsite’s settings + support.
• Network-activated: all subsites run referral tracking and receive updates right away.
• Limited plan / no subsite license: tracking stays on, but subsite settings are read-only.
• Support follows the license: sites covered by the active key are eligible.

Yes; the plugin runs out of the box on every subsite as soon as you network-activate it—no manual setup required. Each subsite can use the tracking and receives updates even without a local license. To change form-level settings or get direct support on a subsite, you still need to activate a license there.

If you have an Unlimited license, you can enable Network Mode from the main site and push that single key to every subsite in one batch (with live progress). Those subsites inherit the license-managed settings and support automatically.

---

Hooks

Actions

pb_wpforms_referral_tracking_loaded

Fires after the plugin is fully initialized — all classes are loaded, hooks are registered, and the API is ready. This is the reliable boot point for add-ons or companion plugins that extend Referral Source Tracking.

Parameters:

• $plugin (Plugin) — The plugin instance.

add_action( 'pb_wpforms_referral_tracking_loaded', function( $plugin ) {
    // Safe to interact with the plugin's classes and filters here.
    // Example: register your own add-on after the plugin is ready.
    if ( class_exists( 'MyReferralAddon' ) ) {
        new MyReferralAddon( $plugin );
    }
} );

Filters

pb_wpforms_referral_tracking_enabled

Override whether referral tracking is enabled for a specific form. Return true to force tracking on, false to force it off, regardless of the per-form toggle or global default.

Parameters:

• $enabled (bool) — Whether tracking is currently enabled.
• $form_id (int) — The ID of the current form.
• $form_data (array|null) — The form data array, or null if not available.

Example Usage:

// Disable tracking on a specific form (e.g. an internal staff-only form).
add_filter( 'pb_wpforms_referral_tracking_enabled', function( $enabled, $form_id, $form_data ) {
    $excluded_form_ids = [ 12, 27 ];
    if ( in_array( $form_id, $excluded_form_ids, true ) ) {
        return false;
    }
    return $enabled;
}, 10, 3 );

pb_wpforms_referral_tracking_merge_tag_map

Modify the Smart Tag map that defines which Smart Tags are available and which tracking keys they resolve to. Use this to add entirely custom Smart Tags or rename existing ones.

Parameters:

• $map (array) — Associative array of tag => tracking key (e.g. 'pb_ref_source' => 'source').

Example Usage:

// Add a custom Smart Tag that maps to a custom tracking key.
add_filter( 'pb_wpforms_referral_tracking_merge_tag_map', function( $map ) {
    $map['pb_ref_landing_page'] = 'landing_page';
    return $map;
} );

pb_wpforms_referral_tracking_value

Filter a raw tracking value before it is used to replace a Smart Tag in a notification or confirmation. Useful for sanitising or transforming specific values.

Parameters:

• $value (string) — The raw tracking value.
• $tag (string) — The Smart Tag key (e.g. pb_ref_source).
• $form_data (array) — The form data array.
• $fields (array) — The entry fields.
• $entry_id (int) — The entry ID.

Example Usage:

// Truncate long referrer URLs in Smart Tag output.
add_filter( 'pb_wpforms_referral_tracking_value', function( $value, $tag, $form_data, $fields, $entry_id ) {
    if ( $tag === 'pb_ref_referrer' && strlen( $value ) > 100 ) {
        return substr( $value, 0, 100 ) . '…';
    }
    return $value;
}, 10, 5 );

pb_wpforms_referral_tracking_formatted_value

Filter the fully formatted Smart Tag value after processing.

Parameters:

• $formatted (string) — The formatted output string.
• $tag (string) — The Smart Tag key.
• $form_data (array) — The form data array.
• $fields (array) — The entry fields.
• $entry_id (int) — The entry ID.

// Wrap the source value in a bold tag in HTML notifications.
add_filter( 'pb_wpforms_referral_tracking_formatted_value', function( $formatted, $tag, $form_data, $fields, $entry_id ) {
    if ( $tag === 'pb_ref_source' ) {
        return '<strong>' . esc_html( $formatted ) . '</strong>';
    }
    return $formatted;
}, 10, 5 );

pb_wpforms_referral_tracking_default_value

Override the fallback value used when a tracking field is empty at submission time. The default is “Unknown”.

Parameters:

• $default (string) — The current default value (“Unknown”).
• $key (string) — Context key: source, referrer, or front_end.

// Use "Direct" instead of "Unknown" for the source field fallback.
add_filter( 'pb_wpforms_referral_tracking_default_value', function( $default, $key ) {
    if ( $key === 'source' ) {
        return 'Direct';
    }
    return $default;
}, 10, 2 );

pb_wpforms_referral_tracking_js_config

Override the entire front-end JavaScript configuration object before it is passed to the tracking script. This gives you full control over cookie settings, source detection patterns, known sources, paid mediums, and more.

Parameters:

• $config (array) — The full JS config array.

// Extend cookie lifetime to 30 days and add a custom paid medium.
add_filter( 'pb_wpforms_referral_tracking_js_config', function( $config ) {
    $config['cookieExpiry'] = 30;

    // Add "social" as a paid medium indicator.
    $config['paidMediums'][] = 'social';

    // Add a custom source pattern for an internal platform.
    $config['sourcePatterns']['custom_platforms'][] = [
        'pattern' => 'myplatform\.com',
        'name'    => 'My Platform',
    ];

    return $config;
} );

pb_wpforms_referral_tracking_custom_sources

Programmatically inject custom source rules that run alongside rules configured in the admin UI. Rules from this filter are merged with saved UI rules and sorted together by priority before being passed to the front-end.

Parameters:

• $sources (array) — Empty array. Return an array of rule arrays to add.

Each rule must have: label, matchField (referrer, utm_source, utm_medium, utm_campaign, utm_term, utm_content), matchType (contains or equals), matchValue, and optionally priority (default 10, higher runs first).

// Add partner and affiliate sources without touching the admin UI.
add_filter( 'pb_wpforms_referral_tracking_custom_sources', function( $sources ) {
    $sources[] = [
        'label'      => 'Partner: Acme Corp',
        'matchField' => 'referrer',
        'matchType'  => 'contains',
        'matchValue' => 'acme.com',
        'priority'   => 20,
    ];
    $sources[] = [
        'label'      => 'Campaign: Spring Sale',
        'matchField' => 'utm_campaign',
        'matchType'  => 'contains',
        'matchValue' => 'spring-sale',
        'priority'   => 10,
    ];
    return $sources;
} );

pb_wpforms_referral_tracking_enqueue_assets

Control whether the plugin’s front-end assets (cookie library and tracking script) are enqueued. Return false to disable loading entirely on a page or condition.

Parameters:

• $enqueue (bool) — Whether to enqueue assets. Default true.

// Disable tracking assets on the homepage only.
add_filter( 'pb_wpforms_referral_tracking_enqueue_assets', function( $enqueue ) {
    if ( is_front_page() ) {
        return false;
    }
    return $enqueue;
} );