ytracking-web（瀏覽器 SDK）

TypeScript 實作，對齊 docs/SDK_DESIGN.md：事件先入 IndexedDB 佇列，背景 flush、退避重試、多 baseUrl 故障轉移；失敗時可降級為記憶體佇列（不持久）。

建置產物（提交於 site/public/sdk/）

| 檔案 | 說明 | |------|------| | ytracking-web.js | IIFE，globalThis.YTrackingWeb | | ytracking-web.min.js | 同上，minify | | ytracking-web.mjs | ESM import { init, track } from '...'（部署路徑依站點） |

根目錄執行：npm run build:web-sdk

npm 套件（選用）

npm install ytracking-web

套件 exports 指向 src/*.ts 原始碼（type: module）；整合專案需使用可轉譯／bundle TypeScript 的工具鏈，或繼續使用倉庫建置之 site/public/sdk/* 靜態檔。發佈 registry 前請於根目錄執行 npm run check:web-sdk 與 npm run build:web-sdk 驗證。

發佈至 npm

1. 於倉庫根目錄先跑契約檢查：npm run check:web-sdk、npm run check:openapi-drift、（建議）npm run build:web-sdk。（本機 npm run publish:ytracking-web 已內含 check:web-sdk 與 check:openapi-drift。）
2. GitHub Actions：「Publish ytracking-web to npm」workflow（workflow_dispatch）。需在 repo 設定 NPM_TOKEN（npm automation access token，具 publish 權限）。
3. 本機（免 npm login，適合首次發佈作法 B）：在倉庫根目錄設定 NPM_TOKEN 後執行 npm run publish:ytracking-web（會先跑 check:web-sdk 再 npm publish）。若有 API 契約改動，請先在 root 執行 npm run check:openapi-drift 並同步更新 docs/API.md / docs/openapi.yaml。

使用（IIFE）

最少程式（腳本與 API 同源、後台未強制 collect 金鑰時）： 只需 siteId；SDK 會從 <script src="…ytracking-web.js"> 推斷 ingest origin，並在啟動後自動送一次 pageview。

<script src="https://你的網域/sdk/ytracking-web.js"></script>
<script>
  YTrackingWeb.init({ siteId: "站點-UUID" });
</script>

明確指定 API 網址或備援、或帶 SDK key（與行動端一致）：

<script src="https://cdn.example.com/sdk/ytracking-web.js"></script>
<script>
  YTrackingWeb.init({
    siteId: "站點-UUID",
    baseUrl: "https://ingest.example.com",
    fallbackBaseUrls: ["https://ingest-backup.example.com"],
    sdkKey: "yt_sdk_…",
  });
</script>

若腳本託管在 CDN 而 API 在另一網域，必須設定 baseUrl 或 baseUrls（不可依賴推斷）。
僅追蹤 SPA 路由、不要自動首屏 pageview 時：加 autoTrackPageView: false，再自行呼叫 pageView()（舊名 trackPageView()）。

0.2.0 行為變更（升級自 0.1.x）

• 預設 autoTrackPageView: true：若你原本在 init 後又手動呼叫一次 pageView()（或 trackPageView()），首屏可能重複計數 — 請刪除多餘呼叫，或設 autoTrackPageView: false。
• baseUrls 改為可選：可只用 baseUrl（字串），或与 baseUrls 合併（baseUrl 優先）。

0.3.0

• 套件／API 行為：與 0.2.0 相同（minor 發佈：對外文件、external-demo.html 的 tracker=web 驗收路徑與靜態 bundle 對齊）。
• 整合測試：Production／本機可於 /external-demo.html?siteId=…&tracker=web 驗證 Web SDK（見 repo docs/SITE_AND_EMBED.md）。

API（YTrackingWeb）

• init(config) — 必填 siteId
  • baseUrl：單一 ingest origin（無尾階 /）；與 baseUrls 可併用（順序：先 baseUrl 再 baseUrls）
  • baseUrls：ingest origins 陣列；若與 baseUrl 皆省略，會嘗試從頁面上最後一個 …ytracking-web(.min).js 的 <script src> 推斷 origin（腳本須與 API 同源才正確）
  • sdkKey：若設定，所有 POST（collect、install、attribution token、domain-health report）會帶 X-YT-Sdk-Key
  • autoTrackPageView：預設 true，start() 後自動 enqueue 一次 pageview；設 false 則完全自行呼叫 pageView／event
  • enableVisitorFallbackFingerprint：可選（預設 false），僅在無 cookie + 無 localStorage visitor 時以低熵指紋產生暫時 visitor seed
  • maxQueueSize：本地 queue 容量上限（預設 500），超量時淘汰低優先且最舊事件
  • batchSize：單次 flush 最多取件數（預設 8）
  • flushConcurrency：單次 flush 內平行送件 worker 數（預設 2，最小 1）
  • endpointListTtlSec：成功送達後重新拉取 /v1/sdk/ingestion-hosts 的最短間隔（秒，預設 300）
  • domainHealthReportMinIntervalMs：同一 domain 不可達回報最短間隔（毫秒，預設 300000）
• event(type, { props }) — 對應 POST /v1/collect envelope
• pageView() — pageview（trackPageView() 仍可用）
• paid({ props? }) — paid
• install({ clickId? }) — 經佇列送出 POST /v1/install（與 yt-embed 之 sendInstall 一致）
• issueAttributionToken({ clickId?, ttlSeconds?, campaignId?, appId?, deferredContext? }) — 同步 POST /v1/attribution/token（不入佇列）；沿用 setContext 之 visitor／session／click 等
• flush() — 手動送出佇列
• setContext({ visitorId, sessionId, clickId, campaignId, appId }) — 後續事件帶入
• shutdown() — 停止定時 flush

與後端的關係

• 每筆事件在 event.props 附 _ytSdkEventId（支援 crypto.randomUUID 時為 UUID）與 _ytSdk: "web-v1"；同時在 JSON 根層帶 idempotencyKey（與該 UUID 相同），與 POST /v1/collect 去重契約對齊（見 API.md §2.2）。重試／重送同一佇列項目時沿用同一 id，consumer 只會落庫一次。
• collect 出站 Idempotency-Key 會優先使用 payload 根層 idempotencyKey（若缺失才回退 queue id），確保 header 與 body 同鍵。
• collect 成功回應若包含 visitorId，SDK 會寫入 localStorage（yt_vid_v1）並自動帶入後續事件 context；可在 cookie 受限環境維持 visitor 關聯。
• 須符合 sites.allowed_origins（見 SITE_AND_EMBED.md）。SDK collect 出站採 credentials: "omit"，不依賴瀏覽器 cookie。
• fallback 會維護 endpoint pool + cursor；成功入口可刷新新 hosts，不可達時會送 best-effort domain-health/report（含節流）。
• Retry-After 同時支援秒數與 HTTP-date；shutdown() 會解除 visibilitychange listener，避免重複初始化時累積監聽器。

型別檢查

npm run check:web-sdk