Referral Source Tracking for Gravity Forms

How do I enable the plugin?

After purchasing Referral Source Tracking for Gravity Forms, 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 the Gravity Forms settings > Referral Source 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 Source 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

---

Merge Tags

{pb_ref_source} – value stored in the hidden “Source” field (defaulting to “Unknown” when the visit couldn’t be classified).

{pb_ref_params} – full string of captured referral parameters (UTMs and other query vars we keep 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.

---

Translations

This plugin is translation-ready and includes bundled translations for:

• Arabic (ar)
• Bengali – Bangladesh (bn_BD)
• Filipino (fil)
• German – Germany (de_DE)
• English – United States (en_US)
• Spanish – Spain (es_ES)
• Spanish – Mexico (es_MX)
• French – France (fr_FR)
• Hindi – India (hi_IN)
• Indonesian (id_ID)
• Italian – Italy (it_IT)
• Japanese (ja)
• Portuguese – Brazil (pt_BR)
• Russian – Russia (ru_RU)
• Urdu – Pakistan (ur_PK)
• Chinese (Simplified) – China (zh_CN)
• Chinese (Traditional) – Hong Kong (zh_HK)

Default language: English (en_US)

If your language isn’t listed under Translations above, you can still translate the plugin. It’s fully translation-ready, and you can use the free Loco Translate plugin to create a translation for your site’s language/locale. If you’ve never used Loco Translate before, here’s a beginner-friendly tutorial.

---

FAQs

Can I export the data?

Yes. The tracking values are saved on each Gravity Forms entry, so they show up in entry exports.

What exactly does the plugin capture?

We capture common attribution fields and store them on the Gravity Forms 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 inside Gravity Forms entries only. 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-gforms-referral-tracking/assets/js/front-end.js
• /wp-content/plugins/pb-gforms-referral-tracking/assets/dist/js.cookie.min.js

Does it work with AJAX-enabled Gravity Forms?

Yes. It works with AJAX forms and standard (non-AJAX) Gravity Forms submissions.

Can I track more than one form?

Yes. It works across your Gravity Forms forms—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 Gravity Forms 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 in 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 fields 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_gforms_referral_tracking_loaded

Fires after the plugin is fully initialised — 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_gforms_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_gforms_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 (array|null) — The form meta array, or null if not available.

Example Usage:

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

pb_gforms_referral_tracking_field_definitions

Filter the array of hidden tracking field definitions before they are injected into the form. Use this to add, remove, or modify any individual tracking field.

Parameters:

• $fields (array) — Array of field definition arrays.
• $form (array) — The current form meta.

Example Usage:

// Remove the Referral Parameters field from all forms.
add_filter( 'pb_gforms_referral_tracking_field_definitions', function( $fields, $form ) {
    return array_filter( $fields, function( $field ) {
        return ! isset( $field['cssClass'] ) || $field['cssClass'] !== 'pb-ref-tracking-ref-params';
    } );
}, 10, 2 );

pb_gforms_referral_tracking_form

Filter the complete form array after all tracking fields have been appended. Gives you full control over the final form object before it is rendered.

Parameters:

• $form (array) — The form array with tracking fields already added.
• $field_definitions (array) — The field definitions that were used.

Example Usage:

// Log which forms have tracking fields injected (useful for debugging).
add_filter( 'pb_gforms_referral_tracking_form', function( $form, $field_definitions ) {
    error_log( 'Referral tracking fields added to form ID: ' . $form['id'] );
    return $form;
}, 10, 2 );

pb_gforms_referral_tracking_merge_tag_map

Modify the merge tag map that defines which merge tags are available and which field IDs they resolve to. Use this to add entirely custom merge tags or rename existing ones.

Parameters:

• $map (array) — Associative array of tag => [ ‘label’ => string, ‘field_id’ => string ].
• $base_id (string) — The base field ID prefix.
• $constants (Constants) — The plugin constants instance.

// Rename the "Source" merge tag label as it appears in the GF dropdown.
add_filter( 'pb_gforms_referral_tracking_merge_tag_map', function( $map, $base_id, $constants ) {
    if ( isset( $map['pb_ref_source'] ) ) {
        $map['pb_ref_source']['label'] = 'Traffic Source';
    }
    return $map;
}, 10, 3 );

pb_gforms_referral_tracking_value

Filter a raw tracking field value before it is formatted and used to replace a merge tag in a notification or confirmation. Useful for sanitising or transforming specific values.

Parameters:

• $value (string) — The raw field value.
• $tag (string) — The merge tag key (e.g. pb_ref_source).
• $data (array) — The merge tag metadata (label, field_id).
• $entry (array) — The current entry.
• $form (array) — The current form.

// Truncate long referrer URLs in merge tag output.
add_filter( 'pb_gforms_referral_tracking_value', function( $value, $tag, $data, $entry, $form ) {
    if ( $tag === 'pb_ref_referrer' && strlen( $value ) > 100 ) {
        return substr( $value, 0, 100 ) . '…';
    }
    return $value;
}, 10, 5 );

pb_gforms_referral_tracking_formatted_value

Filter the fully formatted merge tag value after Gravity Forms’ own formatting pipeline has been applied (escaping, URL encoding, etc.).

Parameters:

• $formatted (string) — The formatted output string.
• $tag (string) — The merge tag key.
• $data (array) — The merge tag metadata.
• $entry (array) — The current entry.
• $form (array) — The current form.
• $url_encode (bool)
• $esc_html (bool)
• $nl2br (bool)
• $format (string)

// Wrap the source value in a bold tag in HTML-format notifications.
add_filter( 'pb_gforms_referral_tracking_formatted_value', function( $formatted, $tag, $data, $entry, $form, $url_encode, $esc_html, $nl2br, $format ) {
    if ( $tag === 'pb_ref_source' && $format === 'html' && ! $url_encode ) {
        return '<strong>' . $formatted . '</strong>';
    }
    return $formatted;
}, 10, 9 );

pb_gforms_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_gforms_referral_tracking_default_value', function( $default, $key ) {
    if ( $key === 'source' ) {
        return 'Direct';
    }
    return $default;
}, 10, 2 );

pb_gforms_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_gforms_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_gforms_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_gforms_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_gforms_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_gforms_referral_tracking_enqueue_assets', function( $enqueue ) {
    if ( is_front_page() ) {
        return false;
    }
    return $enqueue;
} );

pb_gforms_referral_tracking_inline_css

Override the inline CSS that hides tracking fields on the front-end and in the block editor preview. The default CSS targets .gform_wrapper .gfield[class*="pb-ref-tracking-"].

Parameters:

• $css (string) — The inline CSS string.

// Replace the default hide rule with a more specific selector.
add_filter( 'pb_gforms_referral_tracking_inline_css', function( $css ) {
    return '.my-theme .gform_wrapper .gfield[class*="pb-ref-tracking-"] { display: none !important; }';
} );