ytracking-web 0.1.2 → 0.3.0

package/README.md

@@ -28,33 +28,59 @@ npm install ytracking-web
 
 ## 使用（IIFE）
 
+**最少程式（腳本與 API 同源、後台未強制 collect 金鑰時）：** 只需 `siteId`；SDK 會從 `<script src="…ytracking-web.js">` 推斷 ingest origin，並在啟動後自動送一次 `pageview`。
+
 ```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 路由、不要自動首屏 `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`、`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 一次 `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）
-- `track(type, { props })` — 對應 `POST /v1/collect` envelope
-- `trackPageView()` — `page_view`
-- `install({ clickId? })` — 內嵌 **`POST /v1/install`**（無 `appId` 之 embed 形態）
+- `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 })` — 後續事件帶入

package/package.json

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

package/src/client.ts

@@ -37,12 +37,51 @@ 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`;
 }
 
-function installUrl(origin: string): string {
-  return `${origin}/v1/install`;
+function randomUuid(): string {
+  return typeof crypto !== "undefined" && crypto.randomUUID
+    ? crypto.randomUUID()
+    : `id_${Date.now()}_${Math.random().toString(36).slice(2)}`;
 }
 
 function attributionTokenUrl(origin: string): string {
@@ -51,7 +90,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 +125,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 +155,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 +201,9 @@ export class YTrackingWebClient {
       document.addEventListener("visibilitychange", this.visibilityHandler);
     }
     void this.flush();
+    if (this.cfg.autoTrackPageView) {
+      void this.pageView();
+    }
   }
 
   shutdown(): void {
@@ -167,7 +221,7 @@ export class YTrackingWebClient {
     this.visibilityHandler = null;
   }
 
-  async track(
+  async event(
     eventType: string,
     options?: { props?: Record<string, unknown> },
   ): Promise<void> {
@@ -188,14 +242,41 @@ export class YTrackingWebClient {
     });
   }
 
-  async trackPageView(): Promise<void> {
-    return this.track("page_view", {});
+  async pageView(): Promise<void> {
+    return this.event("pageview", {});
   }
 
-  async install(opts?: { clickId?: string }): Promise<void> {
-    const body: Record<string, string> = { siteId: this.cfg.siteId };
+  async paid(options?: { props?: Record<string, unknown> }): Promise<void> {
+    return this.event("paid", options);
+  }
+
+  async install(opts?: {
+    clickId?: string;
+    installId?: string;
+    status?: "first_open" | "install_complete";
+    occurredAt?: string;
+    props?: Record<string, unknown>;
+  }): Promise<void> {
+    const occurredAt = opts?.occurredAt?.trim() || new Date().toISOString();
+    const installId = opts?.installId?.trim() || randomUuid();
+    const status = opts?.status?.trim() || "first_open";
+    const event: Record<string, unknown> = {
+      type: "install",
+      timestamp: occurredAt,
+      occurredAt,
+      installId,
+      status,
+    };
     const cid = opts?.clickId?.trim() || this.context.clickId?.trim();
-    if (cid) body.clickId = cid;
+    if (cid) event.clickId = cid;
+    const visitorId = this.context.visitorId?.trim();
+    if (visitorId) event.visitorId = visitorId;
+    const appId = this.context.appId?.trim();
+    if (appId) event.appId = appId;
+    if (opts?.props && typeof opts.props === "object") {
+      event.props = opts.props;
+    }
+    const body = { siteId: this.cfg.siteId, event };
     await this.enqueue({
       kind: "install",
       payload: JSON.stringify(body),
@@ -244,6 +325,7 @@ export class YTrackingWebClient {
         payload,
         this.cfg.requestTimeoutMs,
         undefined,
+        this.sdkHeaders(),
       );
       if (!res.ok) {
         log(
@@ -442,7 +524,7 @@ export class YTrackingWebClient {
   }
 
   private async sendOne(rec: OutboxRecord): Promise<void> {
-    const pathFn = rec.kind === "install" ? installUrl : collectUrl;
+    const pathFn = collectUrl;
     let lastRetryAfter: number | undefined;
 
     for (const origin of this.originsInOrder()) {
@@ -456,6 +538,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 +646,8 @@ export class YTrackingWebClient {
       `${origin}/v1/sdk/domain-health/report`,
       payload,
       this.cfg.requestTimeoutMs,
+      undefined,
+      this.sdkHeaders(),
     );
   }
 
@@ -648,12 +733,12 @@ export async function track(
   options?: { props?: Record<string, unknown> },
 ): Promise<void> {
   if (!singleton) throw new Error("YTrackingWeb: call init() first");
-  return singleton.track(eventType, options);
+  return singleton.event(eventType, options);
 }
 
 export async function trackPageView(): Promise<void> {
   if (!singleton) throw new Error("YTrackingWeb: call init() first");
-  return singleton.trackPageView();
+  return singleton.pageView();
 }
 
 export async function flush(): Promise<void> {
@@ -665,11 +750,37 @@ export function shutdown(): void {
   singleton = null;
 }
 
-export async function install(opts?: { clickId?: string }): Promise<void> {
+export async function install(opts?: {
+  clickId?: string;
+  installId?: string;
+  status?: "first_open" | "install_complete";
+  occurredAt?: string;
+  props?: Record<string, unknown>;
+}): Promise<void> {
   if (!singleton) throw new Error("YTrackingWeb: call init() first");
   return singleton.install(opts);
 }
 
+export async function event(
+  eventType: string,
+  options?: { props?: Record<string, unknown> },
+): Promise<void> {
+  if (!singleton) throw new Error("YTrackingWeb: call init() first");
+  return singleton.event(eventType, options);
+}
+
+export async function pageView(): Promise<void> {
+  if (!singleton) throw new Error("YTrackingWeb: call init() first");
+  return singleton.pageView();
+}
+
+export async function paid(options?: {
+  props?: Record<string, unknown>;
+}): Promise<void> {
+  if (!singleton) throw new Error("YTrackingWeb: call init() first");
+  return singleton.paid(options);
+}
+
 export async function issueAttributionToken(opts?: {
   clickId?: string;
   ttlSeconds?: number;

package/src/index.ts

@@ -8,6 +8,9 @@ export {
 export { buildCollectEnvelope, getOrCreateSessionId } from "./payload";
 export {
   init,
+  event,
+  pageView,
+  paid,
   track,
   trackPageView,
   flush,

package/src/retry.ts

@@ -20,8 +20,14 @@ export function backoffMs(attemptIndexZeroBased: number): number {
   return Math.min(Math.max(0, Math.floor(base + jitter)), 600000);
 }
 
-const HIGH = new Set(["download_click", "registration", "payment", "app_open"]);
-const LOW = new Set(["page_view", "scroll", "heartbeat"]);
+const HIGH = new Set([
+  "download_click",
+  "registration",
+  "paid",
+  "payment",
+  "app_open",
+]);
+const LOW = new Set(["pageview", "page_view", "scroll", "heartbeat"]);
 
 export function eventPriority(eventType: string): number {
   if (HIGH.has(eventType)) return 10;

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 `pageview` (default **true**).
+   * Set `false` if you only track SPA navigations or call `pageView()` yourself.
+   */
+  autoTrackPageView?: boolean;
   debug?: boolean;
   enableVisitorFallbackFingerprint?: boolean;
   maxQueueSize?: number;