ClickTrail – UTM, Click ID & Ad Tracking (with Consent)

Changelog

The entries below are historical release notes. They do not replace the current source/evidence status in
docs/reference/INTEGRATIONS.md and docs/guides/SECURITY-PRIVACY.md; earlier claims may describe intended
behavior that still requires current runtime verification. In particular, older wording that calls platform-named
server paths “first-class native delivery adapters” predates the current evidence classification: those paths are
configured-endpoint relays whose provider authentication, acceptance, and runtime delivery remain unverified.

1.10.0

• Consent-safe delivery: queued retries recheck the current consent snapshot immediately before adapter delivery, so a withdrawal is not replayed from historical queue state.
• Cross-tab consent authority: browser consent state now uses versioned timestamped authority, same-tab events, and cross-tab storage synchronization; stale plugin-cookie and banner values cannot revive a withdrawal.
• WooCommerce privacy lifecycle: order metadata is managed through an explicit ClickTrail allowlist, with personal-data export/erase, bounded retention, manual purge, uninstall cleanup, and classic/HPOS-compatible CRUD access. Unrelated order metadata is preserved.
• Form evidence contract: deterministic six-case manifests cover Contact Form 7, Fluent Forms, Gravity Forms, WPForms, Ninja Forms, and Elementor. These manifests remain explicitly runtime-unverified without pinned WordPress/plugin staging evidence.
• Free capture layer: normalized marketing-trail envelopes now carry stable event, trail, anonymous, lead, workspace, and site identifiers alongside first/last-touch attribution, UTMs, click IDs, landing page, referrer, consent, and form context.
• Diagnostics and quality: added readiness analyzers, consent snapshot contracts, WooCommerce classic/HPOS contract coverage, pinned supply-chain workflows, Dependabot, OSV, Scorecard, and contributor/security guidance.
• Release boundary: provider acceptance, compliance, and complete runtime integration claims remain evidence-gated. See the integration reference and security guide for the current limits.

1.9.1

• Fluent Forms fix: attribution now persists in Fluent Forms submission metadata using its response_id schema column.
• Compatibility: tested up to WordPress 7.1.

1.9.0

• New foundation (no visible UI change): ClickTrail writes structured touch-event records in clicutcl_touch_events alongside the legacy diagnostics table. This is a reporting foundation, not a complete privacy certificate: the current audit found hashed-identity matching gaps, WooCommerce order-meta lifecycle gaps, retention coupling, and queue/revocation boundaries. See docs/architecture/DATA-MODEL.md and docs/guides/SECURITY-PRIVACY.md for the current evidence status.

1.8.19

• Maintenance: removed dead Settings API code left over from before the unified settings screen (includes/admin/class-admin.php, ~890 lines removed). Verified against every live admin page before removal. No functional or user-facing changes.

1.8.18

• Maintenance: expanded the automated test suite to cover REST API auth boundaries (token validation, webhook signatures, CRM lifecycle tokens) and queue retry-backoff logic. No functional or user-facing changes.

1.8.17

• Diagnostics: the Conflict Scan now detects active call tracking scripts (CallRail, CallTrackingMetrics, WhatConverts, and others) and surfaces an informational note explaining that ClickTrail already skips tel: link decoration automatically — no action needed.
• UX: corrected the Conflict Scan card description on the Diagnostics screen, which had fallen out of sync with what the scan actually checks.

1.8.16

• Diagnostics UX: the “Lookup Order” tool now explains when an order’s attribution is empty because marketing consent was denied at capture time, instead of just showing empty first-touch/last-touch data. Closes GitHub issue #44, where a consent-denied order correctly fell back to “Direct” but the diagnostics gave no indication why.

1.8.15

• Security (informational hardening): the per-IP rate limiter now uses an atomic increment-then-check when a persistent object cache is available, closing a small burst-margin race under concurrent requests from the same IP; falls back to the existing transient-based check otherwise.
• Security (informational hardening): classic UTM/click-ID attribution fields are now capped at 255 characters before being stored in the attribution cookie, session storage, and WooCommerce order meta, matching the length cap already used for the signed cross-domain attribution token.

1.8.14

• Packaging fix: config/feature-registry.json was accidentally excluded from every shipped release build, including the current WordPress.org version, causing the delivery-adapter dropdown and destinations list to render empty. The config directory now ships again.
• Security UX: the settings backup export now carries an explicit on-screen warning that the downloaded file contains live, unmasked webhook secrets and should be handled like a credentials file.
• Docs: corrected a stale reference to a removed legacy API file in the REST API reference.
• Maintenance: internal dev-tooling cleanup (removed unused local Claude Flow tooling, added GitHub Spec Kit for planning). No functional or user-facing changes.

1.8.13

