六個方法

init

SDK 初始化。設定 collector endpoint、app 識別資訊、flush 間隔、buffer 大小。在 app 啟動時呼叫一次。

1Monitor.init({
2  endpoint: 'https://collector.example.com/v1/events',
3  app: 'my_app',
4  version: '1.2.0',
5  flushInterval: 30000,   // 毫秒
6  bufferSize: 100,
7})

init 負責建立 session、記錄 lifecycle.session.start 事件、啟動 flush 計時器。init 之前呼叫其他方法應該拋出明確錯誤（SDK 未初始化），而非靜默忽略。

連線驗證策略：lazy。init 不驗證 collector 是否可達 — 不發 HTTP 請求、不 ping endpoint。init 的失敗只代表配置錯誤（缺少 endpoint 參數），不代表網路問題。網路問題在第一次 flush 時才浮現，flush 失敗時事件保留在 buffer 等待重試。

Lazy 策略的理由：SDK 不應阻塞主程式的啟動流程。如果 init 驗證連線，collector 暫時不可用時 app 會啟動失敗 — 監控工具反而變成可用性的瓶頸。短生命週期腳本（Python 平台適配：短生命週期腳本）對這一點更敏感 — hook 腳本不能因為 collector 沒啟動就拒絕執行。

event

記錄使用者操作事件（四類事件中的 Event 類）。接受事件名稱和可選的 data 物件。

1Monitor.event('terminal.connect.start', { url: 'wss://...' })
2Monitor.event('enrollment.qr.scan')

event 方法是非阻塞的 — 事件進入內部 buffer 立即返回，不等待網路送出。應用程式的操作流程不應該被監控 SDK 的網路延遲阻塞。

error

記錄錯誤事件。接受 Error/Exception 物件或自訂的錯誤描述。自動附加 stack trace、錯誤類型、觸發位置。

1Monitor.error(exception, { step: 'ws_connect' })
2Monitor.error('Auth token missing', { context: 'handshake' })

error 方法和自動攔截機制（自動攔截）互補 — 自動攔截處理未捕獲的例外，error 方法處理開發者主動上報的已知錯誤。

metric

記錄數值指標。接受指標名稱和數值。

1Monitor.metric('connect.duration_ms', 320)
2Monitor.metric('terminal.fps', 58.5)

metric 方法記錄的是離散的數值快照。聚合計算（平均、百分位、趨勢）在 collector 端完成，SDK 端只負責記錄原始值。

flush

強制送出 buffer 中所有待發事件。正常情況下 SDK 按 flushInterval 定期自動 flush（攢批送出）。flush 方法用於需要確保事件已送出的場景 — 例如 app 即將進入背景或使用者手動觸發 log 上傳。

1await Monitor.flush()

flush 是非同步方法 — 需要等待網路請求完成。呼叫端可以 await 確認送出成功，也可以 fire-and-forget。

close

SDK 資源釋放。停止 flush 計時器、送出 buffer 中剩餘事件、關閉網路連線、記錄 lifecycle.session.end 事件。

1await Monitor.close()

close 在 app 關閉時呼叫。呼叫後 SDK 進入已關閉狀態，後續的 event/error/metric 呼叫應該被靜默忽略（不拋錯，因為 app 正在關閉）。

API 設計原則

方法名稱和四類事件對齊。event / error / metric 三個方法直接對應三類事件，lifecycle 事件由 init 和 close 自動產生。開發者看到方法名稱就知道對應哪類事件。

所有上報方法非阻塞。event、error、metric 進 buffer 立即返回。監控 SDK 阻塞應用程式的操作流程是反模式。

init 和 close 成對出現。init 開始 session，close 結束 session。兩者界定 SDK 的活躍期間。

各平台的 SDK 整合範例（Flutter 的 pubspec.yaml + main.dart init、Python 的 pip install + init code、JS 的 script tag + init）見 monitor repo 各 SDK 的 README。

下一步路由

• 自動攔截未捕獲的錯誤 → 自動攔截機制
• Buffer 和 flush 的策略 → 攢批送出策略
• SDK 端的資料脫敏 → SDK redaction helper
• SDK 的 HTTP POST 行為需要 protocol test → testing 模組三 協議整合測試

