Pixel for OpenAI Ads

將 WooCommerce 商店的商品瀏覽、加入購物車、結帳與購買行為，串接至 ChatGPT Ads Measurement Pixel，協助衡量 ChatGPT 廣告帶來的網站轉換。

本外掛依據 OpenAI Measurement Pixel 官方文件 開發，以 WooCommerce 為主要整合對象，提供台灣繁體中文設定介面，並可選擇搭配伺服器端 Conversions API。本專案為獨立開發，與 OpenAI 無隸屬關係。

作者：手哥 · 網站：硬是要學 · 電子郵件：besthand@soft4fun.net

主要功能

• WooCommerce 自動事件：商品瀏覽、加入購物車、開始結帳、完成購買與前台帳號註冊。
• 瀏覽器與伺服器事件：載入 Measurement Pixel SDK；選擇啟用 Conversions API 後，由伺服器傳送對應事件，並共用事件 ID 以供去重。
• 商品與訂單資料：帶入商品 ID、名稱、數量、金額及幣別，將一般金額換算為最小貨幣單位。
• 自訂事件：依網址規則追蹤詢價完成等行為，也可透過 PHP 串接自己的流程。
• 訪客同意管理：搭配 WordPress Consent API 與相容的 Cookie 同意工具，依所選同意類別控制追蹤。
• 連線與診斷工具：檢查已儲存的連線設定，查看最近 40 筆伺服器傳送紀錄，支援篩選、分頁與每頁筆數設定。
• WooCommerce 商品目錄：預覽、驗證、下載 UTF-8 CSV，或使用 Advertiser API 設定 SFTP 定期同步，並查詢平台處理結果。

環境需求

若未啟用 WooCommerce，仍可使用頁面瀏覽、網址規則及已支援的其他整合。Easy Digital Downloads 購買事件需啟用對應外掛。

安裝與初次設定

1. 將本專案資料夾命名為 pixel-for-openai-ads，放入 wp-content/plugins/。
2. 到 WordPress「外掛」頁面啟用 Pixel for OpenAI Ads，並確認 WooCommerce 已啟用。
3. 開啟「OpenAI 廣告追蹤 → 一般設定」，填入 Ads Manager 提供的 Pixel ID，再按「儲存設定」。
4. 如需由伺服器傳送事件，填入 Conversions API 金鑰，開啟「啟用伺服器 Conversions API」並儲存。Pixel ID 與金鑰的取得方式見 Conversions API 官方文件。
5. 到「事件設定」選擇需要的自動事件；頁面瀏覽開關也在此分頁。
6. 如需等待訪客同意，先設定 WordPress Consent API 與相容的 Cookie 同意工具，再啟用同意限制及選擇類別。
7. 到「總覽」執行連線測試，接著以測試商品完成一次瀏覽、加入購物車、結帳與付款流程，查看瀏覽器及「診斷紀錄」。

填入 Pixel ID 後，外掛會負責載入 SDK 與初始化。若網站已有相同 Pixel 的手動程式碼或標籤管理器設定，請整合成單一追蹤來源，避免重複初始化與重複事件。

WooCommerce 事件對應

商店事件使用的資料格式與名稱可對照 OpenAI Supported Events。自動頁面瀏覽只由瀏覽器傳送；其餘整合事件可依設定由瀏覽器與伺服器處理。

購買事件的判斷

order_created 以符合 WooCommerce 已付款狀態的訂單為準。預設略過後台建立的訂單與總額為零的訂單；單純建立待付款訂單不會被當成完成購買。

同一筆購買的瀏覽器與伺服器事件使用 order_<訂單 ID>。外掛會在結帳時保存可用的同意與廣告歸因資訊，供後續付款狀態變更使用。伺服器傳送仍需啟用 Conversions API、具備有效設定，且符合保存的同意狀態。

程式碼已加入傳統結帳與 Store API 結帳的訂單情境擷取，並宣告 WooCommerce HPOS 與購物車／結帳區塊相容性。本機已用 WooCommerce 10.2.2、HPOS、傳統及區塊結帳實測，且在 Ads Manager 確認收到四種主要商店事件。實際商店的付款外掛、佈景主題與歸因結果仍需在自己的環境驗證。

結帳完成、清空購物車或移除最後一項商品後，結帳去重紀錄會重設。因此下一次購買相同商品仍會觸發 checkout_started，同一次結帳的重新整理則不會重複觸發。

設定介面

