Utmatra – UTM Attribution and Tracking

FAQ

Does this plugin store personal data?

Raw IP addresses are never stored. Each IP address is combined with a secret per-site salt and hashed with SHA-256 before storage, so the stored hashes cannot be correlated with hashes from other sites. User agents and referrer URLs are stored as-is. This applies to the first page of each visit (landing page and referrer, recorded while “Track the first page of every visit” is on under Settings → Tracking) and to every tagged visit. A form submission that carries attribution is recorded as a conversion event with the same data as a campaign visit (hashed IP, user agent, referrer, the page the form was on) — never the submitted field values. Events are pruned automatically after a retention period (180 days by default, adjustable from the dashboard settings card; 0 keeps events forever). CSV exports never include IP hashes or user agents. If you configure a webhook, attributed orders and form submissions, including the submitted form fields, are sent to that external service. Suggested privacy policy text is provided under Settings → Privacy → Policy Guide.

How does tracking work on a cached site?

Full-page caches serve HTML without running PHP, which breaks purely server-side trackers. Utmatra ships a small beacon script in every front-end page: when the visitor’s URL carries a tracked parameter, or on the first page of a visit, the beacon reports it to a public REST endpoint. On uncached pages a server-side fallback records tagged visits even for visitors without JavaScript; it does not record untagged landings, because PHP has no per-session marker to tell a landing from the next page view and would count every page of a no-JS visit. Deduplication ensures a tagged visit recorded by both paths is only counted once.

Contact Form 7, Gravity Forms, Ninja Forms and Elementor Pro fill their attribution fields when the page is generated, so a cached page carries the campaign of whoever loaded it first. When the form is submitted, the values the plugin filled in are replaced with the submitter’s own attribution (or the field’s default when there is none), so entries and notification emails do not show another visitor’s campaign. Values you supply yourself are kept: a Gravity Forms parameter in the page URL or field_values (and Gravity Forms REST or API submissions are left as sent), an Elementor dynamic-tag default when the visitor has no attribution, and any Contact Form 7 form tag you added under an attribution field name. Bricks resolves its tags when the page is generated and is not corrected on submit.

How do I create a tracked short link?

Add a link under Tracked Links on the dashboard. With pretty permalinks enabled the link is served at /go/{slug}/; on plain permalinks it falls back to /?utmatra_track={slug}. Either URL records the click and 302-redirects the visitor to the destination with the link’s UTM parameters appended. You can copy the URL, embed it with [utmatra_link id="my-link" label="Click here"], or use the QR button to download a scannable PNG for print, packaging, or slides.

You can also use the drawer as a plain UTM builder: switch on Build a URL only and the live preview becomes a tagged URL you copy with the submit button — no short link is created and nothing is saved. Presets apply in both modes, and link-level custom parameters (see the next FAQ) are appended too.

Can I track my own URL parameters (coupon, affiliate ID, promo code)?

Yes. Under Settings → Tracking → Custom parameters, enter up to ten names separated by commas (for example coupon, aff, promo2). Names must start with a letter and use lowercase letters, digits and underscores (up to 32 characters); input is lowercased on save. From then on a URL such as /?coupon=SPRING10 is treated exactly like a tagged visit: the value is recorded on the event (in a JSON column, one key per parameter), carried in the attribution cookie and in webhook payloads, offered to forms as <name> and <name>_first fields, exported as its own CSV column, and available as an optional per-link field on tracked links — a link with a coupon value set appends ?coupon=… to the destination on redirect. Values are stored as-is (case-sensitive, up to 255 characters), so SPRING10 never becomes spring10.

Some names are reserved and rejected with a message: the built-in parameters, anything starting with utm_, utmatra_ or first_, anything ending in _first, the plugin’s own field and touch names (landing_page, channel, lp, params, …), events-table columns, common form and credential field names (email, name, password, …) and WordPress public query variables (s, p, page, …).

Three things to know:

• Do not name a parameter after a form field or after anything that identifies a person (an email address, a phone number, a name). Whatever the URL parameter carries is stored on the event, placed in the attribution cookie and written into any form input that shares the parameter’s name — a visible input named like a custom parameter is pre-filled from the cookie on every page, which is the point for coupon boxes but the wrong tool for personal data. The reserved list blocks the most common collisions, but you are naming a field that lives in the same namespace as real HTML form fields.
• Tracking Doctor may report forms as “partial”. Every form adapter that does not inject fields itself (Gravity Forms, Ninja Forms, Elementor, Fluent Forms, Formidable, Forminator, Bricks) compares the form’s fields against the full field list, so once you define a custom parameter those forms count as missing coupon and coupon_first until you add the fields. Contact Form 7 and WPForms inject the fields automatically and stay “complete”. This is the check working as intended: the form really does not capture the parameter yet.
• On cached sites the list reaches visitors when the page cache regenerates. The parameter list is baked into the page HTML, so a newly added parameter is captured on cached pages only after the cache is purged, and a removed parameter keeps being written into the attribution cookie by the stale page (the server ignores the value) until then. Adding and removing a parameter takes effect on uncached pages immediately.

Are clicks from bots and link previews counted?

No. Requests whose user agent looks like a crawler, link-preview unfurler (Slack, WhatsApp, Facebook, etc.), or monitoring tool are excluded from your stats. They still receive the redirect so previews resolve correctly. Adjust the verdict with the utmatra_is_bot filter.

What does the attribution cookie store?

When a visitor arrives with a UTM parameter or ad click ID, or lands from another site (a search engine, social network, AI assistant or any other referrer), the plugin sets a first-party cookie named utmatra_attr containing two sets of campaign data: the visitor’s first touch (preserved once written) and last touch (updated on every tagged or referred visit). Each set holds the whitelisted UTM/click-ID parameters present on that visit, or the channel and referrer host of an untagged landing, plus the landing page URL and a timestamp. A direct visit without parameters never writes or updates the cookie. The cookie does not store names, email addresses, or IP addresses.

The cookie lives for 90 days (path=/, SameSite=Lax, Secure on https sites). Change the lifetime with utmatra_cookie_days or disable the cookie entirely with utmatra_enable_cookie (see the filter reference below).

A second cookie, utmatra_vid, holds a random visitor id (UUID v4) generated in the browser — from the browser’s cryptographically secure random source, falling back to JavaScript’s Math.random() only in browsers that lack it — or by the server-side fallback for visitors without JavaScript. It is not derived from your IP address or any personal data, and it is written, refreshed and deleted under exactly the same conditions and lifetime as utmatra_attr. It links a visitor’s tagged visits to their later orders and form submissions for the Journeys report. On sites with a consent banner, visits recorded before the visitor consents carry no visitor id, so a journey begins with the first tagged visit after consent.

How does the plugin handle cookie consent?

The plugin does not ship a consent banner. If a plugin implementing the WP Consent API is active (Complianz, Real Cookie Banner, Borlabs Cookie, and others implement it), the attribution cookie is gated on the visitor’s consent:

• The decision is made in the browser. The front-end beacon asks the Consent API’s JavaScript whether the visitor granted the configured category before it writes the cookie, so gating is correct even on pages served from a full-page cache. The PHP fallback writer (for visitors without JavaScript) applies the same rule per request.
• Consent category. Choose which category gates the cookie under Settings → Data and privacy → Consent: Marketing (the default — the cookie carries advertising click IDs), Statistics, or Marketing or statistics.
• Withdrawal deletes the cookie. When the visitor withdraws consent, the beacon deletes the attribution cookie immediately.
• While the banner is undecided no cookie is written. The landing visit’s campaign data is kept in page memory only and written to the cookie the moment consent is granted on that page; forms are not pre-filled from an existing cookie until the visitor decides. A visitor who navigates away before deciding and grants consent on a later page is attributed from their next tagged visit. The beacon’s per-tab duplicate guards for the collect request (the utmatra_sent marker, which holds the URL’s own query string, including any UTM values and click IDs, and the utmatra_visit flag that records that the tab is already inside the site, having reported its landing or been opened from an internal link) are kept in session storage, which lasts only for the life of the tab, and are unaffected by consent.
• Events are recorded regardless of consent by default: a tagged-visit event and an untagged landing visit carry no cookie and only a salted IP hash. Return true from the utmatra_consent_gate_events filter to withhold events as well until the visitor consents.
• The plugin declares itself to the Consent API and describes the cookie (name, category, lifetime, purpose) so consent banners can list it.

