Sensors Wave UniApp SDK

Sensors Wave UniApp 数据采集 SDK 是一个跨平台的数据埋点采集库，一套代码即可在多个平台自动采集用户行为数据。 如果你是第一次接触 Sensors Wave，欢迎访问 sensorswave.com 了解产品并创建账号。

特性

• 🌐 跨平台支持：微信 / 支付宝 / 抖音 / 百度小程序、App（iOS / Android / HarmonyOS）、H5
• 🚀 自动采集：页面浏览与离开、应用启动与退出、元素点击、小程序分享等全生命周期埋点
• 🧩 Vue 插件：通过 app.use() 一键接入，自动注入页面生命周期 mixin，零侵入采集页面事件
• 👤 用户体系：匿名 / 登录用户标识、用户属性（profile）增删改、公共属性注册
• 🧪 A/B 测试：功能开关（Feature Gate）、远程配置（Feature Config）、实验分组（Experiment）
• 📡 UTM 追踪：自动解析营销渠道参数并完成首次归因
• 💾 离线持久化：事件队列持久化存储、批量上报、失败重试，保障数据不丢
• 🔌 插件化架构：内置插件管理器，支持自定义采集插件扩展能力

平台支持

| 平台 | platform | lib 标识 | 自动采集事件 | | --- | --- | --- | --- | | 微信小程序 | miniProgram | wechatMini | $MPLaunch $MPShow $MPHide $MPPageView $MPPageLeave $MPShare | | 支付宝小程序 | miniProgram | alipayMini | 同上 | | 抖音小程序 | miniProgram | douyinMini | 同上 | | 百度小程序 | miniProgram | baiduMini | 同上 | | App iOS | app | ios | $AppStart $AppEnd $AppPageView $AppPageLeave $AppInstall | | App Android | app | android | 同上 | | App HarmonyOS | app | harmony | 同上 | | H5 | h5 | webjs | $PageView $PageLoad $PageLeave $WebClick |

平台在运行时通过 uni.getSystemInfoSync() 自动识别，无需手动指定。

安装

# npm
npm install @sensorswave/uniapp-sdk

# yarn
yarn add @sensorswave/uniapp-sdk

快速开始

UniApp 推荐通过 Vue 插件 接入，插件会在 app.use() 时自动完成初始化，并注入页面生命周期 mixin，实现无侵入的页面浏览 / 离开采集。

Vue 3（推荐）

import { createSSRApp } from 'vue'
import App from './App.vue'
import Sensorswave from '@sensorswave/uniapp-sdk'

export function createApp() {
  const app = createSSRApp(App)

  // 安装插件：自动初始化 SDK + 注入页面生命周期 mixin
  app.use(Sensorswave.plugin, {
    sourceToken: 'your-source-token',
    apiHost: 'https://your-api-host.com',
    autoCapture: true,
    batchSend: false,
    debug: false,
  })

  return { app }
}

Vue 2

import Vue from 'vue'
import App from './App.vue'
import Sensorswave from '@sensorswave/uniapp-sdk'

App.mpType = 'app'

Vue.use(Sensorswave.plugin, {
  sourceToken: 'your-source-token',
  apiHost: 'https://your-api-host.com',
  autoCapture: true,
  batchSend: false,
  debug: false,
})

const app = new Vue({ ...App })
app.$mount()

在组件中使用

插件安装后，SDK 实例会挂载到 Vue 全局属性 $sensors。需要特别说明的是：

• this.$sensors 只在「Options API」中可用（Vue2 的 methods/data，或 Vue3 的 export default { methods: {} }）。
• Vue3 的 <script setup> 没有 this，不能写 this.$sensors，需改用下面的写法。
• 无论哪种写法，拿到的是同一个 SDK 单例，调用方式完全一致。

Vue 2 / Options API

<script>
export default {
  methods: {
    onSubmit() {
      this.$sensors.trackEvent('OrderSubmit', {
        order_id: 'ORDER_001',
        amount: 99.9,
      })
    },
  },
}
</script>

Vue 3 <script setup>（推荐：直接 import 单例）

由于 Sensorswave 默认导出本身就是单例，最简单的方式是直接 import 调用，无需依赖 this：

