ytracking-web 0.1.1 → 0.2.0

package/README.md

@@ -21,31 +21,51 @@ npm install ytracking-web
 
 ## 發佈至 npm
 
-1. 於倉庫根目錄：`npm run check:web-sdk`、（建議）`npm run build:web-sdk`。
+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`）。亦可手動：`cd packages/ytracking-web && npm publish`（需已 `npm login` 或 `~/.npmrc` token）。
+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，並在啟動後自動送一次 `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`）
@@ -55,6 +75,7 @@ npm install ytracking-web
 - `track(type, { props })` — 對應 `POST /v1/collect` envelope
 - `trackPageView()` — `page_view`
 - `install({ clickId? })` — 內嵌 **`POST /v1/install`**（無 `appId` 之 embed 形態）
+- `issueAttributionToken({ clickId?, ttlSeconds?, campaignId?, appId?, deferredContext? })` — 同步 **`POST /v1/attribution/token`**（不入佇列）；沿用 `setContext` 之 visitor／session／click 等
 - `flush()` — 手動送出佇列
 - `setContext({ visitorId, sessionId, clickId, campaignId, appId })` — 後續事件帶入
 - `shutdown()` — 停止定時 flush
@@ -64,7 +85,7 @@ npm install ytracking-web
 - 每筆事件在 `event.props` 附 **`_ytSdkEventId`**（支援 `crypto.randomUUID` 時為 UUID）與 **`_ytSdk: "web-v1"`**；同時在 JSON 根層帶 **`idempotencyKey`**（與該 UUID 相同），與 **`POST /v1/collect`** 去重契約對齊（見 [API.md](../../docs/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](../../docs/SITE_AND_EMBED.md)）。
+- 須符合 `sites.allowed_origins`（見 [SITE_AND_EMBED.md](../../docs/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，避免重複初始化時累積監聽器。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ytracking-web",
-  "version": "0.1.1",
+  "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`;
 }
@@ -45,9 +82,16 @@ function installUrl(origin: string): string {
   return `${origin}/v1/install`;
 }
 
+function attributionTokenUrl(origin: string): string {
+  return `${origin}/v1/attribution/token`;
+}
+
 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;
@@ -79,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,
@@ -106,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;
@@ -146,6 +199,9 @@ export class YTrackingWebClient {
       document.addEventListener("visibilitychange", this.visibilityHandler);
     }
     void this.flush();
+    if (this.cfg.autoTrackPageView) {
+      void this.trackPageView();
+    }
   }
 
   shutdown(): void {
@@ -200,6 +256,106 @@ export class YTrackingWebClient {
     });
   }
 
