ytracking-web 0.1.2 → 0.2.0

package/README.md

@@ -28,24 +28,44 @@ npm install ytracking-web
 
 ## 使用（IIFE）
 
+**最少程式（腳本與 API 同源、後台未強制 collect 金鑰時）：** 只需 `siteId`；SDK 會從 `<script src="…ytracking-web.js">` 推斷 ingest origin，並在啟動後自動送一次 `page_view`。
+
 ```html
 <script src="https://你的網域/sdk/ytracking-web.js"></script>
+<script>
+  YTrackingWeb.init({ siteId: "站點-UUID" });
+</script>
+```
+
+**明確指定 API 網址或備援、或帶 SDK key（與行動端一致）：**
+
+```html
+<script src="https://cdn.example.com/sdk/ytracking-web.js"></script>
 <script>
   YTrackingWeb.init({
     siteId: "站點-UUID",
-    baseUrls: ["https://你的網域"],
-    fallbackBaseUrls: [],
-    endpointListTtlSec: 300,
-    domainHealthReportMinIntervalMs: 300000,
-    debug: false,
+    baseUrl: "https://ingest.example.com",
+    fallbackBaseUrls: ["https://ingest-backup.example.com"],
+    sdkKey: "yt_sdk_…",
   });
-  YTrackingWeb.trackPageView();
 </script>
 ```
 
+若腳本託管在 CDN 而 API 在另一網域，**必須**設定 `baseUrl` 或 `baseUrls`（不可依賴推斷）。  
+僅追蹤 SPA 路由、不要自動首屏 `page_view` 時：加 **`autoTrackPageView: false`**，再自行呼叫 `trackPageView()`。
+
+### 0.2.0 行為變更（升級自 0.1.x）
+
+- 預設 **`autoTrackPageView: true`**：若你原本在 `init` 後又手動呼叫一次 `trackPageView()`，首屏可能重複計數 — 請刪除多餘呼叫，或設 `autoTrackPageView: false`。
+- `baseUrls` 改為可選：可只用 **`baseUrl`**（字串），或与 `baseUrls` 合併（`baseUrl` 優先）。
+
 ## API（`YTrackingWeb`）
 