各平台的攔截點

JavaScript / TypeScript

JS 環境有兩個全域錯誤攔截點：

window.onerror 捕獲同步程式碼中未處理的例外。回呼函式收到 error message、來源 URL、行號、列號和 Error 物件。

window.onunhandledrejection 捕獲未處理的 Promise rejection。回呼函式收到 PromiseRejectionEvent，包含 rejection reason。

SDK 在 init 時註冊這兩個處理器。註冊前先保存原有的處理器（如果有），攔截後先呼叫原有處理器再執行 SDK 的記錄邏輯 — 避免覆蓋應用程式已有的錯誤處理。

限制：onerror 對跨域腳本的錯誤只收到 Script error. 訊息，沒有 stack trace。需要在 <script> 標籤加 crossorigin 屬性，server 端的 CORS header 加 Access-Control-Allow-Origin。

Flutter

Flutter 有兩個攔截層：

FlutterError.onError 捕獲 widget build / layout / paint 過程中的例外。預設行為是在 console 印出錯誤，SDK 替換為記錄 error 事件後再呼叫預設處理器。

PlatformDispatcher.instance.onError 捕獲其他非同步區域的未處理例外（Dart 2.15+）。包含 Isolate 內的未捕獲例外。

runZonedGuarded 是另一個選項 — 在指定的 Zone 內捕獲所有未處理例外。SDK 可以用 runZonedGuarded 包住整個 runApp()，但這和 PlatformDispatcher.onError 有重疊，需要避免同一個例外被記錄兩次。

限制：Flutter 的 release mode 會移除 stack trace 的符號資訊（obfuscation）。需要保留 debug symbols 檔案（.dSYM / mapping.txt），在 collector 端做 symbolication。

Python

sys.excepthook 處理主執行緒的未捕獲例外。回呼函式收到 exception type、value 和 traceback。

threading.excepthook（Python 3.8+）處理子執行緒的未捕獲例外。

atexit.register 用於在 Python 程序退出時 flush 剩餘的 buffer。但 atexit 在 os._exit() 或 SIGKILL 時不會執行。

限制：Python 的 GIL 讓 SDK 的網路操作可能阻塞主執行緒。SDK 的 flush 應該在獨立的 daemon thread 中執行，主執行緒只負責把事件放入 buffer。

攔截後的統一處理

不同平台的錯誤物件格式不同（JS 的 Error、Flutter 的 FlutterErrorDetails、Python 的 sys.exc_info tuple）。SDK 在攔截後把平台特定的錯誤物件轉換為統一的 error 事件格式：

• type: "error"
• name: 從 error class name 推導（TypeError → error.TypeError）
• data: 包含 message、stack trace（字串化）、觸發位置

轉換層是每個平台 SDK 唯一的平台特定程式碼。轉換完成後，事件進入和手動上報相同的 buffer → flush 管線。

和手動上報的分工

自動攔截處理「開發者沒有預期到的錯誤」— 未捕獲的例外、未處理的 rejection。手動上報（Monitor.error()）處理「開發者知道可能發生但想記錄的錯誤」— 已捕獲的例外、業務邏輯的異常狀態。

兩者進入同一個 buffer 和 flush 管線，在 collector 端可以用 data 中的 source: "auto" / source: "manual" 欄位區分。

下一步路由

• SDK 公開 API → SDK 公開 API 設計
• 各平台的深入適配問題 → 模組五 平台適配
• Buffer 和 flush → 攢批送出策略
• 主動感測器設計（和被動攔截互補）→ 前端感測器設計

三個觸發條件

時間觸發（flush interval）

固定間隔自動 flush。SDK 在 init 時啟動計時器，每隔 N 毫秒檢查 buffer 是否有待發事件，有則送出。

合理的間隔範圍：10-60 秒。間隔太短（1 秒）接近逐筆送出，失去攢批的效益；間隔太長（5 分鐘）可能讓事件延遲到達 collector，影響即時監控和告警的反應速度。

自用工具場景下 30 秒是合理的預設 — 事件量低，30 秒的延遲對 debug 分析沒有實質影響。商業產品可以降到 10 秒以獲得更接近即時的 error 告警。

