=== Forge TrueConversion Lead Tracking for Google Ads ===
Contributors: forgeonline
Tags: utm tracking, lead source, google ads, offline conversions, form tracking
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.0.1
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Track where your form leads come from, mark real enquiries as conversions, and send them back to Google Ads so it stops optimising for junk.

== Description ==

**TrueConversion** tracks the traffic source of every form submission on your WordPress site and lets you mark only the real commercial enquiries as conversions. Those conversions are then sent back to Google Ads via the offline conversion API, so Google can optimise your ad spend for leads that actually matter.

= The Problem =

Google Ads counts every form submission as a conversion — including spam, sales pitches, job seekers, and people who clicked the wrong button. This means Google optimises your campaigns to find more of these junk leads, wasting your budget.

= The Solution =

TrueConversion captures the Google Click ID (gclid) along with UTM parameters and other ad platform click IDs. When a form is submitted, you can mark genuine commercial enquiries as conversions and send them back to Google Ads. Google then learns what a real lead looks like and optimises accordingly.

= Key Features =

* **Automatic UTM & Click ID Capture** — Captures utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid, msclkid, and more.
* **Works With All Major Form Plugins** — Contact Form 7, WPForms, Gravity Forms, Ninja Forms, Formidable Forms, Fluent Forms, Elementor Pro Forms, Forminator, and Jetpack Forms.
* **Conversion Marking** — Mark real enquiries as conversions with one click.
* **Google Ads Upload** — Automatically send conversions to Google Ads via the offline conversion API.
* **Dashboard** — View all form submissions with traffic source, UTM data, and conversion status.
* **CSV Export** — Export all entries including conversion data.
* **Email Notifications** — Per-submission alerts and a monthly summary email.
* **Privacy Friendly** — IP addresses are anonymised. No data sent to third parties beyond Google Ads (only when you connect it).

Want AI to automatically classify leads for you, plus daily/weekly summary emails? See **TrueConversion Pro**, a separate add-on plugin.

= Supported Form Plugins =

1. Contact Form 7
2. WPForms (Lite & Pro)
3. Gravity Forms
4. Ninja Forms
5. Formidable Forms
6. Fluent Forms
7. Elementor Pro Forms
8. Forminator
9. Jetpack Forms
10. Any form via the `[tc_fields]` shortcode

= Free vs. Pro =

This plugin (Free) includes all form integrations, the dashboard, CSV export, email notifications, conversion marking, and Google Ads offline conversion upload — unlimited entries, no time limit.

**TrueConversion Pro** is a separate add-on plugin that layers on top of this one and adds AI-powered lead classification plus daily/weekly summary emails.

== Installation ==

1. Upload the `trueconversion` folder to the `/wp-content/plugins/` directory, or install directly from the WordPress plugin repository.
2. Activate the plugin through the 'Plugins' menu in WordPress.
3. Follow the setup wizard to select your form plugins and configure notifications.
4. (Optional) Connect Google Ads to start sending conversions.

== Frequently Asked Questions ==

= Which form plugins are supported? =

Contact Form 7, WPForms, Gravity Forms, Ninja Forms, Formidable Forms, Fluent Forms, Elementor Pro Forms, Forminator, and Jetpack Forms. You can also use the `[tc_fields]` shortcode with any other form.

= Do I need a Google Ads account? =

No. The free plan tracks traffic sources without any Google Ads connection. Google Ads integration is included free — connect it when you're ready.

= How does the Google Ads integration work? =

TrueConversion captures the Google Click ID (gclid) when a visitor arrives from a Google ad. When you mark a form submission as a conversion, the plugin sends the gclid and conversion data to Google Ads via the offline conversion API. Google then uses this signal to optimise your campaigns.

= What is AI classification? =

That's a TrueConversion Pro feature (separate add-on plugin). Pro automatically analyses form submissions to determine if they have genuine commercial intent, so real enquiries are marked as conversions while spam and sales pitches are filtered out.

= Does this plugin send data to external services? =

Only when you connect Google Ads integration, which sends conversion data to Google via a relay server (see Third-Party Services below). Nothing else leaves your site.

= Is my data secure? =

