ArgoLog

ArgoLog 是一个用于处理埋点统计的工具类，基于 AnalysysAgent SDK 封装，提供了埋点追踪、用户画像设置和用户别名设置等功能。

特性

• 🚀 优化的加载策略 - 使用静态导入，支持更好的 tree-shaking
• 🔇 静默处理 - 移除了困惑用户的初始化提示信息
• 📦 文档环境支持 - 在 docs 环境中提供 Mock 实现，确保构建正常
• 🛡️ 类型安全 - 完整的 TypeScript 类型定义
• 🔄 向后兼容 - 完全兼容现有代码，无需修改

示例

loading

基本用法

创建实例

import { ArgoLog } from '@qxs-bns/utils'

const argoLog = new ArgoLog({
  appkey: 'your-app-key',
  uploadURL: 'your-upload-url',
  debugMode: 2 // 开启调试模式
})

事件追踪

// 追踪页面访问
argoLog.track('page_view', {
  page: 'home',
  section: 'header'
})

// 追踪用户行为
argoLog.track('button_click', {
  button: 'submit',
  form: 'login'
})

用户画像设置

// 设置用户属性
argoLog.setProfile({
  age: 25,
  gender: 'male',
  city: 'Beijing',
  vip_level: 'gold'
})

用户别名设置

// 设置用户别名
argoLog.setAlias('user_12345')

高级用法

检查初始化状态

// 检查是否已初始化
if (argoLog.initialized) {
  console.log('SDK 已初始化')
}

// 等待初始化完成
const initialized = await argoLog.waitForInitialization()
if (initialized) {
  console.log('SDK 初始化成功')
} else {
  console.log('SDK 初始化失败或超时')
}

在 Vue 组件中使用

<script setup lang="ts">
import { ArgoLog } from '@qxs-bns/utils'

const argoLog = new ArgoLog({
  appkey: 'your-app-key',
  uploadURL: 'your-upload-url'
})

const sdkStatus = ref('初始化中...')

onMounted(async () => {
  const initialized = await argoLog.waitForInitialization()
  sdkStatus.value = initialized ? 'SDK 已初始化' : 'SDK 初始化失败'
})

function trackEvent() {
  argoLog.track('button_click', { button: 'submit' })
}
</script>

配置参数

参数	说明	类型	必填	默认值
appkey	应用标识	string	✅	-
uploadURL	埋点上传地址	string	✅	-
encryptType	加密类型	number	❌	0
debugMode	调试模式 (0: 关闭, 1: 开启, 2: 详细)	number	❌	0
autoProfile	自动采集用户信息	boolean	❌	false
autoTrack	自动采集页面信息	boolean	❌	false

API 方法

track(eventName, properties?)

追踪用户事件。

参数：

• eventName (string): 事件名称
• properties (object, 可选): 事件属性

示例：

argoLog.track('page_view', { page: 'home' })
argoLog.track('purchase', { product_id: '123', amount: 99.99 })

setProfile(properties)

设置用户画像信息。

参数：

• properties (object): 用户属性对象

示例：

argoLog.setProfile({
  age: 25,
  gender: 'male',
  city: 'Beijing'
})

setAlias(aliasId)

设置用户别名，用于关联匿名用户和已知用户。

参数：

• aliasId (string): 用户别名

示例：

argoLog.setAlias('user_12345')

initialized (只读属性)

获取 SDK 初始化状态。

返回：

• boolean: 是否已初始化

示例：

if (argoLog.initialized) {
  console.log('SDK 已就绪')
}

waitForInitialization()

等待 SDK 初始化完成。

返回：

• Promise<boolean>: 初始化是否成功

示例：

const success = await argoLog.waitForInitialization()
if (success) {
  console.log('SDK 初始化成功')
}

注意事项

1. 单例模式: 相同配置的 ArgoLog 实例会复用，避免重复初始化
2. 队列机制: 在 SDK 未初始化时，调用会被暂存并在初始化完成后自动执行
3. 错误处理: 所有方法都有完善的错误处理，不会因为 SDK 问题而影响主业务
4. 环境兼容: 自动检测浏览器环境，在 Node.js 环境中会给出警告
5. 文档环境: 在文档构建环境中会使用 Mock 实现，确保构建正常

最佳实践

1. 统一配置管理

// config/argo-log.ts
export const argoLogConfig = {
  appkey: process.env.ARGO_APP_KEY,
  uploadURL: process.env.ARGO_UPLOAD_URL,
  debugMode: process.env.NODE_ENV === 'development' ? 2 : 0
}

// 在应用中使用
import { ArgoLog } from '@qxs-bns/utils'
import { argoLogConfig } from '@/config/argo-log'

const argoLog = new ArgoLog(argoLogConfig)

2. 事件命名规范

// 推荐使用下划线分隔的命名方式
argoLog.track('page_view', { page: 'home' })
argoLog.track('button_click', { button: 'submit' })
argoLog.track('form_submit', { form: 'login' })

3. 属性数据规范

// 使用有意义的属性名和值
argoLog.track('product_view', {
  product_id: 'SKU123',
  product_name: 'iPhone 15',
  category: 'electronics',
  price: 999.99,
  currency: 'USD'
})