=== ConvoPixel ===
Contributors: 2jaseel
Tags: chatgpt ads, openai ads, conversion tracking, lead tracking, conversions api
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

ChatGPT Ads conversion tracking for any WordPress site: form leads, calls, sign-ups and WooCommerce sales, via pixel and Conversions API.

== Description ==

**ConvoPixel is conversion tracking for ChatGPT Ads (OpenAI Ads) on any WordPress site.** Paste your Pixel ID and ConvoPixel reports your leads, calls, sign-ups and page views to ChatGPT Ads Manager – plus every WooCommerce event if you run a shop – so you can see which results your ads bring in and run conversion-optimised campaigns.

Without conversion tracking, ChatGPT Ads can't see your leads or sales. ConvoPixel installs the official OpenAI Ads Measurement Pixel, can send leads, sign-ups and purchases from your server through the Conversions API as well, and makes sure each conversion is counted once.

= Built for lead generation =

* **Form leads from 10 form plugins**, detected automatically: Contact Form 7, WPForms, Gravity Forms, Elementor Pro Forms, Fluent Forms, Formidable Forms, Ninja Forms, Jetpack Forms, MC4WP (Mailchimp for WordPress) and Forminator.
* **Only real submissions count.** Leads are recorded when the form plugin confirms a successful submission, so spam and failed validation are left out.
* **Any other form** – theme, page-builder or custom forms – by adding its CSS selector.
* **Thank-you pages** for leads and appointments, for booking plugins and forms that redirect.
* **Calls and WhatsApp.** Click-to-call and WhatsApp clicks can be counted as leads, ideal for local businesses.
* **Lead value.** Give leads an average value (for example 500 INR) so ChatGPT Ads can report conversion value.
* **Sign-ups** from WordPress registration, WooCommerce and membership plugins that create WordPress users.

= Also for online shops =

With WooCommerce active, ConvoPixel adds product views, add to cart, checkout, purchases, completed orders, coupons, cart and wishlist events, with order revenue sent in the currency the customer paid.

= Why ConvoPixel =

* **Two-minute setup.** Install, paste your Pixel ID, save. No code, no Google Tag Manager.
* **Browser pixel + Conversions API.** Leads, sign-ups and purchases are also sent server-side, so ad blockers and closed tabs don't lose conversions.
* **Automatic deduplication.** Browser and server use the same event ID, so ChatGPT Ads keeps one conversion.
* **Ad click matching.** Passes the ChatGPT ad click reference (oppref) and browser reference (obref) with every server event.
* **Better matching, private by design.** Email, phone and name from forms, accounts and orders are normalised and hashed with SHA-256 before they leave your site.
* **Works with caching.** Events from AJAX forms and carts are delivered through a cache-safe queue.

= Events =

Any WordPress site – standard ChatGPT Ads events: page_viewed, contents_viewed (the content types you choose, such as services, listings or courses), lead_created, registration_completed, appointment_scheduled. Custom events: search, phone_clicked, whatsapp_clicked, email_clicked, file_downloaded.

WooCommerce – standard events: contents_viewed (products and variations), items_added, checkout_started, order_created. Custom events: cart_viewed, item_removed, coupon_applied, wishlist_added, order_submitted, order_completed.

Standard events can be used as campaign goals in ChatGPT Ads; custom events are reported for insight. Every event can be switched off.

= Built-in testing tools =

* "Send test event" checks your Pixel ID and API key without recording anything
* Log of recent server-side events with response codes and ad-click matches
* An order note on every WooCommerce order that was sent
* Debug mode that prints every pixel event in the browser console

ConvoPixel is an independent plugin. It is not affiliated with, endorsed by or sponsored by OpenAI or Automattic. ChatGPT and OpenAI are trademarks of OpenAI. WooCommerce is a trademark of Automattic Inc. Other plugin names are trademarks of their respective owners.

== External services ==

ConvoPixel connects your site to the ChatGPT Ads (OpenAI Ads) measurement service, operated by OpenAI, so conversions from your ad campaigns can be reported. Nothing is loaded or sent until you enter a Pixel ID under Settings > ConvoPixel. Administrators, editors and shop managers are not tracked by default, and with Consent set to "Wait for marketing consent" nothing is sent until the visitor agrees.