一般設定中的主要選項：

各分頁只儲存自己的設定。網址規則驗證失敗時，整筆事件設定會保留原值，介面會顯示錯誤原因。

自訂事件

透過網址規則設定

在「事件設定 → 網址規則與自訂事件」按「新增規則」。例如，詢價完成後導向專屬頁面：

每次符合規則的頁面請求都會觸發事件。名稱限 1 至 64 個小寫英文字母、數字、底線或連字號，開頭與結尾需為英文字母或數字，且不可與內建事件同名。最多可設定 50 筆規則；金額與 3 碼幣別需一起填寫。

以 / 開頭的規則只比對路徑，含 ? 時也比對查詢字串。完整網址規則會比對網域、路徑及查詢字串；「完全相符」會忽略 HTTP／HTTPS 與結尾斜線。比對不區分大小寫，並支援網址解碼。

網址規則獨立於自動事件開關，仍遵守 Pixel ID 與同意設定。請將規則涉及的頁面排除於整頁快取；WooCommerce 購買事件已由訂單流程處理，通常不需要再為訂單完成頁新增購買規則。

透過 PHP 整合

在外掛載入完成後，於自己的前台流程呼叫：

if ( class_exists( 'PFOA_Tracker' ) ) {
    PFOA_Tracker::instance()->track(
        'custom',
        array(
            'type'     => 'custom',
            'amount'   => 10000,
            'currency' => 'TWD',
        ),
        array( 'custom_name' => 'quote_requested' )
    );
}

PHP 呼叫使用最小貨幣單位，範例中的 10000 代表 100.00 TWD；設定介面則使用一般金額，由外掛換算。此呼叫沿用事件 ID 與同意檢查流程。若在付款通知或背景工作中觸發，需由整合程式提供適當的事件情境。

WooCommerce 商品 feed

到「OpenAI 廣告追蹤 → 商品目錄」填入實際商家名稱及商品沒有品牌資料時使用的預設品牌。商家網址、退貨政策及市場欄位依實際資料與帳號設定填寫。儲存後可依狀態、商品名稱或 ID 篩選，切換頁數與每頁筆數，再下載 CSV。

feed 與 Pixel 設定獨立，不需要 Pixel ID 或 Conversions API 金鑰。商品 ID 預設沿用 WooCommerce ID；每個變體各一列，帶入父商品群組 ID 與選項資料。保留公開目錄中的缺貨商品，排除草稿、私人、設有密碼、目錄隱藏及不支援的商品類型。必要欄位缺漏、網址格式不符或商品 ID 重複時，顯示原因並阻止整檔匯出。

需要自動上傳時，填入 Advertiser API 金鑰並儲存，依序測試帳戶、建立或連結上傳連線，再啟用每小時、每 12 小時或每日同步。金鑰與 SFTP 密碼加密保存，SSH 指紋變更會阻擋傳送。完整 CSV 通過檢查後才上傳；傳送成功與平台處理結果分開顯示。網址檢查只驗證格式，商品頁與圖片仍須公開可存取。市場與幣別依帳戶核准內容為準。操作及限制見 商品目錄說明。

欄位、價格、排除條件與操作方式見 商品 feed 使用說明，格式依據 OpenAI Stable Products 及 Ads Product Feeds。

延伸整合

Easy Digital Downloads 整合只有在對應外掛與功能啟用後才會觸發，涵蓋率畫面也會顯示目前偵測結果。

同意與資料傳送

同意限制需搭配 WordPress Consent API 與相容的 Cookie 同意工具。啟用同意限制但未偵測到 Consent API 時，Pixel 與伺服器事件會停止傳送。請先安裝並設定 Consent API 與相容的 Cookie 同意工具；關閉此限制則會依追蹤設定直接傳送事件。

啟用伺服器事件時，資料可能包含事件名稱、商品與訂單金額、來源網址、IP 位址、瀏覽器資訊，以及可用的廣告歸因識別。開啟使用者識別或帳單資料後，也會附加相應的雜湊識別欄位；帳單中的國家、城市與郵遞區號不經雜湊。

「附加使用者識別資料」只控制本外掛主動附加的欄位。SDK 自身的進階比對行為，請另依 Measurement Pixel 官方文件 與 Pixel 設定確認。

外掛使用的服務與暫存資料：

僅在購買伺服器追蹤已設定並啟用時擷取訂單同意情境。未同意的情境只保存同意未通過的狀態，不擷取 IP、瀏覽器資訊或歸因 Cookie。

