Presswell Tracking Signal Relay

Presswell Tracking Signal Relay captures attribution parameters and stores them with supported form submissions. It reads query parameters from the current URL, merges them with previously stored values, and keeps them in the visitor's browser for later form views until the Attribution Expiry passes with no page views (7 days by default). Supported Form Plugins

• Contact Form 7
• Fluent Forms
• Formidable Forms
• Forminator
• Gravity Forms
• WPForms (1.9.1 or later)

Features

• Captures common attribution parameters and stores them with submissions
• Tracks utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid, fbclid, msclkid, ttclid, landing_page, landing_query, and referrer
• Captures attribution on whichever page a visitor lands on, not just pages with forms
• Stores last-touch attribution, first-touch attribution, or both
• Persists values in browser localStorage, for 7 days without a page view by default, adjustable in settings
• Automatically populates tracking inputs when supported forms render: added to every Contact Form 7 and Forminator form, and through a Tracking field in the other builders
• Supports per-site custom parameters from plugin settings

Documentation Attribution Model Choose a model under Settings -> Tracking Signal Relay. The default, First and last, stores two sets of values with every submission:

• Last touch (utm_source, referrer, ...): replaced whenever the visitor arrives on a URL with any tracked parameter. Untagged visits, such as internal navigation, direct, or organic, keep the current values.
• First touch (first_utm_source, first_referrer, ...): recorded from the first visit with a source and never replaced while the stored record lasts. A direct visit (no tracked parameters and no referrer from another site, such as a typed address or bookmark) holds the spot only until a tagged or referred visit arrives.

Last touch and First touch store the plain keys alone (utm_source, ...), holding that model's values. Values share one record in browser localStorage. It expires once the Attribution Expiry passes with no page views (7 days by default, up to one year), and the next visit starts a new record. A longer expiry keeps first-touch attribution across more widely spaced visits; a shorter one makes last touch reset sooner. Changing the model only affects new submissions. Existing entries keep the values they were saved with, so with a single model, a field such as utm_source can mean different things before and after the change. landing_page, landing_query, and referrer always describe the visit itself and can't be set through the query string. Capture Methods

• Contact Form 7: Hidden tracking inputs are appended during form render.
• Fluent Forms: Custom field type that users add from the builder.
• Formidable Forms: Custom field type that users add from the builder.
• Forminator: Hidden tracking inputs are appended during form render.
• Gravity Forms: Custom field type that users add from the builder.
• WPForms: Custom field type that users add from the builder.

Merge Tags Each form plugin can use the captured values in notifications and confirmations:

• Contact Form 7: [tracking-all], [tracking-utm_source] (listed in the Mail panel)
• Fluent Forms: {tracking.all}, {tracking.utm_source}
• Formidable Forms: [tracking_all], [tracking_utm_source] (or {tracking_all}, {tracking_utm_source})
• Forminator: {tracking_all}, {tracking_utm_source}
• Gravity Forms: {tracking:all}, {tracking:utm_source}
• WPForms: {tracking_all}, {tracking_utm_source}

utm_source stands for any tracking key. The all-values tag lists one key: value per line, except in Gravity Forms, where it's a single line (utm_source=google, utm_medium=cpc), and Fluent Forms, which labels each line from its key (Utm Source: google). Keys with no value are left out. pwtsr_tracking_keys( $keys, $context )

• $keys (array) (required) - Ordered list of tracking keys that should be captured and stored with each entry.
• $context (string) (required) - Adapter context (core, contactform7, fluentforms, formidable, forminator, gravityforms, or wpforms).
• Return an indexed array of string keys.
• These values are used to build hidden inputs and entry-detail output.
• The browser script captures the keys from the core context and from every active form plugin's context.
• Return last-touch keys only; with the First and last model, a first_ copy of each key is added automatically.

Example: add_filter( 'pwtsr_tracking_keys', function( $keys, $context ) { if ( 'gravityforms' !== $context ) { return $keys; } $keys[] = 'custom_param'; $keys[] = 'utm_id'; return $keys; }, 10, 2 ); pwtsr_tracking_ttl( $ttl, $context )

• $ttl (int) (required) - Seconds without a page view before stored attribution is cleared. Defaults to the Attribution Expiry setting (7 days).
• $context (string) (required) - Always core; one TTL applies to the whole page.
• Return a positive integer. Values over one year are capped at one year, as in the settings; anything else falls back to the default (7 days).

Example: add_filter( 'pwtsr_tracking_ttl', function( $ttl, $context ) { if ( 'core' !== $context ) { return $ttl; } return DAY_IN_SECONDS * 30; }, 10, 2 ); pwtsr_storage_key( $storage_key, $context )

• $storage_key (string) (required) - Browser storage key used for the attribution payload.
• $context (string) (required) - Always core; one storage key applies to the whole page.
• Return a non-empty string.

pwtsr_enqueue_tracking_script( $enqueue )

• $enqueue (bool) (required) - Whether to load the tracking script on every front-end page. Default true while a supported form plugin is active.
• Return false to load it only on pages that render a form. Attribution from visitors who land on other pages is then lost.

