安裝 AI 爬蟲追蹤

本頁逐步說明每一條安裝路徑。關於爬蟲追蹤測量什麼、驗證如何運作，見 AI 爬蟲。同一份安裝也會回報由 AI 回答引薦的人類造訪，因此完成安裝後 AI 流量也會有資料；該頁面的純瀏覽器 選項見安裝 AI 流量追蹤。

選擇與你的網站執行環境相符的指南：

開始之前：產生網站金鑰

無論使用哪個平台，每種安裝方式都需要一個網站金鑰：

1. 在應用中前往 設定 → 連接 → 網站追蹤。
2. 點擊產生網站金鑰。為金鑰取一個名字，最好同時填寫它將回報的網域； 該網域還能加強該網站的簽章爬蟲驗證。
3. 從確認對話框中複製兩個值：金鑰 ID 與簽章密鑰（以 ctk_ 開頭）。簽章密鑰只顯示一次；如果遺失，請在該金鑰上使用輪換 產生替代密鑰。

請務必保管好簽章密鑰：任何拿到它的人都可以為你的網站提交偽造的流量 回報。Cloudflare、Vercel 與自建伺服器的程式碼片段都從環境變數 CITLYZE_SIGNING_SECRET 讀取它，因此它永遠不會出現在你的程式碼中；WordPress 外掛則把它保存在外掛設定裡。永遠不要把它提交到程式碼儲存庫，也不要貼到用戶端 程式碼中。

Cloudflare Worker

適用於 DNS 託管在 Cloudflare 且網站已開啟代理（橘色雲開關）的情況。這是 最完整的方案：它在邊緣看到每一個請求，回報真實的 HTTP 狀態碼，而且無論 Cloudflare 背後執行的是什麼都能運作。