Yes. OAuth tokens are stored encrypted using AES-256-CBC. The Google Ads OAuth flow uses a relay server so the client secret never touches your WordPress site.

== Third-Party Services ==

This plugin connects to the following third-party services:

= Google Ads API =
* **When:** When uploading offline conversions or fetching conversion actions (all plans, when Google Ads is connected).
* **What is sent:** Google Click ID (gclid), conversion action ID, conversion timestamp.
* **Service:** [Google Ads API](https://developers.google.com/google-ads/api/docs/start)
* **Privacy Policy:** [Google Privacy Policy](https://policies.google.com/privacy)
* **Terms:** [Google Ads API Terms and Conditions](https://developers.google.com/google-ads/api/terms)

= TrueConversion Relay Server =
* **When:** During Google Ads OAuth connection flow, token refresh, and API requests.
* **What is sent:** OAuth state token, site URL, refresh token (for token refresh), Google Ads API requests (proxied with developer token).
* **Service:** trueconversion.net/wp-json/tc-relay/v1
* **Purpose:** Securely handles Google OAuth and API requests without exposing the client secret or developer token in the plugin code.
* **Privacy Policy:** [TrueConversion Privacy Policy](https://trueconversion.net/privacy-policy/)

== Screenshots ==

1. Dashboard showing form entries with traffic sources and conversion status.
2. Entry detail modal with UTM parameters and conversion status.
3. Google Ads setup page with step-by-step guide.
4. Settings page with form plugin selection and notification preferences.
5. Setup wizard for first-time configuration.

== Changelog ==

= 2.0.1 =
* Fix: the setup wizard rendered as a completely blank step, and the Previous/Next buttons didn't advance correctly — `wp_localize_script()` always sends numbers as strings, and the step-matching logic used strict comparison (`===`) against the un-cast string, so no step ever matched.

= 2.0.0 =
* Split into two plugins: TrueConversion (this plugin, free) and TrueConversion Pro (separate add-on for AI classification and daily/weekly summaries).
* Removed Freemius licensing SDK from this plugin — it now ships with zero third-party licensing dependencies.
* Fix: the "Mark as Conversion" button was gated behind a Pro-plan check in the admin JS even though conversion marking is a free/all-plans feature — this silently disabled it for non-Pro installs. Removed the check.

= 1.3.2 =
* Fix: upgraded Google Ads API from v20 (deprecated/blocked) to v24, resolving the "Version v20 is deprecated" error when creating conversion actions and uploading offline conversions.

= 1.3.1 =
* Privacy: internal tracking fields (utm_*, tc_*) and uploaded file names are no longer included in the data sent for AI classification.
* Fix: the full message and form-field details are now stored and shown in View Details; the dashboard list shows a short preview only.
* Fix: duplicate form field labels are preserved instead of silently overwriting each other.
* Fix: multi-select / checkbox values now display consistently as comma-separated lists across all form plugins.
* Fix: last-click attribution no longer loses an ad click ID when a later visit carries only UTM parameters.
* Maintenance: distribution build script and packaging improvements; readme stable tag corrected.

= 1.1.0 =
* Fix: Safari ITP / private browsing no longer blocks tracking after ad click redirects.
* Added hidden form field injection as cookie fallback for all supported form plugins.
* Added MutationObserver for dynamically-loaded forms (popups, AJAX content).
* Improved localStorage backup with form-level data injection.

= 1.0.0 =
* Initial release.
* UTM parameter and click ID capture for 10 form plugins.
* Admin dashboard with search, sort, and CSV export.
* Manual conversion marking with Google Ads offline conversion upload.
* Per-submission email notifications and periodic summary emails.
* Setup wizard with Google Ads connection step.
* AES-256-CBC encryption for stored tokens.

== Upgrade Notice ==

= 2.0.0 =
This plugin no longer includes AI lead classification or Freemius licensing — install the separate TrueConversion Pro plugin if you want those. Everything else is unchanged.

= 1.3.2 =
Required update: Google Ads API upgraded from the now-blocked v20 to v24. Install to restore conversion action creation and offline conversion uploads.

= 1.0.0 =
Initial release of TrueConversion.
