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

Complete marketing attribution for Gravity Forms — UTM tracking, click IDs, landing pages, traffic channel detection, REST/JS APIs, and session data.

== Description ==

UTM Tracker for Gravity Forms is a complete marketing attribution solution for Gravity Forms. It captures campaign data from the URL, stores it in browser cookies, classifies traffic into marketing channels, and automatically fills matching Gravity Forms hidden fields.

**What you can track**

* **UTM parameters** — source, medium, campaign, term, content, id
* **Advertising click IDs** — gclid, gbraid, wbraid, fbclid, msclkid, ttclid, li_fat_id, twclid
* **Custom URL parameters** — affiliate, coupon, salesperson, campaign_owner, or any key you define
* **Attribution** — first-touch or last-touch models, plus first/last touch UTM summaries
* **Landing pages** — first and current landing page URLs
* **Page context** — current page URL, form submission URL, page title, URL path, query string
* **Visitor data** — browser, OS, device type, referrer, session ID, visit date/time, timezone
* **Traffic channels** — Paid Search, Organic Search, Paid Social, Organic Social, Email, Referral, Direct, AI Search

**Developer tools**

* REST API endpoint: `/wp-json/utm-tracker/v1/current`
* JavaScript API: `UTMTracker.get()`, `getAll()`, `has()`, `clear()`, and attribution helpers
* Dynamic shortcodes: `[utm_source]`, `[traffic_channel]`, `[landing_page]`, and more
* WordPress hooks and filters for extending tracking behavior

**Admin tools**

* Cookie Manager — inspect, search, copy, and clear tracking cookies
* UTM URL Builder — generate campaign links with one click
* Debug Panel — admin diagnostics and frontend overlay for testing
* Export / Import — backup and migrate settings as JSON

Configure everything from the **UTM Tracker** menu in your WordPress admin sidebar. No coding required for standard Gravity Forms integration.

For direct support, email admin@auxanoglobalservices.com.

= Key Features =

**Attribution**

* First Touch Attribution
* Last Touch Attribution
* First / Last Touch UTM summaries (source, medium, campaign)

**Marketing Tracking**

* Standard UTM parameters
* Advertising click IDs
* Custom parameters

**Landing Page Tracking**

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

**Visitor Tracking**

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

**Traffic Detection**

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

**Developer Features**

* REST API
* JavaScript API
* Dynamic shortcodes

**Admin Features**

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

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/` or install from the WordPress plugin directory.
2. Activate the plugin through the **Plugins** screen.
3. Install and activate **Gravity Forms**.
4. Open **UTM Tracker → Settings** in the WordPress admin sidebar.
5. Configure cookie duration, attribution model, and tracking toggles.
6. In Gravity Forms, add **Hidden** fields for each value you want to capture.
7. Enable **Allow field to be populated dynamically** on each hidden field.
8. Enter the exact **Parameter Name** (e.g. `utm_source`, `gclid`, `traffic_channel`, `landing_page`).
9. Test with a campaign URL or open **UTM Tracker → Debug**.

**Example test URL**

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

== Frequently Asked Questions ==

= Does the field label matter in Gravity Forms? =

No. Only the **Parameter Name** must match the tracking key exactly (e.g. `utm_source`). The field label can be anything.

= Does it work with AJAX forms? =

Yes. The tracker refreshes hidden fields on form render and submission, including AJAX-powered Gravity Forms.

= Does it support multi-page forms? =

Yes. Fields are re-populated when 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 tracked values.

= Can I track custom URL parameters? =

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

= What is First Touch Attribution? =

Cookie values are set once on the visitor's first detected campaign and are not overwritten by later visits.

= What is Last Touch Attribution? =

Cookie values are replaced whenever new parameter values appear in the URL. The latest campaign always wins.

= How does Traffic Channel Detection work? =

The plugin analyzes click IDs, UTM medium and source, 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 (e.g. `chatgpt`, `perplexity`, `claude`), or when the referrer is from 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 tracking? =

Use **UTM Tracker → Debug**, append `?utgf_debug=1` to any page URL (administrators), or use **UTM Tracker → Cookies** to inspect stored values.

= How do I clear cookies during testing? =

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

= Can I export plugin settings? =

Yes. Go to **UTM Tracker → Settings → Import / Export** and download your configuration as JSON.

= Is there a developer API? =

Yes. 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 contact support? =

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

== Screenshots ==

1. UTM Tracker settings — cookie duration, session tracking, and traffic channel toggles.
2. Gravity Forms hidden fields with dynamic population enabled.
3. Tracking parameters — UTM keys, click IDs, and custom parameters.
4. Cookie Manager — inspect and clear stored tracking cookies.
5. Debug Panel — URL parameters, cookies, and attribution diagnostics.
6. UTM URL Builder — generate campaign links.
7. Developer documentation — JavaScript API, REST API, and shortcodes.

== Upgrade Notice ==

= 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.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.