• Security and consent hardening: browser REST intake now accepts only ClickTrail’s real browser events, applies a per-page-token replay limit, preserves separate analytics and marketing consent categories across supported CMPs, honors custom consent cookies server-side, and never lets an external CMP re-enable gating when Consent Mode is disabled.
• Attribution reliability: cross-domain verification now sends the required page token; attribution cookies are encoded, size-bounded, and cleared instead of leaving stale server values; pre-consent attribution is not persisted while consent is required.
• Webhook and privacy fixes: Typeform and HubSpot use their native signatures, HubSpot batches are handled item by item, consent-skipped webhook/lifecycle responses report their real status, retry rows no longer persist raw IP or user agent, and consent withdrawal removes pending attribution plus browser identifiers.
• Maintenance and tests: removed dead legacy tracking-v2 AJAX handlers and added focused PHP/JavaScript boundary regressions.

1.8.12

• UX: clearer in-app explanation of how ClickTrail preserves landing-page attribution across the consent banner.

1.8.11

• Maintenance: internal code cleanup. No functional changes.

1.8.10

• Security: server-side delivery endpoint is validated against SSRF: The collector / server-side GTM endpoint URL is now checked on save (internal, loopback, and non-public addresses are rejected), and every outbound delivery request rejects unsafe URLs, so a misconfigured or hostile endpoint can no longer be pointed at internal network resources.
• Security: webhook signature and secret handling hardened: Inbound webhook signatures are compared on the raw value with strict format validation, and provider secrets are stored exactly as entered (they are no longer truncated or whitespace-stripped, which previously could corrupt long secrets and break verification). Replay protection is now race-safe on sites with a persistent object cache.
• Security: cross-domain attribution-token verification now requires the page token, matching the signing endpoint and removing an unauthenticated request path.
• Privacy: visitor IP is anonymized in the diagnostic event log (the full IP is still used only transiently for server-side conversion matching). The personal-data eraser now also clears queued server-side delivery records.
• Privacy: geo-based consent no longer trusts client-supplied country headers by default, since those headers can be spoofed unless set by a trusted CDN. An unknown region now safely defaults to requiring consent. Sites behind a trusted edge can re-enable header trust with the clicutcl_trust_geo_request_headers filter, or provide an authoritative country with clicutcl_request_country_code.
• Security: Gravity Forms attribution merge tags are always HTML-escaped in output.
• Admin: a warning now appears when “encrypt secrets at rest” is enabled but the server cannot support it, so secrets are not silently stored unencrypted.

1.8.9

• i18n: German (de_DE) JavaScript translations now load: Added the script-translation JSON for the React settings app. Without this file, the de_DE locale shipped in v1.8.7 only translated PHP-side strings; the JS-side React UI (Capture/Forms/Events/Delivery tabs) stayed in English. Generated via wp i18n make-json for assets/js/admin-settings-app.js.

1.8.8

• Security: Reject unsubstituted ad-platform dynamic-parameter macros (Facebook {{campaign.name}}, {{adset.name}}, etc.) during attribution capture. These placeholders appear literally in landing-page URLs when ads aren’t served through the ad platform, and previously flowed into attribution storage and downstream destinations as if they were real campaign names. Applied to both PHP server-side sanitizer and the client-side sanitizeValue() helper.
• Fix: Consent gate no longer defaults to ON when Consent Mode is disabled. Two paths previously read a removed legacy require_consent option (default TRUE) — on any site without Consent Mode + a CMP, that implicit default silently blocked all attribution. Now the gate is only active when Consent Mode is explicitly enabled.
• Housekeeping: GTM Starter Kit lead-magnet banner disabled in-plugin; the kit is now distributed via the website. The class file stays for future re-activation; the runtime init() call is commented out and the source files added to .distignore so they’re not bundled in the WP.org SVN release.

1.8.7

• Brazilian Portuguese (pt_BR) translations refreshed: Regenerated from current source code (was last updated at v1.5.2). 533 strings translated, 81 strings carried over from the prior translation but flagged for human review where the underlying source string changed.
• German (de_DE) translations added: Full translation of all 614 strings — first locale beyond Portuguese.

1.8.6

• Block third-party promotional banners: Bundle-sale ads and other plugin notices can no longer inject promotional banners into the ClickTrail wizard, settings, logs, or diagnostics pages.
• Admin UI consistency pass: Expanded design tokens (status colors, background scale, 8px spacing scale), aligned card and section header padding, removed a duplicated 90-line GTM-offer CSS block.

1.8.5

• WordPress 7.0 compatibility: Tested up to WordPress 7.0 “Armstrong” (released 2026-05-20). Requires WooCommerce 10.4.2 or later for WP 7.0 compatibility.
• Script enqueue refactor: Removed dead pre-WP-6.3 fallback from clicutcl_script_args(). All supported installs (WP 6.5+) now use the array-form registration and optional defer/async strategy keys.
• Deprecation scan in CI: Added composer phpcompat and a PHPCompatibilityWP GitHub Actions workflow to flag PHP and WordPress deprecated/removed API usage on every push.

