更新记录

1.0.5（2026-07-22）

修改

• 修改 日志

1.0.4（2026-07-22）

修改

• 修改 package.json 平台声明

1.0.3（2026-07-21）

[1.0.3] - 2026-07-21

修复

• 修复 HarmonyOS 6.0.2 / API 22 环境下 ArkTS 编译报错问题
• 修复 preInit 调用因匿名对象字面量触发 arkts-no-untyped-obj-literals 的兼容性问题
• 调整 Harmony 侧预初始化参数构造方式，提升不同 SDK / ArkTS 编译器版本下的兼容性

平台兼容性

uni-app(4.87)

uni-app x(4.87)

友盟统计插件 (umeng-analytics)

iOS 平台友盟统计 UTS 插件，支持隐私合规的初始化流程。

平台支持

• iOS 12.0+
• 自动集成友盟 SDK：UMCommon 7.5.10、UMAnalytics 9.6.3

权限配置

iOS 平台无需额外配置权限，插件会自动处理 App Tracking Transparency 权限。

快速集成

1. App.vue 启动时预初始化

// App.vue
import { ensurePreInit } from "@/uni_modules/umeng-analytics"

export default {
  onLaunch() {
    // ...其他初始化
    ensurePreInit() // 应用启动时预初始化（推荐）
  }
}

2. 用户同意隐私政策后正式初始化

import { initUmengAnalytics } from "@/uni_modules/umeng-analytics"

initUmengAnalytics({
  appKey: "你的友盟AppKey",
  channel: "AppStore",
  debug: false
})

3. 发送自定义埋点事件

import { umengEvent } from "@/uni_modules/umeng-analytics"

umengEvent("button_click", {
  button_name: "购买按钮",
  page: "商品详情页"
})

API 说明

ensurePreInit()

预初始化友盟统计模块，用于提前初始化SDK减少首次埋点延迟。

说明：建议在 App.vue 的 onLaunch 中调用，保证应用启动即完成预初始化。

initUmengAnalytics(options?)

初始化友盟统计，用户同意隐私政策后调用，正式开始数据收集。

参数：

• options.appKey - 友盟AppKey（可选，默认使用插件配置的AppKey）
• options.channel - 渠道标识（可选，默认AppStore）
• options.debug - 是否开启调试模式（可选，默认false）

示例：

// 使用默认配置初始化
initUmengAnalytics()

// 使用自定义配置初始化
initUmengAnalytics({
  appKey: 'your_appkey',
  channel: '华为应用市场',
  debug: true
})

umengEvent(eventName, params?)

上报自定义埋点事件。

参数：

• eventName - 事件名称，用于标识用户行为（如 'click_button', 'purchase_success'）
• params - 事件参数（可选），键值对形式

示例：

// 无参数事件
umengEvent('button_click')

// 带参数事件
umengEvent('purchase', { 'product_id': '12345', 'amount': 99.9 })

pageStart(pageName)

页面开始统计，调用此方法标记用户进入某个页面，配合 pageEnd 统计页面停留时长。

参数：

• pageName - 页面名称，用于标识页面

示例：

pageStart('商品详情页')

pageEnd(pageName)

页面结束统计，调用此方法标记用户离开某个页面，配合 pageStart 统计页面停留时长。

参数：

• pageName - 页面名称，需与 pageStart 的 pageName 保持一致

示例：

pageEnd('商品详情页')

login(userId)

用户登录统计，调用此方法上报用户登录事件，用于用户维度的统计分析。

参数：

• userId - 用户唯一标识（PUID）

示例：

login('user_12345')

logout()

用户登出统计，调用此方法上报用户登出事件，清除用户登录状态。

示例：

logout()

常见问题

Q: 需要手动预初始化吗？

推荐：在 App.vue 的 onLaunch 中调用 ensurePreInit()，保证应用启动即完成预初始化。

Q: 用户同意隐私政策后还需要做什么？

必须在用户同意隐私政策后调用 initUmengAnalytics()，否则不会采集和上报任何数据。

Q: 事件多久会上报？

• 满 30 条、切后台、30 分钟、退出应用等时机自动上报。

Q: 后台多久能看到数据？

• 通常 2-4 小时，最慢次日。

Q: 只调用 umengEvent 不初始化可以吗？

• 不可以。必须先 ensurePreInit()（建议 App.vue onLaunch），再 initUmengAnalytics()（用户同意后），之后再调用 umengEvent 才能保证数据被采集和上报。

数据验证

查看日志

在 Xcode 控制台中搜索以下关键词：

1. 初始化成功：

   [umeng-analytics][iOS] 友盟统计预初始化完成
   [umeng-analytics][iOS] 友盟统计已初始化

2. 事件发送成功：

   [umeng-analytics][iOS] 埋点事件: test_event

触发数据上报

友盟采用批量上报机制，以下情况会触发上报：

• ✅ 事件累积到一定数量（如 30 条）
• ✅ 应用切换到后台
• ✅ 应用正常退出
• ✅ 距离上次上报超过 30 分钟

查看后台数据

⚠️ 注意：友盟后台数据有延迟，通常需要 2-4 小时 或 次日 才能看到

1. 登录友盟后台：https://www.umeng.com/
2. 选择对应的应用
3. 进入 统计分析 → 事件分析
4. 查找自定义事件

隐私合规

• ✅ 必须在用户同意隐私政策后才调用 initUmengAnalytics()
• ✅ 调用前不会收集任何用户数据
• ✅ 符合工信部和应用商店隐私合规要求

参考

• 友盟官网
• 官方文档配置 umconfig.json