Without a Consent API plugin the cookie is written on every tagged visit and every landing from another site; gate it yourself by returning false from utmatra_enable_cookie, or install a consent plugin that implements the API.

Two notes for sites with a full-page cache:

• On sites with a full-page cache, a change to the consent category reaches visitors after the cache is purged.
• After deactivating a Consent API plugin, purge the page cache: cached HTML that still advertises the API makes the beacon hold the touch until the visitor’s next uncached load.

How does WooCommerce order attribution work?

When a visitor who previously arrived through a tracked campaign or from another site places an order, the order is stamped at checkout with their first- and last-touch attribution sets (order meta, shown in a “Campaign attribution” metabox on the order edit screen). The conversion event with the order total is recorded, and the conversion webhook sent, once the order is paid: when the gateway completes payment, or when the order moves to a paid status such as processing or completed (cash on delivery, or bank transfer once marked paid). Declined, abandoned and unpaid orders are never counted, and each order is counted once. Each touch carries ch (the channel) and, when known, rh (the referrer host) alongside the campaign parameters, in the order meta and in the conversion webhook payload. The dashboard then shows a revenue-by-campaign chart, and the weekly email includes a revenue table. No configuration needed — it activates automatically when WooCommerce is present.

How are channels classified?

Every recorded visit, click and conversion is filed into one channel when it is written, following the rule order of Google Analytics’ default channel grouping with one addition for AI assistants: a gclid or msclkid is paid search; a source naming an AI assistant is AI assistant; a display medium (display, banner, cpm, …) is display; a paid medium (cpc, ppc, paid-social, …) is paid search, paid social or paid (other) depending on the source; a social medium or source is organic social; an organic medium or search-engine source is organic search; an email or newsletter source or medium is email; affiliate is affiliate; referral, app or link is referral; a Facebook, TikTok, LinkedIn or X click ID without a medium is paid social; otherwise the referrer host decides (AI assistant, search engine, social network, or referral for any other site); anything else with campaign data is other and a visit with neither is direct.

Three host lists drive the referrer rules and can be extended with the utmatra_ai_assistant_hosts, utmatra_search_engine_hosts and utmatra_social_network_hosts filters. AI assistants include ChatGPT, Perplexity, Claude, Gemini, Copilot, You.com, Phind, Poe, Meta AI, Mistral, Grok, DeepSeek, Duck.ai and Kimi; ChatGPT and Perplexity also tag their outbound links with utm_source, which the source rules recognise. Brave Search counts as organic search, because its AI answers render on the normal results page and the referrer cannot tell them apart. Facebook appends fbclid to organic clicks too, so an untagged Facebook click reads as paid social; override any verdict with the utmatra_channel filter. The channel is derived from the visitor’s own referrer, so a Google Mail or Google Docs link is filed as organic search, as in GA4.

Untagged landings are reported by the front-end beacon only (no PHP fallback, see the cached-site FAQ) and share the collect endpoint’s rate limit with tagged visits; raise it with utmatra_rate_limit when many visitors share one IP.

How do I capture attribution in my lead forms?

Every tracked parameter is available to forms under its own standard name: utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content, gclid, fbclid, msclkid, ttclid, li_fat_id, twclid, landing_page (the landing page URL), channel and referrer_host — plus every custom parameter you define, under its own name (for example coupon and coupon_first). These hold the visitor’s last touch; append _first (e.g. utm_source_first, landing_page_first) for the first touch.