1. 在 設定 → 連接 → 網站追蹤 → 安裝程式碼片段中開啟 Cloudflare 頁籤並複製程式碼片段。
2. 將程式碼片段中的 SITE_KEY_ID 替換為你的金鑰 ID。簽章密鑰不要寫進程式碼； 你會在第 5 步把它新增為 Worker 機密。
3. 在 Cloudflare 控制台中，前往 Workers & Pages → Create → Create Worker。取一個名字（例如 ai-crawler-tracker），點擊 Deploy 建立空的 Worker。
4. 點擊 Edit code，把自動產生的範例替換為你的片段，再次點擊 Deploy。
5. 新增簽章密鑰：在 Worker 中開啟 Settings → Variables and Secrets → Add， 類型選擇 Secret，命名為 CITLYZE_SIGNING_SECRET，貼上你的簽章密鑰， 然後點擊 Deploy。Cloudflare 會加密保存它，它永遠不會出現在 Worker 的程式碼中。
6. 把 Worker 連接到你的網站：開啟該 Worker 的 Settings → Domains & Routes → Add → Route，選擇你的區域（zone），加入路由 example.com/*。如果網站同時透過 www.example.com 提供服務，再為 www.example.com/* 加入一條路由。
7. 完成：網站程式碼無需任何改動。Worker 會把每個請求原樣透傳到你的 來源站，並在背景回報相符的造訪。

有兩點需要檢查：

• 路由必須涵蓋所有路徑（/*），否則爬蟲對未涵蓋頁面的造訪將不可見。
• 如果這些路由上已經執行了一個 Worker，Cloudflare 每條路由只會執行一個 Worker；請把片段的邏輯合併進現有 Worker，而不是再加一個。

Vercel / Next.js 中介軟體

適用於部署在 Vercel 上的 Next.js 應用。同一個檔案也適用於自架的 Next.js。

1. 在 設定 → 連接 → 網站追蹤 → 安裝程式碼片段中開啟 Vercel / 反向代理 頁籤並複製 程式碼片段。
2. 在你的 Next.js 儲存庫中，在專案根目錄（如果應用位於 src/，則在 src/ 中）建立 middleware.ts 並貼上片段。
3. 將 SITE_KEY_ID 替換為你的金鑰 ID。簽章密鑰不要寫進該檔案。
4. 在 Vercel 專案中開啟 Settings → Environment Variables，為每個需要 追蹤的環境新增 CITLYZE_SIGNING_SECRET，值為你的簽章密鑰，並將其標記為 Sensitive。自行託管 Next.js？請在伺服器環境中設定同一個變數。
5. 如果你已經有 middleware.ts，不要再新增第二個檔案；Next.js 只會 執行一個。把片段的輔助程式碼區塊複製進現有檔案，在你的中介軟體函式 開頭呼叫其回報邏輯，並確保 matcher 設定仍涵蓋所有路徑。
6. 提交並部署。

說明：

• 中介軟體在回應產生之前執行，因此事件的 HTTP 狀態會回報為 unknown。這是 預期行為。如需狀態碼，請改用 Vercel log drain 取代此中介 軟體（兩者同時使用會把每次造訪計算兩次），或使用 Cloudflare 或自建伺服器 安裝方式，它們也會回報重新導向。
• 在 Vercel 上，訪客 IP 取自平台設定的請求標頭，可以信任。如果你把 Next.js 自架在自己的代理之後，請確保片段讀取的轉發 IP 標頭是由 你的代理設定的，而不是從用戶端透傳的。

WordPress 外掛

適用於任何可以安裝外掛的 WordPress 網站。

此外掛還能免費檢查你的 robots.txt 允許哪些 AI 爬蟲存取，以及是什麼阻擋了其餘爬蟲；參見 WordPress 外掛。

1. 在 WordPress 後台前往 外掛 → 安裝外掛，搜尋 AI Crawler Control by Citlyze，點擊立即安裝，再點擊啟用。 外掛已上架 WordPress.org 官方外掛目錄， 無需上傳 zip。

2. 想手動安裝？在 設定 → 連接 → 網站追蹤 → 安裝程式碼片段中開啟 WordPress 頁籤，點擊 下載外掛（Download plugin），然後在 外掛 → 安裝外掛 → 上傳外掛 中上傳該 zip。

3. 前往 Citlyze → Connect Citlyze，填寫全部三個欄位：

   • Tracker base URL：https://app.citlyze.com
   • Key ID：你的金鑰 ID
   • Signing secret：你的 ctk_... 簽章密鑰 在填寫追蹤器基礎 URL 之前，外掛不會回報任何資料。

4. 點擊發送測試事件（Send test event）。你應該會看到「已連線」的 確認；這證明你的憑證與連線能力端到端有效。

5. 位於 Cloudflare 以外的代理或負載平衡器之後？在 Visitor IP behind a proxy 中選擇你的代理設定的標頭，並填寫代理位址，以便按真實 IP 驗證 爬蟲。位於 Cloudflare 之後則無需任何設定。

外掛會在每個頁面送出之後回報，並附上精確的狀態碼，包括在頁面算繪前被其他 外掛重新導向的請求。事件會先保存在你的 WordPress 資料庫中並分批傳送；Connect Citlyze 頁面 會顯示有多少事件在等待，以及最近一次送達的時間。

注意：由全頁快取直接回傳的頁面、由你的 Web 伺服器或 CDN 完成的重新導向， 以及在 WordPress 載入前被防火牆攔截的請求，都不會到達外掛。Connect Citlyze 頁面偵測到 頁面快取時會提示你。如果你的網站大量使用快取，建議使用 Cloudflare Worker 安裝方式或上傳伺服器記錄檔。

自建伺服器 / Node

適用於自己架設的自行開發網站：AWS、Google Cloud、Azure、VPS 或容器。 該片段是面向 Node 20 及更新版本的 Express 風格中介軟體（也可在 Bun 與 Deno 上執行）。

1. 在 設定 → 連接 → 網站追蹤 → 安裝程式碼片段中開啟自建伺服器 / Node 頁籤並複製 程式碼片段。
2. 把它儲存為 aeo-tracker.mjs，放在伺服器進入點旁邊。
3. 將 SITE_KEY_ID 替換為你的金鑰 ID，並在伺服器上將環境變數 CITLYZE_SIGNING_SECRET 設定為你的簽章密鑰：可以在託管平台的機密設定中 設定，或寫入一個永不提交的 .env 檔案。簽章密鑰永遠不要寫進這個檔案本身。
4. 在你的路由之前註冊中介軟體：

   import { aeoCrawlerTracker } from "./aeo-tracker.mjs";
   app.use(aeoCrawlerTracker());

5. 如果伺服器位於負載平衡器或反向代理（nginx、ALB）之後，請設定 Express 信任它（例如 app.set("trust proxy", 1)），這樣中介軟體回報 的才是真實的用戶端 IP，而不是代理的 IP。爬蟲身分驗證檢查的正是這個 IP。
6. 部署。中介軟體在每次回應完成後才回報，因此不增加任何延遲，並且包含 真實的 HTTP 狀態碼。

不用 Express？回傳的處理函式接收一般的 (req, res, next) 參數，可適配 Fastify、Koa 或 Node 的 http 伺服器。對於完全不同的語言（Python、Go、PHP、 Ruby 等），請實作 簽章信標協定； 每個帶簽章的 HTTPS POST 攜帶一個最多包含 50 個相符請求的批次。

Webflow

Webflow 自身的託管無法執行伺服器端程式碼，而瀏覽器端指令碼看不到 AI 訓練爬蟲，因此追蹤要安裝在 Webflow 前面的代理層：

1. Webflow 在 Enterprise 方案上支援自行管理的反向代理；請與你的 Webflow 聯絡人協商開通，並把網域路由到你的代理（Cloudflare、 CloudFront、Fastly 或你自己的 nginx）。
2. 在該代理層安裝追蹤器：
   • 代理在 Cloudflare 上 → 依照 Cloudflare Worker 指南操作。
   • 你自己的 Node 代理 → 依照 自建伺服器 / Node 指南操作。
   • 其他情況 → 在你的代理中實作 簽章信標協定。
3. 依照下文所述進行驗證。

Webflow Cloud 應用程式不是全站追蹤的途徑：它們只服務掛載路徑下的請求， 永遠看不到爬蟲對一般頁面的造訪。

Shopify

標準 Shopify 店面無法執行此追蹤器：Shopify 不允許商家在店面請求上執行 伺服器端程式碼，也不支援在商店前架設代理（例如 Cloudflare）。瀏覽器端 指令碼不是替代方案：AI 訓練爬蟲從不執行 JavaScript，而且瀏覽器指令碼 會暴露你的簽章密鑰。

你可以做的：

• 以 Hydrogen 建構、託管在 Oxygen 上（或任何自架環境）的 Headless 店面執行伺服器端程式碼；把 自建伺服器 / Node 片段的邏輯接入店面的伺服器 請求處理器。
• 對於標準商店，Citlyze 的其他測量（提示詞追蹤、引用、GEO 稽核）不受 商店託管位置影響，照常運作。

驗證安裝

• 在 設定 → 連接 → 網站追蹤中，網站金鑰表格有一欄最後事件。當你的 安裝送達第一份被接受的回報後它就會更新；爬蟲造訪與來自 AI 回答的 引薦點擊都算。
• WordPress 使用者可以透過發送測試事件（Send test event）立即確認 送達（測試事件驗證憑證與連線能力，但不會更新最後事件）。
• 給它一點時間：低流量網站的第一次真實爬蟲造訪可能需要幾小時到幾天。 事件到達後，診斷 → AI 爬蟲活動 → 總覽就會填入資料。
• 如果幾天後仍然沒有任何資料，請重新檢查：程式碼片段（或外掛設定）中的金鑰 ID 是否屬於一把有效、未撤銷的金鑰；CITLYZE_SIGNING_SECRET 是否為該金鑰目前的 簽章密鑰；你的路由或中介軟體是否涵蓋所有路徑。沒有有效的簽章密鑰時，程式碼 片段不會回報任何資料，並會記錄一次「Citlyze crawler tracking is off」。
• 網站金鑰表還會顯示每個金鑰使用的採集器版本，並在片段或外掛有新版本、或 WordPress 外掛偵測到頁面快取時提示你。