costway-tracking-v2 2.0.0

package/.cursor/README.md

@@ -0,0 +1,150 @@
+# Cursor 规则配置说明
+
+本项目包含了一系列适用于 Cursor 编辑器的自定义规则和配置，旨在提高开发效率和代码质量。
+
+## 目录结构
+
+```
+.cursor/
+  ├── rules.json                    # 基本编辑器规则
+  ├── settings.json                 # 编辑器设置
+  ├── cursors-intellisense-rules.json # 智能提示规则
+  ├── snippets.json                 # 代码片段
+  └── README.md                     # 说明文档
+```
+
+## 规则说明
+
+### 基本规则 (rules.json)
+
+包含了代码格式化、搜索排除和文件关联等基本设置。规则内容：
+
+- 自动格式化保存
+- 标签大小为2个空格
+- 设置搜索过滤规则
+- 文件关联配置
+- 终端和Git相关设置
+
+### 编辑器设置 (settings.json)
+
+定义了编辑器外观和行为的详细设置：
+
+- 字体设置 (JetBrains Mono)
+- 编辑器视觉增强
+- JavaScript 格式化规则
+- 差异编辑器设置
+
+### 智能提示规则 (cursors-intellisense-rules.json)
+
+提供了与跟踪功能相关的智能代码补全：
+
+- tracking-import: 导入跟踪功能相关依赖
+- vue2-init: Vue 2项目中初始化跟踪
+- vue3-init: Vue 3项目中初始化跟踪
+- track-event: 跟踪自定义事件
+- nuxt-tracking: NUXT框架中初始化跟踪
+- vite-tracking: VITE框架中导入和设置跟踪
+- global-params: 设置全局跟踪参数
+- cdn-tracking: 添加CDN跟踪脚本
+
+### 代码片段 (snippets.json)
+
+包含了常用代码片段，提高编码效率：
+
+- trackVue2: 初始化Vue2项目的跟踪功能
+- trackVue3: 初始化Vue3项目的跟踪功能
+- trackEvent: 跟踪自定义事件
+- vueTrack: 带有跟踪功能的Vue组件
+- trackNuxt: 在NUXT框架中初始化跟踪功能
+- trackVite: 在VITE框架中初始化跟踪功能
+- trackGlobalParams: 设置全局跟踪参数
+- trackCDN: 添加CDN跟踪脚本（正式环境）
+- trackCDNDev: 添加CDN跟踪脚本（测试环境）
+- npmPublish: 完整的NPM包发布流程
+- npmVersion: 更新NPM包版本号的命令
+- npmPublishBeta: 发布NPM包的beta版本
+
+## 使用方法
+
+1. 确保所有文件都放在项目根目录的 `.cursor` 文件夹中
+2. 在 Cursor 编辑器中重新打开项目以应用设置
+3. 使用代码片段：在编辑器中输入相应前缀（如 `trackVue3`）然后按 Tab 键
+4. 智能提示：在编写代码时，Cursor 会根据上下文提供智能建议
+
+### 常用片段示例
+
+```javascript
+// NUXT框架集成 - 输入 trackNuxt 后按Tab
+import Vue from 'vue';
+import { initTracking, setConfig } from 'costway-tracking/index.cjs';
+
+export default ({ app }) => {
+  // 设置国家代码
+  setConfig({ country: 'us' });
+  // 初始化跟踪
+  initTracking(app.router);
+};
+
+// Vue3/VITE框架集成 - 输入 trackVite 后按Tab
+import { initTracking, setConfig } from 'costway-tracking/trackvue3';
+
+// 设置国家代码
+setConfig({ country: 'us' });
+// 初始化跟踪
+initTracking(router);
+
+// 全局参数设置 - 输入 trackGlobalParams 后按Tab
+window.customGlobalParams = {
+  email: 'userEmail',
+  customerId: 'userId'
+};
+
+// 自定义事件跟踪 - 输入 trackEvent 后按Tab
+trackCustomEvent('eventName', {
+  'key': 'value'
+});
+```
+
+```html
+<!-- 添加CDN跟踪脚本（正式环境） - 输入 trackCDN 后按Tab -->
+<script src="https://assets.costway.com/email/css/jquery.min.js"></script>
+<script src="https://cdn1.costway.com/cgs-assets/tracking.js"></script>
+```
+
+```bash
+# NPM包发布流程 - 输入 npmPublish 后按Tab
+# 1. 确保代码已提交到git
+git add .
+git commit -m "准备发布新版本"
+
+# 2. 更新版本号
+npm version patch  # 可选 patch, minor, major
+
+# 3. 构建项目
+npm run build
+
+# 4. 发布到npm
+npm publish
+
+# 5. 推送到git仓库，包括标签
+git push && git push --tags
+
+# 发布Beta版本 - 输入 npmPublishBeta 后按Tab
+# 更新版本号，添加beta标识
+npm version prepatch --preid=beta
+
+# 构建项目
+npm run build
+
+# 发布beta版本
+npm publish --tag beta
+```
+
+## 自定义
+
+您可以根据项目需要修改这些文件来自定义规则和设置：
+
+1. 编辑 `rules.json` 更改基本编辑器行为
+2. 更新 `settings.json` 调整编辑器外观
+3. 在 `snippets.json` 中添加更多代码片段
+4. 修改 `cursors-intellisense-rules.json` 自定义智能提示规则 