數量觸發（buffer size）

Buffer 內的事件數量達到上限時立即 flush。Buffer size 設定為一次 HTTP POST 的合理 payload 大小對應的事件數量。

合理的數量範圍：50-200 筆。數量太少（10 筆）頻繁觸發 flush；數量太多（1000 筆）單次 HTTP POST 的 payload 過大，增加傳輸失敗的風險（超時、記憶體）。

數量觸發和時間觸發互為備援。高頻事件場景（使用者快速操作）靠數量觸發避免 buffer 溢出；低頻事件場景（使用者長時間閒置）靠時間觸發確保事件在合理時間內送出。

關閉觸發（flush on close）

SDK close 時強制 flush buffer 中所有剩餘事件。這是最後一道保障 — app 關閉後 buffer 中未送出的事件就永久遺失了。

close flush 的挑戰是時間限制。iOS app 進入背景後約 5 秒會被系統 suspend，Android 的限制更嚴格。Close flush 必須在這個時間窗口內完成網路請求。如果 buffer 中事件太多導致 flush 超時，需要截斷 — 送出最近的 N 筆，放棄較舊的。

Buffer 管理

記憶體 buffer

Buffer 在記憶體中維護一個事件陣列。新事件 append 到尾端，flush 時取出整個陣列送出並清空。

記憶體 buffer 的上限應該設定為 buffer size 的 2-3 倍（允許 1-2 次 flush 失敗後累積的事件）。超過上限時丟棄最舊的事件（FIFO），保留最新的 — 最新的事件對 debug 和即時分析的價值更高。

離線 buffer

網路不可用時，事件累積在記憶體 buffer 中。如果離線時間超過記憶體 buffer 容量，需要離線 persistence — 見 離線 buffer 與重試。

Flush 失敗處理

HTTP POST 失敗時（網路中斷、server 回 5xx、超時），事件保留在 buffer 中等待下一次 flush 重試。不立即重試 — 連續失敗通常代表網路問題或 server 問題，立即重試只會增加負載。

重試次數有上限（3 次）。超過重試上限的事件被丟棄，記錄一筆 sdk.flush.dropped metric 事件（這筆 metric 本身也進 buffer，在下次成功 flush 時送出）。

SDK 對 collector 回應的處理

SDK 只需要判斷 HTTP status code 就知道怎麼處理 buffer，不需要解析 response body 的細節。

207 和 400 都清 buffer 的關鍵判斷：Schema 驗證失敗是 SDK 端產出了不合規的事件，問題在 SDK 的事件建構邏輯（程式碼 bug），不在 collector 或網路 — 重試相同事件永遠不會過。SDK 把失敗事件的 error 訊息記到 warning/error log 供開發者排查，然後放行後續事件。

503 保留 buffer 的關鍵判斷：collector 暫時不可用是基礎設施問題（SQLite busy timeout、背壓），事件本身合法，等 collector 恢復後重試會成功。retry_after 由 collector 在回應中指定，SDK 用這個值設定下次 flush 的最小等待時間。

Batch 格式

SDK 在 flush 時把 buffer 中所有事件包裝成一個 batch，帶上 batch_id 送出。

1{
2  "batch_id": "019537a0-7b2c-7def-8a2b-3c4d5e6f7890",
3  "events": [ ... ]
4}

batch_id 由 SDK 在 flush 時產生。使用 UUID v7（uuid.uuid7()，Python 3.14+ 標準庫）——時間戳前綴保證有序（debug 時按 batch_id 排序即時間順序），隨機後綴保證唯一（高負載下多個 SDK 同時 flush 不碰撞）。用途是追蹤和 debug（collector log 中標記同一批事件的來源）。Collector 不依賴 batch_id 做去重 — 同一批事件被 SDK 重試時會帶不同的 batch_id（每次 flush 重新產生），collector 按事件內容（timestamp + source + name）判斷是否重複。

UUID v7 而非時間戳格式的選型理由：時間戳格式（b-{YYYYMMDD}-{HHMMSSfff}）在同毫秒多次 flush 時會碰撞，雖然 MVP 的 debug 用途碰撞無害，但 batch_id 碰撞在後續版本的離線補發去重場景（見 離線 buffer 與重試）會造成歧義。UUID v7 兼顧有序和唯一，一次到位。