外掛設定、最近 40 筆診斷紀錄與使用計數會保留至清除或解除安裝；連線測試結果保存 60 秒。解除安裝會清除各網站的設定與短期事件／連線測試暫存。WooCommerce／EDD 訂單中的同意、歸因情境及事件傳送標記依商店訂單保留政策保存，解除安裝不刪除訂單中繼資料；已同意的 EDD 情境包含 IP 與瀏覽器資訊。已送到 OpenAI 的資料由其政策管理，解除安裝不會刪除外部資料。WordPress 隱私權政策工具已提供建議說明文字，請依實際功能與保留期限調整。

• https://bzrcdn.openai.com/sdk/oaiq.min.js：載入瀏覽器 SDK。
• https://bzr.openai.com：瀏覽器事件傳送服務。
• https://bzr.openai.com/v1/events：伺服器 Conversions API。
• SDK 的第一方歸因 Cookie，以及外掛的 pfoa_vid 訪客事件暫存佇列。

請依實際啟用的功能更新網站隱私權說明。若網站使用 CSP，SDK 與事件連線的來源設定可參照官方文件的 CSP 章節。

檢查與常見問題

連線測試成功，就代表轉換已記錄嗎？

連線測試使用已儲存的設定，API 請求採 validate_only=true。它用於檢查連線與驗證，不建立正式轉換；實際接收結果需以真實事件及 Ads Manager 確認。本機涵蓋率也只表示目前設定與整合狀態。

為什麼診斷紀錄沒有頁面瀏覽？

自動頁面瀏覽由瀏覽器傳送，診斷紀錄只記錄伺服器事件。可開啟偵錯模式，從瀏覽器主控台及網路請求檢查 Pixel。

為什麼訂單沒有購買事件？

確認訂單已符合付款狀態、購買事件開關已開啟，並檢查是否為後台建立或零元訂單。若查看的是伺服器紀錄，還需確認 Conversions API、金鑰與訂單保存的同意狀態。

結帳 NT$1，為什麼事件 JSON 的 amount 是 100？

OpenAI 的 Pixel 與 Conversions API 均要求金額使用 ISO 4217 最小貨幣單位的整數。TWD 的標準小數位數為 2，因此 amount: 100、currency: "TWD" 代表 NT$1.00；NT$100.00 則傳送 amount: 10000。這個規則依貨幣標準處理，不隨 WooCommerce 的價格顯示小數位數改變。規格見 OpenAI Supported Events，TWD 小數位數可查 SIX 官方 ISO 4217 清單的 List One。

最外層 amount 是事件總額，contents[].amount 是商品金額；兩者各描述自己的範圍，不應加在一起解讀。網址規則的金額欄請填一般金額，例如 NT$1 填 1.00，外掛會換算；直接呼叫 PHP 追蹤介面時則使用最小貨幣單位。

如何避免快取造成事件異常？

將結帳、訂單完成頁及網址規則涉及的頁面排除於整頁快取，避免略過 PHP 或重複使用帶有事件 ID 的頁面。使用 JavaScript 延遲載入、CSP 或其他最佳化工具時，也請實測 SDK 與事件是否正常執行。

驗證範圍

目前已完成 PHP、本機 WordPress 介面、WooCommerce 傳統與區塊結帳，以及 OpenAI Pixel／Conversions API 的實際事件接收驗證。正式站快取、實際金流、廣告歸因及其他整合外掛的完整流程需另外驗證。測試程式、檢查報告與打包產物未納入此儲存庫。

從原始碼建置

GitHub 儲存庫保存標準版原始碼與鎖定的相依套件清單。直接下載原始碼後，先在專案根目錄安裝 SFTP 相依套件：

composer install --no-dev --prefer-dist --no-scripts --no-plugins

使用 PowerShell 7 產生可安裝的 ZIP：

pwsh -NoProfile -File scripts/package-standard.ps1

產物為 dist/pixel-for-openai-ads-1.1.1.zip，包含 SFTP 執行套件與授權文件。可在 WordPress「外掛 → 安裝外掛 → 上傳外掛」安裝；正式站不需要執行 Composer。測試資料、研究草稿與 Premium 模組均不包含在標準版原始碼與安裝檔中。

授權：GPL-2.0-or-later。WordPress 外掛格式的說明見 readme.txt。

繁體中文的外掛目錄說明另存於 docs/readme-zh-TW.md。