ChatGPT Ads Pixel & Conversions API: Installation and Set-up

ChatGPT Ads Pixel & Conversions API

With this extension, you can integrate the ChatGPT Ads pixel into your Shopware shop and also transmit key shop events on the server side via the OpenAI Conversions API. This allows you to reliably track your campaigns in ChatGPT Ads, even if an ad blocker blocks the pixel in the browser. Tracking only begins once the visitor has consented to marketing tracking.

1. Client-side ChatGPT Ads Pixel and server-side Conversions API
2. Deduplication of browser and server events using a shared event ID
3. Standard events: page_viewed, contents_viewed, items_added, checkout_started and order_created
4. Enhanced matching using SHA-256-hashed customer data for logged-in customers
5. Integration with the Shopware Cookie Consent Manager and seven external consent tools
6. A unique Pixel ID and a unique Conversion API key for each sales channel

Prerequisites

• An account in ChatGPT Ads Manager with a pixel set up (pixel ID)
• For server-side transmission, you will also need a Conversion API key from the ChatGPT Ads Manager
• Shopware 6.5, 6.6 or 6.7
• An active cookie consent manager (Shopware’s standard option or one of the supported tools)
• For asynchronous sending (default): a running worker for the Shopware Message Queue

Compatibility

The extension is available for Shopware 6.5, 6.6 and 6.7. The pixel is loaded via the official OpenAI script, and server-side events are sent directly from your shop to the OpenAI Conversions API. You do not need any additional third-party extensions.

If your shop is running behind a reverse proxy, you must trusted_proxies must be set up correctly. Otherwise, the shop will transmit the proxy’s IP address instead of the visitor’s.

Installation

1. Purchase the extension from the Shopware Store and install it in your shop.
2. To enable the extension, go to Extensions › Enable my extensions.
3. Open the configuration and enter the pixel ID and, optionally, the Conversions API key (see „Set-up“).
4. Clear the cache so that the pixel is displayed in the storefront.

Furnishings

Open the configuration under Extensions › My Extensions for the „ChatGPT Ads Pixel & Conversions API“ entry via the three-dot menu › Configure. Select the sales channel at the top and enter the following in the „ChatGPT Ads Pixel Configuration“ section:

• Active: enables tracking for the selected sales channel.
• ChatGPT Ads pixel ID: You can find them in the ChatGPT Ads Manager under „Conversions“ in the „Data source“ tab, listed under the name of the pixel.

For server-side tracking, you’ll also need a Conversions API key. You can generate this in ChatGPT Ads Manager under „Conversions“ by clicking the key icon in the top right-hand corner („Conversion Key“). The key is only displayed once, so make sure you copy it straight away. It is a separate key and not the API key for advertisers.

In Shopware 6.7, you can check the connection to the Conversions API in the configuration by clicking the „Test connection“ button.

1 · Events recorded

If tracking is enabled and the visitor has given their consent, the extension reports these events to OpenAI:

• page_viewed: every page view (client-side only)
• contents_viewed: Viewing a product detail page
• items_added: Item added to your basket
• checkout_started: Displaying the order confirmation page at checkout
• order_created: Completed order showing the amount, currency and items

An order is only counted as a conversion on the final page. Anyone who abandons the checkout process therefore does not generate a conversion. Amounts are sent to OpenAI in the format expected by the API: as a whole number in the smallest currency unit (8900 corresponds to 89.00 EUR).

You can enable or disable e-commerce tracking separately in the „Tracking Options“ section.

2 · Conversions API & Enhanced Matching

In addition to the pixel in the browser, the extension sends the events directly to the OpenAI Conversions API on the server side. Browser and server events are assigned the same event ID, meaning OpenAI counts each event only once. As the server call does not run within the browser, conversions are still tracked even when ad blockers and tracking protection are enabled in the browser.

With Enhanced Matching, the extension also transmits hashed data (email, telephone number, first name and surname, customer number) as well as town, postcode and country for logged-in customers. Hashing is carried out using SHA-256 within the shop, so the plaintext data never leaves your shop. This enables OpenAI to attribute conversions more accurately.

In the „Server-side tracking (OpenAI Conversions API)“ section, the following options are available to you:

• Enable server-side tracking: enables data transfer to the Conversions API.
• Conversions API key: the key from the ChatGPT Ads Manager.
• Enable Enhanced Matching: sends the hashed customer data along with it.
• Asynchronous sending: passes the requests on to the Shopware Message Queue to ensure the storefront remains fast. This option is enabled by default and is recommended.
• Minutes: writes the error messages to the Shopware logs.
• Test mode: OpenAI checks the data but does not store the events. Switch off during live operation.

3 · Cookie Consent & Data Protection

The pixel is only loaded once the visitor has consented to the „Marketing“ category. If they withdraw their consent, tracking stops and the extension removes the OpenAI cookies __oppref and __obref.

The Shopware Cookie Consent Manager and the following consent tools are supported:

• Cookiebot
• CookieFirst
• Usercentrics
• ACRIS EU Cookie Policy Pro
• CCM19
• CMP (Consent Manager)
• CookieYes

The extension also only sends server-side events with consent. If it does not recognise a particular consent tool, it does not send anything at all on the server side. In the „Expert mode for the selected consent manager“ field, you can adjust the category that your consent tool expects.

The server-side consent check can be disabled. We advise against doing this, as the responsibility for obtaining consent then lies with you as the shop operator.

Data protection notice: OpenAI is a US-based provider. In addition to event data, the Conversions API also collects the visitor’s IP address and user agent. Please state in your privacy policy that data is transferred to OpenAI.

4 · Sales channels & other options

• Multiple sales channels: Select the sales channel at the top of the configuration and enter a separate pixel ID and key for each channel.
• Gross/Net: Specify whether amounts are to be transferred on a gross or net basis.
• Order price: Enter the order value, with or without delivery charges.
• Exclude customer groups: Under „Disable tracking for the following customer groups“, you can exclude individual customer groups from tracking.
• Own events: In the „My Events“ section, you can create additional events, with one entry per line in the format route_name = event_name. No route (just event_name) the event is triggered on every page. Rows containing # are ignored. Custom events are only sent on the client side.

FAQs