Any form plugin (generic): add a hidden input (or text field) with one of the names above and it is auto-filled from the attribution cookie on page load. Fields that already have a value are never overwritten. Forms injected into the page after load (some popup builders) are not filled automatically. The cookie carries channel only for visits without campaign parameters, so the generic fill populates it for organic, social, AI-assistant and referral visitors; the server-side adapters below always have it.

Contact Form 7: zero configuration — the last-touch fields are appended to every form as hidden fields automatically and arrive with each submission. Use special mail tags in your mail templates to include them in notification emails: [_utm_source], [_utm_campaign], [_gclid], [_landing_page], [_channel], [_referrer_host], etc. (any field name above with a leading underscore works, including _first variants such as [_utm_source_first]).

Gravity Forms: add a Hidden field, enable “Allow field to be populated dynamically” under the field’s Advanced tab, and set the parameter name to e.g. utm_source or utm_source_first.

Ninja Forms: add a Hidden field to your form and set its default value to {utmatra:utm_source} (or any other tracked parameter, e.g. {utmatra:gclid}, {utmatra:landing}, {utmatra:channel}, {utmatra:referrer_host}, {utmatra:utm_source_first}) to capture attribution.

Elementor (Pro Forms): add a Hidden field to your form (Advanced tab), set its Field ID to utm_source (or any other tracked parameter name, e.g. utm_source_first for first touch), and it is auto-filled from attribution data on render. Requires Elementor Pro — free Elementor has no form builder.

Fluent Forms: add a Hidden Field and set its Name Attribute to e.g. utm_source (or utm_source_first). It is filled from the attribution cookie by the page script on load. Submissions are listed in the dashboard widget automatically.

WPForms (Lite and Pro): zero configuration — every attribution field above is added to each form as an empty hidden input and filled on page load, so the values arrive with each submission. To put them in notification emails, add the smart tags {utm_source}, {utm_campaign}, {landing_page} … (any field name above, including _first variants) to the notification subject or message. To store a value in an entry (Pro), set one of those tags as the default value of a Hidden Field (Lite: a Single Line Text field); it is filled on page load, not when the page is generated. If “Optimize Email Sending” is enabled, notification emails are sent later in the background, where the tags cannot be resolved — use a field default instead.

Formidable Forms: add a Hidden field and, under Advanced, set its Field Key to e.g. utm_source (Formidable may append a number on other forms, such as utm_source2 — that still works). The field is filled on page load.

Forminator: add a Hidden Field, set Default Value to “Query parameter” and the Query parameter to e.g. utm_source (or utm_source_first). The field is filled on page load; a matching URL parameter on the current page takes precedence. Forms set to “Load form using AJAX” are inserted after page load and are not filled.

Bricks Builder: add a Hidden field to the Form element and set its value to the dynamic data tag {utm_source} (all field names above are listed under the “Utmatra” group of the dynamic data picker). To list the submission as a lead in the dashboard widget, add the “Custom” action under “Actions after successful form submit”. The tag is resolved when the page is generated, so on a fully page-cached site the stored value may be stale. Bricks support is untested against a live Bricks install; please report problems.

Can I send leads and orders to Zapier, Make, HubSpot or GoHighLevel?

Yes. Under Settings → Webhooks, paste your receiver’s URL, pick a preset (Generic JSON, Zapier, Make, HubSpot Forms, GoHighLevel) and use the “Send for” switches to enable or disable WooCommerce orders and form leads independently (both are on by default; the HubSpot preset sends leads only). Because the payloads carry the submitted form fields, use an https:// URL so the values are not sent in cleartext. Every request is a JSON POST signed with an X-Utmatra-Signature header (sha256 = HMAC of the body over a per-site secret shown on the same card) and tagged with an X-Utmatra-Event header (conversion, lead or test), so any receiver can verify and route it — compare the signature with a constant-time check (e.g. PHP’s hash_equals()). Send test webhook posts a synthetic payload in the selected preset’s shape before you rely on it. Lead webhooks are sent as the form is submitted; order webhooks are sent by the background queue (Action Scheduler) once the order is paid, usually within a minute.