package/.cursor/cursors-intellisense-rules.json

@@ -0,0 +1,62 @@
+{
+  "rules": [
+    {
+      "name": "tracking-import",
+      "pattern": "import \\{ initTracking",
+      "suggestion": "import { initTracking, trackCustomEvent } from '${source}';",
+      "description": "导入跟踪功能的完整依赖"
+    },
+    {
+      "name": "vue2-init",
+      "pattern": "mounted\\(\\)",
+      "suggestion": "mounted() {\n  initTracking(this.$router);\n}",
+      "description": "在Vue2组件中初始化跟踪"
+    },
+    {
+      "name": "vue3-init",
+      "pattern": "const router = createRouter",
+      "suggestion": "const router = createRouter({\n  history: createWebHistory(),\n  routes\n});\n\n// 初始化跟踪\ninitTracking(router);",
+      "description": "在Vue3应用中初始化跟踪"
+    },
+    {
+      "name": "track-event",
+      "pattern": "trackCustomEvent",
+      "suggestion": "trackCustomEvent('${eventName}', {\n  '${key}': '${value}'\n});",
+      "description": "跟踪自定义事件"
+    },
+    {
+      "name": "nuxt-tracking",
+      "pattern": "export default \\(\\{ app \\}\\)",
+      "suggestion": "export default ({ app }) => {\n  // 设置国家代码\n  setConfig({ country: 'us' });\n  // 初始化跟踪\n  initTracking(app.router);\n};",
+      "description": "在NUXT框架中初始化跟踪"
+    },
+    {
+      "name": "vite-tracking",
+      "pattern": "import \\{ createApp \\}",
+      "suggestion": "import { createApp } from 'vue';\nimport { initTracking, setConfig } from 'costway-tracking/trackvue3';\n\n// 设置国家代码\nsetConfig({ country: 'us' });",
+      "description": "在VITE框架中导入和设置跟踪"
+    },
+    {
+      "name": "global-params",
+      "pattern": "window\\.customGlobalParams",
+      "suggestion": "window.customGlobalParams = {\n  email: 'userEmail',\n  customerId: 'userId'\n};",
+      "description": "设置全局跟踪参数"
+    },
+    {
+      "name": "cdn-tracking",
+      "pattern": "<script src=\"https://assets.costway.com/email/css/jquery.min.js\"></script>",
+      "suggestion": "<script src=\"https://assets.costway.com/email/css/jquery.min.js\"></script>\n<script src=\"https://cdn1.costway.com/cgs-assets/tracking.js\"></script>",
+      "description": "添加CDN跟踪脚本"
+    }
+  ],
+  "filePatterns": {
+    "*.js": true,
+    "*.ts": true,
+    "*.vue": true,
+    "*.html": true
+  },
+  "excludePatterns": [
+    "**/node_modules/**",
+    "**/dist/**"
+  ]
+} 

package/.cursor/rules.json