Heartbeat 和 flush 的整合

DevOps dashboard 需要 sdk.heartbeat 事件判斷 SDK 是否存活。Heartbeat 不需要獨立的 timer — 整合在 flush timer 中：

flush timer 觸發時，如果 buffer 為空且距上次 heartbeat 超過設定間隔（預設 5 分鐘），自動注入一筆 sdk.heartbeat lifecycle 事件後送出。App idle 時仍有心跳但不多一個 timer；app 活躍時 heartbeat 被正常事件的 flush 取代（buffer 不會為空）。

Heartbeat 間隔由 SDK init config 的 heartbeatInterval 設定。設為 0 停用 heartbeat。

下一步路由

• 離線場景的處理 → 離線 buffer 與重試
• SDK 公開 API → SDK 公開 API 設計
• Collector 端如何接收批次事件 → 模組四 Collector 架構

三種策略

FIFO 丟棄（最簡單）

Buffer 滿時丟棄最舊的事件，保留最新的。整個 buffer 在記憶體中，不做本地 persistence。

優點：實作最簡單（array + 容量檢查），不需要檔案系統存取，不增加磁碟 I/O。

代價：離線超過 buffer 容量時，較舊的事件永久遺失。如果離線 30 分鐘、buffer 容量 200 筆、事件產生速率每分鐘 10 筆，前 100 筆（前 10 分鐘）的事件被丟棄。

適合場景：自用工具（離線場景少、遺失部分事件影響低）、SDK 初期版本（先用最簡單的策略上線）。

本地 persistence（最完整）

Buffer 滿時把事件寫入本地檔案（SQLite、JSONL 檔案、SharedPreferences / UserDefaults）。網路恢復後從本地檔案讀取並補發。

優點：離線期間的事件不會遺失（在本地儲存容量內）。

代價：實作複雜度高 — 需要處理檔案讀寫、並發存取（多執行緒安全）、本地儲存容量管理（磁碟空間上限）、補發時的去重（同一筆事件可能已在記憶體 buffer 中被 flush 過）。

適合場景：商業產品（使用者在地鐵、電梯、飛航模式下使用）、離線時間長且事件不可遺失的需求。

混合策略

記憶體 buffer 處理正常情況和短暫離線。離線超過記憶體 buffer 容量時，溢出的事件寫入本地檔案。網路恢復後先 flush 記憶體 buffer（最新事件），再補發本地檔案中的事件（較舊事件）。

混合策略的實作複雜度介於兩者之間。本地檔案只在溢出時使用，正常情況下不產生磁碟 I/O。

恢復後補發

網路恢復後補發離線期間累積的事件，需要處理三個問題：

補發順序

離線事件按 timestamp 順序補發，保持事件的時間順序。Collector 端收到的事件 timestamp 可能比當前時間早數小時 — 這是正常的離線補發，collector 應該根據事件的 timestamp 處理，不依賴收到時間。

補發速率

一次送出大量離線事件可能讓 collector 過載。分批補發（每批 50-100 筆，間隔 1-2 秒），讓 collector 有時間處理。

去重

同一筆事件可能同時存在於記憶體 buffer 和本地檔案中（寫入本地檔案時 buffer 中也有一份）。Collector 端用事件的唯一識別（timestamp + session_id + name 的組合，或 SDK 產生的 event_id UUID）做去重。

本地儲存容量管理

本地 persistence 需要設定磁碟使用上限。上限取決於事件大小和保留時間。

以平均每筆事件 500 bytes 估算：

自用工具 1 MB 足夠（離線場景少）。行動 app 10-50 MB 合理（使用者可能整天離線）。超過上限時用 FIFO 丟棄最舊的本地檔案。

各平台的本地儲存路徑

本地 persistence 的檔案路徑和格式因平台而異。MVP 階段全用記憶體 FIFO（最簡單策略），本地 persistence 標為第二階段。

