@cnv-vn/track 0.2.0-beta.7 → 0.3.0-beta.1

package/dist/types/index.d.ts

@@ -496,6 +496,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 Loyalty". 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 +680,19 @@ 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 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.
+     */
+    panelSessionToken?: string;
+    /** Epoch-ms hết hạn của {@link panelSessionToken} — so `Date.now() > panelSessionExp` không cần decode JWT. */
+    panelSessionExp?: number;
 }
 /**
  * Phiên QR-login đang chờ người dùng quét. SDK KHÔNG tự vẽ QR — host page tự
@@ -644,7 +786,10 @@ interface Dispatcher {
  *  spin up an isolated copy without leaking state between cases.
  *
  *  Public API and what each method does:
- *    init(projectId, options?)         → set up runtime, build transport
+ *    init(projectId, options?)         → set up runtime, build transport,
+ *                                        optionally fire an automatic pageview
+ *    pageview(name?, properties?)      → emit `type:"page"`
+ *    page(name?, properties?)          → emit `type:"page"`  (alias of pageview)
  *    track(event, properties?)         → emit `type:"track"`
  *    identify(userId, traits?)         → emit `type:"identify"`, persist uid
  *    reset()                           → rotate anonymousId, drop userId
@@ -652,14 +797,16 @@ interface Dispatcher {
  *    consent(state)                    → merge consent flags
  *    set(options)                      → patch SDK options at runtime
  *
+ *  `pageview()`/`page()` mở lại platform-wide (mọi project, không whitelist) — backend
+ *  (`CnvIngestService.enforceEventAllowed`) đã cho `type=page` qua không điều kiện, xem cùng thay
+ *  đổi phía tracking-api.
+ *
  *  RETIRED (platform-wide, mọi site — ke_hoach_gioi_han_event_cho_phep.md):
- *  `pageview()`/`page()`/`screen()`/`group()`/`alias()` vẫn còn tồn tại như no-op (giữ chữ ký hàm
- *  để không phá interface `Dispatcher`/`Runtime` và code cũ gọi vào không throw), nhưng KHÔNG còn
- *  gửi gì đi nữa cho BẤT KỲ site nào — backend (`CnvIngestService.enforceEventAllowed`) đã luôn từ
- *  chối các type này khi project resolve được rồi, nên quyết định là bỏ hẳn khả năng gửi ở SDK
- *  luôn, không riêng site nào. Chỉ còn `track()` + `identify()` hoạt động thật — whitelist tên
- *  event nào được phép là việc của backend (`allowedEventNames`), SDK không tự gate gì thêm ở phía
- *  client nữa (tránh khai báo trùng 2 nơi dễ lệch nhau).
+ *  `screen()`/`group()`/`alias()` vẫn còn tồn tại như no-op (giữ chữ ký hàm để không phá interface
+ *  `Dispatcher`/`Runtime` và code cũ gọi vào không throw), nhưng KHÔNG còn gửi gì đi nữa cho BẤT KỲ
+ *  site nào — backend vẫn luôn từ chối các type này khi project resolve được rồi. Whitelist tên
+ *  event nào được phép cho `track()` là việc của backend (`allowedEventNames`), SDK không tự gate
+ *  gì thêm ở phía client nữa (tránh khai báo trùng 2 nơi dễ lệch nhau).
  *
  *  Init order matters:
  *    1. Cookie / LS reads happen on demand (lazy) — every event resolves

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cnv-vn/track",
-  "version": "0.2.0-beta.7",
-  "description": "CNV Tracking SDK — lightweight, async-first web analytics tracker (<20KB gzipped).",
+  "version": "0.3.0-beta.1",
+  "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"
+  }
 }