@@ -0,0 +1,50 @@
+{
+  "editor": {
+    "formatOnSave": true,
+    "tabSize": 2,
+    "insertSpaces": true,
+    "detectIndentation": true,
+    "trimTrailingWhitespace": true,
+    "insertFinalNewline": true
+  },
+  "javascript": {
+    "formatter": "prettier",
+    "validate": true,
+    "autoClosingBrackets": true,
+    "suggestFromImports": true,
+    "updateImportsOnFileMove": true
+  },
+  "search": {
+    "exclude": {
+      "**/node_modules": true,
+      "**/dist": true,
+      "**/.git": true
+    }
+  },
+  "files": {
+    "associations": {
+      "*.vue": "vue"
+    },
+    "exclude": {
+      "**/node_modules": true,
+      "**/dist": true,
+      "**/.git": true
+    }
+  },
+  "terminal": {
+    "integrated": {
+      "shell": {
+        "osx": "/bin/zsh"
+      }
+    }
+  },
+  "git": {
+    "enabled": true,
+    "autofetch": true,
+    "confirmSync": false
+  },
+  "workbench": {
+    "iconTheme": "material-icon-theme",
+    "colorTheme": "One Dark Pro"
+  }
+} 

package/.cursor/settings.json

@@ -0,0 +1,32 @@
+{
+  "editor.fontFamily": "JetBrains Mono, Monaco, 'Courier New', monospace",
+  "editor.fontSize": 14,
+  "editor.fontLigatures": true,
+  "editor.lineHeight": 24,
+  "editor.wordWrap": "on",
+  "editor.bracketPairColorization.enabled": true,
+  "editor.guides.bracketPairs": true,
+  "editor.minimap.enabled": true,
+  "editor.cursorBlinking": "smooth",
+  "editor.cursorSmoothCaretAnimation": true,
+  "editor.smoothScrolling": true,
+  "workbench.startupEditor": "none",
+  "explorer.compactFolders": false,
+  "explorer.confirmDelete": true,
+  "window.zoomLevel": 0,
+  "terminal.integrated.fontSize": 14,
+  "javascript.updateImportsOnFileMove.enabled": "always",
+  "javascript.format.semicolons": "insert",
+  "javascript.preferences.quoteStyle": "single",
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/dist": true,
+    "**/.git": true
+  },
+  "extensions.ignoreRecommendations": false,
+  "git.autofetch": true,
+  "git.confirmSync": false,
+  "git.enableSmartCommit": true,
+  "diffEditor.ignoreTrimWhitespace": false,
+  "diffEditor.renderSideBySide": true
+} 

package/.cursor/snippets.json