App 被強制終止時（iOS 的 kill、Android 的 process death），記憶體 buffer 中未 flush 的事件會遺失。Flutter 的 AppLifecycleState.detached 不保證有時間執行 flush。接受這個遺失 — 強制終止是極端情境，下次啟動時 SDK 重新開始收集。

下一步路由

• 攢批送出策略 → 攢批送出策略
• SDK 端的資料脫敏 → SDK redaction helper
• Collector 端如何處理補發事件 → 模組四 Collector 設計
• 從 SDK 到 storage 的端到端資料損失地圖 → 端到端資料完整性

預設 redaction rule

SDK 內建一組預設 rule，處理常見的敏感資訊 pattern：

密碼欄位

匹配 data 物件中 key 包含 password、passwd、secret、token、api_key、apiKey、authorization 的欄位。匹配方式是 key 名稱的子字串比對（case-insensitive）。

URL 中的認證資訊

匹配 https://user:password@host 格式的 URL，把 user:password 部分替換為 [REDACTED]。

Stack trace 中的檔案路徑

匹配 stack trace 字串中的使用者目錄路徑（/Users/username/、/home/username/、C:\Users\username\），替換為 [USER_HOME]/。避免使用者名稱從 stack trace 洩漏。

自訂 redaction rule

業務特定的敏感資訊（信用卡號、身分證字號、醫療資料）不在預設 rule 的範圍內。SDK 提供 API 讓開發者在 init 時註冊自訂 rule。

1Monitor.init({
2  redactionRules: [
3    { pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/, replace: '[CARD]' },
4    { keyPattern: /^ssn$/i, replace: '[REDACTED]' },
5  ],
6})

自訂 rule 和預設 rule 一起執行。如果同一個值被多個 rule 匹配，第一個匹配的 rule 生效（rule 的執行順序：預設 rule 先，自訂 rule 後）。

Redaction 的執行時機

Redaction 在事件進入 flush payload 的那一刻執行 — buffer 中的事件保持原始內容，flush 時複製一份並在複製上執行 redaction。

在 buffer 中保持原始內容的理由是 debug：開發者在本地 console 看到的 log 應該包含完整資訊（開發環境不需要脫敏），只有離開 SDK 時才脫敏。SDK 可以提供 debugMode flag — debugMode 開啟時 console log 印出原始內容，HTTP POST 仍送出脫敏後的內容。

Redaction 和模組七的關係

SDK redaction helper 是模組七 資安與隱私中 redaction 策略的實作層。模組七定義「什麼資訊需要被保護」（策略），本章定義「SDK 如何在程式碼中實現這個保護」（實作）。

兩者的分工：

Collector 端可以做第二道檢查（re-scan 收到的事件是否仍包含敏感 pattern），作為 SDK 端 redaction 的備援。但主要的脫敏責任在 SDK 端 — 資料離開 SDK 後經過網路，已經暴露在傳輸風險中。

下一步路由

• SDK 公開 API → SDK 公開 API 設計
• 資安與隱私的完整策略 → 模組七 資安與隱私
• 自動攔截的 error 也需要 redaction → 自動攔截機制

點擊/觸碰感測器

點擊感測器偵測使用者和 UI 元素的互動 — 按鈕點擊、連結觸碰、選單選擇。每次互動產生一個 event 類型的事件。

哪些元素值得追蹤

追蹤粒度的判斷依據是「這個互動是否對應一個有意義的使用者意圖」。

有意義的互動（值得追蹤）：提交表單、點擊導航按鈕、觸發功能操作（連線、配對、匯出）。這些互動對應使用者的明確意圖，是 funnel 分析 的步驟候選。

低價值的互動（通常不追蹤）：滾動、hover、重複的相同操作（每秒多次的按鈕連按）。這些互動要麼太頻繁（滾動每秒觸發數十次），要麼不代表新的使用者意圖。

實作方式

Web（JS/TS）：在 document 層級用 event delegation 攔截 click 事件，過濾出帶 data-track attribute 的元素。開發者在需要追蹤的元素上加 data-track="connect-button"，感測器自動收集。不追蹤所有 click — 只追蹤被標記的。

Flutter：用 NavigatorObserver 或 custom GestureDetector wrapper。GestureDetector 包裝在需要追蹤的 widget 外層，onTap 觸發時送出事件。