1.7.2

• NitroPack compatibility: ClickTrail now detects NitroPack and automatically attempts to exclude its scripts from NitroPack’s “Postpone JS” feature via two mechanisms: the nitropack_js_url_exclude filter and the data-nitropack-exclude HTML attribute on script tags. Without this, postponed scripts can cause empty UTM data on leads when users navigate away before interacting with the page.
• NitroPack diagnostic warning: The Diagnostics conflict scan now surfaces a warn finding when NitroPack is active, with instructions to verify script exclusions in NitroPack → Optimization → JavaScript → Script exclusions.
• pt-BR playbook — webhook middleware pattern: Expanded the Padrão 5 section in the Portuguese Implementation Playbook to document the three-layer webhook architecture (script → webhook middleware → CRM), the complete field reference for Google Ads and Meta Ads attribution, PipeRun-specific notes on custom field IDs, and common errors including the silent field-drop behaviour when CRM fields do not exist before the first webhook call.

1.7.1

• Setup Wizard: Added a 3-step onboarding wizard that fires automatically on first activation. Step 1 auto-detects active form plugins, WooCommerce, CMPs, and caching layers. Step 2 collects the GA4 Measurement ID. Step 3 confirms attribution is active with a quick-test link. All external admin notices are suppressed while the wizard is open. A permanent “Setup Wizard” link is added to the plugin action row on the Plugins screen.
• Activation fix: Setup_Wizard::init() now registers before the preflight class check so the activation redirect fires reliably on all environments.
• Two-phase consent capture: UTMs and click IDs are now buffered to sessionStorage immediately on page load before any consent banner fires. On consent grant the pending buffer is promoted to the attribution cookie, preserving first-touch even when the user accepts the banner on a later page.
• Call tracking MutationObserver skip: The MutationObserver watching for dynamically inserted links now bails early when every new anchor has a skippable scheme (tel:, mailto:, #). Eliminates wasted debounce cycles from Dynamic Number Insertion tools such as CallRail, CallTrackingMetrics, and WhatConverts.
• GF / WPForms attribution field diagnostic: The Diagnostics conflict scan now checks every active Gravity Forms and WPForms form for ct_* hidden fields. Forms without attribution fields surface a warning with a direct edit link. No new AJAX endpoints.
• Cross-domain decoration checklist warning: The setup checklist now shows a warn state when link decoration is on but no allowed domains are listed, and an informational note about external payment providers when decoration is correctly configured.
• Cross-domain limitations documentation: Added a “Cross-Domain Limitations” section to the Implementation Playbook and a payment provider table to the Integrations reference covering Stripe, PayPal, Mollie, and Square.
• Portuguese (pt-BR) Implementation Playbook: Added IMPLEMENTATION-PLAYBOOK.pt-BR.md covering all rollout patterns including webhook/CRM integrations, the window.ClickTrail JS API field reference, and external checkout limitations.
• WP.org compliance: Plugin zip folder renamed from cth to click-trail-handler to match the WordPress.org plugin slug requirement.
• Elementor Forms popup fix: Attribution data is now injected reliably when an Elementor popup opens and when new form inputs appear in the DOM after initial page load.
• CI: Fixed CodeQL workflow — removed PHP from the language matrix and updated action refs to v4.

1.7.0

• Hardening release. No user-visible feature changes; addresses ten findings from the 1.6.0 internal code review.
• Fixed admin QA mode cache-poisoning risk: adminQaMode is no longer baked into the localized attribution config, where a full-page cache plugin could capture it from an admin-viewed response and serve it to anonymous visitors. It is now a 1-hour clicutcl_admin_qa cookie set on init only for logged-in manage_options users, which cache plugins correctly exclude.
• Fixed minification-exclusion attributes: the previous set advertised support for WP Rocket and LiteSpeed but used non-existent attribute names. Replaced with the canonical attributes each tool actually reads: data-no-optimize, data-noptimize, data-cfasync, data-no-defer, data-no-minify.
• Replaced str_replace(' src=', ...) injection with regex-based injection after the opening <script token, robust to attribute order and leading/trailing whitespace.
• Refactored Gravity_Forms_Adapter from ~660 lines into four focused classes: Gf_Channel_Resolver, Gf_Form_Settings_Tab, Gf_Merge_Tags, Gf_Minification_Protector. The adapter is now a thin coordinator under 350 lines. All public method signatures preserved; resolve_channel_fallback() kept as a backward-compat shim.
• Memoized Attribution_Settings instance inside the adapter and shared it with the extracted classes — fewer redundant Option_Cache reads per request.
• Added PHPUnit unit-test suite for Gf_Channel_Resolver covering 10 classification rules, including the gemini.google.com precedence over Google Organic and the fbclid+paid-medium gate.
• Added documentation in HOOKS-REFERENCE.md clarifying that ct_* entry meta is registered for all forms but values are gated per-form, and that channel labels are stored data values (not UI strings) and should not be wrapped with __().
• Added inline comments documenting fail-open semantics when GF form context is unavailable, and the GF 2.5+ single-arg signature of gform_pre_form_settings_save.

1.6.0

• Added full channel classification to Gravity Forms entries: ct_ft_channel stores a human-readable label (Google Ads, ChatGPT, Mailchimp, etc.) derived from click IDs, UTM parameters, or referrer context; server-side fallback computes the label when JS is unavailable.
• Added six new click IDs to the capture schema: rdt_cid (Reddit), pin_cid (Pinterest), snap_cid (Snapchat), mc_cid and mc_eid (Mailchimp), and dclid (Display & Video 360).
• Added nine {clicutcl_*} merge tags for Gravity Forms notifications and confirmations, including {clicutcl_channel}, {clicutcl_click_id}, and seven UTM-based tags.
• Added per-form attribution tracking toggle in Gravity Forms form settings, with a global default option and clicutcl_gf_tracking_enabled filter for developer overrides.
• Added admin QA mode: attribution data is written to sessionStorage only when a manage_options user is logged in, preventing admin browsing from polluting attribution records.
• Added sessionStorage fallback for attribution capture when browser cookies are blocked.
• Added minification-exclusion data attributes to ClickTrail script tags to prevent cache and optimization plugins from deferring or bundling them.
• Added entry-edit safety for Gravity Forms: ct_* attribution meta is excluded from the editable fields screen and restored automatically if cleared during a manual entry edit.

1.5.2

• Normalized mixed line endings in core PHP handlers to keep standards checks deterministic across environments.
• Resolved the remaining PHPCS findings in the consent, attribution-token, and privacy handlers.
• Kept runtime behavior unchanged from 1.5.1.

1.5.1

• Aligned the public plugin version to 1.5.1 across release surfaces.
• Cleaned up public changelog wording to keep it competitor-neutral and product-focused.
• Kept runtime behavior unchanged from 1.5.0.

1.5.0

• Declared WooCommerce HPOS compatibility during bootstrap and kept Woo order tracking on Woo order APIs.
• Enriched WooCommerce purchase payloads with additive order totals, coupon/status data, richer item detail, and customer/order metadata.
• Added opt-in WooCommerce storefront events for view_item, view_item_list, view_cart, add_to_cart, remove_from_cart, and begin_checkout, including richer product-list context.
• Added a dedicated sGTM compatibility mode with tagging-server URL support, first-party or custom-loader GTM delivery, and preview checks in the Events tab.
• Added Woo order milestone delivery for order_paid, order_refunded, and order_cancelled, plus Diagnostics trace lookup for stored payload snapshots.
• Added setup checklist, conflict scan, backup restore, and Woo order trace lookup in the admin surfaces.
• Added Pinterest Conversions API and TikTok Events API as first-class native delivery adapters.
• Added registry-backed QA/docs alignment for the expanded destination and diagnostics surface.
• Included the recent WordPress.org deployment cleanup, Plugin Check fixes, privacy-query hardening, and better debug visibility.

1.3.9

• Made WordPress privacy export and erasure safer by escaping user_id fragments used inside LIKE-based event matching.
• Improved large-site privacy erasure performance by deleting matched event rows in batches.
• Added lightweight caching for frequently read plugin settings.
• Stopped loading the frontend consent bridge script on pages that do not need attribution capture, consent handling, or browser events.
• Added clearer debug output for invalid attribution-token payloads and for database-level failures during privacy erasure.

1.3.8

• Added a smarter referrer fallback for visits that arrive without UTMs or click IDs.
• ClickTrail now classifies common search, social, and external referral traffic into first-touch and last-touch source / medium values.

1.3.7

• Introduced dedicated session management with a 30-minute inactivity model and separate session storage.
• Added client-side and server-side session helpers so forms, purchases, and event payloads can include consistent session information.

1.3.6

• Added native Elementor Forms support and completed the Ninja Forms submission-storage path.
• Expanded the capture schema to include newer UTM fields and browser/platform identifiers.
• Split browser event collection from browser event transport and moved frontend attribution onto the shared consent bridge.

1.3.5

• Rebuilt the main settings experience around four capability-based tabs: Capture, Forms, Events, and Delivery.
• Removed user-facing “Tracking v2” language from the main admin flow while keeping backward-compatible internal storage where needed.

Older release notes remain available in `changelog.t