{"_id":"z-behav-track","name":"z-behav-track","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"z-behav-track","private":false,"version":"1.0.0","type":"module","main":"./src/index.ts","module":"./src/index.ts","scripts":{"dev":"tsc && vite","build":"tsc && vite build","preview":"vite preview"},"devDependencies":{"typescript":"~5.6.2","vite":"^6.0.1"},"dependencies":{"@types/lodash":"^4.17.13","@vitejs/plugin-vue":"^5.2.1","behav-track":"file:","gio-webjs-sdk":"^4.2.3","lodash":"^4.17.21","qx-behav-track":"file:"},"_id":"z-behav-track@1.0.0","gitHead":"749e761cf192e00db1424c725957eb6da591b586","description":"Behav-Track 是一个专为 Vue 项目设计的行为跟踪工具，旨在帮助你高效地收集和分析用户在应用中的行为数据。本手册将详细指导你如何在 Vue 项目中安装、配置、使用 Behav-Track，并介绍数据埋点和相关注意事项。","_nodeVersion":"22.5.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-akbfBv9Noll+wo6bMoy0lLhCOe5yIzDRpAgeEzu20Xg6ekYZj8RWHIUq0zdYf3kHpj38wX9YRMRFKBxncfA1Jg==","shasum":"494f80f2d3ee755f8f470a7bd2e2fe1b50ef4df9","tarball":"https://registry.npmjs.org/z-behav-track/-/z-behav-track-1.0.0.tgz","fileCount":21,"unpackedSize":44141,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCFkuD7wSiFCE4L8uUglND7m5AOq9VGrUJ23on8RYaYTAIgJlvZ7rqsJB0WLf7bAifKaBG3uMAXNh04nrlOxnNtQsA="}]},"_npmUser":{"name":"mfksxy","email":"812786905@qq.com"},"directories":{},"maintainers":[{"name":"mfksxy","email":"812786905@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/z-behav-track_1.0.0_1734682164502_0.8605383750185915"},"_hasShrinkwrap":false}},"time":{"created":"2024-12-20T08:09:24.501Z","1.0.0":"2024-12-20T08:09:24.686Z","modified":"2024-12-20T08:09:24.944Z"},"maintainers":[{"name":"mfksxy","email":"812786905@qq.com"}],"description":"Behav-Track 是一个专为 Vue 项目设计的行为跟踪工具，旨在帮助你高效地收集和分析用户在应用中的行为数据。本手册将详细指导你如何在 Vue 项目中安装、配置、使用 Behav-Track，并介绍数据埋点和相关注意事项。","readme":"# Behav-Track 使用手册\r\n\r\nBehav-Track 是一个专为 Vue 项目设计的行为跟踪工具，旨在帮助你高效地收集和分析用户在应用中的行为数据。本手册将详细指导你如何在 Vue 项目中安装、配置、使用 Behav-Track，并介绍数据埋点和相关注意事项。\r\n\r\n### 一、安装\r\n##### **使用 npm 安装**\r\n\r\n```bash\r\nnpm install qx-behav-track\r\n```\r\n\r\n##### 环境参数配置\r\n\r\n环境参数非必需，未配置时可通过初始化函数的 `options` 传入。配置环境参数需要在本地的`.env`文件中添加内容。\r\n\r\n###### **Vite 环境参数**\r\n\r\n```text\r\nVITE_VERSION=2.0.0\r\nVITE_DEV_SERVER_URL=https://buriedpoint.100bm.cn/track\r\nVITE_PROD_SERVER_URL=https://buriedpoint.qianxingniwo.com/track\r\nVITE_STORAGE_TYPE=localStorage\r\n```\r\n\r\n###### **Webpack 环境参数**\r\n\r\n```text\r\nVERSION=2.0.0\r\nDEV_SERVER_URL=https://buriedpoint.100bm.cn/track\r\nPROD_SERVER_URL=https://buriedpoint.qianxingniwo.com/track\r\nSTORAGE_TYPE=localStorage\r\n```\r\n\r\n\r\n### 二、初始化\r\n\r\n初始化代码需要放到`main.ts`文件中。Behav-Track 提供两种方式初始化：\r\n\r\n#### 方式1：通过 `app.use` + `options`\r\n\r\n```typescript\r\nimport { createApp } from 'vue';\r\nimport App from './App.vue';\r\nimport behaveTrack from \"behav-track\";\r\n\r\nconst app = createApp(App);\r\napp.use(behaveTrack, {\r\n    platform: 'wxwv', // 平台类型：微信嵌入h5\r\n    projectId: 'mall', // 商城项目\r\n    systemId: 'zsy', // 中石油商城\r\n    forceLogin: true, // 登录成功后开始上报\r\n    localTracking: true // 启动本地调试模式上报\r\n    // 其它参数参见：options\r\n});\r\n```\r\n\r\n#### 方式2：通过 `behaveTrack.$gdp`\r\n\r\n```typescript\r\nimport { createApp } from 'vue';\r\nimport App from './App.vue';\r\nimport behaveTrack from \"behav-Track\";\r\n\r\nconst app = createApp(App);\r\napp.use(behaveTrack);\r\n\r\n// wechatH5: 微信嵌入h5, mall: 商城项目, zsy: 中石油商城, appid: 空，options: 覆盖默认参数, true: 登录成功后开始上报\r\nbehaveTrack.$gdp.wechatH5(\"mall\", \"zsy\", \"\", { localTracking: true }, true);\r\n```\r\n\r\n初始化成功后可通过 Vue 全局对象或 `window.$gdp` 调用挂载函数：\r\n\r\n```javascript\r\nthis.$gdp.track({event:\"user.login.sms\",id: \"u983782923\",title:\"短信登录\" }); // Vue Composition API 中\r\n\r\n// 或\r\n\r\nwindow.$gdp.track({event:\"user.login.sms\",id: \"u983782923\",title:\"短信登录\" }); // Vue Composition API 或 JS 模块中\r\n```\r\n\r\n**options 参数说明**\r\n\r\n| 参数名           | 描述                                                                                                                 | 类型   | 默认值               |\r\n| ---------------- | -------------------------------------------------------------------------------------------------------------------- | ------ | -------------------- |\r\n| `projectId`      | 项目编号，见基础数据表                                                                                               | 字符串 | 无                   |\r\n| `systemId`       | 系统编号，见基础数据表                                                                                               | 字符串 | 无                   |\r\n| `platform`       | 平台类型: `web` PC/H5 站点, `Android` 安卓内嵌页, `wxwv` 微信公众号内嵌页, `iOS` iOS 内嵌页, `Minp` 微信小程序内嵌页 | 字符串 | 无                   |\r\n| `forceLogin`     | 是否强制登录（需要登录后才能使用的系统请设为 `true`）                                                                | 布尔值 | `false`              |\r\n| `version`        | 版本号                                                                                                               | 字符串 | behav-track 的版本号 |\r\n| `debug`          | 调试模式（开启后在控制台打印上报日志）                                                                               | 布尔值 | `false`              |\r\n| `localTracking`  | 本地上报开关（`true` 时开启本地上报）                                                                                | 布尔值 | `false`              |\r\n| `serverUrl`      | 上报服务器地址（根据 `debug` 或 `localTracking` 自动选择）                                                           | 字符串 | 自动选择             |\r\n| `storageType`    | 埋点数据存储类型 (`\"localStorage\"`, `\"cookie\"`)                                                                      | 字符串 | `\"localStorage\"`     |\r\n| `sessionExpires` | session 过期时间                                                                                                     | 数字   | 1 年                 |\r\n\r\n### 三、用户信息\r\n\r\n#### 1. 设置 Identify\r\n\r\n`forceLogin` 设置为 `true` 时：**必须**在登录成功后调用 `identify` 函数设置唯一标识，否则数据不会上报。\r\n\r\n```typescript\r\nthis.$gdp.identify(\"87698372112\");// Vue Composition API 中\r\n\r\n// 或\r\n\r\nwindow.$gdp.identify(\"87698372112\"); // Vue Composition API 或 JS 模块中\r\n```\r\n\r\n\r\n#### 2. 设置 User ID\r\n\r\n**用户登录成功后立即设置**：\r\n\r\n```javascript\r\nthis.$gdp.setUserId(\"u908777\"); // Vue Composition API 中\r\n\r\n// 或\r\n\r\nwindow.$gdp.setUserId(\"u908777\"); // Vue Composition API 或 JS 模块中\r\n```\r\n\r\n#### 3. setUserAttributes\r\n\r\n用于设置用户信息，可传递任意数据，输入为对象。\r\n\r\n```javascript\r\nthis.$gdp.setUserAttributes({ uid: \"u908777\", age: 28 }); // Vue Composition API 中\r\n\r\n// 或\r\n\r\nwindow.$gdp.setUserAttributes({ uid: \"u908777\", sex: 1 }); // Vue Composition API 或 JS 模块中\r\n```\r\n\r\n#### 4. setUser\r\n\r\n**用户登录成功后立即设置**：\r\n\r\n```javascript\r\nthis.$gdp.setUser(\"u908777\", \"张三\"); // Vue Composition API 中\r\n\r\n// 或\r\n\r\nwindow.$gdp.setUser(\"u908777\", \"张三\"); // Vue Composition API 或 JS 模块中\r\n```\r\n\r\n`setUser` 是 `identify`、`setUserId`、`setUserAttributes` 的组合。实现代码如下：\r\n\r\n```typescript\r\nexport function setUser(userId: string | number, userName?: string): void {\r\n    setUserId(userId);\r\n    identify(userId);\r\n    setUserAttributes({\r\n        userName: userName\r\n    });\r\n}\r\n```\r\n\r\n### 四、数据埋点\r\n\r\n#### 1. `event` 介绍\r\n\r\n`event` 是用于标识某一功能具体行为的唯一名称，是进行大数据分析计算时的关键。所有 `event` 必须预先定义好，并统一配置到数据中。前端在初始化时会自动拉取这些配置并缓存。埋点时，必须使用已定义的 `event`，否则会报错。这样做确保了数据的一致性和准确性。\r\n\r\n#### 2. 指令埋点\r\n\r\n**适用场景**：指令埋点适用于需要在模板中直接绑定埋点数据的场景，特别是当埋点数据与模板中的某个元素或属性紧密相关时。它简化了埋点的过程，使得在模板中就能完成埋点的配置。\r\n\r\n```typescript\r\n<script setup lang=\"ts\">\r\nimport { ref } from 'vue';\r\nlet data = ref<{ event: string; id: string; title: string }>({});\r\ndata.value = {\r\n  event: 'home.topbar.banner.click', // 事件名称，必须使用预定义的名称\r\n  id: '16892', // 对象的数据编号，必须\r\n  title: '元旦福利', // 对象的标题说明，必须\r\n};\r\n</script>\r\n\r\n<template>\r\n  <!-- 使用 v-x-track 指令将埋点数据绑定到 a 元素上 -->\r\n  <a v-x-track=\"data\">点击这里查看元旦福利</a>\r\n</template>\r\n```\r\n\r\n以上埋点在 `click` 事件触发后上报埋点数据。\r\n\r\n`v-x-track` 等同于 `v-x-track:click`，还支持 `v-x-track:change`，在元素的 `change` 事件触发后上报埋点数据。\r\n\r\n#### 3. 函数埋点\r\n\r\n**适用场景**：函数埋点适用于需要在组件的某个方法或生命周期钩子中进行埋点的场景。它提供了更大的灵活性，允许开发者在代码逻辑中动态地决定何时进行埋点。\r\n\r\n```typescript\r\n<script setup lang=\"ts\">\r\nconst login = () => {\r\n    // 用户登录成功后处理以下逻辑----------------------\r\n    window.$gdp.identify(\"16892\"); // 设置用户登录唯一标识\r\n    window.$gdp.setUserId(\"16892\"); // 设置用户编号\r\n    // 上报登录事件\r\n    window.$gdp.track({\r\n        event: 'user.login.sms',\r\n        id: '16892', // 用户编号，日志编号皆可\r\n        title: '登录成功', // 说明字段\r\n    });\r\n}\r\n</script>\r\n```\r\n\r\n在上面的例子中，`login` 方法处理用户登录成功后设置用户信息，并添加埋点数据。\r\n\r\n另外，同时调用 `identify` 和 `setUserId` 函数比较繁琐，也可以调用它们的合并函数 `setUser`：\r\n\r\n```typescript\r\n<script setup lang=\"ts\">\r\nconst login = () => {\r\n    // 用户登录成功后处理以下逻辑----------------------\r\n    window.$gdp.setUser(\"16892\", \"张三\"); // 设置用户 identify, user id, name\r\n    // 上报登录事件\r\n    window.$gdp.track({\r\n        event: 'user.login.sms',\r\n        id: '16892', // 用户编号，日志编号皆可\r\n        title: '登录成功', // 说明字段\r\n    });\r\n}\r\n</script>\r\n```\r\n\r\n\r\n#### 4. 数据类型\r\n只有符合`IEventData`数据结构的数据才能会上报\r\n```typescript\r\n// 定义产品项接口，包含事件名称、SKU ID和SPU ID\r\nexport interface IProductItem {\r\n    event: string; // 事件名称\r\n    name: string; // 产品名称\r\n    skuId: string | number; // SKU ID，可以是字符串或数字\r\n    spuId: string | number; // SPU ID，可以是字符串或数字\r\n}\r\n\r\n// 定义搜索接口，包含事件名称和关键词\r\nexport interface ISearch {\r\n    event: string; // 事件名称\r\n    keywords: string; // 搜索关键词\r\n    resultCount?: number; // 结果数量\r\n}\r\n\r\n// 定义用户接口，包含事件名称、用户ID和用户名\r\nexport interface IUser {\r\n    event: string; // 事件名称\r\n    id: string | number; // 用户ID，可以是字符串或数字\r\n    name: string; // 用户名\r\n}\r\n\r\n// 定义项目接口，包含事件名称、项目ID和项目标题\r\nexport interface IItem {\r\n    event: string; // 事件名称\r\n    id: string | number; // 项目ID，可以是字符串或数字\r\n    title: string; // 项目标题\r\n}\r\n\r\n// 定义结果接口，包含事件名称、输入数据和结果数量\r\nexport interface IQuery {\r\n    event: string; // 事件名称\r\n    input: any; // 输入数据，可以是任何类型\r\n    resultCount: number; // 结果数量\r\n}\r\n\r\n// 定义事件数据类型，可以是IProductItem、ISearch、IItem、IUser或IQuery中的任何一个\r\nexport type IEventData = IProductItem | ISearch | IItem | IUser | IQuery;\r\n\r\n// 类型保护函数，用于判断给定事件是否为IProductItem类型\r\nexport function IsProductItem(event: any): event is IProductItem {\r\n    // 检查event是否为非空对象，并且包含event、skuId和spuId属性\r\n    return typeof event === 'object' && event !== null && 'event' in event && 'name' in event && 'skuId' in event && 'spuId' in event;\r\n}\r\n\r\n// 类型保护函数，用于判断给定事件是否为ISearch类型\r\nexport function IsSearch(event: any): event is ISearch {\r\n    // 检查event是否为非空对象，并且包含event和keywords属性\r\n    return typeof event === 'object' && event !== null && 'event' in event && 'keywords' in event;\r\n}\r\n\r\n// 类型保护函数，用于判断给定事件是否为IUser类型\r\nexport function IsUser(event: any): event is IUser {\r\n    // 检查event是否为非空对象，并且包含event、id和name属性\r\n    return typeof event === 'object' && event !== null && 'event' in event && 'id' in event && 'name' in event;\r\n}\r\n\r\n// 类型保护函数，用于判断给定事件是否为IItem类型\r\nexport function IsItem(event: any): event is IItem {\r\n    // 检查event是否为非空对象，并且包含event、id和title属性\r\n    return typeof event === 'object' && event !== null && 'event' in event && 'id' in event && 'title' in event;\r\n}\r\n\r\n// 类型保护函数，用于判断给定事件是否为IQuery类型\r\nexport function IsQuery(event: any): event is IQuery {\r\n    // 检查event是否为非空对象，并且包含event、input和resultCount属性\r\n    return typeof event === 'object' && event !== null && 'event' in event && 'input' in event && 'resultCount' in event;\r\n}\r\n\r\n// 综合判断函数，用于判断给定事件是否为IEventData类型中的任何一种\r\nexport function IsIEventData(event: any): event is IEventData {\r\n    // 依次调用各个类型保护函数，如果任何一个返回true，则event是IEventData类型\r\n    return IsProductItem(event) || IsSearch(event) || IsItem(event) || IsUser(event) || IsQuery(event);\r\n}\r\n```\r\n\r\n**非`IEventData`类型报错：**\r\n\r\n\r\n\r\n**`event`未定义时报错:**\r\n\r\n\r\n","readmeFilename":"README.md"}