效能影響

Event delegation 在 document 層級只有一個 listener，效能影響接近零。瓶頸在事件產生頻率 — 如果追蹤了高頻操作（每秒多次的滑動），事件進入 buffer 的速度可能超過 flush 的速度。用取樣控制（見本章末段）。

導航/路由感測器

導航感測器偵測使用者在不同畫面之間的切換 — page view、screen view、route change。每次切換產生一個 lifecycle 類型的事件。

平台差異

Web SPA：SPA 的 route 變換不觸發頁面載入，需要主動偵測 URL 變化。兩種偵測方式：

• History API 攔截：覆寫 pushState / replaceState，攔截 popstate 事件
• 框架層級 Hook：React Router 的 useLocation、Vue Router 的 afterEach guard

History API 攔截是 SDK 層的通用做法（不依賴框架）；框架 Hook 更精確但需要使用者整合（見 JS/TS 平台 的 SPA 路由段）。

Flutter：用 NavigatorObserver 的 didPush / didPop / didReplace 回呼。每次路由變化自動觸發，不需要使用者在每個頁面手動埋點。

Python CLI/Hook：沒有「畫面切換」的概念。對應的 lifecycle 事件是 hook.start / hook.complete — 每個 Hook 執行視為一個「畫面」。

事件 schema

1{
2  "type": "lifecycle",
3  "name": "screen.view",
4  "data": {
5    "screen_name": "TerminalScreen",
6    "previous_screen": "HomeScreen",
7    "navigation_method": "push"
8  }
9}

navigation_method（push / pop / replace / go）記錄導航方式，和 go vs push 的 UX 語意 對應。

錯誤邊界感測器

錯誤邊界感測器攔截元件級的 error — 和 auto-intercept 的全域 error 攔截互補。

和 auto-intercept 的職責分工

全域攔截捕獲「逃逸到頂層的 error」，錯誤邊界捕獲「在元件層級就被攔住的 error」。如果一個 error 被元件的 ErrorBoundary 捕獲，它不會觸發 window.onerror — auto-intercept 看不到它。錯誤邊界感測器填補這個缺口。

實作方式

React：ErrorBoundary 元件的 componentDidCatch 回呼中呼叫 monitor.error()。

Flutter：在 Widget 層用 ErrorWidget.builder 或自訂的 error handling widget。

額外 context

錯誤邊界感測器比全域攔截多一個 context — 知道 error 發生在哪個元件（component name / widget name）。這個資訊在 error 的 data schema 中記錄為 component 欄位。

效能標記感測器

效能標記感測器量測操作的延遲和系統的渲染表現。產生 metric 類型的事件。

Web Core Vitals

Web 平台用 PerformanceObserver API 自動收集三個核心指標：

• LCP（Largest Contentful Paint）：最大內容元素的載入時間
• FID（First Input Delay）：首次互動的延遲
• CLS（Cumulative Layout Shift）：累計佈局位移分數

1new PerformanceObserver((list) => {
2  for (const entry of list.getEntries()) {
3    monitor.metric(`web.vitals.${entry.entryType}`, {
4      value: entry.startTime || entry.value,
5      url: location.pathname
6    });
7  }
8}).observe({ type: 'largest-contentful-paint', buffered: true });

實務上依 entryType 分別取值（LCP 用 startTime、CLS 用 value、FID 用 processingStart - startTime），上述範例簡化示意。

Flutter frame timing

Flutter 用 SchedulerBinding.addTimingsCallback 偵測掉幀：

 1SchedulerBinding.instance.addTimingsCallback((timings) {
 2  for (final t in timings) {
 3    if (t.totalSpan > const Duration(milliseconds: 16)) {
 4      monitor.metric('render.frame_drop', {
 5        'build_ms': t.buildDuration.inMilliseconds,
 6        'raster_ms': t.rasterDuration.inMilliseconds,
 7      });
 8    }
 9  }
10});

16ms 是 60fps 的單幀預算。超過代表掉幀。

自訂 duration 量測

業務操作的延遲用手動標記量測：

1final stopwatch = Stopwatch()..start();
2await connectToTerminal();
3stopwatch.stop();
4monitor.metric('terminal.connect.duration', {
5  'duration_ms': stopwatch.elapsedMilliseconds,
6});