<script setup>
import Sensorswave from '@sensorswave/uniapp-sdk'

function onSubmit() {
  Sensorswave.trackEvent('OrderSubmit', {
    order_id: 'ORDER_001',
    amount: 99.9,
  })
}
</script>

手动初始化（不使用插件）

如果你不需要自动页面生命周期采集，或希望完全自己控制初始化时机，可以直接调用 init：

import Sensorswave from '@sensorswave/uniapp-sdk'

Sensorswave.init('your-source-token', {
  apiHost: 'https://your-api-host.com',
  autoCapture: true,
  batchSend: false,
})

// 上报自定义事件
Sensorswave.trackEvent('ButtonClick', {
  button_name: 'submit',
  page: 'home',
})

⚠️ sourceToken 和 apiHost 为必填项，缺失会导致数据无法上报（SDK 会在控制台输出告警）。

配置项

| 配置项 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | sourceToken | string | — | 必填。数据上报凭证，由服务端分配 | | apiHost | string | '' | 必填。数据上报 API 地址 | | debug | boolean | false | 是否开启调试模式，输出详细日志 | | autoCapture | boolean | true | 是否开启自动采集（页面浏览、启动等） | | batchSend | boolean | false | 是否启用批量发送（攒够一批或定时 flush） | | enableAB | boolean | false | 是否启用 A/B 测试功能 | | enableClickTrack | boolean | false | 是否启用 H5 元素点击采集（$WebClick），仅 H5 平台生效 | | enableShareTrack | boolean | true | 是否启用小程序分享采集 | | abRefreshInterval | number | 600000 | A/B 测试缓存刷新间隔（毫秒，默认 10 分钟，最小 30 秒） |

API 方法

事件追踪

trackEvent(eventName, properties?)

手动上报一个自定义事件。

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

Sensorswave.trackEvent('OrderSubmit', {
  order_id: 'ORDER_001',
  amount: 99.9,
  currency: 'CNY',
})

track(event)

以完整的原始事件对象上报，可覆盖 time、trace_id、login_id、user_properties 等字段。

Sensorswave.track({
  event: 'PurchaseCompleted',
  properties: {
    product_id: '12345',
    amount: 99.99,
  },
  time: Date.now(),
  trace_id: 'unique-trace-id-12345',
  login_id: 'user_12345',
  user_properties: {
    plan: 'premium',
  },
})

用户标识

identify(loginId)

设置登录 ID，并发送 $Identify 事件，将匿名行为与登录用户关联。

Sensorswave.identify('user_12345')

setLoginId(loginId)

设置登录 ID，不发送 $Identify 事件。仅需要标识用户、不需要追踪关联事件时使用。

Sensorswave.setLoginId('user_12345')

getLoginId()

获取当前登录用户 ID。返回 string。

const loginId = Sensorswave.getLoginId()

getAnonId()

获取当前匿名用户 ID，该 ID 在设备首次使用时自动生成并持久化。返回 string。

const anonId = Sensorswave.getAnonId()

用户属性（Profile）

profileSet(properties)

设置用户属性，已存在的属性会被覆盖。

Sensorswave.profileSet({
  name: '张三',
  age: 30,
  plan: 'premium',
})

profileSetOnce(properties)

首次设置用户属性，已存在的属性不会被覆盖。常用于记录首次注册时间、首次来源等。

Sensorswave.profileSetOnce({
  signup_date: '2026-01-15',
  initial_referrer: 'google',
})

profileIncrement(properties)

对数值型用户属性进行递增操作，仅支持数值类型。

// 递增单个属性
Sensorswave.profileIncrement({ login_count: 1 })

// 递增多个属性
Sensorswave.profileIncrement({
  login_count: 1,
  points_earned: 100,
  purchases_count: 1,
})

profileAppend(properties)

向数组类型的用户属性追加元素，不去重。

Sensorswave.profileAppend({
  categories_viewed: ['electronics', 'mobile_phones'],
})

profileUnion(properties)

向数组类型的用户属性追加元素，自动去重。

Sensorswave.profileUnion({
  interests: ['technology', 'gaming'],
})

profileUnset(keys)

