更新记录

1.0.2（2025-12-31）

[1.0.2] - 2025-12-31

更新

• 修改 package.json 平台声明

1.0.1（2025-12-31）

[1.0.1] - 2025-12-31

更新

• 优化和补充了集成文档、权限说明、集成流程、常见问题等内容

1.0.0（2025-12-31）

变更日志

[1.0.0] - 2025-12-31

新增

• 初始版本发布
• 支持友盟统计预初始化 preInitUmeng()
• 支持友盟统计正式初始化 initUmengAnalytics()
• 支持自定义埋点事件 umengEvent()
• 自动安装友盟 SDK 依赖 (@umeng/analytics 1.2.4, @umeng/common 1.1.3)
• 隐私合规初始化流程
• 完整的文档和使用示例

特性

• ✅ HarmonyOS API 12+ 支持
• ✅ UTS 原生插件
• ✅ 自动依赖管理
• ✅ 隐私政策合规
• ✅ 完整的类型定义
• ✅ 详细的日志输出

已知限制

• 仅支持 HarmonyOS 平台
• 由于 ArkTS 类型系统限制,无法使用完整的 preInit 配置

平台兼容性

uni-app(4.87)

uni-app x(4.87)

权限配置

请在 harmony-configs/entry/src/main/module.json5 的 requestPermissions 字段中添加如下权限：

requestPermissions: [
  { name: "ohos.permission.INTERNET" },
  { name: "ohos.permission.GET_NETWORK_INFO" },
  { name: "ohos.permission.GET_BUNDLE_INFO" },
  {
    name: "ohos.permission.APP_TRACKING_CONSENT",
    reason: "用于统计分析，合规收集设备标识符",
    usedScene: {
      abilities: ["EntryAbility"],
      when: "inuse"
    }
  }
]

说明：

• INTERNET 用于数据上报。
• GET_NETWORK_INFO 用于判断网络状态。
• GET_BUNDLE_INFO 用于获取应用信息。
• APP_TRACKING_CONSENT 用于合规收集设备标识符（如 OAID）。

友盟统计插件 (umeng-analytics)

HarmonyOS 友盟统计 UTS 插件,支持隐私合规的初始化流程。

友盟统计插件 (umeng-analytics)

快速集成

1. 配置 umconfig.json

在 harmony-configs/AppScope/resources/rawfile/ 目录下新建 umconfig.json，内容如下：

{
  "appKey": "你的友盟AppKey",
  "channel": "harmonyos"
}

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

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

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

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

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

// 用户同意隐私协议后调用
initUmengAnalytics()

4. 发送自定义埋点事件

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

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

umconfig.json 配置案例

{
  "appKey": "5fxxxxxxxxxxxxxxxxxxxxxx",
  "channel": "harmonyos"
}

常见问题

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

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

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

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

Q: 事件多久会上报？

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

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

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

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

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

API 说明

• initUmengAnalytics() 用户同意隐私政策后调用，正式初始化统计。
• umengEvent(eventName, params) 发送自定义事件。

参考

• 友盟官网
• 官方文档 用户同意隐私政策后调用,正式初始化友盟统计,开始数据收集。

用法:

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

umengEvent(eventName, params)

发送自定义埋点事件。

参数:

• eventName: 事件名称 (字符串)
• params: 事件参数对象,支持字符串和数字类型

示例:

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

umengEvent("user_action", {
  action_type: "click",
  button_id: "submit_btn",
  timestamp: Date.now()
})

📊 数据验证

查看日志

在 DevEco Studio 中搜索以下关键词:

1. 初始化成功:

   [UmengHelper] ✅ 友盟统计预初始化完成(含 context)
   [umeng-analytics] 友盟统计已初始化

2. 事件发送成功:

   [umeng-analytics] 埋点事件: test_event
   [@umeng][common][log_store]:表[tongji]总记录 1

3. 数据上报成功:

触发数据上报

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

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

查看后台数据

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

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

⚠️ 注意事项

隐私合规

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

配置要求

• ✅ 必须配置 umconfig.json 中的 App Key
• ✅ 支持 HarmonyOS API 12+
• ✅ 自动安装依赖: @umeng/analytics 1.2.4, @umeng/common 1.1.3

数据延迟

• ⏰ 本地日志实时可见
• ⏰ 数据上报有批量延迟(秒级到分钟级)
• ⏰ 后台展示有处理延迟(2-4 小时或次日)

🔍 常见问题

Q1: 发送了事件但后台没数据?

1. 检查是否调用了 initUmengAnalytics()
2. 查看日志确认事件已发送
3. 触发数据上报(切换到后台或累积更多事件)
4. 等待 2-4 小时或次日查看后台

Q2: 如何测试集成是否成功?

发送测试事件并查看日志:

umengEvent("test_integration", {
  test_name: "集成测试",
  timestamp: Date.now()
})

应该看到日志:

[umeng-analytics] 埋点事件: test_integration
[@umeng][common][log_store]:表[tongji]总记录 1

📄 更多信息

• 友盟官网: https://www.umeng.com/
• 友盟文档: https://developer.umeng.com/docs/147377/detail/209050
• 变更日志: 查看 changelog.md

版本: 1.0.0
更新时间: 2025-12-31
支持平台: HarmonyOS API 12+