pwtsr_attribution_model( $model, $context )

• $model (string) (required) - both, last, or first. Defaults to the Attribution Model setting.
• $context (string) (required) - Adapter context. The browser script uses the core value.
• Unknown values fall back to both.

pwtsr_require_consent( $required )

• $required (bool) (required) - Whether the script waits for consent before storing anything. Defaults to the Visitor Consent setting.

pwtsr_consent_category( $category )

• $category (string) (required) - WP Consent API category to wait for. Default marketing.

pwtsr_tracking_values( $values, $context, $form )

• $values (array) (required) - A submission's sanitized tracking values ([ 'utm_source' => 'google', ... ]), before the form plugin saves them. Empty values are left out.
• $context (string) (required) - Adapter context (contactform7, fluentforms, formidable, forminator, gravityforms, or wpforms).
• $form (mixed) (required) - The form as the form plugin has it: a WPCF7_ContactForm object, a form ID (Fluent Forms, Formidable Forms, Forminator), the form array (Gravity Forms), or the form data array (WPForms).
• Return the values to save. Only the context's tracking keys are kept and every value is sanitized again; leave a key out to save nothing for it. A return that isn't an array keeps the values unchanged. Merge tags and notifications use the filtered values.

Example: add_filter( 'pwtsr_tracking_values', function( $values ) { unset( $values['referrer'], $values['first_referrer'] ); return $values; } ); Actions pwtsr_submission_tracked( $values, $context, $entry_id, $form )

• $values (array) - The tracking values saved with the submission. Empty values are left out.
• $context (string) - Adapter context, as above.
• $entry_id (int|null) - The form plugin's entry ID, or null when it stores none (Contact Form 7, WPForms Lite, or Forminator with entry storage off).
• $form (mixed) - The form, as for pwtsr_tracking_values.
• Fires once per submission after its values are saved, only when there is at least one value. Contact Form 7 fires it once the mail is sent; Gravity Forms skips spam entries.

Example, sending attribution to a CRM: add_action( 'pwtsr_submission_tracked', function( $values, $context, $entry_id, $form ) { wp_remote_post( 'https://crm.example.com/attribution', [ 'blocking' => false, 'body' => [ 'plugin' => $context, 'entry' => $entry_id, 'values' => $values ], ] ); }, 10, 4 ); JavaScript Event After each page view's values are stored, the tracking script dispatches a pwtsr:captured event on document. event.detail holds values (the stored record), replaced (whether this page view set the attribution values), and model: document.addEventListener( 'pwtsr:captured', function( event ) { if ( event.detail.replaced ) { console.log( event.detail.values.utm_source ); } } ); It fires once per page view, and not until consent is given when Visitor Consent is on. Consent With Visitor Consent on, the script reads and stores nothing until the visitor consents. Consent plugins that support the WP Consent API work without setup. Other consent banners can use the JavaScript interface: // After the visitor accepts, or on each page load once they have. presswellSignalRelay.setConsent( true ); // When the visitor withdraws consent; the stored record is removed. presswellSignalRelay.setConsent( false ); // Whether attribution is currently being stored. presswellSignalRelay.hasConsent(); A script that runs before Tracking Signal Relay loads can set window.presswellSignalRelayConsent = true instead. Attribution on the page where consent is given is still captured, but parameters on pages viewed before consent are lost. Default Tracking Keys

• utm_source
• utm_medium
• utm_campaign
• utm_content
• utm_term
• gclid
• fbclid
• msclkid
• ttclid
• landing_page
• landing_query
• referrer

With the First and last model, each is also stored as a first-touch copy prefixed with first_, such as first_utm_source. Settings and Debug Display Use Settings -> Tracking Signal Relay to:

• Choose the attribution model: first and last touch, last touch, or first touch.
• Set how long attribution lasts without a page view.
• Wait for visitor consent before storing attribution.
• Add custom query parameter keys.
• Enable Debug Display for logged-in editors/admins.
• Inspect tracking field wrappers on the frontend while validating form output.

Install via the WordPress plugin installer, or manually upload the plugin directory to wp-content/plugins/. Configuration

1. Activate the plugin.
2. If using Contact Form 7, publish any form (tracking inputs are injected automatically).
3. If using Fluent Forms, edit a form and add the Tracking field.
4. If using Formidable Forms, edit a form and add the Tracking field.
5. If using Forminator, publish a custom form (tracking inputs are injected automatically).
6. If using Gravity Forms, edit a form and add the Tracking field from Advanced Fields.
7. If using WPForms, edit a form and add the Tracking field.
8. Send traffic with UTM/click parameters.

1.0.1

• Now requires PHP 8.2 and WordPress 6.9.
• Added public functions and developer hooks.
• Fixed issue with landing attribution.

1.0.0

• First public release with Contact Form 7, Fluent Forms, Formidable Forms, Forminator, Gravity Forms, and WPForms support, first- and last-touch attribution, and custom parameters.