+  /**
+   * Issue a one-time deferred deep link token (`POST /v1/attribution/token`).
+   * Synchronous HTTP (not queued); rotates ingestion origins on success like collect/install.
+   */
+  async issueAttributionToken(opts?: {
+    clickId?: string;
+    ttlSeconds?: number;
+    campaignId?: string;
+    appId?: string;
+    deferredContext?: Record<string, unknown>;
+  }): Promise<{ attributionToken: string; expiresAt: string }> {
+    const body: Record<string, unknown> = { siteId: this.cfg.siteId };
+    const cid = opts?.clickId?.trim() || this.context.clickId?.trim();
+    if (cid) body.clickId = cid;
+    const vid = this.context.visitorId?.trim();
+    if (vid) body.visitorId = vid;
+    const sid = this.context.sessionId?.trim();
+    if (sid) body.sessionId = sid;
+    const camp = opts?.campaignId?.trim() || this.context.campaignId?.trim();
+    if (camp) body.campaignId = camp;
+    const aid = opts?.appId?.trim() || this.context.appId?.trim();
+    if (aid) body.appId = aid;
+    if (opts?.ttlSeconds != null) body.ttlSeconds = opts.ttlSeconds;
+    if (
+      opts?.deferredContext &&
+      typeof opts.deferredContext === "object" &&
+      !Array.isArray(opts.deferredContext)
+    ) {
+      body.deferredContext = opts.deferredContext;
+    }
+    const payload = JSON.stringify(body);
+    let lastRetryAfter: number | undefined;
+
+    for (const origin of this.originsInOrder()) {
+      const url = attributionTokenUrl(origin);
+      const res = await postJson(
+        url,
+        payload,
+        this.cfg.requestTimeoutMs,
+        undefined,
+        this.sdkHeaders(),
+      );
+      if (!res.ok) {
+        log(
+          this.cfg.debug,
+          "issueAttributionToken transport fail",
+          origin,
+          res.kind,
+        );
+        if (res.retryAfterMs !== undefined) lastRetryAfter = res.retryAfterMs;
+        if (res.kind === "network" || res.kind === "timeout") {
+          await this.reportDomainUnreachable(origin, res.kind);
+          this.rotateCursorAfter(origin);
+        }
+        continue;
+      }
+      if (res.retryAfterMs !== undefined) lastRetryAfter = res.retryAfterMs;
+
+      if (res.status === 201) {
+        const j = res.bodyJson as {
+          attributionToken?: unknown;
+          expiresAt?: unknown;
+        };
+        const tok =
+          typeof j?.attributionToken === "string"
+            ? j.attributionToken.trim()
+            : "";
+        const exp = typeof j?.expiresAt === "string" ? j.expiresAt.trim() : "";
+        if (tok && exp) {
+          this.setCursorToOrigin(origin);
+          await this.refreshEndpointPool(origin);
+          return { attributionToken: tok, expiresAt: exp };
+        }
+      }
+      if (isNonRetryableStatus(res.status)) {
+        throw new Error(
+          `YTrackingWeb: issueAttributionToken failed with HTTP ${res.status}`,
+        );
+      }
+      if (isRetryableStatus(res.status)) {
+        log(
+          this.cfg.debug,
+          "issueAttributionToken retryable",
+          res.status,
+          origin,
+        );
+        continue;
+      }
+      throw new Error(
+        `YTrackingWeb: issueAttributionToken failed with HTTP ${res.status}`,
+      );
+    }
+
+    throw new Error(
+      lastRetryAfter !== undefined
+        ? `YTrackingWeb: issueAttributionToken failed (Retry-After hint ${lastRetryAfter}ms)`
+        : "YTrackingWeb: issueAttributionToken failed on all origins",
+    );
+  }
+
   private async enqueue(p: {
     kind: OutboxRecord["kind"];
     payload: string;
@@ -353,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);
@@ -460,6 +617,8 @@ export class YTrackingWebClient {
       `${origin}/v1/sdk/domain-health/report`,
       payload,
       this.cfg.requestTimeoutMs,
+      undefined,
+      this.sdkHeaders(),
     );
   }
 
@@ -567,6 +726,17 @@ export async function install(opts?: { clickId?: string }): Promise<void> {
   return singleton.install(opts);
 }
 
+export async function issueAttributionToken(opts?: {
+  clickId?: string;
+  ttlSeconds?: number;
+  campaignId?: string;
+  appId?: string;
+  deferredContext?: Record<string, unknown>;
+}): Promise<{ attributionToken: string; expiresAt: string }> {
+  if (!singleton) throw new Error("YTrackingWeb: call init() first");
+  return singleton.issueAttributionToken(opts);
+}
+
 export function setContext(partial: {
   visitorId?: string;
   sessionId?: string;

package/src/index.ts

@@ -13,6 +13,7 @@ export {
   flush,
   shutdown,
   install,
+  issueAttributionToken,
   setContext,
   getClient,
   YTrackingWebClient,

package/src/transport.ts

@@ -24,17 +24,26 @@ 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",
       headers: hdrs,
       body,
-      credentials: "include",
+      // Collect does not depend on cookies. Keep this non-credentialed so
+      // wildcard ACAO ("*") deployments remain browser-compatible.
+      credentials: "omit",
       signal: ctrl.signal,
       keepalive: true,
     });

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;