=== TrueConversion — Lead Source Tracking & Google Ads Offline Conversions ===
Contributors: forgeonline 
Tags: utm tracking, lead source, google ads, offline conversions, form tracking
Requires at least: 6.0
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.1.0
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.
* **AI Classification (Pro)** — Automatically classify leads as conversions or not using AI. No API key needed — it's all handled for you.
* **Dashboard** — View all form submissions with traffic source, UTM data, conversion status, and AI classification.
* **CSV Export** — Export all entries including conversion and AI data.
* **Email Notifications** — Per-submission alerts and periodic summary emails.
* **Privacy Friendly** — IP addresses are anonymised. No data sent to third parties on the free plan.

= 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

= Plans =

* **Free** — All form integrations, dashboard, CSV export, email notifications, conversion marking, Google Ads offline conversion upload.
* **Pro ($79/month)** — Everything in Free + AI-powered lead classification via the TrueConversion server (10,000 classifications/month). No API key needed.

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

On the Pro plan, TrueConversion automatically analyses form submissions to determine if they have genuine commercial intent. This means real enquiries are automatically marked as conversions, while spam, sales pitches, and job applications are filtered out. No API key needed — classification is handled via the TrueConversion server.

= Does the free plan send data to external services? =

The free plan only connects to external services when you use Google Ads integration (which sends conversion data to Google). AI classification on the Pro plan sends form data to the TrueConversion server for analysis.

= 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. AI classification is processed via a secure proxy — no API keys are stored on your 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 Terms](https://ads.google.com/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)

= TrueConversion AI Proxy =
* **When:** Pro plan, when classifying form submissions via hosted AI.
* **What is sent:** Freemius license key, site URL, form name, submitter name, submitter email, message content.
* **Service:** trueconversion.net/wp-json/tc/v1/classify
* **Purpose:** Provides AI classification without requiring users to manage API keys. Uses Claude AI (Anthropic) for classification.
* **Privacy Policy:** [TrueConversion Privacy Policy](https://trueconversion.net/privacy)

= Freemius =
* **When:** Always (handles licensing, updates, and in-dashboard checkout).
* **Service:** [Freemius](https://freemius.com)
* **Privacy Policy:** [Freemius Privacy Policy](https://freemius.com/privacy)

== Screenshots ==

1. Dashboard showing form entries with traffic sources and conversion status.
2. Entry detail modal with UTM parameters, conversion status, and AI classification.
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 ==

= 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.
* AI lead classification via hosted TrueConversion proxy (Pro plan).
* Per-submission email notifications and periodic summary emails.
* Setup wizard with Google Ads connection step.
* AES-256-CBC encryption for stored tokens.

== Upgrade Notice ==

= 1.1.0 =
Fixes a tracking issue affecting Safari users in private browsing mode or 
with ITP enabled. Upgrades are recommended for all sites running Google Ads 
traffic, as some conversions may have been missed due to blocked cookies. 
No database changes — safe to update.