@@ -0,0 +1,186 @@
+{
+  "JavaScript": {
+    "初始化Vue2跟踪": {
+      "prefix": "trackVue2",
+      "body": [
+        "import { initTracking, trackCustomEvent } from '${1:your-library/index}';",
+        "",
+        "export default {",
+        "  mounted() {",
+        "    initTracking(this.\\$router);",
+        "  }",
+        "}"
+      ],
+      "description": "初始化Vue2项目的跟踪功能"
+    },
+    "初始化Vue3跟踪": {
+      "prefix": "trackVue3",
+      "body": [
+        "import { createApp } from 'vue';",
+        "import App from './App.vue';",
+        "import { createRouter, createWebHistory } from 'vue-router';",
+        "import { initTracking } from '${1:./tracking}';",
+        "",
+        "// 定义和创建路由",
+        "const routes = [",
+        "  $2",
+        "];",
+        "const router = createRouter({",
+        "  history: createWebHistory(),",
+        "  routes",
+        "});",
+        "",
+        "// 初始化跟踪",
+        "initTracking(router);",
+        "",
+        "// 创建和挂载应用",
+        "const app = createApp(App);",
+        "app.use(router);",
+        "app.mount('#app');"
+      ],
+      "description": "初始化Vue3项目的跟踪功能"
+    },
+    "跟踪自定义事件": {
+      "prefix": "trackEvent",
+      "body": [
+        "trackCustomEvent('${1:eventName}', {",
+        "  '${2:key}': '${3:value}'",
+        "});"
+      ],
+      "description": "跟踪自定义事件"
+    },
+    "NUXT跟踪初始化": {
+      "prefix": "trackNuxt",
+      "body": [
+        "import Vue from 'vue';",
+        "import { initTracking, setConfig } from 'costway-tracking/index.cjs';",
+        "",
+        "export default ({ app }) => {",
+        "  // 设置国家代码",
+        "  setConfig({ country: '${1:us}' });",
+        "  // 初始化跟踪",
+        "  initTracking(app.router);",
+        "};"
+      ],
+      "description": "在NUXT框架中初始化跟踪功能"
+    },
+    "VITE跟踪初始化": {
+      "prefix": "trackVite",
+      "body": [
+        "import { initTracking, setConfig } from 'costway-tracking/trackvue3';",
+        "",
+        "// 设置国家代码",
+        "setConfig({ country: '${1:us}' });",
+        "// 初始化跟踪",
+        "initTracking(router);"
+      ],
+      "description": "在VITE框架中初始化跟踪功能"
+    },
+    "全局参数设置": {
+      "prefix": "trackGlobalParams",
+      "body": [
+        "window.customGlobalParams = {",
+        "  email: '${1:userEmail}',",
+        "  customerId: '${2:userId}'",
+        "};"
+      ],
+      "description": "设置全局跟踪参数"
+    }
+  },
+  "HTML": {
+    "CDN跟踪正式环境": {
+      "prefix": "trackCDN",
+      "body": [
+        "<script src=\"https://assets.costway.com/email/css/jquery.min.js\"></script>",
+        "<script src=\"https://cdn1.costway.com/cgs-assets/tracking.js\"></script>"
+      ],
+      "description": "添加CDN跟踪脚本（正式环境）"
+    },
+    "CDN跟踪测试环境": {
+      "prefix": "trackCDNDev",
+      "body": [
+        "<script src=\"https://assets.costway.com/email/css/jquery.min.js\"></script>",
+        "<script src=\"https://cdn1.costway.com/cgs-assets/tracking-dev.js\"></script>"
+      ],
+      "description": "添加CDN跟踪脚本（测试环境）"
+    }
+  },
+  "Vue": {
+    "Vue组件跟踪": {
+      "prefix": "vueTrack",
+      "body": [
+        "<template>",
+        "  <div>${1}</div>",
+        "</template>",
+        "",
+        "<script>",
+        "import { trackCustomEvent } from '${2:your-library/index}';",
+        "",
+        "export default {",
+        "  name: '${3:ComponentName}',",
+        "  methods: {",
+        "    trackAction() {",
+        "      trackCustomEvent('${4:actionName}', {",
+        "        component: '${3:ComponentName}',",
+        "        action: '${5:click}'",
+        "      });",
+        "    }",
+        "  }",
+        "}",
+        "</script>"
+      ],
+      "description": "带有跟踪功能的Vue组件"
+    }
+  },
+  "NPM": {
+    "发布NPM包流程": {
+      "prefix": "npmPublish",
+      "body": [
+        "# 1. 确保代码已提交到git",
+        "git add .",
+        "git commit -m \"${1:准备发布新版本}\"",
+        "",
+        "# 2. 更新版本号",
+        "npm version ${2|patch,minor,major|}",
+        "",
+        "# 3. 构建项目",
+        "npm run build",
+        "",
+        "# 4. 发布到npm",
+        "npm publish",
+        "",
+        "# 5. 推送到git仓库，包括标签",
+        "git push && git push --tags"
+      ],
+      "description": "完整的NPM包发布流程"
+    },
+    "更新NPM版本号": {
+      "prefix": "npmVersion",
+      "body": [
+        "# 更新补丁版本号 (1.0.0 -> 1.0.1)",
+        "npm version patch",
+        "",
+        "# 更新小版本号 (1.0.0 -> 1.1.0)",
+        "# npm version minor",
+        "",
+        "# 更新大版本号 (1.0.0 -> 2.0.0)",
+        "# npm version major"
+      ],
+      "description": "更新NPM包版本号的命令"
+    },
+    "发布Beta版本": {
+      "prefix": "npmPublishBeta",
+      "body": [
+        "# 更新版本号，添加beta标识",
+        "npm version ${1:prepatch} --preid=beta",
+        "",
+        "# 构建项目",
+        "npm run build",
+        "",
+        "# 发布beta版本",
+        "npm publish --tag beta"
+      ],
+      "description": "发布NPM包的beta版本"
+    }
+  }
+} 

package/README.md

