aidata-sdk

轻量级前端埋点 SDK，支持浏览器和 uni-app 小程序运行时：

• pnpm install aidata-sdk
• 通过 <script> 直接引入 dist/aidata-sdk.iife.js

pnpm 使用

import { createAidataSDK } from 'aidata-sdk'

const sdk = createAidataSDK()

sdk.init({
  endpoint: 'https://aidata.hawnlink.cn/api/track/events',
  trackingToken: 'your-tracking-token',
  transport: 'auto',
  autoTrackPage: false,
  batchDelay: 300,
})

sdk.updateConfig({
  channelCode: 'web',
})

sdk.identify('user-1', {
  plan: 'pro',
})

sdk.track('button_click', {
  buttonName: 'create-project',
})

uni-app / 小程序使用

推荐在 uni-app 项目里统一接入这套 SDK，然后复用到多个微信小程序、支付宝小程序或 H5 端。

import { createAidataSDK } from 'aidata-sdk'

export const sdk = createAidataSDK({
  endpoint: 'https://aidata.hawnlink.cn/api/track/events',
  trackingToken: 'your-tracking-token',
  transport: 'auto',
  autoTrackPage: false,
  debug: true,
})

export function initTracking(channelCode?: string) {
  sdk.init({
    channelCode,
    appVersion: '1.0.0',
  })
}

export function trackPageView(pageCode: string) {
  sdk.page(pageCode)
}

说明：

• transport: 'auto' 会优先在 uni-app / 小程序环境下使用 uni.request，浏览器环境下自动回退到 fetch
• page() 在 uni-app 中会自动采集当前页面路由，并尽量补充上一页路径、设备信息、语言等上下文
• 如果你需要接第三方请求层，也可以传 requestAdapter
• 微信小程序后台仍需配置合法请求域名，否则请求依然会失败

script 使用

<script src="https://aidata.hawnlink.cn/aidata-sdk.iife.js"></script>
<script>
  const sdk = window.AidataSDK.sdk
  sdk.init({
    endpoint: "https://aidata.hawnlink.cn/api/track/events",
    trackingToken: "your-tracking-token",
    transport: "auto",
    autoTrackPage: false,
  })
  sdk.updateConfig({
    channelCode: "landing",
  })
  sdk.track("hero_cta_click")
</script>

API

• init(options): 首次启动 SDK，并根据配置开启批量上报与定时 flush
• updateConfig(options): 在实例运行后更新配置，适合 channelCode、请求头或用户信息稍后才能确定的场景
• identify(userKey, traits?): 设置用户身份与 traits；不调用时会自动使用匿名 user_key
• track(eventCode, properties?, overrides?): 写入一条事件到队列
• page(eventCode?, properties?, overrides?): 发送页面浏览类事件
• flush(): 立即上报当前队列
• destroy(): 清理定时器

关键配置补充：

• transport: 默认 auto，会自动选择 uni.request 或 fetch
• requestAdapter: 可选，自定义请求适配器，适合特殊宿主或统一网络层封装
• channelCode: 可选；如果不传，SDK 不会回填默认渠道值，最终上报的 channel_code 保持为空
• userKey: 可选；如果不传且未调用 identify()，SDK 会自动生成并复用一个匿名 user_key。浏览器默认走 localStorage，uni-app / 小程序默认走本地存储

身份策略补充：

• track() / page() 的 user_key 优先级为：overrides.userKey > identify() / init({ userKey }) / updateConfig({ userKey }) > SDK 自动生成的匿名 user_key
• clearUser() 会清空显式设置的用户身份，后续事件会重新回退到匿名 user_key

请求结构

SDK 会自动按后端接口组装：

• 顶层请求体为 { events: [...] }
• track() 连续触发时会先进入队列，在 batchDelay 窗口内尽量合并成一次请求
• 单批次达到 maxBatchSize 时会立即 flush

示例一：传了 channelCode

{
  "events": [
    {
      "event_code": "button_click",
      "channel_code": "web",
      "user_key": "user-1",
      "occurred_at": "2026-07-16T08:30:00.000Z",
      "request_id": "req_xxx",
      "properties": {
        "buttonName": "create-project"
      },
      "sdk_name": "aidata-sdk",
      "sdk_version": "0.1.3"
    }
  ]
}

示例二：未传 channelCode

{
  "events": [
    {
      "event_code": "button_click",
      "user_key": "user-1",
      "occurred_at": "2026-07-16T08:30:00.000Z",
      "request_id": "req_xxx",
      "properties": {
        "buttonName": "create-project"
      },
      "sdk_name": "aidata-sdk",
      "sdk_version": "0.1.3"
    }
  ]
}

说明：

• 未传 channelCode 时，channel_code 不会回填默认值
• 最终序列化后的请求体里，这个字段会直接缺失

发布到 npm

推荐在包目录下发布：

cd /Users/jiadongzhu/Documents/projects/ai-data/packages/aidata-sdk

1. 构建产物

pnpm install
pnpm run build

2. 登录 npm 官方源

如果本机默认 registry 不是 npm 官方源，登录时请显式指定：

npm login --registry=https://registry.npmjs.org/

登录后可检查当前账号：

npm whoami --registry=https://registry.npmjs.org/

3. 发布

当前包已配置为发布到 npm 官方源，可直接执行：

npm publish

如果是重复发布，需要先升级版本号：

npm version patch
npm publish

可选版本类型：

• npm version patch：修复类更新，例如 0.1.0 -> 0.1.1
• npm version minor：新增功能，例如 0.1.0 -> 0.2.0
• npm version major：破坏性变更，例如 0.1.0 -> 1.0.0

4. 使用 Access Token 发布

如果 npm 账号开启了 2FA，推荐使用带发布权限的 Access Token。

先在 npm 官网生成 Granular Access Token，并开启发布权限；如果页面有对应选项，勾选 bypass 2FA for publish。

然后在当前终端设置环境变量：

export NPM_TOKEN=your_npm_token

在包目录下创建或追加 .npmrc：

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

再执行发布：

npm publish

发布完成后可清理本次终端中的 token：

unset NPM_TOKEN

5. 常见问题

• ENEEDAUTH：通常是未登录 npm 官方源，或当前 registry 指到了镜像源
• E403 ... bypass 2fa enabled is required：账号开启了 2FA，需使用 OTP 或 Access Token 发布
• You cannot publish over the previously published versions：当前版本号已存在，需要先执行 npm version patch|minor|major