Description
GlobalDev SignalBridge for OpenAI Ads adds the OpenAI Ads Measurement Pixel to WordPress and provides configurable tracking for WordPress content, WooCommerce commerce actions, common form submissions, registrations, subscription events, URL-based success events, and custom events. For WooCommerce purchases it can also send paid order_created events through the OpenAI Conversions API from the server.
The plugin accepts the complete OpenAI base pixel snippet from Ads Manager. For security, it does not store or execute arbitrary pasted JavaScript. It extracts the pixelId and debug setting, then generates the fixed official SDK loader itself.
Current standard events supported:
page_viewed– selectable public WordPress post types plus optional archive/search/taxonomy/404 routes.contents_viewed– WooCommerce single product pages.items_added– successful WooCommerce AJAX/Blocks add-to-cart actions plus non-AJAX fallback.checkout_started– WooCommerce checkout page with cart value/currency/contents when available.order_created– paid WooCommerce order on a valid order-received URL, with order value/currency/contents, stable event ID, mandatory order-key validation, and a persistent one-time database guard.lead_created– successful Contact Form 7, Elementor Pro Form, and WPForms AJAX submissions, plus optional success URL rules.registration_completed– frontend WordPress/WooCommerce registrations plus optional success URL rules.appointment_scheduled– configurable success URL rules or JavaScript API.trial_started– configurable success URL rules, JavaScript API, and automatic WooCommerce Subscriptions trial detection when available.subscription_created– configurable success URL rules, JavaScript API, and automatic WooCommerce Subscriptions parent-order detection when available.custom– configurable custom event name and URL rule, plus JavaScript API.
The plugin maps each standard event to the OpenAI data type documented by the official OpenAI Ads Measurement Pixel GTM template:
contents: page_viewed, contents_viewed, items_added, checkout_started, order_created.customer_action: lead_created, registration_completed, appointment_scheduled.plan_enrollment: trial_started, subscription_created.custom: custom event.
The browser also exposes window.gdOpenAIAdsTrack() for integrations that need to fire a standard event at a business-specific success point.
Click triggers measure an event when a visitor clicks a button, link or any other element. On the settings page each rule pairs a CSS selector with an event (lead_created, appointment_scheduled, registration_completed, contents_viewed, items_added, checkout_started, trial_started, subscription_created or a custom event) and can be sent on every click, once per page view or once per browser session. The same can be done without a rule by adding the attribute data-gd-oai-event to an element, or from code with window.gdOpenAIAdsOnClick(). Click triggers cannot send page_viewed or order_created.
Optional server-side tracking uses the OpenAI Conversions API. When enabled, the plugin sends paid WooCommerce order_created events to https://bzr.openai.com/v1/events using the same wc_order_{ID} identifier as the browser Pixel so OpenAI can deduplicate browser and server delivery. The Conversions API key is stored only in WordPress options and is never exposed to frontend JavaScript. Successful server delivery is recorded in WooCommerce order metadata and failed deliveries are retried a limited number of times.
Since 1.3.0 the Conversions API can also deliver the other measured events, not only purchases: contents_viewed, items_added, checkout_started, lead_created, registration_completed, appointment_scheduled, trial_started, subscription_created, custom events and, optionally, page_viewed. When the browser Pixel measures one of the selected events, the visitor’s browser posts the same event to your own site, and WordPress forwards it to OpenAI with the same event ID so the browser and server copies are deduplicated. Because the request comes from the visitor’s browser, this also works on fully cached pages. order_created is never accepted from the browser; it is sent only from verified, paid WooCommerce orders. The settings page shows the last successful server delivery, the last error, and a connection test that validates the saved Pixel ID and key without recording a conversion.
WooCommerce attribution diagnostics can record an OpenAI Ads click when the official oppref signal is present and can record a direct ChatGPT referral when a browser referrer is available. These local records are stored on WooCommerce orders and are diagnostic only; OpenAI Ads Manager determines final ad attribution.
An optional enhanced matching setting can add supported customer matching fields to Pixel initialization when they are available. Email, phone, first name, last name and external customer ID are normalized and SHA-256 hashed server-side. Supported location fields are passed in the format accepted by the OpenAI Pixel. This setting is disabled by default and should be enabled only when the site owner’s privacy and consent configuration permits it.
When enhanced matching is enabled, three coverage options (all on by default, each can be switched off) raise the share of events that carry user data:
- External ID for every visitor – registered customers keep their hashed account ID; all other visitors get a random, pseudonymous first-party ID (cookie
gd_oai_vid, 12 months) that is SHA-256 hashed and sent as the external ID. Guest orders carry the same ID in their server-side event. - Remember hashed identifiers – after a visitor is identified once (login, checkout, order or form), the SHA-256 hashes are kept in the browser’s local storage and reused on later page views, including cached pages and logged-out visits. Only hashes are stored.
- Checkout and lead-form email – the email typed into the WooCommerce checkout, or submitted through a tracked Contact Form 7, Elementor Pro or WPForms form, is hashed in the browser and added to the Pixel before the conversion is measured.
Developers can add customer information with window.gdOpenAIAdsIdentify() and connect a consent manager with window.gdOpenAIAdsConsent().
This community plugin is developed by GlobalDev and is not affiliated with or endorsed by OpenAI. OpenAI and ChatGPT are trademarks of their respective owner.
External services
This plugin connects to OpenAI Ads measurement services when configured.
The browser loads the official JavaScript SDK from:
https://bzrcdn.openai.com/sdk/oaiq.min.js
Measurement events are transmitted by the OpenAI SDK according to the configured Pixel ID and enabled events. When Conversions API / server-side tracking is enabled, paid WooCommerce order_created events and the events selected under “Additional server-side events” are also sent from the WordPress server to:
https://bzr.openai.com/v1/events
The additional events first travel from the visitor’s browser to this WordPress site (wp-admin/admin-ajax.php, same origin) and are forwarded from the server. No third party other than OpenAI receives them.
Server requests use the saved Conversions API key in an Authorization header and the configured Pixel ID as the pid query parameter. This external service is required for OpenAI Ads tracking functionality.
OpenAI terms and privacy information:
https://openai.com/policies/terms-of-use/
https://openai.com/policies/privacy-policy/
Site owners are responsible for appropriate privacy disclosures and for obtaining any consent required by applicable law before enabling measurement technologies.
Privacy
The plugin stores its WordPress configuration, including Pixel ID, debug preference, event toggles, post-type selections, URL trigger rules, click trigger rules, product identifier preference, attribution setting, enhanced-matching setting, Conversions API enablement, and the Conversions API key when supplied.
When local attribution is enabled and a qualifying OpenAI Ads or ChatGPT source signal is detected, the plugin may set a signed first-party attribution cookie for up to 30 days and save source metadata on the resulting WooCommerce order. The OpenAI oppref value, when available, is stored with the order for diagnostics.
When enhanced matching is enabled, supported customer identifiers are normalized and hashed before being added to OpenAI measurement payloads. Supported location values may be sent in the documented format. For Conversions API purchase events, the OpenAI browser reference (__obref), customer IP address, and user agent may also be sent when available.
When the “External ID for every visitor” option is enabled, the plugin sets the first-party cookie gd_oai_vid (random identifier, 12 months) and, when Conversions API is enabled, stores that identifier on the WooCommerce order created by the visitor. Only its SHA-256 hash is sent to OpenAI. When “Remember hashed identifiers” is enabled, the hashed user object is stored in the browser’s local storage under gd_oai_user. A consent denial set through gdOpenAIAdsConsent(false) is stored in local storage under gd_oai_consent and removes both identifiers.
For events relayed through the Conversions API with enhanced matching enabled, the visitor’s hashed identifiers, the OpenAI browser reference (__obref), IP address and user agent are sent to OpenAI. The OpenAI click identifier (oppref) is sent when present. The plugin stores the time and result of the last server delivery and connection test in the gd_oai_ads_capi_status option.
A click trigger set to “once per browser session” stores a marker in the browser’s session storage (gd_oai_click_*), as the existing once-per-session events do (gd_oai_once_*).
Frontend measurement data is sent through the OpenAI Ads Measurement Pixel when configured. Review OpenAI documentation and your applicable privacy/consent obligations before deployment.
Installation
- Upload the plugin ZIP through Plugins > Add New > Upload Plugin.
- Activate the plugin.
- Go to WooCommerce > SignalBridge when WooCommerce is active, or Settings > GlobalDev SignalBridge otherwise.
- Paste the complete OpenAI Ads base pixel snippet from Ads Manager, or enter the Pixel ID directly.
- Optional: enable Conversions API / server-side tracking and paste the Conversions API key from OpenAI Ads Manager.
- Save changes.
- Optional: under “Additional server-side events” choose which events are also delivered server-side, then use “Test Conversions API connection” in the “Server-side delivery status” box.
- Optional: enable Enhanced matching when your privacy and consent configuration permits it.
- Select which WordPress post types and standard events should be tracked.
- Keep debug mode enabled while validating, then disable it in production.
FAQ
Does the plugin store the JavaScript snippet I paste?
No. It extracts the Pixel ID and debug flag. Arbitrary JavaScript is not stored or executed.
Why does page_viewed work on custom post types?
The settings page enumerates all currently public WordPress post types and allows administrators to select or clear them individually.
Why does the plugin sometimes send only {type:”contents”}?
OpenAI’s current event schema makes fields such as contents optional. For events where richer metadata is reliable, the plugin sends it. For generic routes or events where product/action metadata is not available, the plugin sends the minimal valid event payload.
How is order value formatted?
Monetary values are sent as integers in the currency minor unit. For example, 129.99 RON is sent as 12999 with currency RON.
Which product ID is sent?
You can choose SKU with a WooCommerce ID fallback, or WooCommerce product/variation ID. Use the option that matches your product/catalog feed.
Does it support WooCommerce Blocks?
Yes. The plugin listens for WooCommerce’s native wc-blocks_added_to_cart success event as well as classic WooCommerce’s added_to_cart event.
Can I track a click on a button or link?
Yes, in three ways.
- Settings page: under “Click triggers” add a rule with the element’s CSS selector, for example
#request-quote,.cta-buttonora[href^="tel:"], and choose the event. A click on anything inside the matched element counts. - HTML attribute: add
data-gd-oai-event="lead_created"to the element. For a custom event usedata-gd-oai-event="custom"together withdata-gd-oai-custom-name="quote_clicked". Adddata-gd-oai-once="page"ordata-gd-oai-once="session"to send it only once. -
JavaScript:
gdOpenAIAdsOnClick(‘#request-quote’, ‘lead_created’);
gdOpenAIAdsOnClick(‘.pricing .cta’, ‘custom’, { custom_event_name: ‘pricing_cta_clicked’, once: ‘session’ });
When server-side tracking is enabled, click events selected under “Additional server-side events” are also delivered through the Conversions API with the same event ID.
Can I fire an event myself from another plugin?
Yes. On the frontend use, for example:
gdOpenAIAdsTrack('appointment_scheduled');
gdOpenAIAdsTrack('trial_started', { plan_id: 'monthly-plan' });
gdOpenAIAdsTrack('custom', {}, { custom_event_name: 'quote_requested' });
Does the plugin support server-side tracking?
Yes. Enable Conversions API / server-side tracking and save the Conversions API key from OpenAI Ads Manager. Paid WooCommerce order_created events are then sent from WordPress to the OpenAI Conversions API. Browser and server purchase events reuse the same event ID so OpenAI can deduplicate them.
OpenAI Ads Manager shows “No recent server-to-server events”. What should I check?
That warning appears when no Conversions API event reached OpenAI during the last 24 complete UTC hours. Check, in this order:
- “Enable server-side tracking” is ticked and a Conversions API key is saved.
- “Test Conversions API connection” in the “Server-side delivery status” box passes. If it fails, the HTTP error returned by OpenAI is shown, for example a wrong key type.
- At least one event is selected under “Additional server-side events”. Before 1.3.0 only paid orders were sent server-side, so a day without a paid order produced this warning.
- “Last successful delivery” in the status box is recent. Ads Manager needs some time to reflect new server events.
OpenAI Ads Manager shows “Some events are missing user data”. How do I raise coverage?
Enable Enhanced matching and keep its three coverage options ticked. External ID coverage then applies to every measured event, because every visitor has either a hashed account ID or a hashed pseudonymous visitor ID. Email coverage rises for visitors who identify themselves (login, checkout, order, lead form) and stays attached on their later page views. Email coverage cannot reach every event: an anonymous visitor who never enters an email has none to send.
How do I connect a consent manager?
In PHP, return false from the gd_oai_ads_pixel_enabled, gd_oai_ads_conversions_api_enabled or gd_oai_ads_enhanced_matching_enabled filters when measurement or matching is not permitted. In the browser, call gdOpenAIAdsConsent(false) to stop measurement and the server relay and to remove the SignalBridge visitor cookie and remembered hashes, and gdOpenAIAdsConsent(true) when consent is granted.
Can I add customer data from my own integration?
Yes, when Enhanced matching is enabled:
gdOpenAIAdsIdentify({ email: 'jane@example.com', first_name: 'Jane', last_name: 'Doe', external_id: 'crm-123' });
Values are normalized and SHA-256 hashed in the browser before they are given to the Pixel.
Which API key should I use?
Use the OpenAI Ads Conversions API key intended for server event delivery. Do not use an Advertiser API key. The key is stored in WordPress options and is never printed into browser code.
Does this plugin use customer data for enhanced matching?
Only when the optional Enhanced matching setting is enabled. Email, phone, first name, last name and external customer ID are normalized and SHA-256 hashed before being included in supported OpenAI measurement payloads. Supported country, city, region and postal-code values are passed in the documented format. For Conversions API purchase events, the stored OpenAI browser reference, customer IP address and user agent can also be included when available. The setting is disabled by default.
Screenshots
Changelog
1.3.0
- Add server-side delivery for
contents_viewed,items_added,checkout_started,lead_created,registration_completed,appointment_scheduled,trial_started,subscription_created, custom events and, optionally,page_viewed, with selectable events. Browser and server copies share one event ID. - Server-side delivery of these events works on fully cached pages and on sites without WooCommerce.
- Add a “Server-side delivery status” box with the last successful delivery, the last error and a validate-only connection test.
- Enhanced matching: send an external ID for every visitor using a hashed pseudonymous first-party ID; guest orders now carry an external ID in their server event.
- Enhanced matching: remember hashed identifiers in the browser so later page views keep email and other matching fields.
- Enhanced matching: use the email entered at checkout and in tracked lead forms, hashed in the browser.
- Enhanced matching: use the WordPress account email and name for logged-in customers without billing details.
- Fix: the Pixel phone hash now includes the country calling code for local-format numbers, matching the Conversions API hash.
- Fix:
page_viewedevent IDs printed into cached HTML were shared by every visitor of that cached page; IDs are now unique per page view. - Fix:
checkout_startedevent IDs were identical for different shoppers with the same cart contents; IDs are now unique per shopper. - Add click triggers: settings-page rules (CSS selector, event, frequency), the
data-gd-oai-eventHTML attribute andwindow.gdOpenAIAdsOnClick(). - Add
window.gdOpenAIAdsIdentify()andwindow.gdOpenAIAdsConsent(). - Add filters
gd_oai_ads_enhanced_matching_enabled,gd_oai_ads_relay_events,gd_oai_ads_capi_event,gd_oai_ads_capi_relay_user_data,gd_oai_ads_checkout_event_id,gd_oai_ads_client_ip,gd_oai_ads_relay_rate_limit,gd_oai_ads_relay_allowed_hosts,gd_oai_ads_relay_urlandgd_oai_ads_click_triggers. - All existing events, settings, hooks and order metadata are unchanged.
1.2.0
- Require the WooCommerce order key on order-received URLs before any order-based event can be generated.
- Send
order_createdonly for paid orders. - Add a persistent WooCommerce order-meta guard so
order_createdis queued only once per order even if the thank-you page is reloaded later. - Store the stable
wc_order_{ID}event ID with the order for diagnostics. - Add local OpenAI Ads / ChatGPT order attribution diagnostics using the official
opprefsignal and direct ChatGPT referrer detection. - Add an admin table showing the latest attributed WooCommerce orders and whether the purchase event was queued.
- Add optional enhanced matching with server-side normalization and SHA-256 hashing for supported WooCommerce customer identifiers.
- Restore optional OpenAI Conversions API server-side tracking for paid WooCommerce
order_createdevents. - Add a masked admin field for the Conversions API key; the saved key is never exposed in browser JavaScript.
- Use the same
wc_order_{ID}identifier for browser and server purchase events so OpenAI can deduplicate delivery channels. - Persist server delivery status and limited retry state in WooCommerce order metadata.
- Capture the OpenAI
__obrefbrowser reference on checkout for optional Conversions API enhanced matching.
1.1.2
- Sanitize the current request URI before URL-rule matching.
- Sanitize the short-lived registration cookie marker before checking it.
1.1.1
- Prevent duplicate page_viewed delivery within the same browser document.
- Add event_id to page_viewed events for stronger deduplication.
- Add same-request server queue deduplication.
- Warn in debug mode when another oaiq pixel is already present before GlobalDev loads.
1.1.0
- Rebuilt the frontend loader to use the official OpenAI bootstrap pattern directly in the document head.
- Added
page_viewedwith selectable public WordPress post types and Select all/Clear all controls. - Added generic archive/search/taxonomy/404 page-view tracking.
- Added
items_addedfor classic AJAX, WooCommerce Blocks, and successful non-AJAX add-to-cart flows. - Added
checkout_startedwith cart metadata. - Hardened
contents_viewedevent generation against unsupported payload fields. - Retained
order_createdwith value, currency, contents, and stable deduplication ID. - Added
lead_createdintegrations for Contact Form 7, Elementor Pro Forms, and WPForms AJAX. - Added frontend WordPress/WooCommerce
registration_completeddetection. - Added
appointment_scheduled,trial_started, andsubscription_createdURL triggers. - Added automatic WooCommerce Subscriptions parent subscription and active-trial detection.
- Added custom OpenAI event support.
- Added public
window.gdOpenAIAdsTrack()helper for business-specific integrations. - Added WooCommerce Cart/Checkout Blocks compatibility declaration.
1.0.0
- Initial release with pixel setup,
contents_viewed, andorder_created.


