=== UTM Tracker for Gravity Forms ===
Contributors: auxanoglobalservices14
Tags: gravity forms, utm tracking, marketing attribution, click id, campaign tracking
Requires at least: 5.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.2.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

UTM tracking and marketing attribution for Gravity Forms — capture UTM tags, click IDs, landing pages, and traffic channels straight into your forms.

== Description ==

**UTM Tracker for Gravity Forms** connects your marketing campaigns to your form submissions. It reads campaign data from the page URL, stores it in browser cookies, and automatically fills matching Gravity Forms hidden fields — so every lead arrives with the source that generated it. No coding is required.

Instead of guessing where your form leads come from, you can see the exact UTM campaign, ad click, landing page, and traffic channel behind each submission.

= How It Works =

1. A visitor lands on your site through a campaign link (for example, a Google Ads or Facebook link with UTM tags).
2. The plugin captures the campaign data from the URL and saves it in cookies.
3. When the visitor submits a Gravity Form, matching hidden fields are filled in automatically.
4. The campaign data is saved with the entry, ready for your reports and follow-up.

= Tracking Parameters =

The plugin monitors every major marketing parameter. Add a hidden field in Gravity Forms with a matching parameter name to capture any of them:

* **Standard UTM parameters** — utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_id
* **Advertising click IDs** — gclid, gbraid, wbraid, fbclid, msclkid, ttclid, li_fat_id, twclid
* **Custom parameters** — add your own URL keys (for example: affiliate, coupon, salesperson, campaign_owner), one per line

= Attribution Models =

Choose how cookie values behave when the same visitor returns through a different campaign:

* **Last Touch Attribution** — cookie values are updated whenever new parameters appear in the URL, so the most recent campaign is recorded.
* **First Touch Attribution** — cookie values stay locked to the first campaign detected, so later visits do not overwrite them.

= Cookie Settings & Automatic Session Data =

* **Configurable cookie duration** — set how long tracking cookies last, from 1 to 3650 days, using a quick preset or a custom value.
* **Landing page tracking** — capture the first landing page, current landing page, page URL, submission URL, page title, and URL path (utgf_first_landing_page, utgf_landing_page, utgf_current_page_url, utgf_submission_url, utgf_page_title, utgf_url_path).
* **Optional session data** — capture referrer, device type, operating system, browser, traffic channel, and session details. Each value can be mapped to a Gravity Forms hidden field.

= Developer API & Integration Reference =

For developers who want to extend tracking or use the data elsewhere:

* **JavaScript API** — the global `UTMTracker` object provides get(), getAll(), has(), clear(), and attribution helpers.
* **REST API** — `GET /wp-json/utm-tracker/v1/current` returns the active tracked values.
* **Dynamic shortcodes** — output tracked values in posts and pages, for example `[utm_source]` or `[landing_page]`.
* **Action & filter hooks** — customize parameters, cookie behavior, field aliases, and more.

Everything is configured from the **UTM Tracker** menu in your WordPress admin sidebar.

For direct support, email admin@auxanoglobalservices.com.

= Key Features =

**Marketing Attribution**

* First Touch and Last Touch attribution models
* First / Last Touch UTM summaries (source, medium, and campaign)

**Campaign Tracking**

* Standard UTM parameters
* Advertising click IDs from major ad platforms
* Custom URL parameters you define yourself

**Landing Page Tracking**

* Landing page and first landing page
* Current page URL (full URL, including the query string)
* Form submission URL (path only, without query or hash)
* Page title, URL path, and query string

**Visitor & Session Data**

* Browser, operating system, and device type
* Referrer hostname
* Session ID, visit date, visit time, and timezone

**Traffic Channel Detection**

* Paid Search, Organic Search, Paid Social, and Organic Social
* Email, Referral, Direct, and AI Search

**Developer Tools**

* REST API
* JavaScript API
* Dynamic shortcodes

**Admin Tools**

* Cookie Manager
* UTM URL Builder
* Debug Panel
* Export / Import settings

== Installation ==

Follow these steps to start tracking campaign data in your Gravity Forms:

1. Install the plugin by uploading the folder to `/wp-content/plugins/`, or search for it from **Plugins → Add New** in your WordPress dashboard.
2. Activate the plugin through the **Plugins** screen.
3. Make sure **Gravity Forms** is installed and activated.
4. Open **UTM Tracker → Settings** in the WordPress admin sidebar.
5. Set your cookie duration, choose an attribution model, and turn on the tracking options you need.
6. In Gravity Forms, open the form you want to track and add a **Hidden** field for each value you want to capture.
7. On each hidden field, enable **Allow field to be populated dynamically**.
8. Enter the exact **Parameter Name** that matches the tracking key you want, for example `utm_source`, `gclid`, `traffic_channel`, or `landing_page`.
9. Test your setup by visiting a campaign URL, then open **UTM Tracker → Debug** to confirm the values are captured.

