WorkOfNeo/analyticsos-skills

analyticsOS 追蹤

analyticsOS 透過每個應用程式一個腳本的方式，記錄頁面瀏覽、點擊、捲動、表單、錯誤、網站速度以及已登入的使用者。安裝方式是在頁面的 <head> 中加入兩個標籤；大部分的工作在於將它們放到適合技術棧的正確位置，並確保個人資料不外洩。

你需要從對方那裡取得什麼

analyticsOS 設定頁面會提供一個提示，其中包含三個值。請索取任何遺漏的值；切勿自行猜測。

• Host (主機)：analyticsOS 運行所在的主機，例如 https://analytics.example.com。
• Key (金鑰)：應用程式的公開金鑰，格式為 prj_…。這不是祕密：它會出現在每個載入該腳本的頁面中。
• Mode (模式)：Identified (已識別，適用於有登入功能的應用程式，且使用者協議中需包含同意條款) 或 Anonymous (匿名，適用於公開網站，裝置上不儲存任何資訊)。

安裝

1. 找出技術棧，並在變更任何內容前閱讀其參考文件：

   • Next.js (App Router 或 Pages Router)：references/nextjs.md
   • Flask 或其他 Jinja 應用程式：references/flask.md
   • Webflow：references/webflow.md
   • 其他任何情況 (純 HTML、Vite、Astro、SvelteKit、Rails、Django、PHP、WordPress…)：references/any-site.md

2. 使用環境變數，而非硬編碼的值：ANALYTICS_HOST 和 ANALYTICS_KEY，並加上技術棧所需的字首，以便在建置時將其暴露給頁面 (Next.js 使用 NEXT_PUBLIC_，Vite 使用 VITE_)。將它們放在本機的 .env 檔案中，將這些變數名稱及其空值新增到 .env.example 檔案中，並告知使用者在需要執行追蹤的每個環境的主機設定中 (Railway → Variables，Vercel → Environment Variables…) 設定這些變數。

3. 兩個標籤，放在每個頁面的 <head> 中，且僅在金鑰有設定時才加入。 若沒有金鑰，則不得載入任何內容：這是本機開發和預覽環境的關閉開關。

   <script>
     window.aos =
       window.aos ||
       function () {
         ;(window.aos.q = window.aos.q || []).push(arguments)
       }
   </script>
   <script defer src="{ANALYTICS_HOST}/s/{ANALYTICS_KEY}.js"></script>
   

   第一個標籤會將腳本載入前發出的呼叫排入佇列；第二個標籤則以延遲載入的方式載入包含應用程式設定的腳本。

4. 已登入的使用者 (僅限 Identified 模式)：請參閱 references/events.md。在 Anonymous 模式下，不要加入任何 identify 呼叫，也不要儲存任何關於訪客的資料。

5. 為主要頁面的區塊命名：在關鍵頁面 (例如 hero、pricing、sign-up form…) 的元素上使用 data-section="Pricing"，讓報表能夠識別它們。在任何其文字內容絕不能外洩的元素上放置 data-private 屬性：例如客戶姓名、金額、地址，以及任何個人資訊。

6. Content-Security-Policy (內容安全政策)：如果專案設定了 CSP，請在 script-src 和 connect-src 中允許 analyticsOS 的主機。

7. 不要做其他事：不要加入其他分析工具、Cookie 或同意横幅。analyticsOS 不需要這些東西。

8. 完成：執行專案的建置和 lint 工具，列出你修改過的檔案，並告知使用者在瀏覽器中開啟應用程式。analyticsOS 的設定頁面會在幾秒內顯示第一個頁面瀏覽已記錄。

腳本已自動擷取的資料

不需要為以下任何項目撰寫程式碼；這些都是由腳本自動處理的：

• 頁面瀏覽，包含單頁應用程式中的客戶端導航；
• 連結、按鈕以及任何帶有 data-aos-event 屬性的元素的點擊，此外還有外部連結、下載、憤怒點擊和無效點擊；
• 捲動深度和頁面停留時間；
• 已開始、已提交和已放棄的表單 (絕不記錄輸入的內容)；
• 核心網頁指標 (LCP、INP、CLS、FCP、TTFB)、JavaScript 錯誤以及失敗的同源請求。

自訂事件、具名點擊和 identify 功能請參閱 references/events.md。

隱私規則

無論使用者要求什麼，這些規則在所有專案中都適用：

• 絕不傳送電子郵件地址、姓名、電話號碼或任何使用者輸入的內容：不要放在 identify 的 traits 中，不要放在 track 的 props 中，也不要放在 data-aos-event 的名稱中。
• 使用應用程式內部的使用者 ID 進行 identify，絕不使用電子郵件。
• 對顯示個人資料的元素標記 data-private 屬性。腳本也絕不會讀取 <input>、<textarea> 或 contenteditable 元素。
• 發送 Do Not Track 或 Global Privacy Control 訊號的瀏覽器完全不會被追蹤，且 aos() 呼叫會被丟棄。請不要試圖繞過這項限制。

當什麼都沒有送達時

使用瀏覽器的開發者工具網路分頁開啟應用程式：

• /s/{key}.js 應該會載入 (200)，接著對 {host}/api/e 的請求應回應 204。
• 403 來自 /api/e：頁面的網域未在應用程式的「允許的網域」(analyticsOS → 應用程式的設定) 中。請加入該網域，或在測試期間將清單留空。
• 404：金鑰錯誤，或金鑰已於超過 24 小時前輪換。
• 完全沒有請求：該環境中未設定金鑰變數，Content-Security-Policy 封鎖了主機，或瀏覽器發送了 Do Not Track / Global Privacy Control。
• Next.js，事件在第一個頁面後停止：標籤是以純粹的 <script> 元素形式加入在巢狀佈局中。請在根佈局中使用 next/script (請參閱 references/nextjs.md)。