-- `init(config)` — 必填 `siteId`、`baseUrls`（無尾階 `/` 之 origin）
+- `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 一次 `page_view`；設 `false` 則完全自行呼叫 `trackPageView`／`track`
   - `enableVisitorFallbackFingerprint`：可選（預設 `false`），僅在無 cookie + 無 localStorage visitor 時以低熵指紋產生暫時 visitor seed
   - `maxQueueSize`：本地 queue 容量上限（預設 `500`），超量時淘汰低優先且最舊事件
   - `batchSize`：單次 flush 最多取件數（預設 `8`）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ytracking-web",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Browser SDK for YTracking collect/install (IndexedDB queue, retry, multi-host)",
   "type": "module",
   "main": "./src/index.ts",

package/src/client.ts

@@ -37,6 +37,43 @@ function normalizeOrigins(urls: string[]): string[] {
   return out;
 }
 
+/** When `baseUrl` / `baseUrls` omitted, use the origin of the last ytracking-web script tag. */
+function inferBaseUrlFromLastYTrackingScript(): string | undefined {
+  if (typeof document === "undefined") return undefined;
+  const scripts = document.getElementsByTagName("script");
+  for (let i = scripts.length - 1; i >= 0; i -= 1) {
+    const el = scripts.item(i);
+    if (!el || el.nodeName !== "SCRIPT") continue;
+    const src = (el as HTMLScriptElement).src;
+    if (!src) continue;
+    try {
+      const baseHref =
+        typeof location !== "undefined" && location.href
+          ? location.href
+          : "https://invalid.invalid/";
+      const u = new URL(src, baseHref);
+      if (/ytracking-web(\.min)?\.js([?#]|$)/i.test(u.pathname)) {
+        return u.origin;
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return undefined;
+}
+
+function mergeBaseOrigins(cfg: InitConfig): string[] {
+  const parts: string[] = [];
+  if (cfg.baseUrl) parts.push(cfg.baseUrl);
+  if (cfg.baseUrls?.length) parts.push(...cfg.baseUrls);
+  let base = normalizeOrigins(parts);
+  if (base.length === 0) {
+    const inferred = inferBaseUrlFromLastYTrackingScript();
+    if (inferred) base = [inferred];
+  }
+  return [...new Set(base)];
+}
+
 function collectUrl(origin: string): string {
   return `${origin}/v1/collect`;
 }
@@ -51,7 +88,10 @@ function attributionTokenUrl(origin: string): string {
 
 export class YTrackingWebClient {
   private cfg: Required<
-    Pick<InitConfig, "siteId" | "baseUrls"> & {
+    Pick<InitConfig, "siteId"> & {
+      baseUrls: string[];
+      sdkKey: string | undefined;
+      autoTrackPageView: boolean;
       fallbackBaseUrls: string[];
       debug: boolean;
       enableVisitorFallbackFingerprint: boolean;
@@ -83,15 +123,18 @@ export class YTrackingWebClient {
   } = {};
 
   constructor(cfg: InitConfig) {
-    const base = normalizeOrigins(cfg.baseUrls);
+    const base = mergeBaseOrigins(cfg);
     if (!cfg.siteId?.trim() || base.length === 0) {
       throw new Error(
-        "YTrackingWeb: siteId and at least one baseUrl are required",
+        "YTrackingWeb: siteId and at least one ingest origin are required (set baseUrl or baseUrls, or load the SDK from your API host so the script origin can be inferred)",
       );
     }
+    const sk = cfg.sdkKey?.trim();
     this.cfg = {
       siteId: cfg.siteId.trim(),
       baseUrls: base,
+      sdkKey: sk || undefined,
+      autoTrackPageView: cfg.autoTrackPageView !== false,
       fallbackBaseUrls: normalizeOrigins(cfg.fallbackBaseUrls ?? []),
       debug: !!cfg.debug,
       enableVisitorFallbackFingerprint: !!cfg.enableVisitorFallbackFingerprint,
@@ -110,6 +153,12 @@ export class YTrackingWebClient {
     ];
   }
 
+  private sdkHeaders(): Record<string, string> | undefined {
+    const k = this.cfg.sdkKey;
+    if (!k) return undefined;
+    return { "X-YT-Sdk-Key": k };
+  }
+
   setContext(partial: {
     visitorId?: string;
     sessionId?: string;
@@ -150,6 +199,9 @@ export class YTrackingWebClient {
       document.addEventListener("visibilitychange", this.visibilityHandler);
     }
     void this.flush();
+    if (this.cfg.autoTrackPageView) {
+      void this.trackPageView();
+    }
   }
 
   shutdown(): void {
@@ -244,6 +296,7 @@ export class YTrackingWebClient {
         payload,
         this.cfg.requestTimeoutMs,
         undefined,
+        this.sdkHeaders(),
       );
       if (!res.ok) {
         log(
@@ -456,6 +509,7 @@ export class YTrackingWebClient {
         rec.payload,
         this.cfg.requestTimeoutMs,
         idempotencyForRequest,
+        this.sdkHeaders(),
       );
       if (!res.ok) {
         log(this.cfg.debug, "post transport fail", rec.id, origin, res.kind);
@@ -563,6 +617,8 @@ export class YTrackingWebClient {
       `${origin}/v1/sdk/domain-health/report`,
       payload,
       this.cfg.requestTimeoutMs,
+      undefined,
+      this.sdkHeaders(),
     );
   }
 

package/src/transport.ts

@@ -24,11 +24,18 @@ export async function postJson(
   body: string,
   timeoutMs: number,
   idempotencyKey?: string,
+  extraHeaders?: Record<string, string>,
 ): Promise<PostResult> {
   const ctrl = new AbortController();
   const t = setTimeout(() => ctrl.abort(), timeoutMs);
   try {
     const hdrs: Record<string, string> = { "Content-Type": "application/json" };
+    if (extraHeaders) {
+      for (const [k, v] of Object.entries(extraHeaders)) {
+        const key = k?.trim();
+        if (key) hdrs[key] = String(v);
+      }
+    }
     if (idempotencyKey) hdrs["Idempotency-Key"] = idempotencyKey;
     const res = await fetch(url, {
       method: "POST",

package/src/types.ts

@@ -13,8 +13,25 @@ export type OutboxRecord = {
 
 export type InitConfig = {
   siteId: string;
-  baseUrls: string[];
+  /**
+   * Primary ingest origin (no trailing slash). Merged with `baseUrls` (order: baseUrl first).
+   * If neither `baseUrl` nor `baseUrls` is set, the SDK tries to infer the origin from the last
+   * `<script src="...ytracking-web(.min).js">` on the page (same host as your deployed `/sdk/` script).
+   */
+  baseUrl?: string;
+  /** Ingest origins (no trailing slashes). Use with or instead of singular `baseUrl`. */
+  baseUrls?: string[];
   fallbackBaseUrls?: string[];
+  /**
+   * When set, all POSTs (collect, install, attribution token, domain-health report) include
+   * `X-YT-Sdk-Key` — same as mobile SDKs; required if your site enforces collect auth.
+   */
+  sdkKey?: string;
+  /**
+   * After IndexedDB/outbox starts, enqueue one `page_view` (default **true**).
+   * Set `false` if you only track SPA navigations or call `trackPageView()` yourself.
+   */
+  autoTrackPageView?: boolean;
   debug?: boolean;
   enableVisitorFallbackFingerprint?: boolean;
   maxQueueSize?: number;