**Example test URL**

`https://example.com/contact/?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale`

Tip: The field label in Gravity Forms can be anything you like — only the **Parameter Name** needs to match the tracking key exactly.

== Frequently Asked Questions ==

= Does the field label matter in Gravity Forms? =

No. Only the **Parameter Name** needs to match the tracking key exactly (for example, `utm_source`). The field label can be anything you like.

= Does it work with AJAX forms? =

Yes. The tracker refreshes hidden fields when a form is rendered and when it is submitted, including AJAX-powered Gravity Forms.

= Does it support multi-page forms? =

Yes. Hidden fields are re-populated as each page of a multi-step form loads.

= Does it support multiple forms on one page? =

Yes. Every form with matching hidden field parameter names receives the tracked values.

= Can I track custom URL parameters? =

Yes. Add your parameter names one per line under **UTM Tracker → Tracking → Custom Parameters**, then create matching hidden fields (for example: `affiliate`, `coupon`, `salesperson`, `campaign_owner`).

= What is First Touch Attribution? =

With First Touch Attribution, cookie values are set once on the visitor's first detected campaign and are not overwritten by later visits — so you always know how the visitor first found you.

= What is Last Touch Attribution? =

With Last Touch Attribution, cookie values are updated whenever new parameter values appear in the URL, so the most recent campaign is the one recorded.

= How does Traffic Channel Detection work? =

The plugin reviews click IDs, the UTM medium and source, the referrer hostname, and AI Search signals to assign a channel such as Paid Search, Organic Social, or AI Search.

= Does it support AI Search traffic? =

Yes. AI Search is detected when `utm_medium` is `ai`, `ai_search`, `llm`, or `chatbot`, when `utm_source` matches a known AI platform (for example, `chatgpt`, `perplexity`, or `claude`), or when the referrer is a known AI search domain.

= Does it support Google Ads click IDs? =

Yes. `gclid`, `gbraid`, and `wbraid` are tracked and classified as Paid Search.

= How do I test that tracking is working? =

Open **UTM Tracker → Debug**, add `?utgf_debug=1` to any page URL while logged in as an administrator, or use **UTM Tracker → Cookies** to inspect the stored values.

= How do I clear cookies during testing? =

Use **UTM Tracker → Cookies**, or add `?utgf_cookie_manager=1` to any page URL while logged in as an administrator.

= Can I export and import my plugin settings? =

Yes. Go to **UTM Tracker → Settings → Import / Export** to download your configuration as a JSON file, or import it back later.

= Is there a developer API? =

Yes. You can use the JavaScript `UTMTracker` object, dynamic shortcodes, WordPress filters, and the REST endpoint `/wp-json/utm-tracker/v1/current`. See the **Developer** tab under UTM Tracker settings for full documentation.

= How do I get support? =