A lead payload carries the integration (e.g. contact-form-7), the form id and title, the submitted form field values keyed by label (up to 50 fields of 1,000 characters each; file uploads, passwords and hidden fields are never sent), the first- and last-touch attribution sets, the page URL and a timestamp. The plugin itself never stores the submitted field values — they travel only in the webhook request. One exception: when a receiver answers with an error, a short excerpt of its response is kept under “Last delivery” so the failure can be diagnosed, and such an error message may quote a submitted value (HubSpot, for instance, echoes an invalid email address back). Values that are arrays (checkbox groups) arrive comma-joined; deeply nested values arrive as a JSON string. Field forwarding for Gravity Forms and Elementor Pro is derived from the vendors’ documentation, untested against a live install.

The Generic JSON preset (also used by Zapier and Make, whose receivers parse nested JSON themselves) sends the payload as-is. The HubSpot preset converts it into a HubSpot Forms API v3 submission: it needs a HubSpot form carrying fields named email, firstname, lastname, phone and hidden utm_source, utm_medium, utm_campaign, utm_term, utm_content (HubSpot rejects submissions with fields the form does not have — the error shows under “Last delivery”); when the visitor carries HubSpot’s own hubspotutk tracking cookie it is forwarded so the submission links to their visitor record. The GoHighLevel preset flattens the payload into one level of snake_case keys (email, phone, first_name, last_name, utm_*, first_utm_*, landing_page, field_<name>), as its Inbound Webhook trigger requires. The HubSpot and GoHighLevel request shapes follow the vendors’ documentation and have not been verified against a live account.

How do I export my data?

Click Export CSV on the dashboard to download the raw events for the selected period and campaign filter (the newest 10,000 rows are exported). The columns, in order: clicked_at, link_id, channel, utm_source, utm_medium, utm_campaign, utm_id, utm_term, utm_content, gclid, fbclid, msclkid, ttclid, li_fat_id, twclid, destination, referrer, is_conversion, order_total, visitor_id, then one column per configured custom parameter (in saved order). The channel column and the custom-parameter columns carry values only once those features are active; visitor_id is empty on events recorded before this version. The export never includes IP hashes or user agents. Because the export also includes conversion rows (flagged in the is_conversion column) — WooCommerce orders (link_id order) and form leads (link_id lead) — alongside click rows, its total row count can exceed the click total shown on the dashboard. Untagged landing visits are left out unless the REST call to utmatra/v1/export passes include_visits=1. Values that could be interpreted as spreadsheet formulas are prefixed with ' for safety.

How do I get a weekly report by email?

Enable “Send a weekly campaign summary email” on the dashboard settings card (it is off by default — no unsolicited mail). Once a week the site admin email receives an HTML summary with total clicks, the top 5 campaigns and sources, and revenue by campaign when WooCommerce is active. Change the recipient with the utmatra_report_recipient filter. Delivery goes through wp_mail(), so any SMTP plugin you use applies.

My site is behind a reverse proxy or CDN — anything to configure?

Yes. Behind a proxy (Cloudflare, Varnish, a load balancer), REMOTE_ADDR is the proxy’s IP, not the visitor’s. Click deduplication and the collect endpoint’s rate limiting key on a hash of that IP — so with the default behaviour all visitors would share the proxy’s identity, over-deduplicating clicks and tripping the rate limit for everyone. Use the utmatra_client_ip filter to return the real client IP from the header your proxy sets (e.g. CF-Connecting-IP, or the first entry of X-Forwarded-For). Only trust forwarded headers when every request passes through a proxy that overwrites them — they are client-spoofable otherwise. If configuring the real IP is not possible, raise the shared ceiling with the utmatra_rate_limit filter instead.

Why are my UTM values being changed when I save a link?

Values are normalized for consistent reporting: lowercased, with whitespace replaced by -. Analytics tools treat Newsletter, newsletter, and News letter as three different sources, silently fragmenting reports. Normalization (applied in the form and again server-side) keeps every report row canonical.