輸入敏感度感測器

輸入敏感度感測器偵測使用者正在輸入敏感資料 — 密碼欄位、API key 輸入、信用卡號碼。這個感測器的責任是觸發 redaction，而非記錄輸入內容。

偵測邏輯

Web：偵測 <input type="password">、帶有 autocomplete="cc-number" 或 data-sensitive attribute 的欄位。當使用者 focus 這些欄位時，標記當前 session 進入「敏感輸入模式」— 後續的事件自動加嚴 redaction 規則（例如暫停記錄按鍵事件）。

Flutter：偵測 TextField 的 obscureText: true 或 enableIMEPersonalizedLearning: false（見 安全敏感輸入框的 IME 控制）。

不記錄的原則

輸入敏感度感測器偵測「使用者正在輸入敏感內容」這個事實，但不記錄輸入的內容本身。送出的事件只包含：

1{
2  "type": "lifecycle",
3  "name": "input.sensitive_mode.entered",
4  "data": { "field_type": "password" }
5}

取樣策略設計

感測器產生的事件量可能很大（效能標記每 30 秒一筆 × 活躍使用者數）。取樣控制事件量、避免 SDK 和 collector 的資源壓力。

三種取樣模式

全收：每筆事件都送出。適合事件量低且每筆都有價值的類型 — error（每筆都可能是新 bug）、lifecycle 狀態轉換（量低）、認證失敗（安全敏感）。

百分比取樣：隨機丟棄一定比例的事件。適合高頻的效能和行為事件。取樣率由 SDK config 控制：

1sensors:
2  metric:
3    render.frame_drop: { sampling: 0.1 }    # 只收 10%
4    resource.memory: { sampling: 0.5 }       # 收 50%
5  event:
6    feature.*.used: { sampling: 1.0 }        # 全收
7    click.*: { sampling: 0.1 }               # 只收 10%

百分比取樣的代價是低機率事件可能被漏掉（取樣 10% 時、發生 5 次的事件可能一次都沒收到）。

條件取樣：正常情況下取樣、特定條件下全收。適合「平時不需要全量但問題發生時需要完整資料」的場景。例：正常 session 取樣 10%、但 session 內發生 error 後、該 session 剩餘事件全收（error session 的完整 context 比正常 session 更有價值）。

取樣率的管理

取樣率可以從三個層級設定：

三個層級由上到下優先順序遞增 — feature flag 覆蓋 collector config、collector config 覆蓋本地 config。

下一步路由

• 動機驅動的事件設計（哪些動機需要哪些感測器） → 動機驅動的事件設計
• 感測器的啟停控制和生命週期 → 感測器生命週期管理
• 被動攔截機制（和感測器互補） → 自動攔截機制
• 安全敏感輸入的完整 checklist → 安全敏感輸入框的 IME 控制

五個階段

早期開發

開發期的首要需求是 debug — 程式碼寫完跑起來、出問題時能定位。

開發期的取樣率全部設 1.0（全收）— 事件量極低（開發者自己操作），不需要取樣。

功能測試

針對被測功能開啟完整感測器，驗證功能的行為事件和效能指標是否正確觸發。

被測功能的 event 和 metric 全開。其他功能維持開發期設定。測試期間的感測器設定通常由測試 config 檔覆寫 SDK 預設值。

Production 上線

上線後的感測器組合平衡覆蓋率和成本：

A/B 測試

實驗感測器只對 treatment group 啟用。Control group 不觸發實驗事件，避免污染對照組資料。

實驗專用事件（experiment.pricing_test.assigned、experiment.pricing_test.converted）由 feature flag 控制 — flag 開啟時 SDK 才送這些事件。實驗結束後 flag 關閉，感測器自動停止。

實驗事件的保留期和實驗週期綁定，實驗結束 + 分析完成後可以 purge。

功能下線

功能移除時，對應的感測器 config 一起移除。Collector 端 purge 該功能的歷史事件（或降級到聚合摘要）。

移除 checklist：SDK config 移除事件名稱 → SDK 版本部署 → 確認 collector 不再收到該事件 → purge 歷史資料（可選）。