@@ -0,0 +1,223 @@
+# Costway 统计脚本使用说明
+
+## 安装方式
+
+### NPM包安装
+
+```bash
+# 使用npm
+npm install costway-tracking
+
+# 使用yarn
+yarn add costway-tracking
+```
+
+## 框架集成指南
+
+### NUXT框架
+
+在`plugins`目录下创建`tracking.js`文件：
+
+```javascript
+import Vue from 'vue';
+import { initTracking, setConfig } from 'costway-tracking/index.cjs'
+
+export default ({ app }) => {  
+    // 使用 app.router 访问路由实例  
+    setConfig({ country: 'us' });  
+    initTracking(app.router);
+};
+```
+
+然后在`nuxt.config.js`中注册插件：
+
+```javascript
+plugins: [
+  { src: '~/plugins/tracking.js', mode: 'client' }
+]
+```
+
+### VITE框架
+
+在`main.js`中添加：
+
+```javascript
+import { initTracking, setConfig } from 'costway-tracking/trackvue3'
+
+setConfig({ country: 'us' })  
+initTracking(router);
+```
+
+### 文件说明
+
+为兼容Vue2和Vue3，我们提供了不同的导入文件：
+
+- Vue2: `costway-tracking/index.cjs`
+- Vue3: `costway-tracking/trackvue3`
+
+## CDN方式集成 (M2相关国家)
+
+> 建议文件加载尽量靠前，在jQuery后面
+
+### 正式环境
+
+```html
+<script src="https://assets.costway.com/email/css/jquery.min.js"></script>
+<script src="https://cdn1.costway.com/cgs-assets/tracking.js"></script>
+```
+
+### 测试环境
+
+```html
+<script src="https://assets.costway.com/email/css/jquery.min.js"></script>
+<script src="https://cdn1.costway.com/cgs-assets/tracking-dev.js"></script>
+```
+
+## 配置与参数设置
+
+### 国家注册（必须设置）
+
+```javascript
+setConfig({ country: 'us' })
+```
+
+### 全局参数注册（必须设置）
+
+```javascript
+window.customGlobalParams = {
+    email: 'value1',
+    customerId: 'value2'
+};
+```
+
+## 事件类型说明
+
+### 自动收集事件
+
+- **pageView**: 页面加载时触发
+- **pageLeave**: 页面离开时触发（跳转、刷新、tab切换等）
+
+这两个事件会在以下情况自动触发：
+- 页面加载
+- 点击跳转
+- 刷新页面
+- Tab切换
+- 移动端回到首页
+
+### 手动触发事件
+
+#### customEvent 自定义事件
+
+用于记录用户行为、手动触发内容等：
+
+```javascript
+trackCustomEvent("mb_serveError", { url: window.location.href });
+```
+
+#### 参数结构体
+
+```javascript
+{
+    userId: "用户uuid",
+    timestamp: "时间戳",
+    customData: "事件数据", 
+    eventName: "自定义事件名称，如add_carts"
+}
+```
+
+### 其他事件类型
+
+- **click**: 点击事件
+- **pageLoadTime**: 页面加载统计
+- **resourceLoadTime**: 资源加载统计
+- **error**: 错误日志
+- **showElement**: 页面新增显示元素数据
+- **closeElement**: 隐藏元素数据
+
+## NPM包更新发布流程
+
+本节介绍如何更新和发布NPM包到公共或私有仓库。
+
+### 前置准备
+
+确保你已经拥有发布权限并且已经登录npm：
+
+```bash
+# 登录到npm账号
+npm login
+```
+
+### 修改版本号
+
+可以手动修改`package.json`中的版本号，或使用npm命令自动更新：
+
+```bash
+# 更新补丁版本号 (1.0.0 -> 1.0.1)
+npm version patch
+
+# 更新小版本号 (1.0.0 -> 1.1.0)
+npm version minor
+
+# 更新大版本号 (1.0.0 -> 2.0.0)
+npm version major
+```
+
+### 构建包
+
+如果项目需要构建，请先执行构建命令：
+
+```bash
+npm run build
+```
+
+### 发布包
+
+发布到公共npm仓库：
+
+```bash
+npm publish
+```
+
+发布到私有仓库（如果有配置）：
+
+```bash
+npm publish --registry=https://registry.costway.com/
+```
+
+### 发布特定标签版本
+
+如需发布特定标签的版本（如beta版本）：
+
+```bash
+npm publish --tag beta
+```
+
+### 撤销发布
+
+如需撤销最近24小时内发布的版本：
+
+```bash
+npm unpublish costway-tracking@版本号
+```
+
+### 完整发布流程示例
+
+```bash
+# 1. 确保代码已提交到git
+git add .
+git commit -m "准备发布新版本"
+
+# 2. 更新版本号
+npm version patch  # 或 minor, major
+
+# 3. 构建项目 （如果需要） 
+npm run build
+
+# 4. 发布到npm
+npm publish
+
+# 5. 推送到git仓库，包括标签
+git push && git push --tags
+```
+
+