@cnv-vn/track 0.3.0-beta.1 → 0.3.0-beta.11

package/dist/types/index.d.ts

@@ -97,6 +97,31 @@ interface ContextCampaign {
      */
     clickIds?: Record<string, string>;
 }
+/**
+ * Nguồn đưa khách tới lần ĐẦU TIÊN, đính vào `context` của event `page` (xem
+ * `core/attribution.ts` và `attachFirstTouch` ở `core/runtime.ts` để biết vì sao là `page`). Đây cũng đúng shape của `attribution` trong thân
+ * `POST /js/v1/zalo-qr/session` — một hình dạng dùng cho cả hai đường là cố ý: chỉ cần một chỗ ánh xạ
+ * (`toAttributionWire`), nên chỉ có một chỗ có thể ánh xạ sai.
+ *
+ * Vì sao tên field là `utm_*` chứ không theo Segment Spec như {@link ContextCampaign}: đích đến là
+ * `ContactEntity.source_info` của CDP, nơi các field tên đúng là `utm_source`/`utm_medium`/…, và cột
+ * `utm_*` trong ClickHouse. Giữ nguyên tên đích thì không hop nào phải dịch — chính chỗ dịch
+ * `campaign.name` → `utm_name` đang làm mất `utm_campaign` ở luồng event của tracking-api.
+ */
+interface ContextFirstTouch {
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    utm_id?: string;
+    /** `fbclid`/`gclid`/… — vắng mặt khi `allowAdTracking: false`. */
+    click_ids?: Record<string, string>;
+    referrer?: string;
+    landing_page?: string;
+    /** epoch-ms lúc GHI nguồn (không phải lúc gửi event) — phân biệt nguồn vừa chớm với nguồn 2 năm trước. */
+    first_seen_at?: number;
+}
 interface ContextLibrary {
     /** Always `@cnv/track`. */
     name: string;
@@ -118,6 +143,16 @@ interface PayloadContext {
     userAgent?: string;
     library?: ContextLibrary;
     campaign?: ContextCampaign;
+    /**
+     * CNV extension — nguồn first-touch, CHỈ đính vào event `page`.
+     *
+     * `campaign` ở trên là UTM của CHÍNH event này (mất ngay ở pageview thứ hai); `firstTouch` là nguồn
+     * ban đầu của cả khách, sống qua nhiều phiên và qua nhiều ngày.
+     *
+     * Vì sao là `page` chứ không phải `identify`/`track`: xem `attachFirstTouch` trong `core/runtime.ts`
+     * — collector bỏ hẳn `identify`, còn `track` tên mới bị allowlist drop im lặng.
+     */
+    firstTouch?: ContextFirstTouch;
     /**
      * Pre-consent flag. Gateway may downgrade storage or skip forwarding to
      * marketing destinations when `marketing === false`.
@@ -573,7 +608,7 @@ interface PanelRemoteConfig {
     colors?: PanelColors;
     shapes?: PanelShapes;
     wallpaper?: 'NONE' | 'WAVES' | 'CUBES' | 'FUN' | 'GEOMETRIC' | 'CROSS_HATCHING';
-    /** `true` ⇒ bỏ chân panel "Cung cấp bởi CNV Loyalty". Thiếu/`false` = vẫn hiện (mặc định). */
+    /** `true` ⇒ bỏ chân panel "Cung cấp bởi CNV CDP". Thiếu/`false` = vẫn hiện (mặc định). */
     hideBranding?: boolean;
 }
 interface PanelHeaderCopy {
@@ -681,18 +716,28 @@ interface ZaloQrLoginResult {
     /** Điểm kinh nghiệm/tích luỹ hiện tại (nếu có). */
     xp?: number;
     /**
-     * JWT HẸP QUYỀN, sống 24h — dùng DUY NHẤT để gọi lại `GET {endpoint}/panel/session` khôi phục
-     * trạng thái Member sau khi khách F5 lại trang, KHÁC HẲN apiToken/loginToken thật (365 ngày, đã
-     * bị chặn không trả về client — xem javadoc trên). An toàn hơn hẳn token thật vì: hẹp quyền (chỉ
-     * verify được ở đúng 1 endpoint này), sống ngắn (24h), và khoá ký riêng theo từng project — lộ
-     * token này chỉ lộ đúng tên/hạng/điểm của 1 khách, không dùng được ở bất kỳ API nào khác trong hệ
-     * sinh thái CNV. `panel.ts` tự lưu 2 field này vào `localStorage` để khôi phục Member state lúc
-     * mở lại trang — integrator dùng `loginWithZalo()` trực tiếp (không qua Panel) có thể tự làm
-     * tương tự nếu muốn hành vi "nhớ đăng nhập" giống vậy.
+     * JWT HẸP QUYỀN, sống 30 PHÚT — dùng để gọi nhóm `{endpoint}/panel/*` (khôi phục Member sau F5,
+     * điểm/ưu đãi/đổi điểm), KHÁC HẲN apiToken/loginToken thật (đã bị chặn không trả về client — xem
+     * javadoc trên). An toàn hơn hẳn token thật vì: hẹp quyền, sống rất ngắn, và khoá ký riêng theo
+     * từng project — lộ token này chỉ lộ đúng tên/hạng/điểm của 1 khách, không dùng được ở bất kỳ API
+     * nào khác trong hệ sinh thái CNV.
+     *
+     * 30 phút KHÔNG có nghĩa khách phải quét lại QR mỗi 30 phút: `panel.ts` tự gia hạn trước hạn qua
+     * `POST {endpoint}/panel/session/refresh`, và cả chuỗi gia hạn có trần 24h kể từ lúc quét QR.
+     * Integrator dùng `loginWithZalo()` trực tiếp (không qua Panel) muốn hành vi "nhớ đăng nhập"
+     * giống vậy thì phải TỰ gia hạn — token này để yên là chết sau 30 phút.
      */
     panelSessionToken?: string;
     /** Epoch-ms hết hạn của {@link panelSessionToken} — so `Date.now() > panelSessionExp` không cần decode JWT. */
     panelSessionExp?: number;
+    /**
+     * Thời lượng còn sống của {@link panelSessionToken}, tính bằng ms kể từ lúc server phát.
+     *
+     * Dùng field này thay cho {@link panelSessionExp} bất cứ khi nào có: mốc tuyệt đối chỉ đúng nếu
+     * đồng hồ máy khách đúng, còn thời lượng thì cùng hệ quy chiếu với `Date.now()` của chính máy đó —
+     * quan trọng vì TTL chỉ 30 phút, máy lệch giờ nửa tiếng là tự đăng xuất ngay khi vừa đăng nhập.
+     */
+    panelSessionExpiresInMs?: number;
 }
 /**
  * Phiên QR-login đang chờ người dùng quét. SDK KHÔNG tự vẽ QR — host page tự

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cnv-vn/track",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.11",
   "description": "CNV Tracking SDK — lightweight, async-first web analytics tracker (<30KB gzipped).",
   "keywords": [
     "analytics",