@jctrans-materials/comps-vue3 1.0.37-beta.5 → 1.0.37-beta.6

package/README.md

@@ -82,3 +82,92 @@ app.mount("#app");
 `JcSearch` 的详细参数说明可参考：
 
 - `packages/vue3/src/components/JcSearch/README.md`
+
+## GIO 埋点接入（Vue3）
+
+### 1) 按需启用（不传配置即不启用）
+
+```ts
+import { createApp } from "vue";
+import App from "./App.vue";
+import JCtransComps from "@jctrans-materials/comps-vue3";
+
+const app = createApp(App);
+
+app.use(JCtransComps, {
+  tracking: {
+    enabled: true,
+    autoInit: true,
+    directiveName: "gio-track",
+    accountId: import.meta.env.VITE_GIO_ACCOUNT_ID,
+    dataSourceId: import.meta.env.VITE_GIO_DATA_SOURCE_ID,
+    appId: import.meta.env.VITE_GIO_APP_ID,
+    initOptions: {
+      debug: import.meta.env.DEV,
+      trackPage: false,
+      autoTrackPage: true,
+      serverUrl: import.meta.env.VITE_GIO_SERVER_URL,
+    },
+  },
+});
+```
+
+如果不传 `tracking`，则不会初始化 GIO。
+
+### 2) 指令与 API 用法
+
+```vue
+<button v-gio-track="'order_submit'">提交订单</button>
+
+<button
+  v-gio-track="{
+    event: 'order_submit',
+    attrs: { source: 'cart' },
+    onTracked: ({ eventName }) => console.log(eventName),
+  }"
+>
+  提交并回调
+</button>
+```
+
+```ts
+const vm = getCurrentInstance()?.proxy;
+vm?.$trackEvent("manual_track", { source: "manual" });
+vm?.$gio.track("direct_track", { source: "direct" }, () => {
+  console.log("done");
+});
+```
+
+### 3) 配置优先级
+
+1. `window.__JCTRANS_GIO_CONFIG__`（或 `globalVarName` 指定对象）
+2. `tracking` 传入配置
+3. `import.meta.env.VITE_GIO_*`
+
+### 4) GIO 单测（Vue3）
+
+测试文件：`src/gio.test.ts`
+
+覆盖点：
+
+- 初始化分支：
+  - 有 `appId`（4 参数 `init`）
+  - 无 `appId`（3 参数 `init`）
+  - 缺少必填配置时不初始化
+- 指令行为：`mounted` / `updated` / `beforeUnmount` 的绑定、重绑、清理
+- 回调行为：`onTracked` 在 `track` 回调后触发
+- 暴露能力：`$trackEvent` 与 `$gio` 常用 API
+
+结合 GrowingIO WebJS 常用 API 文档（含 `trackTimerStart`）对齐了以下接口可用性：
+
+- `setUserId`
+- `clearUserId`
+- `setVisitor`
+- `trackTimerStart`
+- `trackTimerEnd`
+
+运行方式：
+
+```bash
+pnpm -C packages/vue3 test:run
+```

package/dist/gio.d.ts

@@ -0,0 +1,61 @@
+import { App } from 'vue';
+
+export type TrackAttrs = Record<string, string | number | Array<string | number>>;
+export type TrackDirectiveValue = string | {
+    event?: string;
+    name?: string;
+    attrs?: TrackAttrs;
+    attributes?: TrackAttrs;
+    trigger?: string;
+    once?: boolean;
+    stop?: boolean;
+    prevent?: boolean;
+    callback?: (payload: {
+        event: Event;
+        eventName: string;
+        attrs: TrackAttrs;
+        trigger: string;
+    }) => void;
+    onTracked?: (payload: {
+        event: Event;
+        eventName: string;
+        attrs: TrackAttrs;
+        trigger: string;
+    }) => void;
+};
+export type TrackConfig = {
+    enabled?: boolean;
+    autoInit?: boolean;
+    directiveName?: string;
+    globalVarName?: string;
+    accountId?: string;
+    dataSourceId?: string;
+    appId?: string;
+    serverUrl?: string;
+    initOptions?: {
+        debug?: boolean;
+        trackPage?: boolean;
+        forceLogin?: boolean;
+        idMapping?: boolean;
+        hashtag?: boolean;
+        autoTrackPage?: boolean;
+        serverUrl?: string;
+    };
+};
+export type GioPublicApi = {
+    isInitialized: () => boolean;
+    isBrowser: () => boolean;
+    init: (...args: any[]) => void;
+    track: (eventName: string, attrs?: TrackAttrs, callback?: () => void) => void;
+    setUserId: (userId: string) => void;
+    clearUserId: () => void;
+    setVisitor: (visitor: Record<string, any>) => void;
+    setGeneralProps: (props: Record<string, any>) => void;
+    setPageAttributes: (props: Record<string, any>) => void;
+    sendPage: () => void;
+    trackTimerStart: (eventName: string) => void;
+    trackTimerEnd: (eventName: string, attrs?: TrackAttrs) => void;
+};
+export declare function createGioTrackingPlugin(rawConfig?: TrackConfig): {
+    install(app: App): void;
+};

package/dist/gio.test.d.ts

@@ -0,0 +1 @@
+export {};