控制機制

三層控制機制各自適合不同的變更頻率：

SDK init config（靜態）

隨 app 版本部署的本地設定檔。變更需要發新版本。適合穩定的感測器組合。

 1sensors:
 2  error: { enabled: true, sampling: 1.0 }
 3  lifecycle: { enabled: true, sampling: 1.0 }
 4  event:
 5    funnel.*: { enabled: true, sampling: 1.0 }
 6    click.*: { enabled: true, sampling: 0.1 }
 7  metric:
 8    duration: { enabled: true, sampling: 0.5 }
 9  experiment:
10    pricing_test: { enabled: false }

Collector 端下發（動態）

SDK 啟動時從 collector 的 /config endpoint 拉取當前的感測器設定。Collector 端修改設定後，下一次 SDK 重啟或定期 refresh（每 5 分鐘）時生效。適合需要動態調整但不值得接 feature flag 服務的場景。

MVP 階段跳過 collector 下發，只用 SDK 本地 config。下發 API 的定義和實作標為第二階段 — 感測器的開關在 SDK 本地 config 已經能完全控制。

Feature flag 服務整合

SDK 在送出事件前查詢 feature flag 判斷感測器是否啟用。適合 A/B 測試 — flag 可以按使用者 / 百分比 / 條件分群啟用。

優先順序

三層控制的覆蓋優先順序：

1Feature flag > Collector 下發 > SDK 本地 config

SDK 本地 config 是 baseline。Collector 下發覆蓋 baseline 的特定欄位。Feature flag 覆蓋一切 — 即使本地 config 和 collector 都說啟用，flag 說關閉就關閉。

取樣率設計

取樣率決定「多少比例的事件會被實際送出」。取樣在 SDK 端執行 — 不送的事件不佔頻寬和儲存。

全收（sampling: 1.0）

每筆事件都送。適用於：

• error：每個 production error 都有 debug 價值，漏掉的 error 可能是最嚴重的那個
• 安全事件：auth 失敗、權限越界的取樣可能讓攻擊嘗試隱形
• 漏斗關鍵步驟：funnel 分析的轉換率計算需要精確的步驟計數

百分比取樣（0.01-0.5）

只送一定比例的事件。適用於高頻且個別事件價值低的場景：

• scroll / mousemove / hover：每秒觸發數十次，全收會產生大量事件。取樣 1-10% 足以分析使用者行為模式
• frame rate 量測：每幀一筆 metric 太多，每秒或每 30 秒取一筆足夠

取樣的實作用 SDK 端的隨機數 — if random() < sampling_rate then send(event) — 不需要 server 端參與。

條件取樣（retrospective full capture）

正常情況取樣，但發生 error 時回溯收集該 session 的全部事件。實作方式是 SDK 在記憶體中保留最近 N 筆事件的環形 buffer，觸發 error 時把 buffer 中的事件一併送出。

條件取樣讓「error session 的上下文完整」和「正常 session 不過度收集」兩個目標共存。

感測器開關的可觀察性

感測器本身的狀態變化需要被觀察 — 如果感測器靜默失效（config 錯誤導致某類事件停送），開發者可能很久後才發現「怎麼最近沒有 funnel 資料」。

啟動時 log 感測器清單

SDK 初始化完成時 log 當前啟用的感測器清單和取樣率。開發者在 debug console 就能看到「哪些感測器在跑」。

Config 變更事件

感測器 config 變更時（collector 下發新 config、或 feature flag 變化），SDK 送一個 lifecycle 事件：

1{
2  "type": "lifecycle",
3  "name": "sensor.config.changed",
4  "data": {
5    "source": "collector_push",
6    "changed": {"click.*": {"sampling": "0.1 → 0.05"}},
7    "active_sensors": 12
8  }
9}

這筆事件讓開發者在查詢時能看到「某個時間點感測器 config 改變了」，和事件量的變化做交叉比對。

下一步路由

• 感測器偵測哪些行為 → 前端感測器設計
• SDK 的公開 API → SDK 公開 API 設計
• 四類事件的定義 → 四類事件的完整定義
• 事件枚舉方法 → 事件枚舉與補齊檢查