citlyze docs
使用 Citlyze

安裝 AI 爬蟲追蹤

Cloudflare、Vercel、WordPress、自建 Node 伺服器、Webflow 與 Shopify 的逐步安裝指南。

本頁逐步說明每一種安裝方式。爬蟲追蹤衡量哪些項目、驗證如何運作,請參閱 AI 爬蟲。同一套安裝也會回報由 AI 回答引薦的 真人造訪,因此完成安裝後,AI 流量也會有資料; 該頁面的純瀏覽器安裝選項,請參閱安裝 AI 流量追蹤。

請依網站的執行環境選擇對應的指南:

你的環境適用指南
網站位於 Cloudflare 後方(橘色雲代理)Cloudflare Worker
部署在 Vercel 上的 Next.js 應用程式(或自行架設的 Next.js)Vercel / Next.js 中介軟體
WordPress 網站WordPress 外掛
架設在自有伺服器上的自行開發網站(AWS、GCP、Azure、VPS、容器)自建伺服器 / Node
Webflow 網站Webflow
Shopify 商店Shopify

開始之前:產生網站金鑰

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

  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_... 簽章密鑰 填入 Tracker base URL 之前,外掛不會回報任何資料。
  4. 點選發送測試事件(Send test event)。你應該會看到「已連線」的確認訊息, 表示你的憑證與網路連線從頭到尾都正常運作。

  5. 如果網站位於 Cloudflare 以外的代理伺服器或負載平衡器後方,請在 Visitor IP behind a proxy 中選擇代理伺服器設定的標頭,並列出代理伺服器的 位址,以便依真實 IP 驗證爬蟲。位於 Cloudflare 後方則不需要任何設定。

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

注意:由全頁快取直接提供的頁面、由網頁伺服器或 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. 在該代理層安裝追蹤器:
  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 外掛偵測到頁面快取時提醒你。

本頁內容