For direct support, email admin@auxanoglobalservices.com. You can also open **UTM Tracker → Settings** and click **Email Support**, or post on the [WordPress.org support forum](https://wordpress.org/support/plugin/utm-tracker-for-gravity-forms/).

== Third-Party Libraries ==

This plugin bundles the [Lucide](https://lucide.dev/) icon library (`assets/js/lucide.min.js`), loaded locally in the admin area only — no external requests are made. Lucide is licensed under the ISC License. Non-minified source code: https://github.com/lucide-icons/lucide

== Screenshots ==

1. Tracking Parameters — standard UTM keys, advertising click IDs, and custom parameters.
2. Attribution Models — choose first-touch or last-touch attribution for campaign cookies.
3. Cookie Settings & Automatic Session Data — cookie duration, landing pages, referrer, device, and session tracking.
4. Developer API & Integration Reference — JavaScript API, REST API, shortcodes, and WordPress hooks.

== Upgrade Notice ==

= 2.2.1 =
New One-Click Field Setup: pick a Gravity Form and add the tracking Hidden fields automatically, with duplicate detection. Query String tracking now works on its own without requiring Landing Pages. No breaking changes.

= 2.2.0 =
Major marketing attribution update: landing page tracking, traffic channel detection including AI Search, first/last touch summaries, REST and JavaScript APIs, cookie optimization, and improved Gravity Forms integration.

= 2.1.0 =
Admin UI refresh with Lucide icons, modern navigation, and bug fixes.

= 2.0.0 =
Expanded tracking, attribution models, debug tools, URL builder, REST API, shortcodes, and export/import.

= 1.1.0 =
Added settings page and configurable cookie duration.

= 1.0 =
Initial release.

== Changelog ==

= 2.2.1 =
* Added a Get Started setup wizard — a guided four-step onboarding flow: Welcome, Connect Gravity Forms, Tracking Features, and Finish. It opens once after activation and can be reopened anytime from UTM Tracker → Get Started.
* Added One-Click Field Setup on the Gravity Forms tab (also used by the wizard) — select a form and automatically create the required Hidden fields for any supported tracking value using the official Gravity Forms API.
* Added automatic duplicate detection — fields already present on a form are shown as "Added" and skipped instead of being recreated.
* Added grouped field selection (UTM, click IDs, page context, attribution, and visitor/session) that respects your enabled tracking options.
* Hidden fields are created only when onboarding is completed on the Finish step; onboarding can be completed only once.
* Note: the optional "Stay Updated" email subscription is not enabled in this release — the email field is hidden and no email is collected or sent. The underlying hook (utgf_process_subscription) remains available for a future version.
* Improved page load speed — frontend tracking script and all admin scripts now load with the non-blocking defer strategy, eliminating render-blocking execution.
* Improved asset scoping — plugin styles and scripts load only on settings and wizard pages.
* Improved wizard layout — reduced spacing so the setup card fits comfortably within standard viewport heights without scrolling.
* Improved dropdown fields — custom cross-browser SVG chevron styling with standardized height, padding, and focus ring.
* Improved tooltip display — help icons wrapped in span containers to preserve the title attribute after Lucide icon replacement; animated CSS tooltip card added.
* Fixed settings toggle switch alignment — containers no longer shrink under long descriptions.
* Fixed Query String tracking so it now works independently of Landing Pages — enabling Query String alone captures utgf_query_string. Previously the field stayed empty unless Landing Pages was also enabled.
* Improved Automatic Session Data toggle descriptions with plain-language help text, and added a "Cookie vs live" note clarifying which fields persist in cookies versus which are read at form submission.
* Improved admin layout to use the full available page width with alignment, spacing, and responsive refinements.
* All new admin actions are nonce-protected, capability-limited to administrators, with sanitized input and escaped output.
* No changes to attribution models, REST/JS APIs, or shortcodes — fully backward compatible. Query String tracking now works standalone, as noted above.

= 2.2.0 =
* Added first-touch and last-touch attribution models with dedicated UTM summary cookies
* Added landing page tracking: first landing page, current landing page, current page URL, submission URL, page title, URL path, and query string
* Added automatic traffic channel detection: Paid Search, Organic Search, Paid Social, Organic Social, Email, Referral, Direct, AI Search, and Other
* Added AI Search detection via UTM source/medium values and AI referrer domains
* Added custom parameter tracking with Gravity Forms and shortcode support
* Added REST API endpoint: GET /wp-json/utm-tracker/v1/current
* Added JavaScript API: UTMTracker.get(), getAll(), has(), clear(), getTrafficChannel(), getFirstTouch(), getLastTouch(), and page context helpers
* Added dynamic shortcodes for UTMs, click IDs, visitor data, page context, and traffic channel
* Added Cookie Manager with search, filter, copy value, and expiry display
* Added Debug Panel in admin and frontend overlay (?utgf_debug=1)
* Added UTM URL Builder and export/import settings as JSON
* Improved Gravity Forms integration with server-side population, field aliases, and AJAX/multi-page support
* Improved cookie optimization — browser, OS, device, and page URLs computed at runtime
* Improved admin UI with developer documentation tab
* Fixed hidden field population for aliased parameters (landing_page, referrer, browser, traffic_channel, etc.)
* Fixed query string and submission URL tracking
* Fixed traffic channel Direct fallback incorrectly overriding AI Search UTM detection
* Fixed admin namespace and debug panel JavaScript errors

= 2.1.0 =
* Migrated admin icons to Lucide
* Redesigned navigation to segmented pill layout
* Added brand logo in admin header
* Fixed URL Builder tooltip, JavaScript boot callback, and skeleton loading overlays
* Standardized button and form field styles

= 2.0.0 =
* Added expanded UTM and click ID tracking
* Added custom URL parameter support
* Added first-touch and last-touch attribution models
* Added landing page, referrer, device, and session tracking
* Added debug panel, cookie manager, URL builder, REST API, shortcodes, and export/import
* Rebuilt plugin with namespaced OOP architecture
* Removed jQuery dependency from frontend tracker

= 1.1.0 =
* Added admin settings page
* Added configurable cookie duration presets

= 1.0 =
* Initial release.