删除指定的用户属性。

• keys (string[], 必填)：要删除的属性名数组

// 删除单个属性
Sensorswave.profileUnset(['temporary_campaign'])

// 删除多个属性
Sensorswave.profileUnset(['old_plan', 'expired_flag'])

profileDelete()

删除当前用户的全部用户属性，操作不可恢复。仅对已登录用户有效。

Sensorswave.profileDelete()

公共属性

公共属性会自动附加到后续上报的所有事件上，适合注入全局上下文（如应用版本、环境等）。

registerCommonProperties(properties)

注册静态或动态公共属性。值可以是字符串等静态值，也可以是「每次事件上报时动态求值」的函数。

Sensorswave.registerCommonProperties({
  // 静态属性
  app_version: '1.0.0',
  environment: 'production',

  // 动态属性（每次上报事件时都会重新求值）
  current_time: () => Date.now(),
  user_tier: () => getUserTier(),
})

clearCommonProperties(keys?)

清除已注册的公共属性。不传 keys 时清除全部。

// 清除指定公共属性
Sensorswave.clearCommonProperties(['app_version', 'user_tier'])

// 清除全部公共属性
Sensorswave.clearCommonProperties()

getCommonProperties()

获取当前已注册公共属性的只读快照。

const props = Sensorswave.getCommonProperties()

A/B 测试

需在初始化时设置 enableAB: true，否则以下方法将直接返回默认值。

checkFeatureGate(key)

检查功能开关（Feature Gate）是否对当前用户开启。返回 Promise<boolean>。

const enabled = await Sensorswave.checkFeatureGate('new_checkout_flow')
if (enabled) {
  showNewCheckout()
}

getFeatureConfig(key)

获取远程配置（Feature Config）。服务端返回的 JSON 字符串会被自动解析。返回 Promise<Record<string, unknown>>，默认 {}。

const config = await Sensorswave.getFeatureConfig('app_settings')
const { theme, layout } = config

getExperiment(key)

获取实验分组（Experiment）。返回 Promise<Record<string, unknown>>。

const exp = await Sensorswave.getExperiment('homepage_layout')
const { layout_type } = exp

isInitialized()

判断 SDK 是否已经 init() 完成。返回 boolean，未初始化时为 false。

if (Sensorswave.isInitialized()) {
  Sensorswave.trackEvent('Ready')
}

自动采集事件

开启 autoCapture（默认开启）后，SDK 会根据运行平台自动注册对应采集器：

• 小程序：启动、显示/隐藏、页面浏览/离开、（默认）分享
• App：启动/退出、页面浏览/离开
• H5：页面浏览、页面加载、页面离开、（可选）点击

页面浏览 / 离开采集通过 Vue 插件注入的页面生命周期 mixin 驱动（onShow / onHide / onUnload），无需手动埋点。

预置属性

SDK 会自动采集一系列以 $ 开头的预置属性，包括设备信息（$os、$model、$screen_width 等）、运行环境（$lib、$lib_version）、网络（$network_type）、页面信息（$url、$url_path 等）以及 UTM 渠道参数。

⚠️ $ 前缀为系统保留，自定义属性请勿使用 $ 前缀，以免与预置属性冲突。

HarmonyOS 适配

App 鸿蒙端需要声明网络与网络信息相关权限，否则 $network_type 等属性无法正常采集：

// entry/src/main/module.json5
{
  "module": {
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" },
      { "name": "ohos.permission.GET_NETWORK_INFO" }
    ]
  }
}

⚠️ 关键说明：必须配置 ohos.permission.GET_NETWORK_INFO 权限才能正确获取网络信息

鸿蒙平台上，SDK 通过 uni.getNetworkType() 获取当前网络类型以采集 $network_type 预置属性。若未声明 ohos.permission.GET_NETWORK_INFO 权限，uni.getNetworkType() 将调用失败，导致 $network_type 始终为空。这是鸿蒙端正确获取网络信息的前提，请务必在 module.json5 中声明该权限。

各权限作用：

• ohos.permission.INTERNET：保证事件数据能正常上报
• ohos.permission.GET_NETWORK_INFO：保证 $network_type 能正确获取

License

Apache-2.0