@cnv-vn/track 0.2.0-beta.8 → 0.3.0-beta.10

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`.
@@ -496,6 +531,135 @@ interface RemoteConfigEnvelope {
     zaloQrLogin?: {
         enabled?: boolean;
     };
+    /** Cấu hình Launcher (FAB loyalty/rewards) đã publish — `config: null` = chưa cấu hình lần nào. */
+    launcher?: {
+        /** Version riêng của Launcher (tăng mỗi lần Lưu) — KHÔNG dùng chung với `version` ở trên (2 tính năng publish độc lập). */
+        version?: number;
+        updatedAt?: string;
+        config?: LauncherRemoteConfig | null;
+    };
+    /** Cấu hình Panel (nội dung mở ra khi khách click Launcher) đã publish — entity RIÊNG với
+     * `launcher` (xem `ke_hoach_tinh_nang_launcher.md` §8.1), `config: null` = chưa cấu hình lần nào. */
+    panel?: {
+        /** Version riêng của Panel — publish độc lập với `launcher`/`version` ở trên. */
+        version?: number;
+        updatedAt?: string;
+        config?: PanelRemoteConfig | null;
+    };
+}
+/**
+ * Cấu hình Launcher do dashboard CDP quản lý (`ke_hoach_tinh_nang_launcher.md` §7) — khớp 1:1
+ * model `LauncherConfigDocument.LauncherConfig` (tracking-system) và `LauncherConfig`
+ * (cdp-frontend, `tracking-launcher-config.model.ts`). SDK chỉ ĐỌC bản published, dùng để tự
+ * render FAB (xem `core/launcher.ts`) — không có API ghi nào ở SDK.
+ */
+interface LauncherRemoteConfig {
+    buttonTextDesktop?: string;
+    buttonTextMobile?: string;
+    /** `'DEFAULT'` dùng `iconPreset`; `'CUSTOM'` dùng `customIconUrl`. */
+    iconType?: 'DEFAULT' | 'CUSTOM';
+    iconPreset?: 'BAG_HEART' | 'TAG' | 'CROWN' | 'STAR' | 'GIFT';
+    customIconUrl?: string | null;
+    buttonShape?: 'SQUARE' | 'SHAVED' | 'ROUNDED' | 'CIRCULAR';
+    placementDesktop?: LauncherPlacement;
+    placementMobile?: LauncherPlacement;
+    backgroundColor?: string;
+    textColor?: string;
+    contentLayoutDesktop?: 'ICON_WITH_TEXT' | 'TEXT_ONLY' | 'ICON_ONLY';
+    contentLayoutMobile?: 'TEXT_ONLY' | 'ICON_ONLY';
+    deviceVisibility?: 'DESKTOP_AND_MOBILE' | 'DESKTOP_ONLY' | 'NONE';
+    hideOnHomepage?: boolean;
+    /** Mỗi phần tử là 1 chuỗi con cần khớp (contains) `location.pathname + location.search`. */
+    hideUrlConditions?: string[];
+    useCustomZIndex?: boolean;
+    zIndex?: number | null;
+    /** `true` ⇒ SDK áp style vị trí/z-index bằng `!important` (phòng CSS site đè lên). */
+    addImportantRule?: boolean;
+}
+interface LauncherPlacement {
+    position: 'LEFT' | 'RIGHT';
+    sideSpacing: number;
+    bottomSpacing: number;
+}
+/**
+ * Cấu hình Panel do dashboard CDP quản lý (`ke_hoach_tinh_nang_launcher.md` §8) — khớp 1:1
+ * model `PanelConfigDocument.PanelConfig` (tracking-system) và `PanelConfig` (cdp-frontend,
+ * `tracking-panel-config.model.ts`), TRỪ 2 field `bannerImageResourceKey`/`brandIconResourceKey`
+ * (chỉ dùng để quản lý media ở tầng admin, SDK chỉ cần `url` để render). SDK chỉ ĐỌC bản
+ * published, dùng để tự render nội dung Panel (xem `core/panel.ts`).
+ */
+interface PanelRemoteConfig {
+    bannerImageUrl?: string | null;
+    brandIconUrl?: string | null;
+    headerVisitor?: PanelHeaderCopy;
+    headerMember?: PanelHeaderCopy;
+    accountCreationCta?: PanelAccountCreationCta;
+    /** Thứ tự + bật/tắt từng section — chỉ `POINTS` có nội dung thật, xem `core/panel.ts`. */
+    sections?: PanelSectionConfig[];
+    /**
+     * Block tự soạn cho view "Cách kiếm thêm điểm". Rỗng/thiếu ⇒ dòng menu giữ hành vi cũ: chỉ bắn
+     * `cnv:panel:menu-click` cho site tự điều hướng, Panel KHÔNG mở view nào (shop chưa cấu hình thì
+     * không được mở ra một màn trống).
+     */
+    earnBlocks?: PanelContentBlock[];
+    /** Cùng vai trò `earnBlocks`, cho view "Cách đổi điểm". */
+    redeemBlocks?: PanelContentBlock[];
+    theme?: 'LIGHT' | 'DARK';
+    colors?: PanelColors;
+    shapes?: PanelShapes;
+    wallpaper?: 'NONE' | 'WAVES' | 'CUBES' | 'FUN' | 'GEOMETRIC' | 'CROSS_HATCHING';
+    /** `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 {
+    caption?: string;
+    title?: string;
+}
+interface PanelAccountCreationCta {
+    title?: string;
+    description?: string;
+    signInLinkText?: string;
+    createAccountButtonText?: string;
+}
+interface PanelSectionConfig {
+    type?: 'POINTS' | 'REFERRAL' | 'VIP';
+    enabled?: boolean;
+    order?: number;
+}
+/**
+ * Icon dựng sẵn cho 1 block nội dung — merchant CHỌN từ bộ này ở dashboard, không tải ảnh riêng.
+ * Khoá lạ (dashboard mới hơn bản SDK đang cache trên máy khách) lùi về icon của chính view chứ
+ * không vẽ ô rỗng — cùng nguyên tắc fail-safe `SECTIONS` đang áp cho section type lạ.
+ */
+type PanelBlockIcon = 'ORDER' | 'STAR' | 'GIFT' | 'USERS' | 'CAKE' | 'SHARE' | 'COIN' | 'CHECK';
+/**
+ * 1 block nội dung do MERCHANT tự soạn cho view "Cách kiếm thêm điểm" / "Cách đổi điểm".
+ *
+ * Panel hiển thị NGUYÊN VĂN, không suy ra con số nào từ nghiệp vụ loyalty — khác hẳn `points`/
+ * `tier` (số thật, do server tính). Đây là chỗ shop tự khai luật tích/đổi điểm của mình, vì luật
+ * đó nằm ngoài dữ liệu mà tracking-api đọc được.
+ */
+interface PanelContentBlock {
+    icon?: PanelBlockIcon;
+    title?: string;
+    description?: string;
+}
+interface PanelColors {
+    bannerBg?: string;
+    bannerFont?: string;
+    /** Mirror model admin — `core/panel.ts` hiện CHƯA render field này (Panel không có header bar riêng). */
+    headerBarFont?: string;
+    buttonBg?: string;
+    buttonFont?: string;
+    linkColor?: string;
+    iconColor?: string;
+}
+interface PanelShapes {
+    container?: 'SQUARE' | 'ROUNDED';
+    card?: 'SQUARE' | 'ROUNDED';
+    button?: 'SQUARE' | 'ROUNDED';
+    /** Mirror model admin — `core/panel.ts` hiện CHƯA render field này (Panel chưa có input nào). */
+    input?: 'SQUARE' | 'ROUNDED';
 }
 /**
  * Lý do `loginWithZalo()` thất bại (`ZaloQrLoginError.reason`). LƯU Ý phạm vi
@@ -551,6 +715,29 @@ interface ZaloQrLoginResult {
     level?: string;
     /** Điểm kinh nghiệm/tích luỹ hiện tại (nếu có). */
     xp?: number;
+    /**
+     * 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,7 +1,7 @@
 {
   "name": "@cnv-vn/track",
-  "version": "0.2.0-beta.8",
-  "description": "CNV Tracking SDK — lightweight, async-first web analytics tracker (<20KB gzipped).",
+  "version": "0.3.0-beta.10",
+  "description": "CNV Tracking SDK — lightweight, async-first web analytics tracker (<30KB gzipped).",
   "keywords": [
     "analytics",
     "tracking",
@@ -97,14 +97,17 @@
     {
       "name": "IIFE (minified + gzipped)",
       "path": "dist/cnv-track.min.js",
-      "limit": "20 KB",
+      "limit": "50 KB",
       "gzip": true
     },
     {
       "name": "ESM tree-shaken (gzipped)",
       "path": "dist/cnv-track.esm.js",
-      "limit": "20 KB",
+      "limit": "50 KB",
       "gzip": true
     }
-  ]
+  ],
+  "dependencies": {
+    "qrcode-generator": "^2.0.4"
+  }
 }