**1. OpenAI Ads Measurement Pixel (in the visitor's browser)**

* What it is: OpenAI's JavaScript pixel, loaded from https://bzrcdn.openai.com/sdk/oaiq.min.js. It sends events to OpenAI's servers (bzr.openai.com) and stores OpenAI's first-party cookies used for ad attribution.
* When: on front-end page loads and visitor actions, for each event you have switched on in the plugin settings.
* What is sent: the event name (for example page_viewed, lead_created, order_created), page URL, content or product IDs, names and quantities, amounts and currency, the order ID for purchases, and, if "Customer matching" is on, SHA-256 hashes of the visitor's email, phone number, first and last name and user ID (from submitted forms, their account or their order), plus country, city, region and postcode for WooCommerce orders. Email, phone and names are never sent in plain text. Click events send only the event name (and the file name for downloads).

**2. OpenAI Conversions API (from your server)**

* What it is: a server-to-server HTTPS request to https://bzr.openai.com/v1/events.
* When: only if you add a Conversions API key. Events are sent when a supported form is submitted successfully, when a visitor creates an account, when a WooCommerce order reaches one of your "purchase" statuses or is marked Completed, and when you click "Send test event" (validate only, nothing is recorded).
* What is sent: the event name, time and ID, the lead value or order total and currency, WooCommerce products, the page URL the form or checkout was on, OpenAI's ad click reference and browser reference when available, and, if "Customer matching" is on, the SHA-256 hashed customer details listed above plus the visitor's IP address and browser user agent.

OpenAI's terms and privacy information:

* Advertising Terms: https://openai.com/policies/advertising-terms/
* Conversion Terms and all other OpenAI policies: https://openai.com/policies/
* Privacy Policy: https://openai.com/policies/privacy-policy/

As the site owner you are responsible for telling visitors about this tracking in your own privacy policy and for collecting consent where the law requires it.

== Installation ==

1. Go to Plugins > Add New > Upload Plugin, choose convopixel.zip, then Install Now and Activate.
2. Open Settings > ConvoPixel.
3. In ChatGPT Ads Manager, open the Conversions tab, create a pixel and copy its Pixel ID. Paste it into ConvoPixel and click Save changes.
4. Recommended: create a Conversions API key in the same tab, paste it into ConvoPixel, save, then click "Send test event".
5. Under Leads & forms, check your form plugins show as Detected, and set a lead value and default phone country code if you like.
6. Test in a private browser window (administrators aren't tracked by default): submit a form, then check the Recent server-side events log.

If you previously added OpenAI pixel code by hand (theme, header plugin or Google Tag Manager), remove it so the pixel doesn't load twice.

== Frequently Asked Questions ==

= Do I need WooCommerce? =

No. ConvoPixel works on any WordPress site – blogs, service businesses, agencies, portfolios and membership sites. When WooCommerce is active, the shop events switch on automatically.

= How do I track ChatGPT Ads leads from my contact form? =

Install ConvoPixel and paste your Pixel ID. Forms from Contact Form 7, WPForms, Gravity Forms, Elementor Pro, Fluent Forms, Formidable, Ninja Forms, Jetpack, MC4WP and Forminator are tracked automatically as lead_created. For other forms, add their CSS selector under Settings > ConvoPixel > Leads & forms.

= Can I track phone calls and WhatsApp clicks? =

Yes. They are tracked as custom events by default. Tick "Count click-to-call and WhatsApp clicks as leads" to send them as lead_created, which can be used as a campaign goal.

= Can I stop a form from counting as a lead (e.g. newsletter)? =

Yes. Add it under "Forms to ignore", for example cf7:123 for one form or mc4wp for all of a plugin's forms, or add the CSS class convopixel-no-track to the form.

= Do I need the Conversions API key? =

No, the pixel works on its own. The key is recommended: it sends leads, sign-ups and purchases from your server too, which keeps conversions that browsers would miss (ad blockers, closed tabs, redirects).

= Will a conversion be counted twice? =

No. The pixel and the server send the same event ID and ChatGPT Ads keeps the first one it receives. If a tracked form also redirects to a page you listed as a lead thank-you page, remove one of the two.

= Why don't I see events when I test? =

Administrators, editors and shop managers are not tracked by default. Test in a private/incognito window, or untick the Staff option while testing. Clear your page cache after installing.

= Server events are delayed on my site =

Without WooCommerce, server events are sent in the background with WP-Cron, which runs when your site gets a visit. On low-traffic sites, set up a real server cron job for wp-cron.php so events are sent promptly.

= Does it work with GDPR / cookie consent? =

Yes. Switch Consent to "Wait for marketing consent". Tracking then starts when your WP Consent API compatible banner reports consent, or when you call ConvoPixel.grantConsent().

= My site uses a Content Security Policy =

Allow script-src https://bzrcdn.openai.com and connect-src https://bzr.openai.com https://bzrcdn.openai.com.

== Screenshots ==

1. Settings: Pixel ID, Conversions API key and connection status.
2. Events for any WordPress site and for WooCommerce.
3. Leads & forms: detected form plugins, lead value and call tracking.
4. Recent server-side events log with ad-click matches.

== Developers ==

JavaScript: ConvoPixel.lead(); ConvoPixel.measure( 'lead_created', { type: 'customer_action' } ); ConvoPixel.custom( 'newsletter_signup' ); ConvoPixel.grantConsent(); ConvoPixel.revokeConsent();

PHP: ConvoPixel_Forms::lead( 'my-plugin', $form_id, array( array( 'key' => 'email', 'value' => $email ) ) ); records a lead from any custom form handler.

wp-config.php: define( 'CONVOPIXEL_PIXEL_ID', '...' ); define( 'CONVOPIXEL_CAPI_KEY', '...' );

Filters: convopixel_event_enabled, convopixel_page_events, convopixel_lead_value, convopixel_track_form_submission, convopixel_capi_lead_event, convopixel_capability, convopixel_paid_statuses, convopixel_order_value, convopixel_items_added_data, convopixel_capi_order_eligible, convopixel_capi_order_event, convopixel_capi_registration_event, convopixel_exclude_user, convopixel_add_order_notes. Action: convopixel_lead_tracked.

== Changelog ==

= 1.0.0 =
* First release.
