ytracking-web 0.2.0 → 0.3.0

package/README.md

@@ -28,7 +28,7 @@ npm install ytracking-web
 
 ## 使用（IIFE）
 
-**最少程式（腳本與 API 同源、後台未強制 collect 金鑰時）：** 只需 `siteId`；SDK 會從 `<script src="…ytracking-web.js">` 推斷 ingest origin，並在啟動後自動送一次 `page_view`。
+**最少程式（腳本與 API 同源、後台未強制 collect 金鑰時）：** 只需 `siteId`；SDK 會從 `<script src="…ytracking-web.js">` 推斷 ingest origin，並在啟動後自動送一次 `pageview`。
 
 ```html
 <script src="https://你的網域/sdk/ytracking-web.js"></script>
@@ -52,29 +52,35 @@ npm install ytracking-web
 ```
 
 若腳本託管在 CDN 而 API 在另一網域，**必須**設定 `baseUrl` 或 `baseUrls`（不可依賴推斷）。  
-僅追蹤 SPA 路由、不要自動首屏 `page_view` 時：加 **`autoTrackPageView: false`**，再自行呼叫 `trackPageView()`。
+僅追蹤 SPA 路由、不要自動首屏 `pageview` 時：加 **`autoTrackPageView: false`**，再自行呼叫 `pageView()`（舊名 `trackPageView()`）。
 
 ### 0.2.0 行為變更（升級自 0.1.x）
 
-- 預設 **`autoTrackPageView: true`**：若你原本在 `init` 後又手動呼叫一次 `trackPageView()`，首屏可能重複計數 — 請刪除多餘呼叫，或設 `autoTrackPageView: false`。
+- 預設 **`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 一次 `page_view`；設 `false` 則完全自行呼叫 `trackPageView`／`track`
+  - **`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.2.0",
+  "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

@@ -78,8 +78,10 @@ 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 {
@@ -200,7 +202,7 @@ export class YTrackingWebClient {
     }
     void this.flush();
     if (this.cfg.autoTrackPageView) {
-      void this.trackPageView();
+      void this.pageView();
     }
   }
 
@@ -219,7 +221,7 @@ export class YTrackingWebClient {
     this.visibilityHandler = null;
   }
 
-  async track(
+  async event(
     eventType: string,
     options?: { props?: Record<string, unknown> },
   ): Promise<void> {
@@ -240,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),
@@ -495,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()) {
@@ -704,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> {
@@ -721,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/types.ts

@@ -28,8 +28,8 @@ export type InitConfig = {
    */
   sdkKey?: string;
   /**
-   * After IndexedDB/outbox starts, enqueue one `page_view` (default **true**).
-   * Set `false` if you only track SPA navigations or call `trackPageView()` yourself.
+   * 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;